apecloud
diff --git a/‎aperag/graph_curation/candidate_generation.py‎
Lines changed: 18 additions & 6 deletions b/‎aperag/graph_curation/candidate_generation.py‎
Lines changed: 18 additions & 6 deletions
diff --git a/‎aperag/graph_curation/dto.py‎
Lines changed: 28 additions & 14 deletions b/‎aperag/graph_curation/dto.py‎
Lines changed: 28 additions & 14 deletions
diff --git a/‎aperag/graph_curation/lineage_merge.py‎
Lines changed: 169 additions & 0 deletions b/‎aperag/graph_curation/lineage_merge.py‎
Lines changed: 169 additions & 0 deletions
diff --git a/‎aperag/graph_curation/service.py‎
Lines changed: 27 additions & 1 deletion b/‎aperag/graph_curation/service.py‎
Lines changed: 27 additions & 1 deletion
@@ -36,11 +36,16 @@ class CandidatePair:
 
 
 def entity_snapshot(entity: Entity) -> dict[str, Any]:
+    # Wave 5 description-NULL invariant (task #31 A3, spec § 3.1.5):
+    # snapshot must not surface ``entity.description`` — Wave 5 graph
+    # extractor stopped emitting descriptions, so reading here would
+    # serialize an empty string at best and a stale fragment at worst.
+    # Reviewers / async accept-apply workers operate on name + type +
+    # source_chunk_count instead.
     return {
         "entity_id": entity.entity_id,
         "entity_name": entity.name,
         "entity_type": entity.type,
-        "description": entity.description,
         "source_chunk_count": len(entity.source_chunk_ids or ()),
     }
 
@@ -176,9 +181,12 @@ def _lexical_signals(left: Entity, right: Entity) -> dict[str, Any]:
     if name_token_overlap >= 0.5:
         signals["name_token_overlap"] = round(name_token_overlap, 3)
 
-    description_overlap = _jaccard(_tokens(left.description), _tokens(right.description))
-    if description_overlap >= 0.2:
-        signals["description_token_overlap"] = round(description_overlap, 3)
+    # Wave 5 description-NULL invariant (task #31 A3, spec § 3.1.5):
+    # ``description`` is no longer a valid lexical signal — Wave 5
+    # graph extractor stopped emitting descriptions, so a Jaccard over
+    # description tokens would compare two empty bags and never trip.
+    # Removed entirely to enforce the invariant via shape (no read =
+    # no silent regression to "" vs "" comparisons that always pass).
 
     return signals
 
@@ -193,8 +201,12 @@ def _pair_score(signals: Dict[str, Any]) -> float:
         score += 0.30
     if signals.get("name_token_overlap"):
         score += min(float(signals["name_token_overlap"]) * 0.35, 0.30)
-    if signals.get("description_token_overlap"):
-        score += min(float(signals["description_token_overlap"]) * 0.20, 0.15)
+    # Wave 5 description-NULL invariant (task #31 A3, spec § 3.1.5):
+    # ``description_token_overlap`` weight removed — _lexical_signals no
+    # longer emits the signal post Wave 5 (descriptions are NULL), so
+    # this branch is dead. Removed to keep scoring weights canonical
+    # across detector + service paths and let the boundary test
+    # (test_graph_curation_description_free) grep-zero this surface.
     if signals.get("shared_chunk_count"):
         score += min(int(signals["shared_chunk_count"]) * 0.20, 0.50)
     if signals.get("vector_score") is not None:
 
@@ -56,13 +56,17 @@ class CurationEntity:
     * ``name`` — same as legacy.
     * ``type`` — entity type / label. Pulled from
       ``EntityWithLineage.entity_type``.
