feat(arch): GraphBuffer 内存 IR — 解耦 parse/write + 可组合 pass

[dreamlx]

背景

来自 ADR-007（codeindex 保持无状态 — 持久化图谱归属 loomgraph）。

当前 codeindex 是线性 2-phase：scan_directory() → parse_file() → SmartWriter.write_readme()。问题：

• parse_file() 一次性提取符号/调用/继承/路由，加新能力（K8s、similarity 等）要改 parser
• 没有中间表示，提取结果直接变 markdown，拿不到全局调用图（单文件视角，"谁调用了 authenticate()" 跨文件答不出）
• 不可组合（不能"跑 definitions 跳过 calls"）

范围（仅内存 IR，不含持久化）

引入 GraphBuffer 内存中间表示 + 可组合 pass。纯内部重构，每 run 重建，不引入任何持久化状态（持久化归 loomgraph，见 ADR-007）。

• GraphBuffer: add_node / add_edge / find_by_qn / find_edges_by_type（内存 dict + list）
• Pass 协议: run(graph, files) / should_skip(mode)
• 把现有提取拆成 pass：pass_discover / pass_definitions / pass_calls / pass_inheritance / pass_routes / pass_tech_debt
• SmartWriter 改为从 GraphBuffer 读，而非直接从 parse 结果

明确不做（ADR-007 边界）

• ❌ 持久化 SQLite 图谱 / file_hashes 状态表 / 增量回读 / 损坏恢复
• ❌ sqlite-vec 向量表
• ❌ 图查询接口
• ❌ 不把全局调用图渲染进 README_AI.md（严格零输出变化；全局图只进 GraphBuffer/export）

门控

不门控——IR 有独立的内部解耦价值，与消费侧 thesis 无关，可直接开工（ADR-007 验证门控节）。

等价定义（重要）

README_AI.md 含 AI 生成描述，非确定（master 上连跑两次都不逐字节一致）。因此「README 逐字节不变」不成立。#101 的等价保证是：「确定性的一切」+「喂给 AI 的输入」逐字节不变，AI 的随机输出不在保证范围内。

等价网分三层（全是硬门）：

产物	怎么测
PROJECT_SYMBOLS.md（纯结构）	直接 golden 逐字节 diff
README_AI.md 结构骨架	mock invoker（AI 描述→固定 stub）→ 整篇逐字节 diff
喂给 AI 的 prompt	snapshot prompt 字符串，前后逐字节 diff（防 #94-class 静默质量回归：GraphBuffer 改了喂给 AI 的 context → 结构骨架绿、AI 描述悄悄变差）

真实 AI 跑出的 README 不纳入等价门（预期变化）。

策略：strangler（GraphBuffer 寄生在老路径旁、对拍全绿才翻转），非 big-bang。

Fixture / 验证目标

语言优先级：Python + TS（其余 php/java/swift/objc/js 不纳入 #101 等价门，但必须不崩，留后续）。

• 合成 fixture：覆盖 error-node（scan-all --ai: enrichment prompt omits the dir’s own files/symbols → leaf dirs punt ("I need the file names"), cached as enrichment: ok #94/fix(parser): extend partial-parse recovery to all parsers (GH #95 fast-follow) #99 容错场景）、routes、嵌套目录、空目录
• self-host 对拍（最高信号）：
  • codeindex 自身（Python）
  • BlueHawkLock（TS monorepo，自带 error-node 分布）

性能预算

• 峰值内存（peak RSS）：≤ baseline 的 5×（上限/绊线，非目标；全局图驻留 RAM 是新增项，超 5× 说明构造有病态放大，需重想 GraphBuffer scope）
• parse 墙钟：宽松（design-philosophy：AI 占 99%，parse 非瓶颈），慢 10-20% 可接受；明显劣化才查

验收

• GraphBuffer + Pass 协议 + Pipeline（TDD，单模块闭环）
• PROJECT_SYMBOLS.md 逐字节不变（直接 golden）
• AI 冻结态下 README_AI.md 逐字节不变（mock invoker，Python + TS fixture）
• 喂给 AI 的 prompt 逐字节不变（snapshot，Python + TS fixture + self-host）
• self-host 对拍绿：codeindex 自身 + BlueHawkLock
• 其余 5 语言不崩（smoke）
• 全局调用图可从 GraphBuffer 查出（跨文件 CALLS 边）
• IndexMode.FAST 可跳过指定 pass
• 峰值内存 ≤ baseline 5×；parse 墙钟无明显劣化

关联

• ADR-007 docs/architecture/adr/007-codeindex-stateless-graph-ownership.md
• absorption-plan B1（N-pass pipeline）

[dreamlx]

Phase 0 完成 — characterization 网已织好（commit 81f664a，分支 feat/101-graphbuffer-ir，未 push）

「网下重构」的安全网就位，全绿。动 GraphBuffer 任何结构之前的可信基线。

三层硬门（tests/characterization/test_graphbuffer_baseline.py）

• ✅ PROJECT_SYMBOLS.md golden — 纯结构。含 broken.ts 的 error-node 恢复（before/after/Broken 在语法错误下全恢复，钉住 scan-all --ai: enrichment prompt omits the dir’s own files/symbols → leaf dirs punt ("I need the file names"), cached as enrichment: ok #94/fix(parser): extend partial-parse recovery to all parsers (GH #95 fast-follow) #99 容错）
• ✅ README_AI.md 结构 golden — AI 冻结（mock invoke_ai_cli → 固定 stub）
• ✅ 喂给 AI 的 prompt snapshot golden — 钉住 enrich prompt 的 subdir context + 符号摘要（防 scan-all --ai: enrichment prompt omits the dir’s own files/symbols → leaf dirs punt ("I need the file names"), cached as enrichment: ok #94-class 静默质量回归）

非确定性归一化：scan 根路径→<ROOT>、ISO 时间戳→<TS>（实测 4 处时间戳：navigation/detailed/overview generator + PROJECT_SYMBOLS）。regen：CODEINDEX_UPDATE_GOLDEN=1 pytest tests/characterization/...

fixture：Python（class/method/function/import/docstring + 嵌套）+ TS（generics queryRaw<T> + error-node + 嵌套）。

验证

• 新增 3 测试，全量 fast suite 1625 passed（原 1622 + 3）
• 重跑 3× 稳定无 flaky（修掉一个潜在 flake：root 的 Parent: 曾泄漏 pytest tmp 目录名 → 固定中间目录名 wsroot）
• ruff 干净

性能 baseline（5× 内存预算的靶子）

机器本地参考（非 CI 门，绝对值依赖环境）。target = codeindex 自身 src/（89 py 文件），结构态 scan-all --no-ai：

指标	baseline	5× 预算上限
peak RSS	~36.6 MB	≤ ~183 MB
wall (real)	~0.26s	parse 非瓶颈，宽松

repro：cp -R src/codeindex $TMP/codeindex + 最小 config → /usr/bin/time -l codeindex scan-all --root $TMP --no-ai --quiet。GraphBuffer 落地后在同机对比前后 peak RSS。

下一步（Phase 1）

GraphBuffer 寄生在老路径旁、对拍这张网；全绿才翻转 SmartWriter（strangler，非 big-bang）。self-host 对拍（codeindex 自身 + BlueHawkLock）在翻转前做。

[dreamlx]

Phase 1 complete — GraphBuffer IR + render seam (parasitic, unwired)

Commit 2e88966 on feat/101-graphbuffer-ir (not pushed).

Shipped (deliberately minimal):

• src/codeindex/graph_buffer.py — GraphBuffer (per-run map of DirNode) + render_directory(), the exact seam the eventual SmartWriter flip will call. DirNode mirrors write_readme's args (level, parse_results, child_dirs) → a lossless capture of the renderer's input.

Deliberately deferred (not built):

