kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/synapse/SYMBOL_IDENTITY.md

@@ -0,0 +1,305 @@
+# Synapse Symbol Identity — Design Doc (TASK_2172)
+
+**Status**: DESIGN ONLY — no production code in this card. For user review before any implementation task is opened.
+
+**Origin**: TASK_2170 Phase 1 (measured 2026-10-02, rune `rune_695b41b3a4024c3dbd63cf745fc5f53d`) confirmed that a pure line-shift edit (no content change) degrades the TASK_2169 hash-diff fix to the exact magnitude of the pre-TASK_2169 bug: `STORAGE_INFO('Symbol').num_values` grows **256/round** for a file where only line numbers moved — identical to a forced full-file fallback, and 8x the ~32/round baseline for a same-line content edit. `synapse_pulse(generate_symbol_id)` rates changing this function **CRITICAL**: 122 impacted symbols, 93 community crossings.
+
+---
+
+## 1. Current identity scheme
+
+`generate_symbol_id(file_path, name, start_line)` — `dashboard/src-tauri/src/features/synapse/scanner.rs:1183-1198`:
+
+```rust
+pub fn generate_symbol_id(file_path: &str, name: &str, start_line: usize) -> String {
+    let digest = md5::compute(file_path.as_bytes());
+    let short_hash = &hex[..8];                // first 8 hex chars of md5(file_path)
+    let safe_name = /* non-alphanumeric -> '_' */;
+    format!("sym_{}_{}_{}", short_hash, safe_name, start_line)
+}
+```
+
+This string is the KuzuDB `Symbol` node's **primary key** (`s.id`). It embeds `start_line` directly, so any edit that shifts a symbol's `start_line` — even with byte-identical source — produces a *different* primary key. KuzuDB has no UPDATE-the-key or MOVE-node operation, so every shifted symbol must be deleted and reinserted, and KuzuDB never compacts tombstones (TASK_2166) — `num_values` only grows.
+
+### 1.1 Known identity-scheme defects already on record
+
+- **MD5 collision risk**: only the first 8 hex chars of `md5(file_path)` are used — two different file paths can produce the same prefix (rune `rune_0a75995f024f5f754137ce70e8686d71`, TASK_682).
+- **`safe_name` collapses distinct names**: non-alphanumeric chars all map to `_`, so `foo-bar` and `foo_bar` produce identical `safe_name` (same rune).
+- **Dual, incompatible ID namespaces already exist in the system.** The cognitive-memory layer (SQLite `runes` table, `sigil_members`) keys by a *different*, human-readable scheme: `symbol_stable_id = "{file_path}:{name}:{kind}"` (confirmed at `dashboard/src-tauri/src/features/synapse/memory/rune.rs:383-391`, query `WHERE symbol_stable_id = ?1`; construction confirmed in rune `rune_ca695c163f874f0282daa69363e71233`: `memory_harvest` reconstructs it as `f"{file_path}:{name}:{kind}"`). This is **not** the same string as `s.id` in KuzuDB.
+  - This mismatch is already a confirmed live bug, independent of line-shift: `scanner::insert_symbol` (`scanner.rs:1772-1790`) calls `mdb.get_runes_for_symbol(symbol_id)` at line 1783 — but the `symbol_id` passed in at every call site is the KuzuDB hash-based id (e.g. `scanner.rs:1753`, `index.rs:4185`), not a `symbol_stable_id`. Since `get_runes_for_symbol` queries `symbol_stable_id = ?1` (`memory/rune.rs:387-389`), this call **always returns zero rows** for every real symbol, so `semantic_tags::apply_rune_overrides` (`scanner.rs:1783-1789`) is dead code today. (TASK_1912's independently-forged sigil `sigil_f70a4685cafe4cf0b786782725b34924`, "Domain-Blind Comparison", documents the identical shape in `health.rs`'s ghost-check, which compared these two namespaces directly and wrongly rejected 6619/6964 runes until fixed.)
+  - **Implication for design**: a PK scheme that *adopts* the `symbol_stable_id` format (or a superset of it) fixes this dead-code path as a side effect, for free.
+
+---
+
+## 2. Consumer inventory (code evidence, file:line)
+
+Method used: `Grep` for `generate_symbol_id(`, `symbol_stable_id`, `sym_id`, `symbol_id` across `dashboard/src-tauri/src/features/synapse/**`, plus `synapse_recall`/`synapse_pulse` (MCP) for historical findings already measured by prior tasks. `synapse_pulse(generate_symbol_id)` itself could not be re-run live in this session (`KuzuDB ... is locked by another process`), so its CRITICAL/122/93 verdict is cited from TASK_2170's rune rather than re-measured.
+
+### 2.1 Graph writers that construct the PK directly
+
+| Call site | What it does |
+|---|---|
+| `scanner.rs:840` | Phase-1 symbol scan, per-symbol id for insert |
+| `scanner.rs:931,964` | Route / handler symbol ids (Tauri command routing) |
+| `scanner.rs:1029,1051,1101,1121` | Markdown/YAML doc + section symbol ids |
+| `scanner.rs:1209` (`find_class_symbol_id`) | Resolves a class's id for `MEMBER_OF` target |
+| `scanner.rs:1753` (`insert_file_level_symbol_if_bare`) | File-level bare symbol id |
+| `scanner.rs:2272,2293,2310,2411` | Phase-3 CALLS-edge resolution (caller/callee ids) |
+| `scanner.rs:2537,2577` | More Phase-3 CALLS resolution |
+| `scanner.rs:3807,3861` | Additional symbol-id construction (reindex path) |
+| `scanner.rs:4567,4646` | Doc symbol ids (second code path) |
+| `index.rs:3869,4149,4185,4219` | Layer-3 incremental insert / `rebuild_incoming_calls` callee id |
+| `index.rs:6867,6910,6955,6990,7042,7062,7166,7180,7197` | Full-reindex-path symbol + doc ids |
+| `delta_graph.rs:684` (`map_changed_symbols_to_kuzu`) | **Fallback** id when a tree-sitter-detected changed symbol has no KuzuDB match yet |
+| `dataflows.rs:787` | DATA_FLOWS edge endpoint id |
+| `cross_boundary.rs:577,585,617,625,669` | `find_caller_symbol_id` / `find_rust_command_symbol_id` / `find_enclosing_symbol_id` — reconstruct a callee/caller's PK from `(name, start_line)` captured separately, to wire `INVOKES_COMMAND` edges across the Rust/TS boundary |
+
+### 2.2 Edges that reference the PK as foreign key
+
+- `CREATE (f)-[:DEFINES]->(s)` — `scanner.rs:2030`, matched by `s.id`
+- `CREATE (m)-[:MEMBER_OF]->(c)` — `scanner.rs:2045-2049`, both endpoints matched by `.id`
+- `CALLS` edges — `scanner.rs:3133,3155,4055`; `index.rs:4102,4154` (`rebuild_incoming_calls`)
+- `EXPORTS` — `scanner.rs:5330`
+- Delete-by-id for every edge type — `index.rs:4011-4070` (`delete_symbols_by_ids`, see §2.5)
+
+### 2.3 FTS and embeddings (both keyed by the raw PK string, not a parsed/structured id)
+
+- `search.rs:695-715` `SearchIndex::insert_symbol` → `symbol_search.symbol_id` (FTS5 table)
+- `search.rs:718-749` `SearchIndex::upsert_symbol_embedding` → `symbol_embeddings.symbol_id` (ONNX embedding blob)
+- Both are called with the same `sym_id` string produced by `generate_symbol_id` (e.g. `scanner.rs:1753→1757`), so every line-shift delete+reinsert of a `Symbol` node also orphans its old FTS row and embedding row (`INSERT OR REPLACE` on the new id leaves the old row as dead weight — same per-row tombstone-growth problem, just in SQLite rather than KuzuDB, and without even a dedup key to collapse it since `symbol_id` is the old value).
+
+### 2.4 Heat / co-change / curiosity (Norn — time-awareness subsystem)
+
+- `delta_graph.rs:644-696` (`map_changed_symbols_to_kuzu`): matches modified tree-sitter symbols against KuzuDB **by `(file_path, name, kind)`**, not by id — but when no match is found (new symbol, or a KuzuDB symbol the lookup missed), it falls back to `generate_symbol_id` at **line 684**, producing a line-embedded id.
+- `delta_graph.rs:770` (`bridge_symbols_to_heat` → `engine.record_edit(&sym.symbol_id, ts)`): Heat (`heat.rs:322-361`, keyed `HashMap<symbol_id, HeatScore>`) is fed `ModifiedSymbol.symbol_id`, i.e. whatever `map_changed_symbols_to_kuzu` resolved — the **existing KuzuDB `s.id`** in the common case, so Heat *is* keyed by the line-embedded id today; every line-shift fragments a symbol's edit-heat history into a "new" key, even though `map_changed_symbols_to_kuzu`'s own doc comment (`delta_graph.rs:642-643`) says it "handles cases where start_line may have shifted" — it only handles that for *matching*, not for the id it emits downstream.
+- `delta_graph.rs:160-172` (`process_commit`, Step 5): the same `symbol_id` is persisted into SQLite `delta_symbols` (co-change + curiosity's substrate) via `insert_delta_symbols`.
+- `delta_graph.rs:176-177`: `curiosity::verify_predictions(project_path, &symbol_ids)` is keyed off the same ids.
+- **Cross-check against `co_change.rs`**: that module's own doc comments and tests (`co_change.rs:291-299,366-423`) assume `delta_symbols.symbol_id` is a human-readable `"file::name"` string — this is *not* what `process_commit` actually writes (it writes the KuzuDB hash id). This is a second, independent instance of the "two ID formats assumed interchangeable" shape, orthogonal to the line-shift bug, and not something this card verifies further — **TASK_2171 is changing Heat/co-change keys in parallel; this section describes the pre-2171 state measured in this session as the baseline for that task, not a target to fix here.**
+
+### 2.5 Delete/reinsert mechanics (the churn mechanism itself)
+
+- `index.rs:7976-8028` (`compute_names_to_delete_with_locations`): computes `shifted_symbols` by comparing each current symbol's `start_line` against `old_line_by_name` (captured before the edit) — any symbol whose line moved, even with unchanged content, is added to both the delete list and the reinsert list. **This is the direct cause of the churn**, independent of `compute_changed_symbols_by_hash` (TASK_2169's content-hash fix only changes which symbols are flagged "changed" — it does not and cannot address symbols that are merely *shifted*).
+- `index.rs:4011-4070` (`delete_symbols_by_ids`): deletes a specific `(file_path, name, start_line)` node — this is the TASK_2169 fix for the *previous* bug (bare-name delete collaterally killing same-name siblings, rune `rune_9187d9f044184ca8b28314af930e5354`, TASK_1624) and the TASK_2169 `DETACH DELETE` fix (comment at `index.rs:4050-4067`) for duplicate-PK errors on reinsert. Both fixes are necessary *only because* the PK embeds `start_line` — a line-independent PK would make the "shifted" category empty and most of this machinery dead.
+- `index.rs:4134-4165` (`rebuild_incoming_calls`): explicitly exists to "rebuild incoming CALLS edges that were lost when old callee symbol nodes were deleted" (doc comment, `index.rs:4129-4131`) — it re-derives the callee's **new** PK from the **new** `start_line` after a shift, to recreate edges destroyed by the delete. This compensating code is PK-identity debt made visible: under a line-independent PK, a shift would never delete the node, so this function would have nothing to rebuild.
+
+### 2.6 Pulse / impact / community (NOT structurally coupled to the line-based format)
+
+- `community_detector.rs:195,229,369,391,1223,1520,1546,2018`, `pulse_propagation.rs:1177` all treat `s.id` as an **opaque foreign key** — they never parse it, split it, or assume a format. They are unaffected by *which* scheme is chosen.
+- They are, however, part of the **blast radius of the migration event**: a full reindex (§4) regenerates every `s.id`, so `BELONGS_TO` (community membership) and any cached id-keyed state must be recomputed afterward — this is the structural source of the "93 community crossings" figure in TASK_2170's `synapse_pulse` measurement (wide fan-out of symbols whose id would change, not a parsing dependency on the id's internal structure).
+
+### 2.7 Collision cases
+
+| Case | Current scheme (`file:hash_name_line`) | Risk under a line-independent scheme |
+|---|---|---|
+| **Two functions, same name, different files** | No collision — `md5(file_path)` differs. | No collision if file_path stays in the key. |
+| **Overloaded / same-name methods on different classes, same file** (e.g. `impl A { fn new }` / `impl B { fn new }`, TASK_1624's exact case) | No collision today (`start_line` differs). `Symbol.qualified_name` (`symbols.rs:98`, populated e.g. `symbols.rs:317-321` as `"{parent_class}.{name}"`) **already disambiguates this case** when used, but today's PK and today's (pre-TASK_2169) delete-by-name logic did not use it — that was the root cause of TASK_1624's sibling-loss ghosts. | **No collision** if the new scheme uses `qualified_name` (not bare `name`): `A.new` ≠ `B.new`. |
+| **Same method name, same class, two impl blocks for different traits** (Rust: `impl Trait1 for X { fn foo }` / `impl Trait2 for X { fn foo }`) | No collision (`start_line` differs). | **Real collision** — `qualified_name` is `X.foo` for both; `kind` is `method` for both. Needs an ordinal or trait-qualified name. |
+| **TS/JS function-overload declarations** (`function f(x: string): void; function f(x: number): void; function f(x: any) { ... }`) | No collision (lines differ); only the implementation signature has a body, tree-sitter extraction behavior for the declaration-only signatures needs checking separately. | Same file/name/kind — needs ordinal if declarations are extracted as separate symbols. |
+| **Nested functions / closures with the same name in different enclosing scopes** (not a class — e.g. two sibling top-level functions each defining a local helper named `helper`) | No collision (`start_line` differs). | `qualified_name` only captures `parent_class` (`symbols.rs:92,98`), **not enclosing function** — two nested `helper`s under different top-level functions would both produce bare `qualified_name = "helper"` → **real collision**, needs either enclosing-function context added to `qualified_name` or an ordinal fallback. |
+| **Generated/templated code** (macro-expanded impls, generated bindings repeating the same symbol name per file) | No collision (distinct `start_line` per expansion site, assuming tree-sitter sees expanded text — unverified for Rust macros that are *not* textually expanded before parsing, i.e. `macro_rules!`-produced items tree-sitter cannot see at all; out of scope — those items are already invisible to Synapse today, independent of PK scheme). | Same risk profile as nested closures — needs ordinal. |
+| **MD5 8-hex-char path collision** (existing defect, `rune_0a75995f`) | Possible, unaddressed today. | Any design keeping `md5(file_path)[..8]` in the key inherits this; **both candidates below drop it** in favor of the literal `file_path` string, which removes this defect as a side effect. |
+
+---
+
+## 3. Candidate designs
+
+Both candidates **keep `start_line`/`end_line` as ordinary mutable *properties* of the `Symbol` node** (needed by UI, blame, pulse context, etc.) — they only remove it from the **primary key**.
+
+### Candidate A — `file_path:qualified_name:kind[:ordinal]`
+
+```
+id = format!("{}:{}:{}", file_path, qualified_name, kind)
+   + if a same-(file,qualified_name,kind) symbol already exists in this file's current parse: append ":" + ordinal (0, 1, 2, ... in source order)
+```
+
+- Builds directly on `Symbol.qualified_name` (`symbols.rs:98`), which is already computed by every language extractor (confirmed for Python, same pattern used for other languages per `symbols.rs:650-672` etc.) and already closer to line-independence than today's PK.
+- This is effectively the same shape as the already-line-independent cognitive-memory `symbol_stable_id` format (`file_path:name:kind`, `memory/rune.rs:387`) **upgraded to use `qualified_name` instead of bare `name`** — adopting it as the graph PK closes the dead-code gap in §1.1 for free, since `get_runes_for_symbol` would now receive a real match.
+- **Collision handling**: the ordinal only fires for the genuine collision cases in §2.7 (same qualified_name+kind+file, which is rare); the overwhelming majority of symbols get a clean, human-readable, line-independent id with zero ordinal suffix.
+- **Pros**: human-readable (debuggable directly from `synapse_cypher` output); closes the rune/graph namespace gap (§1.1); smallest conceptual jump from today's scheme (same inputs, minus `start_line`, plus `qualified_name` instead of `name`); `file_path` is already escaped for Cypher everywhere (`scanner::escape_cypher`), so no new escaping surface.
+- **Cons**: ordinal assignment is **order-dependent** — if tree-sitter's traversal order for two colliding symbols is not stable across runs (e.g. for macro-expanded or minified/generated code with no stable source order), the ordinal could flip between reindexes, causing spurious churn for exactly the pathological cases it exists to handle. Needs a stable tie-breaker (e.g. ordinal by `start_line` *value* at insert time, not traversal order — still fully determined by file content, not line *position* relative to other edits elsewhere in the file).
+- **Removes line-shift churn**: yes — a pure line-shift (no name/kind/qualified_name change) now produces the *same* id, so Layer 3's shifted-symbol path (`index.rs:7990-7998`) finds nothing to delete for shifted symbols; only `start_line`/`end_line` properties get updated in place (`SET s.start_line = ..., s.end_line = ...`, a property update, not a delete+reinsert).
+
+### Candidate B — content-anchored id
+
+```
+id = format!("{}:{}", file_path, blake3_or_sha256(normalized_symbol_source)[..N])
+```
+
+where `normalized_symbol_source` is the symbol's own source text (already captured in `Symbol.source`, `symbols.rs`) with insignificant whitespace/line-ending normalized, and the hash truncated to N hex chars (longer than today's 8, to control collision probability now that collisions are the *only* uniqueness signal within a file).
+
+- **Pros**: genuinely immune to both line-shift *and* pure renames-that-preserve-everything-else is not true — a rename changes `source` too, so this id changes on rename (arguably correct: a renamed symbol *is* a different thing cognition-wise, vs. a moved one which is not). Immune to the `qualified_name` nested-closure gap in §2.7 — two structurally-different `helper` closures with different bodies get different hashes automatically, no ordinal logic needed.
+- **Cons**: (1) **Any content edit — not just a move — changes the id**, including the hash-diff edits TASK_2169 specifically optimized for; this would make TASK_2169's "same symbol, new content_hash, in-place content update" case collide with "this is a structurally different symbol" at the identity layer, since both look identical from the PK's perspective: old id gone, new id appears. This likely *reintroduces* the churn TASK_2169 just fixed, for the common case of editing a function body (every edit becomes a delete+reinsert, same as the original Layer-2 bug) — a serious regression risk that needs explicit measurement before this candidate is considered. (2) Whitespace-only/formatting-only edits (prettier/rustfmt re-runs) would also change the id unless normalization is very aggressive, which itself risks false-negative identity (two genuinely different symbols hashing the same after over-normalization). (3) Loses human-readability entirely — `synapse_cypher` output and `log` lines become opaque hashes, a debuggability regression from today. (4) Does not by itself close the §1.1 rune/graph namespace gap (still two different formats) unless additionally paired with a `symbol_stable_id`-shaped lookup key kept as a *secondary* index — which duplicates most of Candidate A's design anyway.
+- **Verdict going in**: Candidate B trades the line-shift problem for very likely reintroducing the content-edit problem TASK_2169 already solved, unless scoped much more narrowly (e.g. hash over *signature* only, not full body — but then two overloads/distinct bodies with identical signatures collide, back to needing an ordinal, i.e. converges toward Candidate A anyway). Listed for completeness per the task's "at least 2 candidates" requirement, but not recommended without a dedicated measurement task of its own.
+
+### 3.1 On `symbol_stable_id` as-is (the Technical Notes question)
+
+> "Rune `symbol_stable_id` (`file:name:kind`) is already line-independent — say whether it can become the PK."
+
+**Not as-is.** `symbol_stable_id` uses bare `name`, not `qualified_name` — it does not disambiguate the TASK_1624 case (`A.new` vs `B.new` both stored as `new`, same `file:name:kind` = `file.rs:new:method`), which is a **real, already-measured collision case** (not hypothetical). Candidate A is `symbol_stable_id`'s design upgraded with `qualified_name` + an ordinal escape valve, specifically to fix this. Recommend: evolve `symbol_stable_id` to match Candidate A's format (same migration, one less format in the system) rather than adopting the current `symbol_stable_id` definition verbatim.
+
+---
+
+## 4. Migration plan
+
+### 4.1 Mechanism: `INDEX_FEATURE_VERSION` bump (not in-place)
+
+`INDEX_FEATURE_VERSION: u32 = 13` (`index.rs:275`) is the existing, battle-tested mechanism for "the on-disk graph's shape changed, wipe and rebuild": `state.index_feature_version < INDEX_FEATURE_VERSION` is checked at `index.rs:1612`, `index.rs:2413`, and `index.rs:8445` (test), and a mismatch forces `run_full_index` (full wipe-and-rebuild) rather than the incremental path. TASK_2169 itself bumped this (comment at `index.rs:8032-8034`: "INDEX_FEATURE_VERSION must be 13").
+
+**Recommendation: bump to 14, full reindex, not an in-place migration.** Rationale:
+- Every single consumer in §2.1-§2.5 constructs or consumes the PK string directly; there is no single choke point to intercept and rewrite ids in place without touching the same surface area as a full reindex would.
+- An in-place "rename all `Symbol.id` values" migration would itself have to delete+reinsert (or at minimum `SET`) every node — i.e. it *is* a full reindex's worth of graph writes, just hand-rolled and unvalidated against the existing `run_full_index` path's edge cases (phantom reconciliation, community detection, FTS/embedding sync). Reusing `run_full_index` is strictly less risky.
+- `.synapse/db/graph` tombstone bloat (TASK_2166) means the existing graph likely already carries churn debt; a full rebuild also resets `num_values` to its true floor, which is a desirable side-effect this migration should capture while it's already paying the cost of a full reindex.
+
+### 4.2 Rollback
+
+- `INDEX_FEATURE_VERSION` is monotonic — rolling back the *binary* to a pre-migration build naturally triggers another full reindex back to the old scheme (`index_feature_version` in `index_state.json` would be 14, binary expects 13 → mismatch → full reindex), which is safe but double-pays the reindex cost.
+- No data-loss risk from rollback: KuzuDB `Symbol` nodes carry no external references outside this project's own `.synapse/` directory that aren't also rebuilt by a full reindex (FTS, embeddings, community, Heat/co-change keys — all rebuilt or re-bridged by the same full-index pass, modulo the TASK_2171 coordination note in §2.4).
+- Runes/sigils (`memory.db`) are **not** touched by a KuzuDB full reindex — they live in a separate SQLite file and are keyed by `symbol_stable_id`, which (per §3.1's recommendation) would now *finally* match the graph scheme. If Candidate A is adopted, no rune migration is needed (symbol_stable_id already excludes `start_line`); confirmed in TASK_2170's rune: "an identity-scheme change would NOT require a rune/symbol_stable_id migration."
+
+### 4.3 Estimated implementation card size
+
+Splitting into dedicated cards, each independently testable:
+
+1. **PK scheme change itself** (`generate_symbol_id` → new signature/logic, `symbols::Symbol::qualified_name` already exists so mostly plumbing) + `INDEX_FEATURE_VERSION` bump — touches scanner.rs, index.rs call sites (§2.1), cross_boundary.rs resolvers (§2.1) which must be updated to reconstruct the *new* key shape. **Medium** (~1 focused card; the hard part is updating every call site consistently, not inventing the scheme).
+2. **Layer-3 shifted-symbol path simplification**: once the PK is line-independent, `compute_names_to_delete_with_locations`'s shifted-symbol branch (`index.rs:7990-7998`) and `rebuild_incoming_calls` (`index.rs:4134-4165`) become dead/near-dead code for the pure-shift case and should be simplified to a property-only `SET start_line/end_line` path. **Small**, but should be its own card so it can be measured (probe: line-shift arm should now show the same ~32/round as a same-line edit, not 256/round) independently of card 1 landing correctly.
+3. **TASK_2171 coordination**: whichever of Heat/co-change lands second must re-derive its symbol keys against the *other* task's output — flagged as a dependency, not estimated here since TASK_2171's own scope is out of this card's investigation per the Ansuz addendum.
+4. **Ordinal collision test fixtures** (§2.7 cases): small, can ride in card 1 as acceptance tests rather than a separate card.
+
+---
+
+## 5. Test plan
+
+### 5.1 Positive probe (must show the fix works)
+
+Extend `index_task_2169_probes.rs` (already has `line_add`/`line_remove` arms, `t2169_storage_info_max_num_values` reading `STORAGE_INFO('Symbol')`, both via `task_2170_driver`) with a **post-migration arm** run against the new PK scheme:
+
+- **Acceptance criterion (from the task card)**: the line-shift probe (`line_add`/`line_remove` arms, same 8-symbol fixture TASK_2169/2170 used) must show **~+32/round**, matching the existing same-line-edit baseline — not ~+256/round.
+- Keep the exact fixture and both arms (`t2170_file_content_line_add`, `t2170_file_content_line_remove`) unchanged so the before/after comparison is apples-to-apples against the already-recorded TASK_2170 numbers.
+
+### 5.2 Negative controls (must NOT silently pass)
+
+- **Control 1 — genuine rename still churns.** A probe arm that renames a symbol (changes `name`/`qualified_name`, same file, same line) must still show the *old* id deleted and a *new* id inserted (expected churn — this is a real identity change, not a false positive the new scheme should hide). If this control shows ~32/round (no churn), the new scheme is wrongly treating a rename as identity-preserving — a bug, not a feature.
+- **Control 2 — genuine collision triggers the ordinal path (Candidate A only).** A fixture with two methods of the same name/kind/qualified_name in one file (the TASK_1624 shape, or an explicit duplicate-name fixture) must index without a "duplicate primary key" error and must produce two distinct ids differing only by ordinal. Negative check: assert the ordinal is **not** sensitive to tree-sitter traversal order by reindexing the same unchanged file twice and diffing the two symbols' ids — they must be identical both times (stability check from §3's Candidate A "Cons").
+- **Control 3 — content-hash edit (TASK_2169's own case) still shows ~32/round, not more.** Re-run TASK_2169's original "fixed" arm (same-line content edit, no shift) against the new scheme to confirm the PK change did not regress the already-fixed case.
+- **Control 4 (Candidate B only, if pursued later) — body edit without rename must NOT churn like a full-file fallback.** Given §3's regression risk, this is the single most important number before Candidate B could be taken seriously: edit a function body only (same name/line/signature) and confirm `num_values` growth stays at ~32/round, not ~256/round. This candidate should not be scheduled for implementation until this number exists.
+
+### 5.3 Non-functional checks
+
+- `node dev/scripts/check-file-size.js --staged` on any touched file (ARCH-001 budget) — `scanner.rs` and `index.rs` are both already large; prefer extraction over further growth when implementing.
+- Rune round-trip: after migration, re-run `get_runes_for_symbol` (`memory/rune.rs:383`) against a symbol with an existing rune and confirm it now returns that rune (regression test for the §1.1 dead-code fix becoming live — a *new* behavior that should be asserted, not just a non-regression).
+
+---
+
+## 6. Recommendation
+
+**Adopt Candidate A** (`file_path:qualified_name:kind[:ordinal]`), implemented as an `INDEX_FEATURE_VERSION` bump (full reindex), split per §4.3.
+
+**Go/no-go criterion**: go if, after implementing card 1 (§4.3) in a throwaway branch, the TASK_2169/2170 probe fixture's `line_add`/`line_remove` arms measure **≤ ~40/round** (allowing some slack above the exact 32/round same-line baseline for ordinal bookkeeping overhead) **and** Control 1 (rename) still shows churn **and** Control 2 (collision) indexes without a duplicate-PK error with stable ordinals across two consecutive reindexes of an unchanged file. No-go (reopen design) if any of: line-shift churn is not reduced below ~100/round (fix didn't work), rename stops churning (false-positive identity stability — a correctness bug), or ordinals are unstable across reindexes (nondeterminism bug).
+
+Candidate B is not recommended for implementation without its own dedicated measurement card (Control 4 above) proving it does not reintroduce TASK_2169's already-fixed content-edit churn — the a priori risk analysis in §3 suggests it likely will.
+
+---
+
+## Open coordination notes
+
+- **TASK_2171** is modifying Heat/co-change key derivation in parallel (per Ansuz addendum to this card). §2.4 describes the state measured in this session as the pre-2171 baseline; this design does not edit `heat.rs` or `co_change.rs`, and whichever card lands second should re-verify §2.4's id assumptions against the other's actual landed state before implementation card 1 (§4.3) touches `delta_graph.rs:684`'s fallback id generation.
+- `generate_symbol_id`'s MD5-collision and `safe_name`-collapse defects (§1.1, `rune_0a75995f024f5f754137ce70e8686d71`) are resolved as a side effect by both candidates (neither keeps `md5(file_path)[..8]`), but are not separately re-verified in this doc — worth a one-line regression test in card 1.
+
+---
+
+## 7. TASK_2178 — persisted-store migration (runes / sigil_members / Heat / co_change)
+
+Card 1 (TASK_2177, merged `b3d9fb4de`) landed Candidate A as the live KuzuDB
+`Symbol.id`. It did **not** touch any already-persisted store that was keyed
+by the OLD `symbol_stable_id` format (`file_path:name:kind`, bare `name` —
+`memory/rune.rs:383-391`, used by `runes`, `sigil_members`, and — since
+TASK_2171's partial landing — `delta_symbols`/Heat's `heat_cache.json`).
+TASK_2178 is that migration.
+
+**Code**: `dashboard/src-tauri/src/features/synapse/stable_id_migration.rs`
+(orchestrator `run_candidate_a_migration`, map builder
+`build_old_stable_to_candidate_a_map`, outcome classifier `classify_old_key`)
++ `heat::migrate_cache_keys_candidate_a`. Supersedes TASK_2171's draft
+migration in the same file (that draft mapped the OLD line-based graph PK to
+the OLD `symbol_stable_id` format; its live run was never executed, and it
+can no longer run as originally written — the live graph has since been
+fully reindexed to Candidate A, so no node carries a `sym_`-shaped id to
+resolve against anymore. Any still-`sym_`-shaped persisted key is now
+permanently unresolvable — reported as `Orphaned`, the same bounded-loss
+category TASK_2171 itself already accepted for deleted/renamed symbols).
+
+**Algorithm**: build one map from the live graph — for every `Symbol` node,
+one entry under its bare `(file_path, name, kind)` group key, one entry
+under its own real id (self-entry). Classify each stored key against that
+map:
+
+| Lookup result | Outcome | Action |
+|---|---|---|
+| Key not found | `Orphaned` | leave untouched (deleted/renamed symbol, or predates both scheme changes) |
+| Found, candidate set contains the key itself | `AlreadyCurrent` | leave untouched (no-op; also how idempotent re-runs behave, and how a rune already correctly anchored to e.g. `A.new` stays on `A.new` even though the bare-name group `new` is ambiguous) |
+| Found, exactly one candidate | `Migrate` | rewrite to that candidate |
+| Found, 2+ candidates | `Ambiguous` | leave untouched, list in the ambiguity report (the TASK_1624 shape: `A.new`/`B.new` both stored as `file.rs:new:method`) |
+
+**Stores touched**: `runes.symbol_stable_id`, `sigil_members.symbol_stable_id`
+(same id namespace, same table family — migrated for consistency even though
+not explicitly named in the TASK_2178 card, to avoid reintroducing the exact
+dead-code-by-format-mismatch shape §1.1 describes), `delta_symbols.symbol_id`
+(backs Heat's history AND the co_change matrix, which is derived from this
+table at query time, per `co_change.rs`'s own doc comments — no separate
+persisted co_change table exists), `heat_cache.json`'s `scores`/`baselines`
+maps. **Not** touched (same id namespace, lower priority, out of this card's
+explicit scope): `access_log.symbol_stable_id`, `proposed_tagged_with.symbol_stable_id`,
+`investigation_log.symbol_id` (curiosity.rs) — all pure history/log tables,
+not on the "runes resolve again" critical path; a follow-up card can extend
+`run_candidate_a_migration` to cover them with the same helpers.
+
+**Runtime fix (not just the migration tool)**: two call sites recomputed an
+OLD-format bare-name key at READ time instead of using the real id already
+in hand, which would have kept rune resolution broken for every
+qualified/collision symbol even after the stores were migrated:
+
+- `harvester.rs::memory_harvest` — now uses `ActivatedSymbol.id` (the real
+  live graph id) directly instead of recomputing via `scanner::symbol_stable_id`.
+  This is the code synapse_recall/pulse use to look up a rune for an
+  activated symbol — the `graph_context` caller-count/community lookup in
+  `mcp_tools/synapse/memory.rs` (lines ~1283-1365) already keyed purely off
+  the rune's OWN `symbol_stable_id` field and the graph's real `s.id` (never
+  recomputed anything), so once the stored rune rows are migrated, its
+  "always null for methods" dead path starts resolving for free.
+- `delta_graph.rs::map_changed_symbols_to_kuzu` / `query_symbols_by_names` /
+  `map_files_to_symbols` — `ModifiedSymbol.stable_id` now carries the same
+  value as `symbol_id` (the real graph id) instead of a separately-derived
+  bare-name key. Since Candidate A no longer embeds `start_line`, there is
+  nothing left for a separate "stable" id to buy — the graph PK IS the
+  stable id now. This is the "Heat/co-change helper from TASK_2171 switches
+  to it" requirement.
+- `scanner.rs::insert_symbol`'s `get_runes_for_symbol(symbol_id)` call
+  (§1.1's dead code) needed **no change** — every call site already passes
+  the real Candidate A id computed by `generate_symbol_ids`/`generate_symbol_id`;
+  it was dead only because the stored rune data was in the wrong format. Same
+  for `activation.rs::resolve_symbol_ids` — unreferenced anywhere in the
+  codebase (confirmed via grep), so left untouched; its name-only matching
+  logic would mis-parse an ordinal-suffixed Candidate A id if ever wired up,
+  flagged here for whoever eventually calls it.
+
+**Known pre-existing, out-of-scope gaps** (not introduced by, and not fixed
+by, TASK_2178 — noted for whoever picks them up): `co_change.rs::find_symbol_ids_by_name`'s
+`%:{name}:%` LIKE pattern only matches when `qualified_name == name` (bare,
+unqualified symbols); `scanner::parse_symbol_stable_id`'s `rsplitn(3, ':')`
+mis-splits an ordinal-suffixed 4-segment Candidate A id (treats the ordinal
+as `kind` and the real kind as `name`) — used by `symbol_name_from_any_id`,
+a display-only fallback.
+
+**How to run**: dry-run (default, writes nothing) or live, against a real
+project:
+
+```text
+KENAZ_PROJECT_PATH=/path/to/project KENAZ_MIGRATION_DRY_RUN=1 \
+  cargo test -p kenaz-dashboard run_candidate_a_migration_live -- --ignored --nocapture
+```
+
+Set `KENAZ_MIGRATION_DRY_RUN=0` for the live run — only after reviewing the
+dry-run report, and only when nothing holds the KuzuDB read lock (an active
+`tauri dev` / dashboard indexing session will block it). The live run backs
+up `memory.db` to `memory.db.pre_2178_bak` and `heat_cache.json` to
+`heat_cache.json.pre_2178_bak` (each exactly once) before writing.

package/core/dev/spikes/A4-cypher-varlen.md

@@ -0,0 +1,176 @@
+# Spike A4 — KuzuDB Cypher Variable-Length Pattern vs. Hand-Rolled BFS
+
+**Task**: TASK_1287  
+**Date**: 2026-04-19  
+**Scope**: `status.rs::impact_analysis_inner`, `imagination.rs::imagine`
+
+---
+
+## Hypothesis
+
+Replacing the hand-rolled BFS in `impact_analysis_inner` (status.rs) with a single Cypher
+variable-length path query (`-[:CALLS|IMPLEMENTS|DATA_FLOWS*1..N]->`) would reduce latency
+and code complexity for the `synapse_impact` MCP tool.
+
+---
+
+## Method
+
+### BFS (existing)
+- `impact_analysis_inner` (status.rs:972): depth-loop, frontier chunks of 200
+- 10 Cypher queries per chunk (CALLS/IMPLEMENTS/DATA_FLOWS/EXTENDS/LINKS_TO, both directions)
+- Per-symbol N+1 enrichment: `query_symbol_community_and_insulation` + `query_symbol_process`
+- Budget: `max_work=500`; per-depth split 20%/80% (d2) or 20%/40%/40% (d3)
+
+### Cypher var-len (prototype)
+- Single `MATCH (s)-[:CALLS|IMPLEMENTS|DATA_FLOWS*1..N]->(t)` query via `synapse_cypher` MCP
+- Outward traversal only; no EXTENDS/LINKS_TO; no reverse (callers) direction
+- N+1 enrichment still required in Rust after result retrieval
+- Measured via MCP round-trip (includes network overhead; proxy for query execution time)
+
+### Benchmark symbols (10 representative)
+Selected to span CRITICAL/HIGH/MEDIUM fan-out, both high in-degree and high out-degree:
+
+| # | Symbol | Fan-out Category |
+|---|--------|-----------------|
+| 1 | hybrid_search | CRITICAL out |
+| 2 | walk_dir | CRITICAL out |
+| 3 | run_incremental_index | CRITICAL out |
+| 4 | postComplete | CRITICAL out |
+| 5 | push | HIGH in |
+| 6 | cn | HIGH in |
+| 7 | buildAssembledPrompt | MEDIUM out |
+| 8 | scan_project | MEDIUM out |
+| 9 | gitBranchAndMerge | MEDIUM out |
+| 10 | resolve_phase4 | HIGH out |
+
+---
+
+## Benchmarks
+
+> (T) = truncated at max_work=500. Cypher counts are unbounded (no budget cap).
+> BFS latency = synapse_impact MCP round-trip. Cypher latency = synapse_cypher MCP round-trip.
+
+### Result-Set Counts
+
+| # | Symbol | BFS d2 | BFS d3 | Cypher d2 | Cypher d3 |
+|---|--------|--------|--------|-----------|-----------|
+| 1 | hybrid_search | 257 (T) | 217 (T) | 150 | 357 |
+| 2 | walk_dir | 430 (T) | 230 (T) | 187 | 435 |
+| 3 | run_incremental_index | 418 (T) | 218 (T) | 160 | 383 |
+| 4 | postComplete | 439 (T) | 239 (T) | 66 | 88 |
+| 5 | push | 60 | 100 (T) | 2 | 2 |
+| 6 | cn | 100 | 100 | 0 | 0 |
+| 7 | buildAssembledPrompt | 411 (T) | 211 (T) | 18 | 37 |
+| 8 | scan_project | 352 | 213 (T) | 48 | 221 |
+| 9 | gitBranchAndMerge | 121 | 321 (T) | 38 | 52 |
+| 10 | resolve_phase4 | 411 (T) | 211 (T) | 376 | 148 |
+
+### Result-Set Divergence Analysis
+
+Across all 10 symbols at d2: Cypher returns 16%–85% fewer results than BFS (except resolve_phase4
+where Cypher d2 ≈ BFS d2). The divergence is structural, not a bug:
+
+1. **Direction asymmetry**: BFS traverses both inward (callers) and outward (callees); Cypher
+   var-len is outward-only. Symbols with many callers (e.g., `cn`, `push`) appear in BFS but
+   not in Cypher d2.
+
+2. **Edge-type gap**: BFS covers 5 edge types (CALLS + IMPLEMENTS + DATA_FLOWS + EXTENDS +
+   LINKS_TO); Cypher covers 3 (CALLS|IMPLEMENTS|DATA_FLOWS). EXTENDS and LINKS_TO relationships
+   are invisible to the Cypher query.
+
+3. **Budget semantics**: BFS truncates at max_work=500; Cypher is unbounded. At d3, Cypher can
+   exceed BFS for high fan-out symbols (walk_dir: Cypher 435 vs BFS 230 truncated).
+
+### Latency Notes
+
+MCP round-trip is dominated by Rust serialization and IPC overhead, not query execution.
+The true differential cannot be isolated from available tooling without compilation. However:
+
+- **N+1 dominance**: The per-symbol community+process enrichment queries (2 per visited symbol)
+  are the dominant cost. At BFS d2 with 400 symbols, this is ~800 additional Cypher queries.
+  Switching traversal to a var-len pattern does NOT eliminate these N+1 queries — they still
+  execute in Rust after the result set is returned.
+
+- **Cypher query planner overhead**: KuzuDB variable-length patterns must enumerate all paths up
+  to depth N. At depth 3 with 400+ reachable nodes, this is significantly more work than the
+  BFS chunked approach (which short-circuits at budget).
+
+- **Cache layer**: `impact_analysis` checks `hot_path_cache` in search.sqlite before BFS. A
+  Cypher prototype bypasses this cache entirely, increasing cold-path cost.
+
+---
+
+## Prototype
+
+A read-only Cypher-based prototype function `cypher_impact_prototype` has been added to
+`status.rs` behind the compile-time constant `CYPHER_IMPACT_PROTOTYPE_ENABLED = false`.
+
+The prototype:
+- Resolves root symbol via `MATCH (s:Symbol {name: $name})`
+- Queries `MATCH (root)-[:CALLS|IMPLEMENTS|DATA_FLOWS*1..N]->(t)` for each depth
+- Returns raw `(id, name, kind, file_path)` tuples without enrichment
+- Does NOT perform N+1 enrichment, risk calculation, or community analysis
+
+The prototype is **disabled by default** and the existing BFS path is untouched.
+
+---
+
+## `synapse_imagine` Budget Cross-Reference
+
+`imagination.rs` uses `FIRE_THRESHOLD = 1.0` (pulse.rs:44) as the SNN firing threshold.
+The `normalize_dynamic_scores` function computes:
+
+```rust
+let threshold = network
+    .get_neuron(symbol_id)
+    .map(|neuron| (FIRE_THRESHOLD - neuron.prediction_error.min(0.25)).max(0.5))
+    .unwrap_or(FIRE_THRESHOLD);
+let normalized = (potential / threshold).clamp(0.0, 1.0);
+```
+
+A Cypher traversal in `imagine` would replace `extract_adjacency` (pulse.rs:4510), which only
+traverses CALLS edges. The Cypher prototype's 3-edge coverage (adding IMPLEMENTS + DATA_FLOWS)
+would expand the structural impact set — potentially increasing `normalized` scores for more
+symbols. The `FIRE_THRESHOLD = 1.0` cap means this expansion would not cause score overflow,
+but it would shift more symbols above the 0.5 near-threshold floor, increasing false positives
+in `thalamus_forecast.near_threshold`.
+
+---
+
+## Decision
+
+**NO-GO** for full replacement of BFS in `impact_analysis_inner`.
+
+### Reasons
+
+1. **Semantic mismatch**: Cypher var-len is outward-only; BFS is bidirectional. Callers (inbound
+   CALLS edges) are a core part of impact analysis — they represent who breaks when the root
+   symbol changes. Dropping them would produce systematically incomplete results.
+
+2. **N+1 cost is unchanged**: The dominant latency driver is per-symbol enrichment (community +
+   process queries), not traversal. Cypher var-len traversal does not eliminate this cost.
+
+3. **Budget incompatibility**: BFS's `max_work=500` budget with depth-proportional allocation is
+   a deliberate UX feature preventing runaway result sets. Cypher var-len returns unbounded
+   results (up to 435 symbols at d3 for walk_dir) with no natural truncation point — requiring
+   post-filtering that loses the depth-proportional semantics.
+
+4. **Missing edge types**: EXTENDS and LINKS_TO relationships are excluded from Cypher var-len
+   patterns to keep the query concise, but they carry real impact signal (inheritance chains,
+   cross-module links).
+
+### Scoped Positive Finding
+
+Cypher var-len IS a viable optimization for `imagine`'s `extract_adjacency` (outgoing CALLS
+only, already depth-capped at 3, no N+1 enrichment). If future profiling shows `extract_adjacency`
+is a bottleneck, replacing its per-depth BFS loop with a single Cypher pattern is a clean win
+with no semantic regression. This is deferred pending actual profiling data.
+
+### Recommendation
+
+- Keep existing BFS in `status.rs` unchanged.
+- Remove the `CYPHER_IMPACT_PROTOTYPE_ENABLED` prototype after this spike is merged (it was
+  additive and non-breaking, but dead code should not accumulate).
+- Revisit Cypher var-len for `imagine::extract_adjacency` if Norn heat data shows it on a hot
+  path (currently it is not).