-    * ``description`` — single-string view used by ``_pair_score`` for
-      Jaccard token overlap. Prefers
-      ``EntityWithLineage.compacted_description`` when populated by the
-      Wave 7 ``GraphIndexCompactor``, falling back to the joined
-      per-doc ``description_parts`` text so newly-extracted entities
-      that have not yet hit the compactor still produce a usable
-      similarity signal.
+    * ``description`` — preserved for backward-compat with the legacy
+      DTO shape; Wave 5 description-NULL invariant (task #31 A3, spec
+      § 3.1.5) means new dedup detection paths must NOT read this
+      field. ``from_lineage`` always sets it to ``""`` — the Wave 5
+      graph extractor no longer emits ``description_parts`` /
+      ``compacted_description``, so any non-empty value here would be
+      stale residue. Field kept (instead of removed) only so existing
+      callers that pass ``description=""`` keyword don't break;
+      boundary test ``test_graph_curation_description_free`` grep-
+      zeroes any ``entity.description`` *read* in
+      ``aperag/graph_curation/**`` + ``aperag/indexing/merge_candidate_detector.py``.
     * ``source_chunk_ids`` — flattened across all
       ``EntityWithLineage.source_lineage`` members so the candidate
       generator's ``shared_chunks`` heuristic still works.
@@ -72,7 +76,12 @@ class CurationEntity:
     collection_id: str
     name: str
     type: str
-    description: str
+    # Wave 5 description-NULL invariant (task #31 A3): always ``""``
+    # for entities materialised via :meth:`from_lineage`. Field kept
+    # default-empty for backward-compat with callers that explicitly
+    # pass ``description=""`` (or pre-Wave-5 fixtures); new code paths
+    # must not read it (boundary test enforced).
+    description: str = ""
     source_chunk_ids: Sequence[str] = field(default_factory=tuple)
 
     def __post_init__(self) -> None:
@@ -97,12 +106,17 @@ def from_lineage(
         ``collection_id`` is supplied by the caller because the
         ``EntityWithLineage`` view is per-collection-bound at the
         store level and does not carry the id field on the row.
-        """
-        if entity.compacted_description:
-            description = entity.compacted_description
-        else:
-            description = "\n\n".join(p.text for p in entity.description_parts if p.text)
 
+        Wave 5 description-NULL invariant (task #31 A3, spec § 3.1.5
+        item 4): description input no longer depends on
+        ``entity.compacted_description`` / ``entity.description_parts``
+        — Wave 5 graph extractor stopped emitting them, so the legacy
+        derivation would always collapse to ``""`` and any non-empty
+        value (e.g. on a stale row from before the cut-over) would
+        leak into dedup scoring. Set explicitly to ``""`` here so the
+        invariant is enforced at the boundary, not silently relied on
+        downstream.
+        """
         chunk_ids: list[str] = []
         for member in entity.source_lineage:
             chunk_ids.extend(member.chunk_ids)
@@ -112,7 +126,7 @@ def from_lineage(
             collection_id=collection_id,
             name=entity.name,
             type=entity.entity_type,
-            description=description,
+            description="",
             source_chunk_ids=tuple(chunk_ids),
         )
 
 
@@ -189,6 +189,20 @@ async def merge_entities(
         Empty ``source_names`` is a no-op (returns immediately with
         ``LineageMergeResult(final_target=target_name, ...,
         merged_source_ids=[])``).
+
+        ⚠️ **Wave 5 description-NULL invariant note** (task #31 A3,
+        spec § 3.1.5): this is the *legacy* description-bearing path
+        — it still calls the LLM unified description / Compactor /
+        ``__curation_merge__`` sentinel write / vector embed write.
+        It is preserved for the manual / sync ``handle_action()`` API
+        compatibility lane (per spec § 3.1.5 «老 ``lineage_merge.py``
+        路径保留作 manual API 兼容，标 deprecation Lesson #14 multi-
+        iteration cleanup follow-up»). The async accept-apply worker
+        introduced by task #31 must use
+        :meth:`merge_entities_apply_description_free` instead — that
+        variant skips every LLM/compactor/vector-embed step so it
+        respects the Wave 5 invariant that
+        ``EntityRecord.description`` is always ``NULL``/``""``.
         """
         if not source_names:
             return LineageMergeResult(
@@ -328,6 +342,161 @@ async def merge_entities(
             compacted_description=compacted,
         )
 
+    async def merge_entities_apply_description_free(
+        self,
+        *,
+        target_name: str,
+        source_names: Sequence[str],
+        merged_by: str | None = None,
+    ) -> LineageMergeResult:
+        """Wave 5 description-NULL apply variant — task #31 A3 (spec
+        § 3.1.5).
+
+        Async accept-apply worker entry point. Mirrors
+        :meth:`merge_entities` step ordering (1 → 2 → 3 → 6a → 8) but
+        deliberately **skips** the four description-bearing steps
+        forbidden by the Wave 5 invariant:
+
+        * Step 4 — LLM unified description **(skipped)**: graph
+          extractor no longer emits ``description_parts`` after Wave
+          5, so unifying empty fragments would call the LLM with no
+          input and burn budget for no value.
+        * Step 5 — :class:`GraphIndexCompactor` pass **(skipped)**:
+          there is no unified description to compact.
+        * Step 6b — final ``__curation_merge__`` sentinel upsert
+          **(skipped)**: nothing to anchor; the canonical entity
+          carries no description text post Wave 5.
+        * Step 7 — vector layer write **(skipped)**: graph entity
+          vectors are owned by the ``graph_vectors`` worker (Wave 5
+          task #5 / #7 split). The merger never re-embeds a
+          description here — the orphan source vectors are GC'd by
+          the ``q:graph_vector`` clean-up lane (task #11) so the
+          accept-apply path does not need to call the vector store at
+          all (no write, no delete).
+
+        What still runs:
+
+        1. ``alias_repo.resolve_canonical(target_name)`` — flatten
+           any pre-existing alias chain so the final target is
+           canonical (1-hop guarantee, same as legacy step 1).
+        2. ``alias_repo.upsert_alias(alias=source, target=...)`` per
+           source — guarantees future indexer writes redirect.
+           :class:`AliasCycleError` propagates.
+        3. ``store.get_entity`` for target + sources — needed only to
+           read ``source_lineage`` so per-doc lineage members can be
+           re-anchored under the canonical name. ``description_parts``
+           is post-Wave-5 always ``[]`` and is **not** read.
+        4. (Step 6a equivalent) Re-anchor each source's
+           ``source_lineage`` members under the target name with
+           ``EntityRecord.description=""`` so per-doc tracking is
+           preserved (invariant #1, L1 不污染) without re-introducing
+           description residue.
+        5. (Step 8 equivalent) Delete sources from L1 only — vector
+           store is left to task #11 GC, mirroring how every other
+           description-free path treats orphan vectors.
+
+        Failure mode is identical to :meth:`merge_entities` — the
+        merge is not a single SQL transaction across all steps; the
+        alias upsert (step 2) is transactional inside
+        :class:`AliasMapRepository`, and every downstream write is
+        keyed on ``(document_id, parse_version)`` so a retried merge
+        is idempotent.
+
+        Returns ``LineageMergeResult`` with
+        ``unified_description=""`` and ``compacted_description=None``
+        — fields are kept on the result shape for backward-compat
+        with the legacy caller (UI layer reuses the same shape) but
+        new callers should ignore them.
+        """
+        if not source_names:
+            return LineageMergeResult(
+                final_target=target_name,
+                merged_source_ids=[],
+                unified_description="",
+                compacted_description=None,
+            )
+
+        # Step 1 — flatten target chain (1-hop).
+        final_target = await self._alias_repo.resolve_canonical(collection_id=self._collection_id, name=target_name)
+
+        # Step 2 — record alias rows. Cycle reject propagates as
+        # AliasCycleError so the caller can abort cleanly.
+        for src in source_names:
+            await self._alias_repo.upsert_alias(
+                collection_id=self._collection_id,
+                alias_name=src,
+                target=final_target,
+                merged_by=merged_by,
+            )
+
+        # Step 3 — read target + sources (lineage only; description_parts
+        # is empty post-Wave-5 and is intentionally not read here).
+        target_entity = await self._store.get_entity(final_target)
+        if target_entity is None:
+            # Target was GC'd between merge initiation and execution —
+            # alias rows already written; no L1 update can succeed.
+            logger.warning(
+                "lineage_merger(description_free): target %r missing at merge time (collection=%s); "
+                "alias rows written but no L1 update performed",
+                final_target,
+                self._collection_id,
+            )
+            return LineageMergeResult(
+                final_target=final_target,
+                merged_source_ids=list(source_names),
+                unified_description="",
+                compacted_description=None,
+            )
+
+        source_entities: list[EntityWithLineage] = []
+        for src in source_names:
+            row = await self._store.get_entity(src)
+            if row is not None:
+                source_entities.append(row)
+
+        # Step 6a equivalent — re-anchor source lineage members under
+        # the target name with ``description=""`` so per-doc tracking
+        # is preserved without leaking Wave-5-erased description text.
+        # We re-anchor per ``LineageMember`` instead of per
+        # ``DescriptionPart`` because post-Wave-5 entities carry
+        # lineage rows but no description parts, and the indexer write
+        # contract still requires a record + lineage tuple.
+        bulk_parts: list[tuple[EntityRecord, LineageMember]] = []
+        for src in source_entities:
+            for member in src.source_lineage:
+                chunk_ids = tuple(member.chunk_ids)
+                bulk_parts.append(
+                    (
+                        EntityRecord(
+                            name=final_target,
+                            entity_type=target_entity.entity_type,
+                            description="",
+                            source_chunk_ids=chunk_ids,
+                        ),
+                        LineageMember(
+                            document_id=member.document_id,
+                            parse_version=member.parse_version,
+                            tenant_scope_key=member.tenant_scope_key,
+                            chunk_ids=chunk_ids,
+                        ),
+                    )
+                )
+        if bulk_parts:
+            await self._store.bulk_upsert_entity_with_lineage_parts(parts=bulk_parts)
+
+        # Step 8 equivalent — delete sources from L1 only. Vector
+        # cleanup is owned by the ``q:graph_vector`` GC lane
+        # (task #11) per the description-free contract.
+        for src_entity in source_entities:
+            await self._store.delete_entity(src_entity.name)
+
+        return LineageMergeResult(
+            final_target=final_target,
+            merged_source_ids=list(source_names),
+            unified_description="",
+            compacted_description=None,
+        )
+
     # ------------------------------------------------------------------
     # internals
     # ------------------------------------------------------------------
 
@@ -241,6 +241,24 @@ async def _load(session: AsyncSession):
         # in W7-8). ``edges_redirected`` / ``edges_collapsed`` are 0
         # by design — alias redirect happens at indexer write-time via
         # the decorator, not as a per-merge count we can surface.
+        #
+        # ⚠️ DEPRECATED (task #31 A3, spec § 3.1.5 — Lesson #14 multi-
+        # iteration cleanup family): the ``merge_result`` carries
+        # ``compacted_description`` / ``unified_description`` only on
+        # the legacy ``LineageEntityMerger.merge_entities`` path —
+        # post-Wave-5 the description-free apply variant
+        # (``merge_entities_apply_description_free``) returns ``None``
+        # / ``""`` for both fields. This sync ``handle_action()`` API
+        # is preserved for back-compat with existing callers that
+        # consume ``merge_result.description`` in the response;
+        # follow-up cleanup once all consumers migrate to the async
+        # accept-apply path will drop this field from the response
+        # shape entirely. The boundary test
+        # ``tests/boundaries/test_graph_curation_description_free.py``
+        # explicitly allowlists ``merge_result.compacted_description``
+        # via the ``NON_ENTITY_BASE_NAMES`` mechanism (it is a
+        # ``LineageMergeResult`` field, not an ``entity`` description
+        # read).
         merge_description = merge_result.compacted_description or merge_result.unified_description
         chunk_ids: set[str] = set()
         target_after = await merger._store.get_entity(merge_result.final_target)  # noqa: SLF001
@@ -842,7 +860,15 @@ async def _fetch_shadow_neighbors(
         flt = Eq("indexer", "graph_entity")
         out: dict[str, list[tuple[str, float]]] = {}
         for entity in entities:
-            text = entity.description or entity.name
+            # Wave 5 description-NULL invariant (task #31 A3, spec § 3.1.5):
+            # ``CurationEntity.description`` is always ``""`` post Wave 5
+            # (see ``CurationEntity.from_lineage``); the legacy
+            # ``description or name`` fallback short-circuits to ``name``
+            # uniformly, so read the name directly. Mirrors the
+            # ``MergeCandidateDetector._embedding_query_text`` shape but
+            # this consumer pre-dates the helper and only needs a stable
+            # text input — name is sufficient.
+            text = entity.name
             if not text:
                 continue
             try: