feat(Wave 7 #6): alias_map + transparent redirect + LineageEntityMerger

[earayu]

Summary

Wave 7 §K.12.6 / §K.12.7 / §K.12.10b task #6 — full storage + service body for user-driven entity merge over the lineage graph. One PR, 24 unit tests, zero changes to the three storage backends (per architect Option (b) lock + huangheng endorse).

Per architect ratify msg=cf860ae4 (5-drift lock) + huangheng endorse msg=22816e0d (sentinel __curation_merge__, decorator passthrough invariant, step ordering L1 → vector → delete).

What ships

1. aperag_lineage_entity_alias table (alembic b5d2e8f1c9a4) — composite PK (collection_id, alias_name) + (collection_id, canonical_name) index for reverse lookup.
2. LineageEntityAlias ORM (aperag/domains/knowledge_graph/db/models.py) — colocated with the other curation domain models.
3. AliasMapRepository (aperag/graph_curation/alias_map.py):
   • resolve_canonical(collection_id, name) — single-indirection read; transitive flatten keeps the table 1-deep at write time.
   • upsert_alias(...) — cycle reject (raises AliasCycleError) + transitive flatten (UPDATE old rows pointing at the alias name + INSERT new row, single transaction).
   • list_aliases_pointing_at(...) for tests / admin tooling; purge_collection(...) for collection teardown.
4. LineageGraphStoreWithAliasRedirect decorator (aperag/indexing/alias_redirect_store.py) — wraps any LineageGraphStore + AliasMapRepository, intercepts upsert_entity_with_lineage / upsert_relation_with_lineage to rewrite entity names through the alias map, forwards every other Protocol method byte-for-byte. Zero changes to the three backend implementations.
5. LineageEntityMerger (aperag/graph_curation/lineage_merge.py) — the user-driven merge orchestrator. Step ordering locked: alias upsert → L1 source-parts re-anchored preserving (document_id, parse_version, chunk_ids) → L1 final unified+compacted with __curation_merge__ sentinel → vector upsert (3-field payload, uuid5 id) → source delete (L1 + vector) last.

§K.12 invariant cross-check (12-item)

#	Invariant	This PR
1	L1 graph data 不污染	✅ source parts re-anchored under target preserve original (document_id, parse_version, chunk_ids) lineage — pinned by test_source_parts_reanchored_preserving_doc_lineage
2	L1 → L2 单向派生	✅ step ordering pinned by test_step_order_is_l1_then_vector_then_delete (L1 writes precede vector writes; deletes last)
3	upsert_entity_with_lineage transparent alias redirect	✅ pinned by test_indexer_upsert_after_merge_redirects_to_canonical
4	Vector store via VectorStoreConnectorAdaptor	✅ uses VectorStoreConnector.upsert/delete via asyncio.to_thread
5	payload indexer="graph_entity" filter	✅ pinned by test_vector_payload_is_3_field_with_deterministic_uuid5 (3-field strict: {indexer, entity_name, entity_type})
6	uuid5 deterministic vector point id	✅ same test pins uuid5(NAMESPACE_DNS, "graph_entity:{cid}:{name}")
7	alias_map persistence independent of doc lifecycle	✅ pinned by test_alias_persists_after_canonical_gc
8	snapshot-diff via lineage entity name set	n/a (covered by task #3 #1757)
9	cycle flatten + reject	✅ 3 tests: test_transitive_flatten_rewrites_existing_alias_rows, test_cycle_reject_self_loop, test_cycle_reject_through_existing_chain
10	DB column length application-layer cap	n/a (alias names use the same String(512) cap as aperag_lineage_entity.name)
11	候选检测仅写不自动合并 (D-3)	✅ LineageEntityMerger.merge_entities is the only entry point; MergeCandidateDetector (PR #1755) does not import it
12	命名 grep-zero LightRAG	✅ grep -rn 'LightRAG|lightrag' aperag/graph_curation/{alias_map,lineage_merge}.py aperag/indexing/alias_redirect_store.py aperag/migration/versions/20260428030000-* tests/unit_test/{graph_curation,indexing}/ → 0 hits

4-pattern pre-check matrix

Pattern 1 v1 — caller-grep:

$ grep -rn 'GraphIndexService.merge_entities\|class.*Alias\|alias_map' aperag/ tests/ | grep -v __pycache__ | grep -v __init__
aperag/domains/knowledge_graph/service.py:171: result = await svc.merge_entities(...)  # legacy KnowledgeGraphService.merge_entities → GraphIndexService.merge_entities (route handler — task #8 cutover)
aperag/domains/knowledge_graph/api/routes.py:160: ...graph_service.merge_entities(...)  # REST POST /graphs/merge (task #8 cutover)

→ legacy path still in place; this PR ships the replacement infrastructure. Task #8 (chenyexuan) wires the REST route to LineageEntityMerger. Detector (#1755) confirmed never calls merge_entities.

Pattern 1 v2 — n/a (new component).

Pattern 2 — dependency interface grep:

• LineageGraphStore.upsert_entity_with_lineage(*, record, lineage, compacted_description) (aperag/indexing/graph.py:533, post task feat/frontend #1) — async-native, kw-only.
• LineageGraphStore.delete_entity(entity_name) -> bool (aperag/indexing/graph.py:511, post task feat/frontend #1) — single-arg.
• GraphIndexCompactor.compact_if_oversized(parts, *, subject_kind, subject_label, language) (aperag/indexing/graph_compactor.py, post task feat: auth bearer token support #2 fix-forward) — kwargs locked.
• VectorStoreConnector.upsert(points: Sequence[VectorPoint]) -> List[str] / .delete(ids: Sequence[str]) (aperag/vectorstore/base.py) — sync, wrapped via asyncio.to_thread.
• EmbeddingService.embed_query(text) -> list[float] (aperag/llm/embed/embedding_service.py:128) — sync, wrapped via asyncio.to_thread.

Pattern 3 — per-collection vs per-tenant binding:
→ Both the decorator and the merger are per-collection bound at construction; AliasMapRepository is the only stateless singleton (takes collection_id per call) — mirrors existing GraphCurationService repo convention so alembic / test setup is unchanged.

simple-stable 4-guardrail

1. 不无限扩范围 ✅ Option (b) decorator → 0 changes to 3 storage backends; LLM judge tier deferred (architect ratify); cross-doc full sweep deferred (no caller).
2. 先做实尽快上线 ✅ ships in one PR; wiring (one-line in worker_factory._build_lineage_graph_store + REST route swap in KnowledgeGraphService.merge_entities) is task feat: chat websocket connect #8's job since it co-lands with retrieval cutover.
3. 简单稳定优于复杂 ✅ existing algorithms reused (Compactor, Vector connector, LLM); transitive flatten is the simplest cycle-safe pattern (1 SQL UPDATE + 1 SQL INSERT in a transaction); alphabetical-first canonical is deterministic.
4. 私有化部署后免维护 ✅ no operator config; sentinel __curation_merge__ is a const; thresholds inherited from existing services.

Scope notes (called out for reviewers)

• Wiring is deferred to task feat: chat websocket connect #8: worker_factory._build_lineage_graph_store does NOT yet wrap with the alias-redirect decorator, and the REST /graphs/merge route still calls legacy GraphIndexService.merge_entities. Both are one-line / few-line changes that belong in task feat: chat websocket connect #8 (chenyexuan retrieval cutover) so we don't ship a partial wiring on its own. The new infrastructure is fully unit-tested and ready to wire.
• Soft-transition semantics documented in the merger module docstring: a mid-step failure leaves a partially-merged target (sources still readable until step 8 deletes them) and the merge is forward-only retry safe ((document_id, parse_version) keys make every upsert idempotent).
• N×M upsert performance (huangheng note in msg=22816e0d): 10 sources × 100 parts = 1000 serial upserts is theoretical — Wave 8+ optimization candidate, not in scope.

Test plan

24 unit cases pass (uv run pytest tests/unit_test/graph_curation/test_alias_map.py tests/unit_test/graph_curation/test_lineage_merge.py tests/unit_test/indexing/test_alias_redirect_store.py -v):

• test_alias_map.py (10): cycle reject self-loop + chain cycle, transitive flatten, target flatten through chain, alias persists after canonical GC, per-collection isolation, purge.
• test_alias_redirect_store.py (5): indexer write redirects to canonical, no-alias passthrough, both-endpoint relation redirect, single-endpoint relation redirect, decorator passthrough invariant for all 13 non-upsert Protocol methods (huangheng CR lock).
• test_lineage_merge.py (9): empty source short-circuit, step order L1 → vector → delete, sentinel __curation_merge__, Compactor kwargs locked (subject_kind/subject_label/language), source parts re-anchored preserving per-doc lineage, vector payload 3-field + uuid5 deterministic, alias cycle propagation, target alias chain flatten, target GC tolerance.
• ruff check + ruff format --check clean.

References

• spec: §K.12.6 / §K.12.7 / §K.12.10b (PRs docs(celery Wave 7 §K.12): legacy graphindex 全删 + LightRAG 风格 graph 层最终态 spec #1751 + spec(§K.12): task#4 schema retract + cycle flatten + 5 mini-pattern #1753), commits c1499777 (feat/frontend #1) + c1c48429 (feat: auth bearer token support #2) for prior task storage / Compactor.
• ratify thread: msg=7f0e1877 in #删除老graph (architect 5-drift ratify msg=cf860ae4, huangheng endorse + decorator passthrough lock msg=22816e0d, sentinel pick msg=22816e0d).

🤖 Generated with Claude Code

[earayu]

🟢 LGTM ✅ (huangheng pass-1, per spec §K.12.11) — GitHub 不允许同账号 approve；verdict = ready to merge

12-invariant 全表 + 4-pattern + simple-stable 4-guardrail 全 paste（hard-gate format 第七个达标 PR），24 tests 覆盖 spec §K.12.6 / §K.12.7 / §K.12.10b 全部架构 invariant，5 drifts 全 byte-level 修复（前 thread 我 surface 的 5 项 + 现 outline 一致），decorator passthrough 严守，sentinel __curation_merge__ 一致。

12-invariant cross-check（task #6 scope，10 项 material ✅）

#	Invariant	This PR	验证依据
1	L1 graph data 不污染（kg.jsonl raw vs storage view 严格分层）	✅	source parts re-anchored 保留原始 (document_id, parse_version, chunk_ids) lineage（lineage_merge.py:266-284）；test_source_parts_reanchored_preserving_doc_lineage 钉
2	L1 → L2 单向派生（step ordering）	✅	Step 6a/6b L1 写入 → Step 7 vector → Step 8 delete sources；test_step_order_is_l1_then_vector_then_delete 钉
3	upsert_entity_with_lineage 透明 alias redirect	✅	LineageGraphStoreWithAliasRedirect line 87-107 entity / 109-136 relation；test_indexer_upsert_after_merge_redirects_to_canonical 钉 inseparability gate
4	Vector store via VectorStoreConnectorAdaptor	✅	lineage_merge.py:_upsert_vector_point 用 await asyncio.to_thread(connector.upsert/delete, ...)，无直接 Qdrant import
5	payload 3 字段 {indexer, entity_name, entity_type}	✅	line 388-401 严格 3 字段；test_vector_payload_is_3_field_with_deterministic_uuid5 钉
6	uuid5 deterministic vector point id	✅	line 389-394 f"{GRAPH_ENTITY_INDEXER}:{collection_id}:{entity_name}" 同一 test 钉
7	alias_map orphan persist（canonical gc 不级联）	✅	alias_map.py 不 cascade-delete on canonical gc；test_alias_persists_after_canonical_gc 钉
8	snapshot-diff via lineage entity name set	n/a	task #3 范畴
9	cycle flatten + reject + transitive flatten	✅	AliasMapRepository.upsert_alias line 153-157 reject + 181-191 transitive flatten 单 transaction；3 tests 钉（self-loop / chain cycle / transitive flatten 3 case）
10	DB 列长度 cap	n/a	alias 表用 String(512) 与 entity 表一致
11	候选检测仅写不自动合并 (D-3)	✅	LineageEntityMerger.merge_entities 是 user-driven 唯一 entry；MergeCandidateDetector (PR #1755 verified) 不 import 本服务
12	命名 grep-zero LightRAG	✅	gh pr diff 1758 | grep -E '^\+' | grep -i lightrag → 0 added lines

5 drifts 修复 byte-level verification（per architect ratify msg=cf860ae4 + 我 msg=22816e0d）

Drift	spec lock	This PR 落点
#1 delete_entity(entity_name) 单参数	task #1 PR #1754 Protocol	lineage_merge.py:314 delete_entity(src_entity.name) ✅
#2 upsert_entity_with_lineage(record=EntityRecord, lineage=LineageMember) shape + sentinel __curation_merge__	architect ratify	line 271-303 调用全 record/lineage shape；line 297 document_id=CURATION_MERGE_DOCUMENT_ID (line 99 const = "__curation_merge__") ✅
#3 Compactor 加 subject_kind/subject_label/language kwargs	task #2 fix-forward	line 254-259 compact_if_oversized([unified], subject_kind="entity", subject_label=final_target, language=self._language) ✅
#4 alias_map cycle detection (transitive flatten + reject cycle)	spec §K.12.10b	alias_map.py:153-157 reject + 181-191 transitive flatten 单 transaction wrap ✅
#5 Step 顺序 L1 → vector → delete	invariant #2 lock	Step 6a (line 266) → 6b (line 286) → 7 (line 306) → 8 (line 313) ✅ + test_step_order_is_l1_then_vector_then_delete 钉

完整 mirror，无任何 stale 残留。

Decorator passthrough invariant（我 CR lock，msg=22816e0d）

alias_redirect_store.py:LineageGraphStoreWithAliasRedirect 13 个非-upsert method 全 forward 到 _inner：

• find_entity_ids_with_lineage / find_relation_keys_with_lineage
• remove_entity_lineage_member / remove_relation_lineage_member
• gc_entity_if_orphan / gc_relation_if_orphan
• delete_entity / delete_relation
• get_entity / get_relation
• query_entities_by_keyword / expand_neighbors_n_hops
• list_entity_labels

test_decorator_passthrough_for_non_upsert_methods 钉死 — 未来 Protocol 加新 method 不在 decorator 处理时立即撞 test，防 silent default break。👍

Architecture quality（细节意识）

1. Option (b) 装饰器 0 改 3 backend：避免 cross-PR risk，task #6 单 PR 全包 vs 拆 Postgres/Neo4j/Nebula 3 个 backend PR 的 sync barrier 节省。decorator 是这种 cross-cutting concern 的标准 pattern。

2. Source parts re-anchor 保留 lineage：line 266-284 不创新 sentinel "curation_merge" pseudo-doc 给 source parts；而是保留 source 原始 (document_id, parse_version, chunk_ids) → 写到 target name 下。这样 L1 仍能干净 trace per-doc origin（invariant #1 严守），未来 user 删除某个 doc 时还能 strip 对应 part。👍

3. Sentinel __curation_merge__ 仅给 unified+compacted：line 286-303 final write 用 sentinel lineage 标识"非 doc-driven"；与 indexer normal lineage 区分清楚。

4. Soft-transition + forward-only retry safety：mid-step fail 后 sources 仍 readable（step 8 last delete），retry 整个 merge (document_id, parse_version) key 全 idempotent。docstring 已记录。

5. Wiring deferred to task #8 显式 documented：worker_factory._build_lineage_graph_store 包 decorator + REST /graphs/merge route swap 都是 task #8 一行 / 几行改动，避免 partial wiring。这种 deferred wiring 必须在 task #10 close-out 之前完成否则 alias redirect 的 inseparability gate 形同虚设（indexer 还走 raw store）。

4-pattern pre-check matrix（PR body paste）

P1 v1 caller-grep 落点正确（legacy merge_entities 走 domains/knowledge_graph/service.py:171 + api/routes.py:160，task #8 cutover）。P2 dependency 接口签名全对齐已 merged commits。P3 per-collection binding 与现有 GraphCurationService repo convention 一致。

simple-stable 4-guardrail

PR description 4 项全显式：Option (b) 不改 backend / smallest surface / production helpers 复用 / no operator config。

测试质量（24/24）

• alias_map (10): cycle 3 case + transitive flatten + target chain flatten + orphan persist + collection 隔离 + purge ✅
• decorator (5): entity redirect + no-alias passthrough + relation both-endpoint redirect + relation single-endpoint redirect + 13-method passthrough invariant ✅
• merger (9): empty short-circuit + step order + sentinel + Compactor kwargs + N×M re-anchor + vector payload + cycle propagate + target chain flatten + target GC tolerance ✅

1 个 task #8 wiring 提醒（不阻塞本 PR，但 task #8 必交付）

PR description 显式说 "wiring is deferred to task #8"：

1. worker_factory._build_lineage_graph_store wrap with LineageGraphStoreWithAliasRedirect
2. REST /graphs/merge route swap to LineageEntityMerger

Critical：这 2 处 wiring 不做的话，本 PR 的 inseparability gate（invariant #3 透明 alias redirect）和 user-driven merge 都不生效。@chenyexuan task #8 PR 必须包含这 2 处 wiring，PR body 显式标注；@huangheng task #8 CR 重点查这 2 处 wiring 落点。

修完会 LGTM 的清单

实际上已经可以 merge ✅。task #8 wiring 检查推到 task #8 CR window，本 PR 无 blocker。

@明书 work 极其 solid — Option (b) 装饰器选择 + source parts re-anchor 保留 lineage 都是 spec 没显式要求但 implementer 主动加的精细度，1 PR 全包 ETA ~04:15 兑现。👍 Wave 7 close-out 路径清晰：剩 task #7（chenyexuan）+ #8（chenyexuan + 本 PR wiring）+ #9（cuiwenbo）+ #10（Bryce sweep）。

@符炫炜 LGTM，可 merge。
@不穷 推进 task #6 → done after merge；critical path 余 #7 / #8 / #9 / #10 = 4 PR 收尾 Wave 7。