package/core/dev/spikes/bloat-rounds.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# TASK_2145/2236: N probe commits, each followed by the post-commit incremental
+# index; record graph bytes after every round. Usage: bloat-rounds.sh <repo> <N>
+set -u
+cd "$1" || exit 1
+N="${2:-6}"
+F=dev/spikes/bloat-probe/probe.js
+mkdir -p dev/spikes/bloat-probe
+[ -f "$F" ] || printf '// TASK_2145 bloat probe target\nfunction bloatProbe() { return 0; }\nmodule.exports = { bloatProbe };\n' > "$F"
+size() { stat -c %s .synapse/db/graph; }
+wait_indexed() {
+  local want; want=$(git rev-parse HEAD)
+  for _ in $(seq 1 100); do
+    sleep 3
+    node -e "const s=require('./.synapse/db/index_state.json');process.exit(s.last_commit_hash===process.argv[1]&&s.phase==='complete'?0:1)" "$want" && { sleep 4; return 0; }
+  done
+  return 1
+}
+echo "start graph=$(size)"
+for r in $(seq 1 "$N"); do
+  printf '// round %s %s\n' "$r" "$(date -u +%T)" >> "$F"
+  git add "$F" && git commit -q --no-verify -m "chore(TASK_2145): bloat probe round $r (measurement only)"
+  if wait_indexed; then echo "round $r graph=$(size)"; else echo "round $r TIMEOUT waiting for index"; fi
+done
+echo "end graph=$(size)"