• Wiring into the production scan-all loop (the flip = Phase 2). Until the buffer is the renderer's source of truth, paying its RAM cost in production buys nothing.
• The global call/inheritance graph + write-once export substrate — gated on LoomGraph#30 per ADR-007.

Equivalence proof (run-both-diff): tests/characterization/test_graphbuffer_equivalence.py renders the char fixture two ways — production worker (parse → write_readme) vs record_directory → render_directory — and byte-diffs the README trees (timestamps normalised), walking get_processing_order() single-threaded to match parallel_workers: 1.

Mutation-checked (has teeth): dropping child_dirs in the adapter makes parent overview READMEs diverge (Files: 0) and the test fails → not a passthrough tautology.

Retention forward-indicator: buffering 46 parse_results / 345 symbols adds ~3 MB RSS — far under the Phase 0 5× budget (≤183 MB). Real multi-dir retention measured at the Phase 2 flip.

Gates: 1626 passed (+1), characterization net (4) green, ruff clean.

---

Phase 2 (the flip) is a behavior-change gate — paused here for review per the strangler plan (flip only when all goldens green; self-host 对拍 codeindex + BlueHawkLock before flip).

[dreamlx]

Spike #30 verdict landed — Phase 2 (2a flip) gating signal: 🟡 YELLOW → conditional GO

Spike LoomGraph#30 reached verdict YELLOW; cross-posted with field-level recommendations to codeindex#102. Direct implication for this issue's Phase 2 review:

The 2a flip's prerequisite — graph-export field set actually exercised

Phase 2's value depends on the eventual graph-export schema. Spike #30 measured WHICH fields the consumption agent actually leans on. Result:

Fields with GREEN backing (✅ flip is justified for these):

• entity (qualified name)
• entity_type
• source_id
• description
• CALLS edges (callers, callees) — Class A's 100% win driver
• Cross-entity search index

Fields blocked on metadata (⚠ flip needs care):

• 🆕 provenance_completeness — silent 0 callers on getattr/ABC dispatch is the most dangerous failure mode the spike found
• 🆕 resolution_qualifier — F-class showed analyze callers can't be distinguished across sibling classes

Reviewer's "is this flip justified" question — direct answer

Yes for the GREEN-confidence subset. The 2a flip exists to decouple render from the eventual export, and the export will固化 at least 4-6 fields with strong evidence. The flip protects those.

Don't flip ahead of the two new metadata fields — adding them later would require revisiting render order anyway.

Concrete proposal

1. Phase 2 lands with render scoped to GREEN-confidence subset only
2. provenance_completeness + resolution_qualifier added in a follow-on phase (call it Phase 2.1)
3. 2a render order considers Phase 2.1 fields when they exist; until then, render is decoupled from those specific fields

References

• LoomGraph#30 verdict comment — full per-class table + findings
• codeindex#102 field-level recommendation comment
• LoomGraph PR B5: CHANGELOG + RELEASE_NOTES_v0.25.0 — migration guide #52 — PLAN + REPORT + harness preserved in history
• REPORT.md: https://github.com/dreamlx/LoomGraph/blob/spike/issue-30-consumption-spike/docs/spikes/spike-30/REPORT.md

Scope: DeepSeek v4 flash, Haiku-class, Python single-fixture. Per G2, does not bind stronger-agent populations.

The 2a render flip is unblocked for the GREEN-confidence subset. Phase 2.1 (metadata fields) is the new gate on the wider schema固化.

[dreamlx]

2a flip 与 graph-export 解耦 —— spike 未 justify flip,flip 退回"可选内部 refactor"

#102 实现形态定为 Path A(独立 graph-export 命令)。直接影响本 issue 的 Phase 2 gating:

纠正上一条 comment 的耦合表述:graph-export 需要的是 buffer 被干净填充(独立命令里做),不需要 render flip。render order 跟 export 无关——export 不往 README 渲染任何东西,只 dump 独立 artifact。所以:

