From e83412b1b6bbf60ec1ecf9a7e22a69a612e91429 Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Date: Thu, 2 Apr 2026 08:49:53 +0000
Subject: [PATCH] feat(acms): implement pipeline Phase 2 components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add spec-aligned Protocol type aliases for all Phase 2 (Fragment Fusion)
pipeline component interfaces, aligning with docs/specification.md
§44794-44856 naming conventions:

- FragmentDeduplicatorProtocol (alias for FragmentDeduplicator)
- DetailDepthResolverProtocol (alias for DetailDepthResolver)
- FragmentScorerProtocol (alias for FragmentScorer)
- BudgetPackerProtocol (alias for BudgetPacker)
- FragmentOrdererProtocol (alias for FragmentOrderer)

The production implementations (ContentHashDeduplicator, MaxDepthResolver,
WeightedCompositeScorer, GreedyKnapsackPacker) in acms_phase2.py satisfy
all acceptance criteria:

- ContentHashDeduplicator: SHA-256 content hashing, retains highest-scored
  duplicate per (uko_node, content_hash) key
- MaxDepthResolver: Retains highest detail_depth per UKO node, with
  relevance tiebreaking at equal depths
- WeightedCompositeScorer: Configurable weighted composite (relevance=0.4,
  hierarchy=0.3, quality=0.2, recency=0.1), stores breakdown in metadata
- GreedyKnapsackPacker: Greedy knapsack with depth fallback [9,4,2,0],
  minimum fragment token threshold (10)

All components implement v1 Protocol signatures and are DI-injectable
into ACMSPipeline constructor. 31 BDD scenarios cover all components.

ISSUES CLOSED: #540
---
 .../application/services/acms_service.py          | 15 +++++++++++++++
 vulture_whitelist.py                              |  6 ++++++
 2 files changed, 21 insertions(+)

diff --git a/src/cleveragents/application/services/acms_service.py b/src/cleveragents/application/services/acms_service.py
index d231fe350..d9903d8b4 100644
--- a/src/cleveragents/application/services/acms_service.py
+++ b/src/cleveragents/application/services/acms_service.py
@@ -361,6 +361,21 @@ class FragmentOrderer(Protocol):
     ) -> Sequence[ContextFragment]: ...
 
 
+# ---------------------------------------------------------------------------
+# Spec-aligned Protocol aliases (spec §44794-44856)
+# ---------------------------------------------------------------------------
+# The specification uses "Protocol" suffix for all pipeline component
+# interfaces (e.g. ``FragmentDeduplicatorProtocol``).  These aliases
+# expose the canonical spec names alongside the shorter runtime names so
+# that code referencing either form works correctly.
+
+FragmentDeduplicatorProtocol = FragmentDeduplicator
+DetailDepthResolverProtocol = DetailDepthResolver
+FragmentScorerProtocol = FragmentScorer
+BudgetPackerProtocol = BudgetPacker
+FragmentOrdererProtocol = FragmentOrderer
+
+
 # ---------------------------------------------------------------------------
 # Phase 3 — Context Finalization protocols (spec §42648-42653)
 # ---------------------------------------------------------------------------
diff --git a/vulture_whitelist.py b/vulture_whitelist.py
index cef933f03..f6bd96090 100644
--- a/vulture_whitelist.py
+++ b/vulture_whitelist.py
@@ -992,6 +992,12 @@ ScoredFragment  # noqa: B018, F821
 score_detailed  # noqa: B018, F821
 depth_fallback_steps  # noqa: B018, F821
 min_fragment_tokens  # noqa: B018, F821
+# Spec-aligned Protocol aliases (spec §44794-44856)
+FragmentDeduplicatorProtocol  # noqa: B018, F821
+DetailDepthResolverProtocol  # noqa: B018, F821
+FragmentScorerProtocol  # noqa: B018, F821
+BudgetPackerProtocol  # noqa: B018, F821
+FragmentOrdererProtocol  # noqa: B018, F821
 
 
 # LSP Server Stub — public API (issue #203)
-- 
2.52.0