package/core/dev/spikes/mods/clean-claude.js

@@ -0,0 +1,9 @@
+// usage: node clean-claude.js <cwd> <claude args...>
+// Runs claude with every inherited CLAUDE* env var removed (CLAUDECODE, CLAUDE_CODE_*,
+// CLAUDE_PID...), otherwise the child runs as a child session and plugins stay silent.
+const { spawnSync } = require('child_process');
+const env = {};
+for (const [k, v] of Object.entries(process.env)) if (!/^CLAUDE/i.test(k)) env[k] = v;
+const [cwd, ...args] = process.argv.slice(2);
+const r = spawnSync('claude', args, { cwd, env, shell: true, stdio: 'inherit' });
+process.exit(r.status ?? 1);

package/core/dev/spikes/mods/drive-probe.js

@@ -0,0 +1,29 @@
+// TASK_2225: keep a stream-json session alive and idle so the probe mod's
+// $.clock.every ticks and its 15s-delayed $.prompt.submit can be observed.
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const repo = process.argv[2];
+const holdMs = Number(process.argv[3] || 80000);
+const out = path.join(__dirname, 'evidence', 'stream-latest.jsonl');
+fs.writeFileSync(out, '');
+
+const child = spawn('claude', [
+  '-p', '--plugin-dir', 'dev/spikes/mods/kenaz-mod-probe',
+  '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+], { cwd: repo, shell: true });
+
+child.stdout.on('data', d => fs.appendFileSync(out, d));
+child.stderr.on('data', d => fs.appendFileSync(out, 'STDERR ' + d));
+
+child.stdin.write(JSON.stringify({
+  type: 'user',
+  message: { role: 'user', content: 'Reply with the single word READY.' },
+}) + '\n');
+
+setTimeout(() => child.stdin.end(), holdMs);
+child.on('exit', code => {
+  console.log('exit', code);
+  process.exit(0);
+});