• YELLOW 解锁的是 feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102(export),不是 2a render-flip。 spike 没有给 flip 新增正当性。
• 2a flip 退回成 Phase 0 review 的结论:对 README 输出零功能变化的纯内部 refactor,唯一可拿来 justify 的是 DRY(buffer 填充后避免 double-parse)。但 Path A 下 scan-all 根本不填 buffer,连 double-parse 这个动机都不成立。
• 结论:2a flip 短期不做。 Phase 1 的 GraphBuffer + render_directory seam 继续休眠,零成本。将来若 scan-all 自身有别的理由要走 buffer,再单独按它自己的 merits 决定 flip。

Phase 1 成果(commit 2e88966,feat/101-graphbuffer-ir)保持原样,被 #102 的 graph-export 复用为 IR 容器。

[dreamlx]

Phase 0+1 shipped in v0.27.0 (PR #103); Phase 2 deferred — issue stays open

v0.27.0 is live on PyPI. What shipped under this issue:

• Phase 0 — characterization safety net (tests/characterization/test_graphbuffer_baseline.py).
• Phase 1 — GraphBuffer IR + render_directory() seam (src/codeindex/graph_buffer.py), dormant/unwired; render output byte-identical. Reused by graph-export (feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102) as the parsed-data container.

Deferred (why this issue stays open):

• Phase 2 — the 2a render-flip (make scan-all render from the buffer). Decoupled from graph-export: the LoomGraph#30 spike (🟡 YELLOW) justified the export (feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102), not the flip. The flip has zero user-facing change and its only motive (avoid double-parse) doesn't apply under feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102's standalone Path A. It remains an optional internal refactor, decided on its own merits when there's a concrete reason.

Closing condition for this issue: either do the flip when justified, or formally retire Phase 2 and close. Leaving open as the tracker for that decision.

[dreamlx]

Closing — Phase 2 (scan-all render-flip) 正式 retire

经评估，Phase 2 的 closing condition（本 issue 自己定的"做 flip 或 retire + close"）取 retire 路径。

理由：

1. GraphBuffer IR 的价值已通过 graph-export（feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102）实现。本 issue 的"解耦 parse/write + 可组合 pass"目标在 export 路径达成 —— graph-export 复用 GraphBuffer 作 parsed-data 容器（walk_and_parse 单次 parse 填 buffer → build_export 多 pass 投影）。近期 graph-export: emit IMPORTS edges (schema_version 1→2) #117（IMPORTS pass）就是"可组合 pass"的体现：加新 edge kind 没动 parser，只加一个遍历 buffer 的投影 pass。

2. scan-all render-flip 无 future driver（comment 4 已论证）：

   • graph-export 定为 Path A 独立命令 → flip 的唯一 motive（avoid double-parse）不成立（scan-all 不填 buffer）。
   • LoomGraph#30 YELLOW 解锁的是 feat(arch): write-once graph-export artifact — 与 loomgraph 的数据契约 #102（export），不 justify flip。
   • README 是 navigation index（ADR-005），不需 call graph → flip 不增功能。
   • 增量（design: 增量策略 — graph-export 加 content-hash,diff 归 loomgraph(schema v1 候选,门控) #110 content-hash）归 loomgraph（ADR-007 codeindex 无状态全量）→ 不驱动 scan-all buffer。
   • 至今无 concrete reason 让 scan-all 走 buffer。

成果保留（permanent value）：

• Phase 0 — tests/characterization/test_graphbuffer_baseline.py（3 层 golden：PROJECT_SYMBOLS 结构 / README_AI 结构 / AI prompt snapshot，防 scan-all --ai: enrichment prompt omits the dir’s own files/symbols → leaf dirs punt ("I need the file names"), cached as enrichment: ok #94-class 静默质量回归）。
• Phase 1 — src/codeindex/graph_buffer.py（GraphBuffer + render_directory seam，被 graph-export 复用为 IR 容器，零成本休眠）。

flip 若未来有 concrete reason（如 scan-all 要消费 export 数据进 README）→ 重开本 issue 或新 issue。 close ≠ 永不 flip，只是当前无 active 推进、无 driver，dormant tracker 该决断。