From a877aa30269e2fcfe7d3a484540ab05fe60da27a Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 04:29:40 +0800
Subject: [PATCH 01/91] docs(upstream): bootstrap v1.5 sync provenance

---
 .gitignore                                 |   4 +-
 .oxfmtignore                               |   5 +
 docs/upstream-sync/KNOWN_DIFFS.md          | 184 +++++
 docs/upstream-sync/UPSTREAM.md             | 886 +++++++++++++++++++++
 docs/upstream-sync/V1_5_COMMIT_MANIFEST.md | 142 ++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md  | 109 +++
 6 files changed, 1327 insertions(+), 3 deletions(-)
 create mode 100644 docs/upstream-sync/KNOWN_DIFFS.md
 create mode 100644 docs/upstream-sync/UPSTREAM.md
 create mode 100644 docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
 create mode 100644 docs/upstream-sync/V1_5_PORTABLE_FIXES.md

diff --git a/.gitignore b/.gitignore
index b1dee1f..a565ed6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,9 +20,7 @@ target/llvm-cov/
 
 # Per-project index DB written by `codegraph init` / `index`.
 .codegraph/
-
-# Local upstream-sync ledger (colby-upstream-sync skill); not part of the repo.
-docs/upstream-sync/
+.codegraph-v2/
 
 # AWS CodeBuild local config (sensitive — never commit)
 .aws/codebuild.env
diff --git a/.oxfmtignore b/.oxfmtignore
index 512eaf0..1aed11b 100644
--- a/.oxfmtignore
+++ b/.oxfmtignore
@@ -9,6 +9,11 @@ changelog/
 .release-please-manifest.json
 release-please-config.json
 
+# Frozen/hash-addressed upstream-sync provenance. These bytes are reviewed and
+# verified by SHA rather than rewritten by the general Markdown formatter.
+docs/upstream-sync/UPSTREAM.md
+docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
+
 # Golden artifacts are byte-compared by the equivalence/golden oracle tests
 # (include_str! / fs::read). Reformatting them breaks the test suite.
 reference/
diff --git a/docs/upstream-sync/KNOWN_DIFFS.md b/docs/upstream-sync/KNOWN_DIFFS.md
new file mode 100644
index 0000000..411cd7b
--- /dev/null
+++ b/docs/upstream-sync/KNOWN_DIFFS.md
@@ -0,0 +1,184 @@
+# Known CodeGraph Equivalence Differences
+
+This file is parsed by `codegraph-bench::oracle::diff::KnownDiffs` for Tier-3
+differences only. Tier-1 and Tier-2 differences are never allowlisted by this
+file.
+
+## Rule format
+
+One grep-able rule per line:
+
+```text
+RULE tier=3 surface=<surface> key=<substring-or-*> justification=<short-token>
+```
+
+- `tier`: currently only `3` can allow a diff.
+- `surface`: presentation or behavioral surface name reported by the differ.
+- `key`: substring matched against the diff key, or `*` for the whole surface.
+- `justification`: short no-spaces reason; expand with prose nearby when needed.
+
+## Current rules
+
+No Tier-3 rules are active yet.
+
+## Canonicalized by design, not allowlisted
+
+Timestamps are stripped before comparison and are therefore not represented as
+Tier-3 rules:
+
+- `nodes.updated_at`
+- `files.modified_at`
+- `files.indexed_at`
+
+## Deferred colby resolution behavior (Task 20, codegraph-resolve)
+
+The v1 Rust port of `reference/colby/src/resolution/` ships the two CORE
+deterministic strategies — import resolution (`import-resolver.ts`) and name
+matching (`name-matcher.ts`) — orchestrated by `ReferenceResolver`
+(`index.ts`), plus THREE concrete `FrameworkResolver` implementations behind the
+`FrameworkResolver` trait EXTENSION POINT (`crates/codegraph-resolve/src/framework.rs`):
+React/Next.js, Vue/Nuxt, and NestJS (`crates/codegraph-resolve/src/frameworks/`),
+detected per-project by `detect_frameworks`. The remaining ~19 colby resolvers
+stay deferred. The following colby behaviors are intentionally NOT ported in v1:
+
+- **The other framework-specific resolvers** — every concrete `FrameworkResolver`
+  in `reference/colby/src/resolution/frameworks/**` EXCEPT react/vue/nestjs:
+  Spring/Java, Drupal `routing.yml`, Express, Svelte, React Native / Expo / Fabric
+  bridges, Swift↔ObjC bridging, the Go-module / Python / Ruby / C# / Play route
+  extractors, and the Astro resolver
+  (`frameworks/astro.ts`: `astro:*` module imports + the `Astro` global resolved
+  as framework-provided, and `src/pages` file-based route-node mapping). These
+  are an additive heuristic layer; on a project where none of react/vue/nestjs is
+  detected the orchestrator holds an empty resolver list, so behavior matches
+  colby with zero frameworks detected. The Astro
+  EXTRACTION half (frontmatter + `<script>` delegation, template `{call(...)}`
+  and `<Component>` refs) IS ported (`crates/codegraph-extract/src/embedded/astro.rs`,
+  #768); only its framework-resolution half is deferred. Re-enable any of the
+  deferred resolvers by adding it to `frameworks/` and the `detect_frameworks`
+  registry — no orchestrator change required.
+- **Callback / observer edge synthesis** — `synthesizeCallbackEdges`
+  (`reference/colby/src/resolution/callback-synthesizer.ts`, invoked at
+  `index.ts:959-963`). Heuristic dynamic-dispatch edge synthesis; deferred behind
+  the same extension point.
+- **C++ receiver-type inference for method calls** — `inferCppReceiverType` /
+  `matchCppCallChain` / `resolveCppCallResultType` (`name-matcher.ts:333-570`).
+  Reads source text + return types to type bare `recv.method()` receivers.
+- **Java/Kotlin field-receiver inference** — `inferJavaFieldReceiverType`
+  (`name-matcher.ts:705-752`), the Spring `@Autowired` field-injection receiver
+  path.
+- **Per-language import refinements in `resolveViaImport`** — Go cross-package
+  (`resolveGoCrossPackageReference`), Python module-member / absolute-module
+  (`resolvePythonModuleMember` / `resolvePythonAbsoluteModule` /
+  `findPythonModuleFile`), Rust qualified-path (`resolveRustPathReference` and
+  the `crate::`/`self::`/`super::` module-file walk), and Lua/Luau `require`
+  (`resolveLuaRequire`) — `import-resolver.ts:1202-1253,1311-1658`. The generic
+  import-mapping + re-export-chase core ships; these language-specific
+  refinements are follow-ups.
+- **Razor `@using` cascade resolution** — `resolveRazorUsing` / `getRazorUsings`
+  (`index.ts:1116-1158`), tied to the Razor framework layer.
+- **Batched/conformance passes** — `resolveAndPersistBatched` +
+  `resolveChainedCallsViaConformance` (`index.ts:836-970`). The v1 port resolves
+  the full `unresolved_refs` set in one pass (`resolveAndPersist`); the bounded
+  batched loop and the deferred-chain conformance second pass are deferred.
+
+None of the above are Tier-3 allowlist rules: they do not introduce a different
+value for a surface colby produces on the validated mini golden — they are
+additional resolution paths colby would exercise only on inputs outside the v1
+core scope. They are recorded here per Task 20's requirement to document deferred
+colby resolution behavior.
+
+## #2c — callback function_ref (colby 8a114ba5 / #756, multi-language)
+
+The Rust port captures colby's "function-as-value / callback registration"
+feature (`reference/colby/src/extraction/function-ref.ts`) and resolves it as a
+`references` edge tagged `fnRef: true` / `resolvedBy: "function-ref"`. The model
+is internal-only: extraction emits an `UnresolvedRef` with `is_function_ref`,
+persisted via the literal `unresolved_refs.reference_kind` string `function_ref`
+(no `.schema` change — the column has no CHECK constraint), read back as
+`references` + `is_function_ref`, and resolved to a `references` edge.
+
+15 of the 17 supported languages produce edge sets BYTE-IDENTICAL to colby 1.0.1
+for the function_ref feature (TS/JS/TSX/JSX, Python, Go, Rust, C, C++, Java,
+Kotlin, Ruby, PHP, C#, Swift, Scala, Lua/Luau). The following two carry minor,
+pre-existing grammar-modeling divergences ORTHOGONAL to function_ref:
+
+- **Dart** — colby's Dart extractor sets `functionTypes: ['function_signature']`,
+  so its generic walker descends into a `function_declaration`'s body at FILE
+  scope and emits an extra duplicate `file -> fn` fnRef edge alongside the
+  enclosing-function edge. The Rust port models a Dart function as the whole
+  `function_declaration` (consuming its body once), so it emits only the
+  enclosing-function fnRef edge. This is a function-node-modeling difference that
+  predates function_ref; forcing the duplicate would require remodeling Dart
+  function extraction (regression risk on existing Dart goldens).
+- **Pascal** — in `tree-sitter-pascal` a `defProc` nests the `declProc` header and
+  the `block` body as SIBLINGS, and `PascalSpec` has no `resolve_body` override
+  that reaches the sibling block, so procedure bodies are not walked under the
+  procedure's node-stack scope. A `@Handler` callback inside a procedure body is
+  therefore attributed to the FILE node rather than the enclosing procedure
+  (colby attributes it to the procedure). This is the same pre-existing
+  body-resolution limitation that already leaves regular Pascal in-body `calls`
+  edges unextracted in BOTH engines — orthogonal to function_ref.
+
+Neither is a Tier-3 allowlist rule on the validated mini golden (mini is
+TS/Python with no callbacks); they are recorded here as scoped follow-ups.
+
+## Task 22 — MCP tool output (Tier-2 text-formatting differences)
+
+The MCP server (`crates/codegraph-mcp`) renders 8 tools byte-identical to colby
+on the mini golden EXCEPT the following text-formatting / relevance-ordering
+differences. Six of the eight tools (`codegraph_search`, `codegraph_callers`,
+`codegraph_callees`, `codegraph_impact`, `codegraph_node` symbol+file modes,
+`codegraph_files` tree/flat/grouped) are byte-identical; the diffs below are
+confined to `codegraph_explore` and `codegraph_status`.
+
+- **`codegraph_explore` relevance ranking (RWR/flow/skeletonization) is not
+  ported; the size-adaptive output BUDGET is.** colby's `findRelevantContext`
+  (`reference/colby/src/context/index.ts`) ranks the subgraph with
+  Random-Walk-with-Restart / personalized PageRank, computes a FLOW spine among
+  named symbols (`buildFlowFromNamedSymbols`), and adaptively SKELETONIZES
+  off-spine polymorphic-sibling files to signatures (`adaptiveExplore`,
+  `tools.ts:2422-2623`). The Rust port reproduces the DETERMINISTIC structure —
+  header, blast radius, relationship map, dynamic boundaries, and per-file source
+  grouped by file — by seeding roots from the FTS search results
+  (`searchLimit: 8`) and pulling their callers/callees + `contains` children into
+  the subgraph. It DOES now apply colby's `getExploreOutputBudget`
+  (`tools.ts:160-258`, ported in `explore_budget.rs`): the size-tiered total /
+  per-file caps, `defaultMaxFiles`, gap-threshold clustering, header symbol cap,
+  relationship edge cap, `excludeLowValueFiles`, the whole-method-drop +
+  "Not shown above" excluded-file list, and the gated completeness-signal /
+  budget-note / relationships sections. Consequences on the mini golden:
+  - The `Found N symbols across M files` count differs (colby prunes the import
+    seed via RWR; the port keeps it → 7 vs 6). The blast-radius entries, section
+    headers, and every verbatim numbered source line are byte-identical.
+  - Within a `#### <file> — <symbols>` source header, the symbol list ordering
+    can differ (the port sorts by start line; colby uses subgraph insertion
+    order). Same symbols, same set.
+  - The mini corpus lands in the <150-file tier (13000-char cap, files small
+    enough to render whole, `includeRelationships/AdditionalFiles/Completeness/
+    BudgetNote` all off), so the budget produces output byte-identical to the
+    pre-budget whole-file render and colby itself emits none of the gated
+    sections.
+  - **Off-spine skeletonization is DEFERRED (follow-up).** The budget tiers,
+    whole-method-drop, clustering, and excluded-list (the core size-adaptive
+    value) ARE ported; colby's `adaptiveExplore` polymorphic-sibling
+    skeletonization (collapse off-spine sibling/god-file methods to signatures)
+    depends on the un-ported FLOW spine + supertype-implementer analysis and is
+    not yet reproduced. Files over the per-file cap fall to importance-ranked
+    cluster windowing (whole methods, never sliced) instead of signature
+    skeletons — a strictly larger-but-bounded response on sibling-heavy flows,
+    never a correctness change.
+- **`codegraph_status` Database size MB can differ by rounding.** colby reports
+  `fs.statSync(dbPath).size` (`reference/colby/src/db/index.ts:177-180`); the
+  port reports the same on-disk file size. The byte count drifts only because
+  colby checkpointed its WAL before the capture (0.14 vs 0.15 MB). Every other
+  status line — counts, backend, journal mode, nodes-by-kind, languages — is
+  byte-identical.
+- **`codegraph_status` daemon-only sections are omitted.** The `Pending sync:`
+  watcher section (`tools.ts:2936-2944`) and the git-worktree-mismatch warning
+  (`tools.ts:2889-2891`) require the live file watcher / git probe; a static
+  index has neither, so the port omits them (colby also omits them when there is
+  nothing pending — which is the indexed-and-quiescent steady state).
+
+These are Tier-2 text-formatting differences (identical input schemas; equal
+output structure), not Tier-3 allowlist rules: they do not change a value the
+oracle compares on the SQLite golden surfaces.
diff --git a/docs/upstream-sync/UPSTREAM.md b/docs/upstream-sync/UPSTREAM.md
new file mode 100644
index 0000000..97871da
--- /dev/null
+++ b/docs/upstream-sync/UPSTREAM.md
@@ -0,0 +1,886 @@
+# Upstream sync ledger — codegraph-rs ⇄ colbymchenry/codegraph
+
+> Single source of truth for which upstream (colby) version this Rust port is
+> faithful to, and what has been ported / evaluated. The `colby-upstream-sync`
+> skill reads this first and updates it last. This is the project's memory —
+> a good entry stops the next sync from re-investigating the same change.
+
+## Current alignment
+
+- **Tracked colby version:** `1.4.1` (the chosen `1.2.0 → 1.4.1` PORT subset + all
+  applicable DEFER items landed across codegraph-rs `v0.28.3`–`v0.39.0`; see the
+  2026-07-17 CLOSEOUT entry below for the full release table)
+- **This project version:** see `Cargo.toml` (`codegraph-rs`, independent line)
+- **Last sync:** `2026-07-17`
+- **Upstream repo:** https://github.com/colbymchenry/codegraph
+
+> **1.2.0 → 1.4.1 sync: COMPLETE.** Every portable, in-scope behavior in that
+> range has landed (see the 2026-07-17 CLOSEOUT entry below). Tracked parity is
+> `1.4.1` with the following recorded caveats — this is "faithful to 1.4.1 for
+> all portable in-scope behavior, with these explicit exceptions," not
+> byte-for-byte everything:
+> - **Framework-resolution bridges deferred per-language** — ArkUI dispatch
+>   (ArkTS), Nix module-system synthesis, Terraform module-boundary wiring,
+>   Erlang OTP behaviour/gen_server/spawn-MFA bridging, CFML
+>   `<cfscript>`-in-tag/cfquery/receiver-type resolution. The port keeps its
+>   single concrete `FrameworkResolver` (`GodotResolver`); extraction for all
+>   these languages is fully ported.
+> - **COBOL and VB.NET permanently deferred** — no usable `tree-sitter-cobol`
+>   crate on crates.io (name-squat stub) and no `tree-sitter-vbnet`/`-vb`
+>   equivalent at all; adding either would require vendoring a git grammar,
+>   which violates this project's no-vendored-grammar invariant.
+> - **Prompt-hook telemetry excluded by policy** — the confidence-gate mechanics
+>   (#1126/#1136/#1138/#1144-1146) landed; all telemetry/usage-counter code was
+>   deliberately not ported (this project has no tracking pipeline).
+> - **TS/Node-only items are N/A** — event-loop yield points, npm/bundled-Node
+>   lifecycle steps, and other TypeScript-runtime-specific fixes have no Rust
+>   analogue and were recorded, not ported.
+
+> Note: the two version numbers are independent. This line is the _only_ place
+> that records colby parity — do not infer it from `Cargo.toml`.
+
+## Sync log
+
+### 2026-07-17 — CLOSEOUT: 1.2.0 → 1.4.1 sync COMPLETE (tracked parity advanced to 1.4.1)
+
+The `1.2.0 → 1.4.1` sync program evaluated on 2026-07-10 is now finished. Every
+chosen PORT item landed, the DEFER phase ran to completion across nine
+releases, and the two structurally-blocked languages (COBOL, VB.NET) are
+recorded as permanently deferred. Tracked colby parity advances from `1.2.0` to
+`1.4.1`. This entry is the compact index; each release has its own detailed
+LANDED entry below (and Release D/E have their own dated entries further down)
+— read those for the per-item disposition tables.
+
+**Full release table, v0.28.3 → v0.39.0:**
+
+| Release | Item(s) shipped |
+| --- | --- |
+| `v0.28.3` | fix(cli): cold-start MCP handshake race (pre-program fix, not part of the chosen subset) |
+| `v0.28.4` | fix(ci): release CI gate + de-flake reopen test (pre-program fix, not part of the chosen subset) |
+| `v0.29.1` | Release A — #1187 orphaned-ref heal-on-sync, #1200/#1185 daemon lifecycle backstops, #1231 WAL-valve (bulk-index half) |
+| `v0.30.0` | Release B — #1063 `codegraph.json` `include` list |
+| `v0.30.1` | Release C — #1220 PHP `$this->prop->method()` declared-type resolution |
+| `v0.31.0` | Release D — C++ namespace-qualified names + template-arg call linking, #1158/#1159/#1133 UE reflection-macro recovery + `.h` C-vs-C++ detection, #1124 Lua/Luau annotation self-match gate |
+| `v0.31.1` | DEFER E — #1212 bounded-memory resolution tail: large-graph streaming fallback + WAL valve extended into the resolution write loop (most of #1212 was N/A for Rust; only these two sub-parts were portable) |
+| `v0.32.0` | DEFER F — prompt-hook confidence-tiered gate: #1126 multilingual structural-keyword gate, #1138 stem-bounding, #1136 confidence-tier mechanics (query-time vocab substitution, no schema change), #1144/#1145/#1146 segment-match integrity — **all telemetry excluded** |
+| `v0.33.0` | DEFER G — Metal (`.metal`) + CUDA (`.cu`/`.cuh`) via the existing `tree-sitter-cpp` grammar (no new `Language` variant) |
+| `v0.34.0` | DEFER H1 — ArkTS (`.ets`) via `tree-sitter-arkts`; ArkUI dispatch/callback-synthesis bridges deferred |
+| `v0.35.0` | DEFER H2 — Solidity (`.sol`) via `tree-sitter-solidity`; fully self-contained, nothing deferred |
+| `v0.36.0` | DEFER H3 — Nix (`.nix`) via `tree-sitter-nix`; module-system/callback-synthesizer bridges deferred |
+| `v0.37.0` | DEFER H4 — Terraform/HCL (`.tf`/`.tfvars`/`.tofu`) via `tree-sitter-hcl`; module-boundary `TerraformResolver` deferred |
+| `v0.38.0` | DEFER H5 — Erlang (`.erl`/`.hrl`) via `tree-sitter-erlang`; OTP behaviour/gen_server/spawn-MFA bridges deferred |
+| `v0.39.0` | DEFER H6 — CFML/ColdFusion (`.cfc`/`.cfm`/`.cfs`) via dual-grammar `tree-sitter-cfml`; `<cfscript>`-in-tag delegation, cfquery, and framework/receiver-type resolvers deferred |
+
+**Permanently deferred (H7/H8) — no crates.io grammar available:**
+
+| Item | Reason |
+| --- | --- |
+| COBOL (`.cbl`/`.cob`/`.cpy`) | `tree-sitter-cobol` on crates.io is a name-squat stub (768 bytes, `println!("to come!")`, no real grammar, no tree-sitter dependency). Adding COBOL would require vendoring a git grammar, which violates this project's no-vendored-grammar invariant. Deferred until a real crate ships. |
+| VB.NET (`.vb`) | No crate exists on crates.io at all — `tree-sitter-vbnet`/`-visual-basic`/`-vb` are absent; the only near-match, `tree-sitter-vb6`, is VB6, not VB.NET. Same no-vendor blocker. Deferred. |
+
+**Parity caveats (see `## Current alignment` above for the full text):**
+framework-resolution bridges deferred per-language (ArkUI, Nix module-system,
+Terraform module-boundary, Erlang OTP, CFML receiver-type); COBOL/VB.NET
+permanently deferred for lack of a crates.io grammar; prompt-hook telemetry
+excluded by policy; TS/Node-runtime-only items recorded as N/A. Everything else
+portable and in-scope for `1.2.0 → 1.4.1` has landed.
+
+### 2026-07-17 — LANDED DEFER item H6: CFML / ColdFusion (`.cfc`/`.cfm`/`.cfs`, #1153 `816bacb`) via the dual-grammar `tree-sitter-cfml` crate — the EXTRACTION SLICE only, scope B (`<cfscript>`-in-tag delegation + cfquery + framework/receiver-type resolvers deferred)
+
+Landed DEFER item H6 — the **scope-B extraction slice** of the upstream
+`816bacb` ("feat(extraction): add CFML/ColdFusion language support (#1153)").
+CFML is a NEW `Language::Cfml` variant backed by the DUAL-GRAMMAR
+`tree-sitter-cfml = "0.26.30"` crate (crates.io; bundles a `cfscript` script
+grammar + a `cfml` tag grammar + a `cfquery` SQL dialect; `LanguageFn` ABI — no
+vendored grammar/wasm). CFML has two syntaxes: a first-token sniff
+(`is_bare_script_cfml`, BOM+ws+comment skip → first token `!= '<'`) picks the
+dialect+grammar PER FILE. This is expressed through a new defaulted
+`LanguageSpec::tree_sitter_language_for_source(&self, source)` trait hook
+(default = `self.tree_sitter_language()`); only `CfmlSpec` overrides it, so all
+41 other specs are byte-identical. Bare-script files (`.cfs` + bare `.cfc`/`.cfm`)
+parse with `cfscript` and drive the generic type-set dispatch; tag files parse
+with the `cfml` tag grammar and are handled by the `Language::Cfml`-guarded
+`visit_cfml_node` walker extension.
+
+| Upstream hunk | Disposition | Notes |
+| --- | --- | --- |
+| `types.ts`: `'cfml'`/`'cfscript'`/`'cfquery'` in `LANGUAGES` | **PORT (one variant)** | ONE `Language::Cfml` maps all three extensions; `cfscript`/`cfquery` are internal grammar handles. `Language::ALL` 41→42, `LANGUAGE_STRINGS` 41→42 in lockstep |
+| `grammars.ts`: `.cfc`/`.cfm`→cfml, `.cfs`→cfscript EXTENSION_MAP + display | **PORT** | `"cfc" \| "cfm" \| "cfs" => Language::Cfml` in `builtin_language_for_ext`; `as_str` `"cfml"` |
+| `grammars.ts`: 3 vendored wasm + ABI-15 branch | **N/A** | port pins `tree-sitter-cfml` from crates.io — no vendored wasm |
+| `cfml-extractor.ts`: `isBareScriptCfml` dialect switch | **PORT** | `is_bare_script_cfml` first-token detector; drives `tree_sitter_language_for_source` + `visit_cfml_node` dialect gate |
+| `cfml-extractor.ts`: `extractBareScript` (delegate to cfscript, file-name component) | **PORT** | cfscript type-set config drives generic dispatch; `emit_cfml_script_component` renames the unnamed `component`/`interface` from the file + script-style `extends`→Extends |
+| `cfml-extractor.ts`: `extractTagBased` `walkProgram`/`extractComponent`/`extractFunctionTag`/`tagAttr` | **PORT** | `visit_cfml_node` tag walk: `cf_component_open_tag`→Class (name attr/file, `extends`/`implements` refs, following-sibling body via `cfml_consumed_until`), `cf_function_tag`→Method/Function |
+| `cfscript.ts`: `getVisibility`/`getSignature`/`extractImport`/`classifyClassNode` | **PORT** | `CfmlSpec` overrides (visibility from `access_type`, signature from `parameters`, imports, interface-vs-class) |
+| `cfml-extractor.ts`: `delegateScriptTag` (`<cfscript>` body re-parse) | **DEFER** | needs a 2nd in-tree parse the one-spec-one-grammar engine lacks |
+| `cfml-extractor.ts`: `delegateQueryTag` / `cfquery.ts` (`LANGUAGE_CFQUERY`) | **DEFER** | cfquery SQL-body extraction — same 2nd-parse limitation |
+| CFML framework resolver (#1152/#1154/#1155: dotted/relative inheritance, receiver-type inference) | **DEFER** | no 2nd `FrameworkResolver`; port keeps its single `GodotResolver` |
+| `__tests__/extraction.test.ts` (+308) | **DEFER** | re-implemented as Rust unit + golden tests |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the eleven existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`/`arkts`/`solidity`/`nix`/`terraform`/`erlang`)
+byte-neutral (none holds a `.cfc`/`.cfm`/`.cfs` file, no regen); one NEW `cfml`
+golden (`reference/golden/cfml/`, corpus `crates/codegraph-bench/fixtures/cfml/`
+— script `Base.cfc`, tag `Widget.cfm`, bare-script `Gadget.cfs`) carries the only
+`"language":"cfml"` string. Both `extends Base` refs RESOLVE to `Base.cfc` as
+EDGES; `Gadget.doThing`'s `helper()` call is the sole unresolved `refs.json` row.
+The DEFERRED `<cfscript>`-in-tag / cfquery / framework-resolver edges are never
+emitted. Extraction-tier add matching the port's other 28 grammar-backed Tier-1
+languages (same discipline as ArkTS H1 / Solidity H2 / Nix H3 / Terraform H4 /
+Erlang H5).
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-16 — LANDED DEFER item H5: Erlang (`.erl`/`.hrl`, #1165 `6511722`) via a dedicated `tree-sitter-erlang` grammar — the EXTRACTION SLICE only (behaviour/gen_server/spawn-MFA framework bridges deferred)
+
+Landed DEFER item H5 — the **extraction slice ONLY** of the upstream `6511722`
+("feat(extraction): add Erlang language support with OTP behaviour/gen_server
+bridging (#1165)"). Erlang is a NEW `Language::Erlang` variant backed by a NEW
+grammar crate (`tree-sitter-erlang = "0.19.0"`, crates.io, WhatsApp/ELP grammar;
+`LanguageFn` ABI — no vendored grammar). Erlang is form-based (a function's name
+lives on its `function_clause`, the grammar emits one `fun_decl` per clause,
+`record_decl` carries fields as direct children, `-spec`/`-callback`/type bodies
+parse as `call` nodes), so `ERLANG_SPEC` has all-empty C-family type-sets (only
+`package_types`/`import_types` wired, as upstream) and the extraction is driven
+entirely by a `Language::Erlang`-guarded `visit_erlang_node` walker extension.
+
+| Upstream hunk | Disposition | Notes |
+| --- | --- | --- |
+| `types.ts`: `'erlang'` in `LANGUAGES` | **PORT** | new `Language::Erlang` variant; `Language::ALL` 40→41, `LANGUAGE_STRINGS` 40→41 in lockstep |
+| `grammars.ts`: `.erl`/`.hrl` EXTENSION_MAP + `Erlang` display | **PORT** | `"erl" \| "hrl" => Language::Erlang` in `builtin_language_for_ext` |
+| `erlang.ts` `erlangExtractor` config (`fun_decl`/`record_decl`/`type_alias`/`opaque`/`import_attribute`/`pp_include(_lib)`, `packageTypes: module_attribute`, name/body/params fields) | **PORT** | `ERLANG_SPEC` wires `package_types`+`import_types`; the C-family type-sets stay empty (form-based) |
+| `erlang.ts` `handleFunDecl` clause-merge dedup | **PORT** | `visit_erlang_fun_decl` tracks `(last_fn_name, last_fn_id)`; a same-name continuation `fun_decl` attaches to the existing node |
+| `erlang.ts` `handleRecordDecl` (struct + direct-child fields) | **PORT** | `visit_erlang_record_decl` |
+| `erlang.ts` `handleTypeAlias`/`handlePpDefine` | **PORT** | TypeAlias / Constant, type-position `call` children NOT descended |
+| `erlang.ts` `spec`/`callback` type-position guard | **PORT** | both consumed without descent — `-spec f(integer())->integer().` mints no `integer` call ref |
+| `tree-sitter.ts` erlang `extractCall`: local `call`→calls, remote `mod:f`→`mod::f`, `?MODULE:f`→bare | **PORT** | `erlang_call_ref_name` (reads module qualifier from the PARENT `remote` node) |
+| `tree-sitter.ts` `internal_fun`/`external_fun`→references, record-expr forms→references | **PORT** | function VALUES + record USAGES are `References`, not `Calls` |
+| `erlang.ts` `handleBehaviour` (`-behaviour(x)`→implements) | **DEFER** | non-Godot framework resolution; the port has one concrete `FrameworkResolver` (`GodotResolver`) |
+| `tree-sitter.ts` gen_server `call/cast(?MODULE\|?SERVER)`→`handle_call`/`handle_cast` (`resolveErlangGenServerTarget`) | **DEFER** | framework bridge |
+| `tree-sitter.ts` spawn/apply/proc_lib/timer/rpc MFA-argument callee lift (`ERLANG_MFA_CALLS`) | **DEFER** | framework bridge |
+| `tree-sitter.ts` `macro_call_expr` use-site→`-define` constant linking + `ERLANG_PREDEFINED_MACROS` | **DEFER** | macro use-site call chain; the `-define` Constant symbol is still emitted |
+| `erlang.ts` `handleAppResourceTuple` (`.app`/`.app.src` `{application,...}` wiring) | **DEFER** | framework/resource resolution |
+| `__tests__/*.test.ts` (resolver + extraction) | **DEFER** | re-implemented as Rust unit + golden tests |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the ten existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`/`arkts`/`solidity`/`nix`/`terraform`)
+byte-neutral (none holds a `.erl`/`.hrl` file, no regen); one NEW `erlang` golden
+(`reference/golden/erlang/`, corpus `crates/codegraph-bench/fixtures/erlang/m.erl`)
+carries the only `"language":"erlang"` string. Its local `g()` self-call and the
+`foo.hrl` include resolve as EDGES; the remote `other::h` (the `other` module is
+absent from the fixture) is the sole unresolved `refs.json` row; the DEFERRED
+behaviour/gen_server/spawn-MFA/`.app` edges are never emitted. This is an
+extraction-tier add matching the port's other 27 grammar-backed Tier-1 languages
+(same disposition as ArkTS H1 / Nix H3 / Terraform H4 deferred bridges).
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-15 — LANDED DEFER item H4: Terraform/HCL (`.tf`/`.tfvars`/`.tofu`, #1173 `6c24f4b`) via a dedicated `tree-sitter-hcl` grammar — the EXTRACTION SLICE only (module-boundary framework resolver deferred)
+
+Landed DEFER item H4 — the **extraction slice ONLY** of the upstream `6c24f4b`
+("feat(extraction): add Terraform/OpenTofu language support with module-boundary
+bridging (#83, #310, #648 — carries #706) (#1173)"). Terraform is a NEW
+`Language::Terraform` variant backed by a NEW grammar crate
+(`tree-sitter-hcl = "1.1.0"`, crates.io, Apache-2.0; `LanguageFn` ABI — no
+vendored `tree-sitter-terraform.wasm`). HCL is intentionally generic — every
+top-level construct is a `block` distinguished only by its first `identifier`
+child — so there are no C-family type-set node kinds; `TERRAFORM_SPEC` has
+all-empty type-sets (faithful to upstream's empty `terraformExtractor` config) and
+the extraction is driven entirely by a `Language::Terraform`-guarded
+`visit_terraform_node` walker extension (the same custom-visitor pattern as
+`visit_nix_node`). Per-item disposition:
+
+| upstream (`6c24f4b`)                                                                                                              | disposition | notes                                                                                                                                              |
+| --------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `types.ts`: `'terraform'` in `LANGUAGES`                                                                                          | **PORT**    | new `Language::Terraform` variant; `Language::ALL` 39→40, `LANGUAGE_STRINGS` 39→40 in lockstep                                                      |
+| `grammars.ts`: `.tf`/`.tfvars`/`.tofu` EXTENSION_MAP + `Terraform` display                                                        | **PORT**    | `"tf" \| "tfvars" \| "tofu" => Language::Terraform` in `builtin_language_for_ext`                                                                   |
+| `grammars.ts`: vendored `tree-sitter-terraform.wasm` ABI-15 branch                                                                | **N/A**     | port pins `tree-sitter-hcl = "1.1.0"` from crates.io — no vendored wasm                                                                             |
+| `languages/index.ts`: register `terraformExtractor`                                                                               | **PORT**    | `TERRAFORM_SPEC` (empty type-sets) + `spec_for_language` arm + `parse_language` (`queries.rs`)                                                      |
+| `terraform.ts` `visitNode`: block-type dispatch resource/data→class, module→module, variable/output→variable, provider→namespace, locals→constant; plain traversal refs | **PORT**    | `visit_terraform_node` + `visit_terraform_locals` + `emit_terraform_references_in_body` + the pure `pub(crate)` AST helpers in `lang/terraform.rs`  |
+| `terraform.ts` `emitModuleWiring`: `module.M:file`/`:var.X`/`:output.X` `:`-scoped refs                                            | **DEFER**   | feeds the deferred `TerraformResolver`; a `module` block still emits its Module symbol + plain body refs                                            |
+| `terraform.ts` `.tfvars` top-level-assignment `var.X` ref                                                                         | **DEFER**   | feeds the deferred `.tfvars` ancestor-walk; `.tfvars` files still index as `Language::Terraform` file nodes                                          |
+| `terraform.ts` `qualifyReference` `module.M:output.<out>` scoped half                                                             | **DEFER**   | plain `module.M` PORTED; the `:output` scoped half feeds the deferred resolver                                                                      |
+| `resolution/frameworks/terraform.ts` (+195): `TerraformResolver` (directory-scoped resolution, `:`-scoped bridge, `.tfvars` walk)  | **DEFER**   | the port has exactly one concrete `FrameworkResolver` (`GodotResolver`); a second is out of scope for the extraction-tier program                  |
+| `resolution/frameworks/index.ts` (+3): register `terraformResolver`                                                               | **DEFER**   | nothing to register                                                                                                                                |
+| `resolution/index.ts` (+6): terraform directory-scoping gate                                                                      | **DEFER**   | resolution-tier gate                                                                                                                                |
+| `__tests__/frameworks-integration.test.ts` (+131), `__tests__/extraction.test.ts` (+290)                                          | **DEFER**   | resolver tests / re-implemented as Rust unit + golden tests                                                                                          |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the nine existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`/`arkts`/`solidity`/`nix`)
+byte-neutral (none holds a `.tf`/`.tfvars`/`.tofu` file, no regen); one NEW
+`terraform` golden (`reference/golden/terraform/`, corpus
+`crates/codegraph-bench/fixtures/terraform/main.tf`) carries the only
+`"language":"terraform"` string in the corpus. Its plain traversal refs with a
+unique same-file target resolve via the existing generic qualified-name matcher
+(`var.region` ×3 → the variable, `aws_s3_bucket.b` → the resource, `module.vpc` →
+the module — all EDGES), leaving the undeclared `aws_kms_key.logs` as the sole
+unresolved `refs.json` row; the DEFERRED `emitModuleWiring` `:`-scoped refs and
+`.tfvars` var ref are never emitted. This is an extraction-tier add matching the
+port's other 26 grammar-backed Tier-1 languages (same disposition as ArkTS H1's
+deferred ArkUI bridges + Nix H3's module-system synthesizer).
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-15 — LANDED DEFER item H3: Nix (`.nix`, #1190 `7f32513`) via a dedicated `tree-sitter-nix` grammar — the EXTRACTION SLICE only (module-system bridges deferred)
+
+Landed DEFER item H3 — the **extraction slice ONLY** of the upstream `7f32513`
+("feat(extraction): add Nix language support with module-system option wiring").
+Nix is a NEW `Language::Nix` variant backed by a NEW grammar crate
+(`tree-sitter-nix = "0.3.0"`, crates.io, MIT; `LanguageFn` ABI — no vendored
+wasm). Because Nix is an expression language with no C-family
+`class`/`struct`/`method`/`enum` node kinds, `NIX_SPEC` has all-empty type-sets
+(faithful to upstream's empty `nixExtractor` config) and the extraction is driven
+entirely by a `Language::Nix`-guarded `visit_nix_node` walker extension (the same
+custom-visitor pattern as `visit_gdscript_node`). Per-item disposition:
+
+| upstream (`7f32513`)                                                                                          | disposition | notes                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `types.ts`: `'nix'` in `LANGUAGES` (after `'solidity'`)                                                       | **PORT**    | new `Language::Nix` variant; `Language::ALL` 38→39, `LANGUAGE_STRINGS` 38→39 in lockstep                        |
+| `grammars.ts`: `'.nix': 'nix'` EXTENSION_MAP + `Nix` display                                                  | **PORT**    | `"nix" => Language::Nix` in `builtin_language_for_ext`                                                            |
+| `languages/index.ts`: register `nixExtractor`                                                                 | **PORT**    | `NIX_SPEC` (empty type-sets) + `spec_for_language` arm + `parse_language` (`queries.rs`)                          |
+| `nix.ts` `visitNode`: `binding`→function\|variable, curried lambda signature, `inherit`, `apply`→calls/imports, `import`/`callPackage`/`imports`-list paths | **PORT**    | `visit_nix_node` + `emit_nix_file_import` + the pure `pub(crate)` AST helpers in `lang/nix.rs`                    |
+| `resolution/callback-synthesizer.ts` (+178)                                                                   | **DEFER**   | the port has no callback-synthesis subsystem                                                                     |
+| `resolution/index.ts` (+31): lexical-scope resolution gates                                                   | **DEFER**   | Nix `let`/`with`/`rec` scope-aware resolution — resolution tier                                                 |
+| `resolution/import-resolver.ts` (+34): module-list wiring                                                     | **DEFER**   | binds `imports`/`modules` path refs; the EXTRACTION emits them, the RESOLVER wiring is deferred                  |
+| `db/queries.ts` (+15) `getNodesByNamePrefix` + `mcp/tools.ts` (+31): option-path lookup                       | **DEFER**   | query surface feeding the deferred option-path synthesizer                                                       |
+| `src/index.ts` (+5): module-lists glue; `__tests__/nix-option-synthesizer.test.ts`                            | **DEFER**   | synthesizer glue + its tests                                                                                      |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the eight existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`/`arkts`/`solidity`)
+byte-neutral (none holds a `.nix` file, no regen); one NEW `nix` golden
+(`reference/golden/nix/`, corpus `crates/codegraph-bench/fixtures/nix/`) carries
+the only `"language":"nix"` string in the corpus. Its `imports`/`callPackage`
+path refs resolve in-corpus (the referenced `.nix` files exist), so `refs.json`
+retains only the three unresolved `Calls` refs — the DEFERRED module-system
+synthesizer / import-resolver wiring binds nothing new. This is an extraction-tier
+add matching the port's other 25 grammar-backed Tier-1 languages (same disposition
+as ArkTS H1's deferred ArkUI bridges).
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-15 — LANDED DEFER item H2: Solidity (`.sol`, #1170 `1441933`) via a dedicated `tree-sitter-solidity` grammar — the WHOLE commit (all extraction; nothing deferred)
+
+Landed DEFER item H2 — the FULL upstream `1441933` ("feat(extraction): add
+Solidity language support (.sol)"). Unlike H1 (ArkTS, which deferred a
+callback-synthesizer slice), the whole Solidity commit is EXTRACTION — there is
+no bundled framework-resolution / runtime-dispatch layer, so **nothing is
+deferred for H2**. Solidity is a NEW `Language::Solidity` variant backed by a NEW
+grammar crate (`tree-sitter-solidity = "1.2.13"`, crates.io, MIT; `LanguageFn`
+ABI — no vendored wasm). Per-item disposition:
+
+| upstream (`1441933`)                                                                                             | disposition           | notes                                                                                              |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
+| `types.ts`: `'solidity'` in `LANGUAGES`                                                                          | **PORT**              | new `Language::Solidity` variant; `Language::ALL` 37→38, `LANGUAGE_STRINGS` 37→38 in lockstep      |
+| `grammars.ts`: `'.sol': 'solidity'` EXTENSION_MAP                                                                | **PORT**              | `"sol" => Language::Solidity` in `builtin_language_for_ext`                                        |
+| `languages/index.ts`: register `solidityExtractor`                                                               | **PORT**              | `SOLIDITY_SPEC` + `spec_for_language` arm + `parse_language` (`queries.rs`)                        |
+| `solidity.ts`: contract/library/interface/struct/enum node-kind sets                                             | **PORT**              | contract/library → Class, interface → Interface, struct → Struct, enum → Enum (generic dispatch)   |
+| `solidity.ts`: synthetic ctor/fallback/receive names (`resolveName`)                                             | **PORT**              | `SOLIDITY_SPEC::resolve_name`                                                                      |
+| `solidity.ts`: `getSignature` (walk direct `parameter`/`return_type_definition`/`visibility`/`state_mutability`) | **PORT**              | params are direct children, not a `parameters` field                                               |
+| `solidity.ts`: `visitNode` inheritance (`inheritance_specifier`)                                                 | **PORT**              | walker D3 (`user_defined_type` ancestor → Extends; resolver promotes to Implements for interfaces) |
+| `solidity.ts`: `visitNode` state-var/struct-member/event/error → field                                           | **PORT**              | walker D5 direct-`name` field fallback (+ D10 for file-level event/error)                          |
+| `solidity.ts`: `visitNode` `enum_value`                                                                          | **PORT**              | walker D6 bare-text `enum_value` → EnumMember                                                      |
+| `solidity.ts`: file-level `constant_variable_declaration`                                                        | **PORT**              | walker D8 Solidity arm in `extract_variable` → Constant                                            |
+| `solidity.ts`: `extractImport` (source string)                                                                   | **PORT**              | `SOLIDITY_SPEC::extract_import`                                                                    |
+| `tree-sitter.ts`: `extractDecoratorsFor` `modifier_invocation` → `calls`                                         | **PORT**              | walker D7 header `modifier_invocation` → Calls (NOT Decorates)                                     |
+| `is`→`implements` reclassification + import resolution                                                           | **EXISTING RESOLVER** | served by `resolver.rs:1231-1247` + name matcher + import resolver — zero new resolve-tier code    |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the seven existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`/`arkts`) byte-neutral (none
+holds a `.sol` file, no regen); one NEW `solidity` golden
+(`reference/golden/solidity/`, corpus `crates/codegraph-bench/fixtures/solidity/`)
+carries the only `"language":"solidity"` string in the corpus. Being fully
+self-contained, its `refs.json` is empty and `edges.json` holds the resolved
+`Implements` (`Token → IERC20`) + `Calls` (`transfer → onlyOwner`,
+`transfer → Transfer`) edges. This is an extraction-tier add matching the port's
+other 24 grammar-backed Tier-1 languages.
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-15 — LANDED DEFER item H1: ArkTS (`.ets`, extraction slice of #1186 `9915221`) via a dedicated `tree-sitter-arkts` grammar
+
+Landed DEFER item H1 — the **extraction slice ONLY** of the upstream ArkTS
+(HarmonyOS / OpenHarmony `.ets`) support. Unlike Metal/CUDA (item G), ArkTS is a
+NEW `Language::ArkTs` variant backed by a NEW grammar crate
+(`tree-sitter-arkts = "0.2.0"`, a TypeScript-superset fork that parses the ArkUI
+`@Component struct` syntax `tree-sitter-typescript` cannot). Per-item disposition:
+
+| upstream (`9915221`)                                                            | disposition | notes                                                                                              |
+| ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `types.ts`: `'arkts'` in `LANGUAGES`                                            | **PORT**    | new `Language::ArkTs` variant; `Language::ALL` 36→37, `LANGUAGE_STRINGS` 36→37 in lockstep         |
+| `grammars.ts`: `'.ets': 'arkts'` EXTENSION_MAP                                  | **PORT**    | `"ets" => Language::ArkTs` in `builtin_language_for_ext`; plain `.ts` stays TypeScript             |
+| `languages/index.ts`: register `arktsExtractor`                                 | **PORT**    | `ARKTS_SPEC` + `spec_for_language` arm + `parse_language` (`queries.rs`)                           |
+| `arkts.ts`: `structTypes: ['struct_declaration']`                               | **PORT**    | `@Component struct` → `NodeKind::Struct` via the existing `extract_struct` path (no walker change) |
+| `arkts.ts`: `callTypes` — the `'call_expression'` element                       | **PORT**    | `call_types = ["call_expression"]`                                                                 |
+| `arkts.ts`: `callTypes` — `arkui_component_expression`/`leading_dot_expression` | **DEFER**   | ArkUI component-instantiation / attribute-chain dispatch                                           |
+| `arkts.ts`: `extractModifiers`/`collectDecoratorNames` decorator hook           | **DEFER**   | feeds the deferred state→build() synthesizer; `extract_modifiers` left at trait default            |
+| `tree-sitter.ts`: arkts `extractCall` branch (attribute chains, `.onXxx`)       | **DEFER**   | ArkUI resolution heuristics                                                                        |
+| state→build() re-render, emitter emit→subscriber, router→`@Entry` bridges       | **DEFER**   | callback synthesizer the port lacks                                                                |
+| ohpm `oh-package.json5` workspace-package import resolution                     | **DEFER**   | import-resolver feature                                                                            |
+| `$r`/`$rawfile` intrinsics, web-family/value-ref/re-export gates                | **DEFER**   | resolution-side gates                                                                              |
+| `index_state` / index-completeness guard                                        | **DEFER**   | unrelated subsystem                                                                                |
+
+Golden impact: `.schema` byte-stable (`language` is a stored TEXT VALUE, not DDL —
+`schema_parity` green, `colby.schema.sql` byte-identical); the six existing
+goldens (`cpp`/`godot`/`ruby`/`mini`/`metal`/`cuda`) byte-neutral (none holds a
+`.ets` file, no regen); one NEW `arkts` golden
+(`reference/golden/arkts/component.ets`) carries the only `"language":"arkts"`
+string in the corpus. Rationale for the DEFER slice: the port has no
+callback-synthesizer subsystem and treats every non-Godot framework's
+runtime-dispatch layer as out of scope (consistent with Godot being the ONE
+concrete `FrameworkResolver`). This is an extraction-tier add matching the port's
+25 other grammar-backed languages.
+
+Tracked colby parity stays `1.2.0` (advances to `1.4.1` only once the full
+`1.2.0..1.4.1` PORT/DEFER subset lands — this is one item of that subset).
+
+### 2026-07-14 — LANDED DEFER item G: Metal (`.metal`, #1121 `cc89146`) + CUDA (`.cu`/`.cuh`, CUDA-lang parts of #1172 `e1a8d88`) via the existing C++ grammar
+
+Landed DEFER item G — the two cheapest deferred languages from the
+`1.2.0..1.4.1` subset. Both ride the ALREADY-PRESENT `tree-sitter-cpp` grammar
+(no new grammar crate) and map to `Language::Cpp` (**no new `Language` variant**,
+so `.schema` + `Language::ALL` len 36 are byte-stable). Per-item disposition:
+
+| upstream                                                                                       | what it is                                                                                          | disposition                                                                   | golden impact                                                     |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| #1121 `cc89146` `.metal`→cpp map                                                               | Metal Shading Language extension mapping                                                            | **PORT** (`engine.rs` `builtin_language_for_ext`)                             | NEUTRAL for existing fixtures; NEW `metal` fixture                |
+| #1121 `cc89146` `blankMetalAttributes`                                                         | offset-preserving `.metal`-gated `[[attribute]]` blank (prevents spurious `extends`)                | **PORT** (`lang/cpp.rs` `blank_metal_attributes`)                             | NEUTRAL (gate proven: `[[nodiscard]]` in `.cpp` byte-identical)   |
+| #1172 `e1a8d88` `.cu`/`.cuh`→cpp map                                                           | CUDA extension mapping                                                                              | **PORT** (`engine.rs`)                                                        | NEUTRAL for existing fixtures; NEW `cuda` fixture                 |
+| #1172 `e1a8d88` `blankCudaConstructs`                                                          | specifier + `__launch_bounds__` + brace-balanced `<<<…>>>` launch blank (offset-preserving)         | **PORT** (`lang/cpp.rs` `blank_cuda_constructs`)                              | NEUTRAL (content/ext-gated; no CUDA markers in existing fixtures) |
+| #1172 `e1a8d88` `looksLikeCudaSource`                                                          | strong content markers (`__global__`/`__device__`/`__constant__`/`cudaStream_t`)                    | **PORT** (`lang/cpp.rs` `looks_like_cuda_source`)                             | NEUTRAL                                                           |
+| #1172 `e1a8d88` `preParseCSource`                                                              | C-detected `.h` headers get the content-gated CUDA blank                                            | **PORT** (`lang/c.rs` `CSpec::pre_parse`)                                     | NEUTRAL                                                           |
+| #1172 `e1a8d88` `recoverCppMacroDefinedName`                                                   | name-in-first-arg macro-kernel recovery (`DEFINE_FLASH_FORWARD_KERNEL(name, …)`; gtest/pybind bail) | **PORT** (`lang/cpp.rs` + `CppSpec::resolve_name`)                            | NEUTRAL (narrow gate; NEW `cuda` fixture guards it)               |
+| #1172 `e1a8d88` namespace-prefix + template-arg call strip                                     | (Release D Items 1+2)                                                                               | **EXCLUDE — already landed in Release D**                                     | n/a                                                               |
+| #1172 `e1a8d88` `cppLocalFnPtrs` local-fn-ptr launch dispatch (`auto k = &fn<…>; k<<<…>>>(…)`) | narrow real-world pattern, per-body binding map                                                     | **DEFERRED within G** (recorded gap; primary launch edges resolve without it) | n/a                                                               |
+
+**Enabling change:** threaded `file_path: &str` into the `LanguageSpec::pre_parse`
+trait method (was path-less) — the faithful analogue of upstream's optional
+`filePath` param, needed for the Metal `.metal` gate. Default body ignores the
+path; `CsharpSpec` gains an unused `_file_path`, `CppSpec`/`CSpec` use it.
+
+**New golden fixtures:** `reference/golden/metal/` (`shader.metal`) and
+`reference/golden/cuda/` (`kernel.cu`), wired into `equivalence.rs` mirroring the
+`cpp` pair. The `cpp`/`godot`/`ruby`/`mini` goldens are byte-identical (no regen).
+See `docs/equivalence.md` "Metal fixture" / "CUDA fixture" for the regen recipe.
+
+Tracked parity STILL `1.2.0` — advances to `1.4.1` only in the final ledger step
+once ALL PORT/DEFER items land.
+
+### 2026-07-14 — LANDED DEFER item F: prompt-hook confidence-tiered gate (#1126 + #1138 + #1136 mechanics; telemetry EXCLUDED; golden-neutral)
+
+Landed DEFER item F — the prompt-hook **gate** improvements from colby
+`1.2.0..1.4.1` — turning `codegraph prompt-hook` from a bare unconditional
+`codegraph_explore` forwarder into a three-tier confidence gate. All telemetry is
+EXCLUDED by maintainer decision (this port has no tracking pipeline and this
+change introduces none). Per-item disposition (each cited to the upstream diff):
+
+| upstream                                                  | what it is                                                                          | disposition                                                                                                                  | golden impact                                                 |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| #1126 `317e7f4`                                           | multilingual structural-keyword gate (WORDS + STEMS + UNSEGMENTED, Unicode bounds)  | **PORT** (`structural_gate.rs`)                                                                                              | NEUTRAL (pure gate logic in the CLI path)                     |
+| #1138 `713ab7a`                                           | right-bound `call`/`trace`/`affect`/`connect` stems (callus/Connecticut don't fire) | **PORT** (folded into `structural_gate.rs`)                                                                                  | NEUTRAL                                                       |
+| #1136 `e699ee9` mechanics                                 | confidence-tiered injection (HIGH full-explore / MEDIUM pointer / silent); tokens   | **PORT-minus-telemetry**                                                                                                     | NEUTRAL (MEDIUM tier derived at query time — see below)       |
+| #1136 `name_segment_vocab` table + schema v7 + write path | index-time materialized vocab                                                       | **N-A (design-substituted)** — replaced by query-time derivation from `distinct_non_file_node_names`; NO table, NO migration | NEUTRAL by substitution (a table would break `schema_parity`) |
+| #1136 gate telemetry / #be55b93                           | anonymous gate-outcome usage counters                                               | **EXCLUDE-telemetry**                                                                                                        | n/a (not ported)                                              |
+| #35611b9 #1144                                            | skip file/import-only names as surfaced symbols                                     | **PORT** (`isSegmentableKind` gate in `distinct_non_file_node_names` + representative pick)                                  | NEUTRAL                                                       |
+| #35611b9 #1145                                            | English-plural variant folding correctness (`segment_lookup_variants`)              | **PORT** (`segments.rs`)                                                                                                     | NEUTRAL                                                       |
+| #35611b9 #1146                                            | co-occurrence variant folding (a plural pair of one word ≠ a two-word match)        | **PORT** (in-Rust word fold in `get_segment_matches`)                                                                        | NEUTRAL                                                       |
+| #35611b9 #1141/#1142                                      | updateNode vocab write / heal-if-empty                                              | **N-A** — no write-path vocab in the query-time design                                                                       | NEUTRAL                                                       |
+
+**What landed (all in `crates/codegraph-cli`, plus one read-only store query):**
+`structural_gate.rs` (the multilingual WORDS/STEMS/UNSEGMENTED term lists copied
+verbatim from `directory.ts`, matched with lookaround-free capture-class
+boundaries since Rust `regex` has no lookbehind; `has_structural_keyword`;
+`extract_code_tokens`), `segments.rs` (`split_identifier_segments`,
+`normalize_prose_word`, `extract_prose_candidates` + full `ENGLISH_PROSE_STOPWORDS`,
+`segment_lookup_variants`), `segment_match.rs` (`get_segment_matches` + the
+`SegmentMatch` struct — Tier-A co-occurrence + Tier-B rare-word, ported from
+`index.ts`), and `distinct_non_file_node_names` in `codegraph-store` (the
+golden-neutral query-time substitution for the index-time vocab table).
+`cmd_prompt_hook` now parses the Claude `{prompt,cwd}` JSON payload (raw-string
+fallback preserved), honors the `CODEGRAPH_NO_PROMPT_HOOK`/`CODEGRAPH_PROMPT_HOOK`
+kill-switch, and runs the HIGH → MEDIUM → silent gate.
+
+**Telemetry is EXCLUDED in full** — no counter, no `gate()` recording, no
+`DO_NOT_TRACK` surface, nothing that phones home. The **schema version 7 is unchanged**:
+NO `name_segment_vocab` table and NO migration were added — the
+MEDIUM tier is derived at query time from existing node names, so
+`reference/golden/colby.schema.sql` and all golden fixtures stay byte-identical
+(`schema_parity` + `cargo test -p codegraph-bench` green, NO regen). No new
+AI/vector/LLM crate (guardrail clean); the two added deps (`regex`,
+`unicode-normalization`) are plain-text crates.
+
+**Outcome:** DEFER-F is CLOSED. This is a golden-NEUTRAL, telemetry-free `feat:`
+release. Tracked parity advances toward `1.4.1` for the prompt-hook gate surface;
+the segment-vocab table remains intentionally N-A by query-time substitution.
+
+### 2026-07-14 — LANDED DEFER item E: #1212 (`a3f9008`) bounded-memory resolution tail (2 PORTs; golden-neutral)
+
+Re-evaluated DEFER item E — `a3f9008` _"bounded-memory yielding pipeline tail +
+daemon session fixes (#1212) (#1226)"_ — after a momus review. #1212 is MOSTLY
+N/A (its TS event-loop yields and OOM'd synthesizers do not exist in this port),
+but it has a REAL, golden-neutral Rust port. 7-part classification (each cited
+against the current tree):
+
+| #   | #1212 sub-part                                                  | verdict                                                                            | cited Rust evidence + one-line rationale                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | event-loop yield points in 31 synthesis passes                  | **N/A (TS-only)**                                                                  | Rust resolution is rayon data-parallel (`resolver.rs` `resolve_chunk_parallel` → `.par_iter().map().collect()` over the `Sync` snapshot), not a JS event loop; no in-process liveness watchdog a synchronous span blocks. No analogue to `await yieldPoint()`.                                                                                                                                                                                         |
+| 2   | whole-graph snapshot OOM — kotlin `getAllNodes()` 2M-node array | **PORT (reachable + streamable)**                                                  | `SnapshotResolutionContext::from_store` (`snapshot_context.rs:92-174`) does `store.all_nodes()` (`:94`) then materializes every node across six whole-graph maps + `build_edge_adjacency` (`:347-363`) reads `all_nodes()` again — O(graph)×copies at kernel scale. `StoreResolutionContext` (`context.rs:28-63`) already gives byte-equivalent ordered lookups over bounded LRUs, so a large-graph fallback bounds memory to batch + LRU. **LANDED.** |
+| 3   | kotlin expect/actual SQL-side filter                            | **N/A (pass absent)**                                                              | No kotlin expect/actual synthesizer exists in `codegraph-resolve`.                                                                                                                                                                                                                                                                                                                                                                                     |
+| 4   | c-fnptr LRU-bounded caches                                      | **N/A (pass absent)**                                                              | No C function-pointer dispatch synthesizer exists (`#932` is DEFER).                                                                                                                                                                                                                                                                                                                                                                                   |
+| 5   | spring reads each `.java` once, not twice                       | **N/A (pass absent)**                                                              | Only per-ref Spring DI receiver-typing exists (`name_matcher.rs`), not a whole-repo `publishEvent` event→listener synthesizer.                                                                                                                                                                                                                                                                                                                         |
+| 6   | `runMaintenance` off-thread + post-index WAL checkpoint         | **ALREADY-HAVE (valve) + PORT (extend to resolution loop) + N/A (worker offload)** | WAL valve landed R-A/#1231 (`queries.rs` `checkpoint_wal_if_over`), but was called ONLY in spill-replay (`main.rs:3525`/`:3536`), NOT the batched-resolution write loop. **LANDED:** the valve now also fires after each resolution-batch write. The worker-thread offload is N/A (no main-thread heartbeat).                                                                                                                                          |
+| 7   | daemon socket-handoff race + `pool.ready` gate                  | **ALREADY-HAVE / N/A**                                                             | The active daemon path (`session.rs` `serve_session_async`) reads the hello + all bytes from one long-lived buffered reader — no Node stream-mode discard. #1200/#1185 already landed R-A. `pool.ready` is a Node cold-start tweak, no analogue.                                                                                                                                                                                                       |
+
+**LANDED PORTs (both golden-neutral, memory/IO only):**
+
+1. **Large-graph streaming fallback** — `resolver.rs`
+   `resolve_and_persist_batched_inner` (shared by the public wrappers): when node
+   count `>= RESOLVE_STREAMING_NODE_THRESHOLD` (default `1_000_000`, override
+   `CODEGRAPH_RESOLVE_STREAMING_THRESHOLD`), resolve each batch SERIALLY through a
+   per-batch `StoreResolutionContext` over the live store instead of the
+   `SnapshotResolutionContext` + rayon path. Prior-batch `implements`/`extends`
+   edges are committed before the next batch reads them, so `get_supertypes` sees
+   the same cross-batch growth `build_edge_adjacency` provides. Same rowid cursor,
+   persistence order, deletion order, marker, and #750/#808 passes. The default
+   threshold is high enough that normal repos ALWAYS keep the unchanged snapshot
+   path (byte-identical output; every golden fixture exercises it).
+2. **WAL valve in the resolution write loop** — the same env-gated
+   `store.checkpoint_wal_if_over(wal_valve_bytes)` (TRUNCATE-only, row-neutral)
+   now fires after each resolution-batch write, bounding WAL growth through the
+   resolution tail, not just spill-replay. `CODEGRAPH_NO_WAL_DEFER` /
+   `CODEGRAPH_WAL_VALVE_MB` govern it exactly as before.
+
+**Golden-verification bridge:** the dual-path equivalence test
+`streaming_fallback_matches_snapshot_across_multiple_batches` (`resolver.rs`
+tests) forces batch_size 1 (≥2 batches, asserted) with a cross-batch
+`Sub extends Base` / `sub.ping()` case, runs BOTH paths on separate identical
+stores, and asserts `nodes`/`edges`/`unresolved_refs` byte-identical — so the
+snapshot path's golden verification transitively covers the fallback. A deliberate
+fallback perturbation was confirmed to fail the assertion (teeth), then reverted.
+`wal_valve_fires_during_resolution_batch_writes` asserts the valve fired DURING
+resolution (telemetry counter) and that the resolved graph is byte-identical valve
+on vs off. `cargo test -p codegraph-bench` passes with NO regen; goldens unchanged.
+
+Tracked parity STILL `1.2.0` — advances to `1.4.1` only in the final ledger step
+once every PORT item lands.
+
+### 2026-07-14 — LANDED Release D: C++ namespace/template resolution + UE macro recovery + `.h` detection + Lua gate
+
+Ports the C++ half of the `1.2.0..1.4.1` PORT subset plus the folded-in Lua
+resolve fix. Tracked parity STILL `1.2.0` — it advances to `1.4.1` only in the
+final ledger step once every PORT item lands. Five upstream items landed:
+
+- **C++ namespace-block qualified names + `ns::fn()` resolution** (from
+  `e1a8d88`, the CUDA commit): `codegraph-extract/walker.rs` gains a
+  `namespace_prefix` stack pushed on `namespace_definition` (prefix-only, no
+  namespace node — avoids the #1093 crowd-out) and seeded into
+  `build_qualified_name`. `ns::fn()` calls resolve for free via the existing
+  qualified-name matcher (no resolver change). C++17 `namespace a::b {` included;
+  anonymous namespaces fall through to bare names.
+- **C++ template-arg call linking `fn<T,256>()`** (from `e1a8d88`):
+  `extract_call` strips template args on C++/C callees via the existing
+  `strip_cpp_template_args` (the #1043 base-class normalization), excluding
+  `operator<`/`operator<<`.
+- **#1158 / `8e697a0` — UE in-body reflection-macro recovery**: `CppSpec` now
+  overrides `pre_parse` with three offset-preserving byte-blanking passes
+  (`blank_cpp_api_prefix_macros`, `blank_cpp_inline_annotation_macros`,
+  `blank_cpp_annotation_macro_calls`), each `contains`-gated so macro-free C++ is
+  byte-identical. The look-ahead boundaries upstream used are reimplemented in
+  code (the `regex` crate has none).
+- **#1159 / #1133 / `c049d9e` — `.h` C-vs-C++ detection**: `looks_like_cpp` /
+  `looks_like_objc` sniff the 8 KB source prefix inside `extract_source` and
+  reclassify a `.h` from C to C++/ObjC. The path-only `detect_language` and its
+  watch/cli/resolve callers are UNCHANGED (they pass no source, so default-C
+  holds — matching upstream).
+- **#1124 / `e53968c` — Lua/Luau annotation self-match gate**: the shipped Rust
+  pattern was a broken lookahead port (`(?!` is silently `.ok()`-dropped by the
+  `regex` crate), so `obj:Method()` still self-matched. Fixed CODE-SIDE:
+  `local_receiver_type_patterns_tagged` tags the annotation regex and
+  `infer_local_receiver_type` rejects the capture via
+  `lua_annotation_is_method_call` when a Lua call form (`(`/`"`/`'`/`[`/`{`) or a
+  `[\w.]` continuation follows.
+
+Two discoveries worth recording: (a) the namespace + template-arg-call code lives
+in the CUDA commit `e1a8d88`, whose CUDA (`blankCudaConstructs`,
+`looksLikeCudaSource`) and local-fn-ptr (`cppLocalFnPtrs`) slices were
+DELIBERATELY EXCLUDED (they belong to a future CUDA release); (b) the pre-existing
+Rust Lua pattern was a broken lookahead port, fixed with a code-side gate rather
+than an (unsupported) regex look-ahead.
+
+Golden: a DELIBERATE `cpp` fixture BUMP. The corpus gained `namespaced.cpp`,
+`templated_call.cpp`, and `ue_actor.h`; the diff is exactly (i) `Tpl`/`Tpl::wrap`
+→ `ns::Tpl`/`ns::Tpl::wrap` (node-ids stable — name is unqualified), (ii) the
+`Q : ns::Tpl<int>` base migrating unresolved→resolved (`Extends` edge appears,
+ref leaves `refs.json`), and (iii)-(iv) the three new files' additive
+file/symbol/Contains records + the intended `ns::compute()` / `process<int>()` /
+`UFoo`→`UObject` edges. `godot`/`ruby`/`mini` goldens byte-identical.
+
+### 2026-07-10 — EVALUATION 1.2.0 → 1.4.1 (parity NOT yet advanced; PORT subset in progress)
+
+Ran Workflow A's diff step against the live upstream delta,
+`git diff v1.2.0..v1.4.1 -- src/` (76 files, +10965/−1209). The range is
+dominated by 11 new language grammars and a prompt-hook feature suite — bulk
+that doesn't map cleanly to this port — so the portable high-value subset out
+of it is small. Two items from this range are already landed under other
+entries: #1043 (C/C++ templated-base inheritance, `v0.27.0`) and #1064 (explore
+change-surface rescue, `v0.28.0`) — both recorded above, not repeated here.
+Tracked parity stays `1.2.0`; the table below is the chosen PORT set, in
+progress across four releases (A/B/C/D), plus the ALREADY-HAVE / N-A / DEFER
+dispositions for everything else in range.
+
+**PORT (chosen, in progress)**
+
+| upstream # / commit                                                                                                                      | title                                                                                                                                                                                          | Rust target                                                                                         | golden impact                | disposition                                                         |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| #1220 / `70b1be6`                                                                                                                        | PHP `$this->dep->method()` resolves via property declared type                                                                                                                                 | `codegraph-resolve/name_matcher.rs` + codegraph-extract PHP field types                             | golden bump                  | PORT (Release C)                                                    |
+| #1231 (WAL-valve half) / `a11a439`                                                                                                       | defer WAL checkpoint write-back during bulk index (`CODEGRAPH_NO_WAL_DEFER` / `CODEGRAPH_WAL_VALVE_MB`)                                                                                        | `codegraph-store/connection.rs`                                                                     | golden-neutral               | PORT (Release A)                                                    |
+| #1187 / `4c15f84`                                                                                                                        | orphaned unresolved-ref sweep so an interrupted index heals on sync + partial-index status warning                                                                                             | `codegraph-watch/sync.rs`, CLI `status`, MCP `status`                                               | golden-neutral               | PORT (Release A)                                                    |
+| #1200 / `356f5f7`                                                                                                                        | daemon inactivity backstop gated on client liveness                                                                                                                                            | `codegraph-daemon/lib.rs`                                                                           | golden-neutral               | PORT (Release A)                                                    |
+| #1185 / `c9f8c0e`                                                                                                                        | reap server when launcher killed during startup + `CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS` backstop                                                                                            | `codegraph-daemon/spawn.rs`                                                                         | golden-neutral               | PORT (Release A)                                                    |
+| C++ namespace-block qualified names + `ns::fn()` resolution + template-arg `fn<T,256>()` call linking (part of 1.3.0, code in `e1a8d88`) | —                                                                                                                                                                                              | `codegraph-extract/walker.rs` (namespace prefix + template-call strip; `name_matcher.rs` unchanged) | golden bump (cpp fixture)    | **LANDED (Release D, 2026-07-14)**                                  |
+| #1158 / #1159 / #1133 (`8e697a0`, `a9e8fa4`, `c049d9e`)                                                                                  | recover heavily-reflected Unreal Engine C++ classes (in-body reflection macros, member-level `*_API`, mid-line `UMETA`/`UPARAM`/`UE_DEPRECATED`, `.h` C-vs-C++ detection through export macro) | `codegraph-extract/lang/cpp.rs` (`pre_parse` blanking) + `engine.rs` (`.h` content sniff)           | golden bump (cpp fixture)    | **LANDED (Release D, 2026-07-14)**                                  |
+| #1124 / `e53968c`                                                                                                                        | Lua/Luau capitalized `obj:Method()` misread as type annotation                                                                                                                                 | `codegraph-resolve/name_matcher.rs`                                                                 | golden-sensitive (Lua edges) | **LANDED (Release D, 2026-07-14; golden-neutral — no Lua fixture)** |
+| #1063 / `2a06d9a`                                                                                                                        | `codegraph.json` `include` list to force gitignored first-party source in                                                                                                                      | `codegraph-core/config.rs` + codegraph-extract scan + codegraph-watch policy                        | golden-neutral               | PORT (Release B)                                                    |
+| #1182 / `f5edf8c`                                                                                                                        | iBatis2 `<sqlMap>` coverage + MyBatis quote/comment robustness + dup-id                                                                                                                        | `codegraph-extract/embedded/mybatis.rs`                                                             | golden bump                  | PORT (low; optional)                                                |
+| #1243 / `4782394`                                                                                                                        | MCP update-available notice (background, once/day, honors `DO_NOT_TRACK` / `CODEGRAPH_NO_UPDATE_CHECK`)                                                                                        | `codegraph-mcp/engine.rs` status                                                                    | golden-neutral               | PORT (low; UX)                                                      |
+
+**ALREADY-HAVE**
+
+| upstream #    | what it does                                 | Rust evidence                                                                                                        |
+| ------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| #1129 / #1130 | typed-param receiver inference               | `name_matcher.rs:765-833`, landed R5 (`v0.26.0`) — Rust already covers more languages than this upstream change adds |
+| #1240         | incremental cross-file re-resolve            | `codegraph-watch/sync.rs` + `queries.rs` already re-resolve in both directions                                       |
+| #1235         | closure-collection scan across all languages | no Rust analogue exists for this to duplicate — the described failure mode cannot occur here                         |
+
+**N/A (TS/Node-only)**
+
+| upstream #                 | why it doesn't apply                                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| #1231 (parse-timeout half) | worker-clock race is a Node worker/coordinator artifact; Rust indexing is rayon in-process with compiled-in grammars — no separate worker clock to race |
+| #1238                      | npm self-shadow — npm-specific install-path collision, no Rust analogue                                                                                 |
+| #1071                      | uninstall binaries — npm/install.sh lifecycle step, not applicable to the cargo-installed/binary-download build                                         |
+| #1238                      | `install --refresh` — npm reinstall flow, no Rust analogue                                                                                              |
+| #1238                      | Windows `npm.cmd` shim handling — npm-only                                                                                                              |
+| #1180                      | Spring config-key scan — this port has no Spring config-key resolver at all; not a gap this upstream fix closes                                         |
+| #1156                      | gitignored child-repo offer — no embedded-repo discovery mechanism exists in this port (already recorded as an architecture gap in earlier entries)     |
+
+**DEFER**
+
+| item                                                                                                                             | why deferred                                                                                                                                                                                                               |
+| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 11 new languages (Nix, ArkTS, Terraform, CUDA, Solidity, Erlang, VB.NET, COBOL, CFML, Metal + iBatis2 counted as low PORT above) | each needs a grammar crate + `LanguageSpec` + golden fixture; Metal/CUDA are cheapest (ride the existing C++ grammar)                                                                                                      |
+| prompt-hook suite (#1126 / #1136 / #1138 / #1141-1146 + telemetry)                                                               | large surface; telemetry conflicts with this project's no-tracking posture — if pursued, cherry-pick the multilingual/plain-words gate WITHOUT the telemetry half                                                          |
+| #1252                                                                                                                            | explore NL-word guard — Rust `explore` is FTS-seeded, not token-seeded, so applicability is low; `KNOWN_DIFFS.md` already records relevance re-ranking as intentionally not ported                                         |
+| #1212                                                                                                                            | ~~snapshot-OOM streaming refactor~~ — **RE-EVALUATED + LANDED 2026-07-14** as DEFER item E (large-graph streaming fallback + resolution-loop WAL valve; both golden-neutral). See the 2026-07-14 DEFER-item-E entry above. |
+| #1114                                                                                                                            | dead reasoning-offload cleanup — Rust never had the reasoning-offload feature, so there's nothing to remove                                                                                                                |
+
+**Outcome:** tracked parity remains `1.2.0`. A 4-release PORT program is in
+progress: Release A is a golden-neutral robustness bundle (#1187 + #1200 +
+#1185 + #1231's WAL-valve half); Release B is #1063 `include`; Release C is
+#1220 (PHP property-typed receiver); Release D is C++ namespace/template
+resolution + Unreal Engine macro recovery. A DEFER phase follows (snapshot-OOM
+#1212, the prompt-hook suite minus telemetry, then the 11 new languages).
+Tracked version advances to `1.4.1` only once the chosen PORT items above
+actually land; the three low/optional items (#1124, #1182, #1243) may fold into
+a related release round or be individually deferred at that time.
+
+### 2026-07-07 — PORT #1064 explore change-surface rescue (explore-side only)
+
+Ports upstream `2b256b9` (`fix(explore): surface a named method's buried
+signature type (#1064)`, shipped in colby 1.1.5) into this project's
+deterministic explore, adapted to the query/ranking spine (no RWR/graph-mass
+score exists here). Extraction is UNCHANGED — the signature edge the rescue
+follows (`References`, function→param-type) already exists for TS/TSX, proven by
+a live 2-file repro; extraction-widening to emit `TypeOf`/`Returns` for more
+languages is DEFERRED.
+
+| Round | Upstream          | Disposition | codegraph-rs | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----- | ----------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| B     | #1064 / `2b256b9` | PORT        | `v0.28.0`    | `codegraph-mcp/src/engine.rs` `find_relevant_context`: (1) named-seed **tier de-noise** — only the top callable seed + any seed with caller-count ≥ 25% of the max is tiered, so a low-centrality namesake can't flood the tier; (2) **change-surface rescue** — from each tiered callable seed, follow outgoing signature edges (`References`/`TypeOf`/`Returns`) to TYPE-kind nodes; a type whose file is BURIED (not a seed file AND < 2 query-term hits) is inserted + marked `rescued_files` so `finalize` floats it to a new TOP tier (3). Deterministic: candidates sorted by `(file, line, id)` before insert; no HashMap/HashSet iteration reaches output. Query/ranking-side only → **golden unchanged** (the mini golden's `Counter add runDemo` query has only primitive `number` param types, so the rescue never fires). |
+
+### 2026-07-06 — FULL SYNC `1.1.2 → 1.2.0` (advances tracked parity to 1.2.0)
+
+Ported the actionable subset of the `1.1.2..1.2.0` upstream delta, in six
+momus-approved, individually-released, Final-Wave-gated rounds (each: TDD ≥95%
+patch coverage → golden regen where extraction/resolution changed → 4-reviewer
+Final Wave → own `fix:`/`feat:` release). Schema round ran first so later rounds
+regenerated golden against the final schema.
+
+| Round | Upstream                                     | Disposition | codegraph-rs | Notes                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ----- | -------------------------------------------- | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| R0    | #1034                                        | PORT        | `v0.25.2`    | UNIQUE edge-identity index + migration v7 (dedup keep-lowest-id then create index). `.schema` golden bump; golden fixtures had no dup edges so edges.json unchanged.                                                                                                                                                                                                                                                  |
+| R1    | #1045, #1047, #1127                          | PORT        | `v0.25.3`    | query drops nonsensical `NNNN%` score (raw score kept in `--json`); Android `res/` default-excluded (res/raw + `src/main/resources` kept; `.gitignore` `!` negation now honored); auto-sync backs off + disables after repeated non-contention failures. Query/config/watch only — no golden.                                                                                                                         |
+| R2    | #1086, #1087, #1089, #1090 (#1088 lock-test) | PORT        | `v0.25.4`    | impact keeps direct edge to already-reached node; callers/callees keep multi-KIND edges; hard node-limit enforced per-insertion. Query-side; golden unchanged.                                                                                                                                                                                                                                                        |
+| R3    | #1093, #1096, #1061, #1035, #1100-#1103      | PORT        | `v0.25.5`    | C++ extraction: skip bodiless forward decls (C/C++-gated; Kotlin/Scala kept), conversion-operator names, export/visibility-macro class recovery, stack/brace construction Instantiates, inline-specifier-macro name/return-type recovery. Guarded by unit tests; retroactively byte-guarded by the `reference/golden/cpp/` fixture added with #1043 in `v0.27.0`.                                                     |
+| R4    | #1110                                        | PORT        | `v0.25.6`    | Ruby `receiver.method` calls now emit edges (`Const.new`→Instantiates, else→Calls); bare `include/extend/prepend` unchanged. Added a Ruby golden fixture (`reference/golden/ruby/`) + equivalence test.                                                                                                                                                                                                               |
+| R5    | #1108, #1125, #1112, #1079                   | PORT        | `v0.26.0`    | Receiver-type inference generalized beyond C++ to TS/JS/Python/Java/C#/Kotlin/Swift/Go/Rust/Dart/Scala/PHP (local-var + typed-param); Lua `:` / R `$` / Pascal `.` separators; same-file preference in 3 method-call paths. All validated via `resolve_method_on_type` (wrong guess → no edge). Mini golden's 3 local-var instance-method edges rose 0.8→0.9 to match upstream 1.2.0's receiver-inference confidence. |
+
+**DEFERRED (recorded, not ported):**
+
+- **#1043 / `703629e`** — C/C++ inheritance from a templated base. ~~This project has
+  no general C++ `base_class_clause` inheritance extraction yet~~ **PORTED** in
+  codegraph-rs `v0.27.0` (general C++ `base_class_clause` extraction + template
+  stripping; added a C++ golden fixture).
+- **#1064** — `explore` change-surface rescue. **PORTED** 2026-07-07 (explore-side
+  only, over the existing `References` signature edge; see the 2026-07-07 entry
+  above). Extraction-widening (emit `TypeOf`/`Returns` for more languages) stays
+  DEFERRED — not needed for the TS/TSX value.
+
+**ALREADY-HAVE (verified, no work):** #1088 (node-id visited dedup, locked with a test in R2), #1046 (explore count).
+
+**N/A (no Rust analogue):** #1044 (CLI `node` subcommand — MCP file-mode already works), #1091 (index watchdog yield), #1092 (Windows console-flash windowsHide), #1041 & gitlink nested-repo items, `dfe13b0` (MCP worker pool), and all `install.sh` / npm / PATH-shadow / bundled-Node items (the Rust build has no npm/install.sh).
+
+### 2026-06-30 — DOWNSTREAM forward-port: always-expose tools/list + required projectPath (issue #94)
+
+This is a **targeted downstream forward-port**, NOT a full upstream sync. Tracked
+colby parity stays `1.1.2` — this entry does not advance it.
+
+Commit `35935be` (branch `feat/mcp-autodetect-no-default-tools`) ports two
+upstream behavioral fixes that were missing from this Rust port, driven by issue
+#94 (通义灵码/Lingma shows 0 tools when no `-p` is given):
+
+- **colby #964 (PR #966)** — `tools/list` ALWAYS returns the visible tool surface,
+  even when no default project is resolved. The prior Rust behavior returned an
+  empty array (`[]`) for the no-default path, which is the #94 root cause.
+- **colby #993 (PR #1007)** — when no default project resolves, `projectPath` is
+  added to each tool's `inputSchema.required` array (a schema-level nudge so a
+  roots-less client's agent supplies the path per call). When a default project IS
+  resolved, `projectPath` stays OPTIONAL (byte-identical to the indexed case).
+
+**Supersedes the 2026-06-28 `d3179f5` ALREADY-HAVE disposition** (see triage
+table below at line 60): that entry called our "hide all tools when no default
+project" behavior "stronger" than upstream's `d3179f5` approach, but that
+hide-all is the #94 root cause. We now adopt colby's always-list (#964) +
+required-projectPath (#993) instead.
+
+Golden artifacts stayed byte-identical — the change only affects the no-default
+path, which no golden frame exercises (`git diff reference/` empty). `make ci`
+green; `cargo test -p codegraph-bench` green; `docs/upstream-sync/KNOWN_DIFFS.md`
+untouched.
+
+| item                   | disposition       | note                                                                                                                                                                                                          |
+| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| colby #964/PR#966      | **PORT (landed)** | `tools/list` always returns visible tools; Rust `dispatch` arm in `server.rs` changed from `Value::Array(Vec::new())` to `schemas::visible_tool_definitions_requiring_project_path()` on the no-default path. |
+| colby #993/PR#1007     | **PORT (landed)** | `with_required_project_path()` pure fn injects `"projectPath"` into each tool's `inputSchema.required`; fires only on the no-default branch; idempotent.                                                      |
+| `d3179f5` (superseded) | **SUPERSEDED**    | The prior ALREADY-HAVE disposition (2026-06-28) incorrectly called hide-all "stronger". The hide-all behavior was the #94 root cause and is now reversed.                                                     |
+
+### 2026-06-28 — LANDED `v1.1.1..v1.1.2` PORT items (codegraph-rs `v0.20.0`)
+
+Shipped the portable subset of `v1.1.1..v1.1.2` in PR #90 → release `v0.20.0`
+(three feature commits + one Windows-clippy fixup). Tracked parity advanced to
+`1.1.2`. Golden impact: the ONLY `reference/` change was
+`reference/golden/mcp/tools_list.json` (the deliberate `readOnlyHint`
+annotations); the extraction corpus is byte-unchanged. `make ci` green, golden
+oracle green, Final Verification Wave (F1 goal/constraint + F2 code quality +
+F3 golden/invariant) all APPROVE.
+
+| commit        | landed as                            | disposition (final) | note                                                                                                                                                                                                                                                   |
+| ------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `a79fa51`     | `feat(mcp)` readOnlyHint annotations | **PORTED**          | all 10 source tool defs annotated `{readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:false}`; golden fixture + `golden_mcp.rs` assertion extended to compare `annotations` (load-bearing).                                 |
+| `f83a1ec`     | daemon FS fallback                   | **PORTED**          | `bind_with_fallback` walks a deterministic socket-candidate chain on bind failure; chosen socket persisted into the lock; all 4 client sites read `recorded_socket_path` (pid/lock stays at `.codegraph/daemon.pid`). golden-neutral.                  |
+| `45d3293` pt1 | name-ceiling                         | **PORTED**          | `AMBIGUOUS_NAME_CEILING=500` (env `CODEGRAPH_AMBIGUOUS_NAME_CEILING`); gates ONLY `match_fuzzy` + the multi-candidate `find_best_match` branch of `match_by_exact_name`. Edge-producing strategies untouched → golden edges byte-identical (verified). |
+| `45d3293` pt2 | `[indexing] exclude`                 | **PORTED**          | TOML `exclude: Vec<String>` (`#[serde(default)]`), root-relative patterns threaded via `ExtractOptions` through the filesystem walk; honored by index AND sync. Off-by-default. NO git-tracked framing (Rust has no git layer — D-Exclude).            |
+| `7a361ef`     | docs for `exclude`                   | **PORTED**          | README + `docs/cli.md`/`docs/mcp.md` document `exclude`, readOnlyHint, daemon FS fallback.                                                                                                                                                             |
+| `b3f59c7`     | Swift computed properties            | **PORTED**          | computed `var body { ... }` / accessors → `property` node, getter routed through the function-body walk; `protocol var x { get }` → `property`; stored/static unchanged. Golden-neutral (no `.swift` in the TS+Py corpus); locked by 5 new unit tests. |
+| `dfe13b0`     | —                                    | **N-A**             | MCP read-tool worker pool. The Rust MCP server is synchronous single-stdin (`server.rs`); concurrent-call starvation cannot occur, so the fix has no Rust analogue. Not ported by design.                                                              |
+| `703629e`     | —                                    | **DEFER**           | C/C++ function-pointer command tables. Rust has no C/C++ resolver foundation; deferred as a future capability-build (user-approved exclusion from this batch).                                                                                         |
+
+(ALREADY-HAVE / N-A items `d3179f5`, `30dc303`, `9716fb2`, `b45f309` need no
+action — see the triage entry below for evidence.)
+
+### 2026-06-28 — triaged `v1.1.1..v1.1.2` (PORT items NOT yet landed)
+
+Read the real per-commit diffs of the 11 meaningful commits in `v1.1.1..v1.1.2`
+and classified each against the Rust code (file:line both sides). This is a
+**triage** — tracked parity stays `1.1.1` until the PORT items land. Two highest-
+stakes items cross-checked by hand (30dc303 SQLite, b45f309 prompt-hook).
+
+| commit    | what it does                                                                                     | Rust status                                                                                                                                                         | disposition      | golden                                       |
+| --------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------- |
+| `dfe13b0` | MCP off-loads read-tool dispatch to a worker pool (fix concurrent-call timeouts)                 | MCP server is synchronous/serial (`crates/codegraph-mcp/src/server.rs`, `engine.rs:60-81`) — no worker pool                                                         | **PORT**         | none                                         |
+| `703629e` | C/C++ function-pointer command tables (macro-built / conditional / bare arrays)                  | No C/C++ resolver at all (extraction only; no `frameworks/c*`)                                                                                                      | **DEFER**        | would change output                          |
+| `b45f309` | prompt-hook: structured detection for non-English prompts                                        | No prompt-hook / front-load-hook feature in Rust (grep: only unrelated "structural" hits; installer only writes MCP config)                                         | **N/A**          | none                                         |
+| `d3179f5` | require `projectPath` when MCP server has no default project                                     | Rust already stronger: hides all tools when no default project (`server.rs:374-380`) + errors on missing path (`:439-455`)                                          | **ALREADY-HAVE** | none                                         |
+| `45d3293` | `codegraph.json exclude` config + resolver ambiguous-name ceiling (anti-wedge) + index watchdogs | Rust config is `.codegraph/config.toml` with only `ignore_dirs` — no `exclude`; resolver has no name-ceiling (`config.rs:48-58`, `resolver.rs:882-992`)             | **PORT**         | exclude none; name-ceiling may affect golden |
+| `7a361ef` | docs for `exclude`                                                                               | depends on 45d3293 landing first                                                                                                                                    | **DEFER**        | none                                         |
+| `f83a1ec` | daemon on ExFAT/FAT/network FS — socket/lock candidate fallback after bind failure               | Rust only does tmp fallback for over-long Unix paths, binds a single socket, no bind-failure retry (`daemon/src/paths.rs:24-31`, `lib.rs:259-270`, `lock.rs:66-71`) | **PORT**         | none                                         |
+| `30dc303` | chunk `deleteResolvedReferences` IN-list under SQLite param limit (public QueryBuilder API)      | Rust delete path binds **per-row** (`queries.rs:677-693`), structurally immune; chunking (`SQLITE_PARAM_CHUNK_SIZE=500`) already systemic                           | **ALREADY-HAVE** | none                                         |
+| `b3f59c7` | index Swift computed properties (computed→property, getter calls attributed)                     | Rust does not node-ify Swift computed properties (`extract/src/walker.rs:149-160`, `lang/swift.rs`)                                                                 | **PORT**         | changes extraction → golden bump             |
+| `9716fb2` | parallelize indexing via parse worker pool                                                       | Rust already parallel-indexes via rayon file-level parallelism (`extract/src/engine.rs:21-36, 213-217`) — different design, same capability                         | **ALREADY-HAVE** | none                                         |
+| `a79fa51` | MCP `readOnlyHint`/annotations so tools work in Cursor Ask mode                                  | Rust `tools/list` emits schema/value only, no `annotations` (`server.rs:374-380`)                                                                                   | **PORT**         | none                                         |
+
+**PORT backlog from this range (pending user go-ahead), low-risk-first:**
+
+1. `a79fa51` MCP readOnlyHint annotations — golden-neutral, small.
+2. `f83a1ec` daemon FS fallback chain — golden-neutral, daemon robustness.
+3. `dfe13b0` MCP read-tool worker pool — golden-neutral, concurrency.
+4. `45d3293` `exclude` config (+ later the resolver name-ceiling, which may touch golden).
+5. `b3f59c7` Swift computed properties — **golden bump** (extraction change), isolate.
+6. `703629e` C/C++ fn-pointer resolver — large; needs a C/C++ resolver foundation first.
+
+**No-action:** `d3179f5`, `30dc303`, `9716fb2` (ALREADY-HAVE); `b45f309` (N/A); `7a361ef` (DEFER until `exclude` lands).
+
+Newest first. Each entry covers one sync of an upstream version range and records
+every meaningful change with its disposition:
+**PORT** (landed in Rust) · **ALREADY-HAVE** (port already implemented it) ·
+**N/A** (TypeScript-only, no Rust analogue) · **DEFER** (real but postponed).
+
+### 2026-06-27 — downstream-only features (no upstream sync)
+
+NOT an upstream sync. Two **downstream-only** features were added to this Rust
+port that have **no analogue in colby** (verified against colby `v1.1.1` HEAD on
+2026-06-27: `git grep` over upstream `src/` + CLI command inventory + docs/tests
+found no orphan/dangling audit command and no Godot id-field / DSL-schema config).
+Both are Godot-research conveniences requested by a downstream Godot/WorldFlipper
+user; they do not change extraction output (golden byte-neutral). Tracked colby
+version is UNCHANGED at `1.1.1` — these do not advance parity.
+
+| feature (this port only)                                                                                                                                                                                                                                                                                            | disposition     | rationale / golden impact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Resource audit** — read-only `codegraph audit` subcommand: orphan `.tres`/`.tscn` resources, dangling path references, reverse-dependency impact (`crates/codegraph-graph/src/graph/mod.rs` `find_orphan_resources`/`find_dangling_references`/`resource_impact`; `crates/codegraph-cli/src/main.rs` `cmd_audit`) | DOWNSTREAM-ONLY | No upstream analogue. Pure read-only over the existing graph + on-disk existence checks — adds NO extraction, NO node/edge writes. Golden byte-neutral (`git diff reference/` empty). Keyed on resource PATHS (godot resource files have no `file:` node; refs live in `unresolved_refs`). Separate `audit` subcommand leaves `check` byte-identical (committed snapshot test). Exclusions: `.godot/`/`addons/` prefix → `godot:dynamic:` → on-disk existence.                                                                  |
+| **Opt-in `idFields` DSL** — capture bare/compound IDs in `.tres` `[resource]` bodies as `godot:id:<kind>:<value>` sentinel references via `.codegraph/codegraph.json` `godot.dsl.idFields` (`crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs`, `godot_resource.rs` `dsl_id_targets`)                    | DOWNSTREAM-ONLY | No upstream analogue (upstream has no godot id-field/schema config). Golden byte-neutral by two-part mechanism: (1) opt-in gating — fires ONLY when `idFields` is configured, and committed golden corpora have no such config; (2) sentinel-unresolvability — a colon-delimited `godot:id:*` literal can never name-match a node (`match_fuzzy` callable/type kinds only), so it stays in `unresolved_refs`, never becomes a golden `edges` row. No domain hardcoding — all field names/kinds/separators are project-supplied. |
+| Bundled fix: Godot DSL config resolved against PROJECT ROOT, not process CWD (`FrameworkResolver::extract` gains an additive `project_root` param; `config_lookup_path`)                                                                                                                                            | DOWNSTREAM-ONLY | Fixes a latent defect (shared by the pre-existing `resourceFields`): the framework resolver received a relative path and joined it onto CWD, so the per-project config was only found when CWD == project root. Now config lookup uses `project_root.join(file_path)` while node/ref attribution stays RELATIVE (golden-safe). Locked by an e2e CLI test that indexes from a foreign CWD.                                                                                                                                       |
+
+**Outcome:** two downstream-only Godot conveniences landed; colby parity unchanged
+at `1.1.1`. No golden impact, no upstream divergence (these are additive features
+upstream does not have, not deviations from upstream behavior). Should a future
+colby release add a comparable audit or id-schema feature, reconcile naming/shape
+against these at that sync.
+
+### 2026-06-26 — synced `v1.1.0` -> `v1.1.1`
+
+A small upstream patch release: two `fix(...)` commits plus release/changelog
+chores. `git diff v1.1.0..v1.1.1` against the live upstream source. **No PORT
+items** — both fixes are either a TypeScript/Node-architecture-specific problem
+with no Rust analogue, or behavior this port already has. The proxy half of #983
+was verified line-by-line against `codegraph-daemon::proxy::run_proxy` and its
+CLI callers before recording it as ALREADY-HAVE. Golden output untouched (no
+extraction change in range). Tracked version advanced to `1.1.1` (upstream HEAD).
+
+| upstream change                                                                                                                                                                                                                                                                                                    | disposition                   | rust landing / rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| #983 (`7c6417e`) daemon half — release the lockfile when `bind` fails (e.g. AF_UNIX flaky on WSL2 `/mnt` DrvFs) so the next launcher doesn't spin on a stale lock (`src/mcp/daemon.ts:183-198`)                                                                                                                    | ALREADY-HAVE                  | `start_with_lock` calls `bind(&rendezvous)?` with `?`: a bind failure propagates up to the `try_acquire_daemon_lock` caller and the RAII lock guard releases the pid lock automatically — no stale lock pointing at a dying pid, no duplicate `serve --mcp` pileup. Structurally cannot leave a hung lock.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| #983 (`7c6417e`) proxy half — a daemon-socket `error` with no listener became a Node `uncaughtException` → `process.exit(1)`, which the MCP client saw as a bare "Transport closed"; fix attaches a lifelong no-op `error` listener so it degrades to the in-process fallback (`src/mcp/proxy.ts:135-145,323-336`) | ALREADY-HAVE (verified)       | Node-specific defect with no Rust analogue. In `run_proxy`, every socket error is an explicit `io::Result::Err`, never an unhandled exception: connect failure → `Err` → CLI `Err` arm falls back to direct (`main.rs:1350`); hello-read failure → `?` → same fallback; host→daemon write failure → `pump_host_to_daemon` `Err` → `up_result?` → fallback; daemon→host read failure → `Err(_) => break` (treated as EOF, clean exit). No path lets an unhandled socket error panic/exit the process, so the "Transport closed" symptom cannot occur. (Minor design difference: on a mid-session daemon drop the Rust proxy exits the stdio session for a clean client reconnect rather than hot-swapping to an in-process engine — a normal transport close, not a crash.) |
+| #980 (`73bcc1a`) extraction — respect `.gitignore` by DEFAULT for embedded-repo discovery: gitignored dirs holding nested `.git` repos are no longer walked/indexed unless opted in via `codegraph.json` `includeIgnored` (#970, #976; `src/extraction/index.ts`, `src/project-config.ts`)                         | N/A (architecture difference) | colby's `git ls-files`-based discovery actively descended INTO gitignored dirs to find embedded `.git` roots (`findIgnoredEmbeddedRepos`), which over-indexed huge reference/data dirs of clones — the bug #980 fixes. This port's walker is a pure filesystem walk (`scan_project`/`scan_dir`, `engine.rs:221-256`): a gitignored dir is matched by `is_ignored_by_patterns` and the whole subtree is `continue`d/skipped. There is no embedded-repo discovery and never was, so the Rust port has ALWAYS exhibited the #980-fixed default (respect `.gitignore`). Nothing to port.                                                                                                                                                                                       |
+| #980 new `codegraph.json` `includeIgnored` opt-in config field                                                                                                                                                                                                                                                     | DEFER (no analogue yet)       | This is a new _feature_ (not the fix): opt-in to index gitignored embedded repos. It only has meaning alongside an embedded-repo / multi-repo-workspace discovery mechanism, which this port does not implement. Recorded as a known gap should a future "multi-repo workspace" direction be pursued; not actionable in this range.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ec0c625` / `4077ed1` / `1e48861` version bump + CHANGELOG edits; `__tests__/*` (daemon-bind-failure, proxy-connect, include-ignored-config, multi-repo-workspace)                                                                                                                                                 | N/A                           | release chores and TypeScript test files — no behavior to port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+**Outcome:** tracked version is `1.1.1` (upstream HEAD). No PORT items in this
+range; no golden impact (extraction output unchanged). The only deferred item is
+the `includeIgnored` config field, which is inert without an embedded-repo
+discovery mechanism this port intentionally lacks.
+
+**Next sync:** when upstream publishes a tag > `1.1.1`, run Workflow A from this
+point (`git diff v1.1.1..v<new>`). Outstanding port backlog is unchanged: the
+B-class extraction/framework golden-bump plan from the v1.1.0 range.
+
+### 2026-06-24 — synced `v1.0.1` -> `v1.1.0`
+
+First true catch-up delta since the baseline: `git diff v1.0.1..v1.1.0` against the
+live upstream source. The headline of v1.1.0 is the issue-#411 **live-watch daemon**
+architecture (a detached background daemon + thin per-client proxy sharing one file
+watcher), plus a batch of extraction/framework upgrades. This sync lands the entire
+**A-class** (daemon/proxy/watcher/robustness/UX — no extraction-output change, golden
+byte-untouched) on branch `feat/live-watch-daemon`. The **B-class** extraction ports
+(value-reference edges, framework dispatch synthesizers, etc.) are each recorded as
+**DEFER** below: every one of them changes extraction _output_ and therefore requires
+a deliberate golden regeneration, so they are scoped to a **separate future plan**
+rather than smuggled into this no-golden-bump sync.
+
+| upstream change                                                                                                                                                                                            | disposition  | rust landing / rationale                                                                                                                                                                                                                                                                                              |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Detached daemon process + launcher decision order (`CODEGRAPH_NO_DAEMON` opt-out, `CODEGRAPH_DAEMON_INTERNAL` be-the-daemon, no-`.codegraph/`→direct, else spawn+proxy) (`src/mcp/index.ts:260-292`, #411) | PORT         | `select_serve_mode` decision in `cmd_serve` + `spawn_detached_daemon` re-invokes the CLI with `CODEGRAPH_DAEMON_INTERNAL=1`, own process group (unix) / `DETACHED_PROCESS\|CREATE_NEW_PROCESS_GROUP` (windows), stdio→`.codegraph/daemon.log`, child dropped (unref) — daemon survives the launcher (this plan T1/T2) |
+| Per-MCPEngine file watcher in `serve --mcp`, direct + daemon (`src/mcp/engine.ts:178-240`)                                                                                                                 | PORT         | one `ProjectWatcher` in `cmd_serve` (direct) and one in the daemon process (`run_accept_loop`, shared by N clients — the #411 collapse of N inotify sets to 1); never per-session (this plan T3/T4)                                                                                                                   |
+| Non-blocking catch-up sync on open (#905)                                                                                                                                                                  | PORT         | background `sync_project_once` thread + `Arc<AtomicBool>` ready flag; the first `tools/call` never blocks on the reconcile (this plan T5)                                                                                                                                                                             |
+| Reopen DB when `.codegraph` is replaced on disk (#925, `src/db/index.ts`)                                                                                                                                  | PORT         | `engine_for` records the db file identity (unix inode / windows `file_index()`) at open and reopens the cached engine only on a true replacement — never on an in-place WAL write (this plan T6)                                                                                                                      |
+| Detached daemon needs a thin client proxy (local-handshake stdio↔socket pipe, hello-version verify, direct fallback, PPID watchdog, refcount-decrement-on-close) (`src/mcp/proxy.ts:194-289`, #277/#411)   | PORT         | `codegraph-daemon::proxy::run_proxy` answers `initialize`/`tools/list` locally from this build's static constants, suppresses the daemon's forwarded `initialize` reply, forwards the rest line-framed, verifies hello → `VersionMismatch` falls back to direct (this plan T7)                                        |
+| Daemon idle-linger + max-idle backstop (`DEFAULT_IDLE_TIMEOUT_MS=300000`, `MAX_IDLE_MS=1800000`, #692) (`src/mcp/daemon.ts:60-72,505-521`)                                                                 | PORT         | `run_accept_loop` tracks `last_active`, exits when idle past `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` with zero clients, and on the `CODEGRAPH_DAEMON_MAX_IDLE_MS` backstop regardless of count (this plan T8)                                                                                                              |
+| Dead-client sweep via a client-hello pid protocol (`DaemonClientHello`, `CLIENT_HELLO_TIMEOUT_MS`, `DEFAULT_CLIENT_SWEEP_MS=30000`, #692) (`src/mcp/daemon.ts:103-127,569-624`)                            | PORT         | optional `{"hostPid":N}` client-hello read from ONE long-lived `BufReader` (buffer-safe `run_session_recv` seam — no dropped JSON-RPC bytes), per-session pid in the registry, 30s sweep reaps peers failing `is_process_alive` (this plan T9)                                                                        |
+| Watcher degraded handling — EMFILE/ENFILE degrade, ENOSPC warn-not-degrade, bounded exp lock-retry backoff (cap 30s), `onDegraded`/`isDegraded` (`src/sync/watcher.ts` +254, #891/#892/#893)               | PORT         | `WatchOptions` gains `on_degraded`/`on_sync_error`; the notify `Err` arm is plumbed as `LoopMessage::WatchError` and classified via `raw_os_error()` (EMFILE 24 / ENFILE 23 → degrade; ENOSPC 28 → warn); surfaced to the agent via **STDERR only** so `ToolResult` bytes stay golden-identical (this plan T10)       |
+| Custom file-extension→language mapping via project config (`{"extensions":{".x":"lua"}}`, mtime-cached, #906) (`src/project-config.ts:1-155`)                                                              | PORT         | net-new `.codegraph/codegraph.json` reader (mtime-cached) merged over `builtin_language_for_ext`; a hard skip-list gate makes an override unable to change any extension a built-in/embedded mapping already resolves — proven golden-safe by a hostile-remap test (`.ts`→`lua` ignored) (this plan T11)              |
+| Front-load prompt-hook + Claude `UserPromptSubmit` installer hook (#964/#966, monorepo-aware) (`src/installer/*`, `bin/codegraph.ts prompt-hook`)                                                          | PORT         | hidden `codegraph prompt-hook` subcommand emits `codegraph_explore`-style retrieval to stdout (NO LLM — pure deterministic retrieval) + an opt-in Claude hook marker block in the installer (this plan T12)                                                                                                           |
+| Pare back the default MCP tool surface                                                                                                                                                                     | ALREADY-HAVE | this port already exposes the intended tool set (the 8 colby tools + additive `check`/`export`); no further trimming needed                                                                                                                                                                                           |
+| Bold labels instead of ATX headings in tool output                                                                                                                                                         | ALREADY-HAVE | the Rust tool formatters already emit bold-label framing; tool-output bytes already match the v1.1.0 shape                                                                                                                                                                                                            |
+| Re-resolve the project path on every call (#926)                                                                                                                                                           | ALREADY-HAVE | `McpServer` already resolves the path per request rather than caching a stale root                                                                                                                                                                                                                                    |
+| Cross-file caller edges preserved across re-index (#899)                                                                                                                                                   | ALREADY-HAVE | `resolver.rs` already retains cross-file caller edges through an incremental re-index                                                                                                                                                                                                                                 |
+| Stop auto-indexing on install                                                                                                                                                                              | ALREADY-HAVE | this port's `install` only writes agent config; it never triggers an index                                                                                                                                                                                                                                            |
+| React `forwardRef`/`memo` component detection                                                                                                                                                              | ALREADY-HAVE | `react.rs` already recognizes `forwardRef`/`memo` wrappers                                                                                                                                                                                                                                                            |
+| In-root symlink indexing (#935)                                                                                                                                                                            | ALREADY-HAVE | the walker already follows in-root symlinks during indexing                                                                                                                                                                                                                                                           |
+| Reasoning offload / CodeGraph AI managed tier / login / logout / usage / offload telemetry                                                                                                                 | N/A          | barred by the no-AI/LLM guardrail (`scripts/guardrail.sh`); also **removed upstream pre-1.1.0** via `e5897d0`, so there is nothing in the v1.0.1→v1.1.0 range to port                                                                                                                                                 |
+| `git ls-files` `./` self-entry handling (#936)                                                                                                                                                             | N/A          | architecture difference — the Rust walker does not enumerate via `git ls-files`, so the self-entry bug does not exist here                                                                                                                                                                                            |
+| Index full-rebuild semantics (#874)                                                                                                                                                                        | N/A          | architecture difference — the Rust indexer already rebuilds fully on `index --force`; no behavioral gap to close                                                                                                                                                                                                      |
+| Submodule de-duplication (#945)                                                                                                                                                                            | N/A          | architecture difference — the Rust walker's submodule handling differs from the TS path; not the same bug                                                                                                                                                                                                             |
+| Same-file value-reference edges across 15 languages (#895/#897)                                                                                                                                            | DEFER        | changes extraction OUTPUT (new edges) → golden regen required; scoped to the separate B-class plan                                                                                                                                                                                                                    |
+| Framework dispatch synthesizers — GoFrame `g.Meta` (#747), Laravel event→listener, Sidekiq, MediatR, Spring `publishEvent`, Celery, Vuex, Pinia, RTK Query, redux-thunk, object-literal registry           | DEFER        | each synthesizes new edges → extraction OUTPUT change → golden regen required; largest B-class surface (~1000+ LOC), separate plan                                                                                                                                                                                    |
+| C/C++ function-pointer dispatch (#932)                                                                                                                                                                     | DEFER        | new dispatch edges → extraction OUTPUT change → golden regen required; separate B-class plan                                                                                                                                                                                                                          |
+| Java Lombok synthesized members (#912)                                                                                                                                                                     | DEFER        | new synthesized member nodes → extraction OUTPUT change → golden regen required; separate B-class plan                                                                                                                                                                                                                |
+| React `styled()` / JSX-file route detection (#841)                                                                                                                                                         | DEFER        | new nodes/edges → extraction OUTPUT change → golden regen required; separate B-class plan                                                                                                                                                                                                                             |
+| C++ phantom-macro-function fix (#946)                                                                                                                                                                      | DEFER        | changes which function nodes are emitted → extraction OUTPUT change → golden regen required; separate B-class plan                                                                                                                                                                                                    |
+| Perf: O(K²) import-node resolution (#915)                                                                                                                                                                  | DEFER        | verify-if-applicable to the Rust resolver; if it reproduces, the fix may shift resolution output → treat as golden-sensitive in the separate B-class plan                                                                                                                                                             |
+
+**Outcome:** tracked version is `1.1.0` (upstream HEAD). The full A-class live-watch
+daemon stack landed (13 todos, T1–T12 implementation + this ledger) with golden
+output **byte-untouched** — `cargo test -p codegraph-bench` (extraction golden) and
+`cargo test -p codegraph-mcp golden_mcp` (MCP-response golden) pass unchanged, and
+`git status --porcelain reference/golden/` is empty. No AI/vector/LLM crate crept in
+(`scripts/guardrail.sh` green). The **B-class** extraction/framework ports are
+deferred to a **separate future plan** specifically because each one changes
+extraction OUTPUT and therefore demands a deliberate golden regeneration — they are
+recorded above so the next sync does not re-investigate them.
+
+**Next sync:** when upstream publishes a tag > `1.1.0`, run Workflow A from this
+point (`git diff v1.1.0..v<new>`). The pending B-class golden-bump plan is the
+outstanding port backlog from this range.
+
+### 2026-06-21 — baseline established at `v1.0.1`
+
+First ledger entry. This port was built directly against colby `1.0.1` (the
+latest upstream tag), so this is not a catch-up delta but a **baseline parity
+audit** confirming faithful coverage. Verified by cross-checking the live
+upstream source (`git clone` @ `1.0.1`) against this workspace.
+
+| upstream surface                                                                                 | finding                                                                                                                                                                                  | disposition        |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `LANGUAGES` (`src/types.ts`) — 32 languages                                                      | this project's `Language` enum has all 32, byte-identical set (incl. `c`, `r`); zero diff either direction                                                                               | ALREADY-HAVE       |
+| MCP tool set — 8 tools (`search`/`callers`/`callees`/`impact`/`node`/`explore`/`status`/`files`) | this project exposes all 8 **plus** two additive own tools (`check`, `export`) — a superset                                                                                              | ALREADY-HAVE       |
+| SQLite `.schema`                                                                                 | golden-anchored to colby 1.0.1 (`reference/golden/colby.schema.sql`); `schema_parity` test green                                                                                         | ALREADY-HAVE       |
+| Golden extraction equivalence                                                                    | `crates/codegraph-bench/tests/equivalence.rs` — **4 passed, 0 failed** against the 1.0.1 mini golden                                                                                     | ALREADY-HAVE       |
+| Per-language edge sets                                                                           | 15 of 17 benchmarked languages byte-identical to colby 1.0.1; the 2 exceptions (Dart, Pascal `function_ref` shape) are deliberate, documented in `KNOWN_DIFFS.md` (Tier-3 allowed diffs) | DEFER (documented) |
+
+**Outcome:** tracked version is `1.0.1`. No PORT items outstanding (upstream has
+no release newer than 1.0.1). Two known per-language edge-set differences (Dart,
+Pascal) remain intentionally deferred and are recorded in `KNOWN_DIFFS.md` — they
+are golden-oracle-allowed Tier-3 diffs, not regressions. Golden + guardrail +
+`cargo test --workspace` green.
+
+**Next sync:** when upstream publishes a tag > `1.0.1`, run Workflow A from this
+baseline (`git diff v1.0.1..v<new>`).
+
+### 2026-06-22 — Windows daemon parity (C6, `feat/windows-daemon`)
+
+Internal port commit, no upstream version bump. Closes the Unix-only IPC gap that
+was the one outstanding platform limitation since the `1.0.1` baseline.
+
+| upstream surface                                                                                            | finding                                                                                                                                                                                                                             | disposition |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `src/mcp/daemon-paths.ts` — named-pipe branch (`\\.\pipe\codegraph-<hash>`) on Windows, Unix socket on unix | Rust port now matches: `codegraph-daemon` uses `interprocess` 2.4 `local_socket` — UDS on unix, named pipe on Windows; pipe name stored bare (`codegraph-<sha256hash16>`), `GenericNamespaced` prepends `\\.\pipe\` at connect time | PORT        |
+| Windows process-liveness check (no `kill -0` on Windows)                                                    | `process.rs` cfg-split: unix uses `rustix` getppid + signal-0; Windows uses `windows-sys` `OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION)` + `GetExitCodeProcess == STILL_ACTIVE`                                                   | PORT        |
+| Stale-socket cleanup on unix (`.sock` unlink)                                                               | cfg-gated to unix only; Windows pipe names are OS-reclaimed, no file to remove                                                                                                                                                      | PORT        |
+| MSRV declaration                                                                                            | bumped `rust-version` 1.70 → 1.75 in workspace `Cargo.toml` and both READMEs (`interprocess` 2.x requires rustc 1.75; actual toolchain was already `stable`/1.96)                                                                   | PORT        |
+| Prebuilt release matrix                                                                                     | `x86_64-pc-windows-msvc` added to `release-please.yml`; packaged as `.zip` via PowerShell `Compress-Archive`; upload-assets glob extended to `dist/*.tar.gz` + `dist/*.zip`                                                         | PORT        |
+| CI gate                                                                                                     | `windows-latest` job added to `ci.yml`; wired into `ci-success` as merge blocker; linux job gains a `cargo check --target x86_64-pc-windows-msvc` cross-check step                                                                  | PORT        |
+
+**Outcome:** Windows IPC gap is fully closed. The daemon start/attach/stop cycle,
+named-pipe accept, lock contention, and ppid-watchdog behavior are all covered by
+the `windows-latest` CI job. No upstream version change — this is Rust-side
+infrastructure work matching the colby `1.0.1` cross-platform design.
+Tracked colby version was `1.0.1` at the time of this entry (subsequently bumped
+to `1.1.0` in the 2026-06-24 sync above).
diff --git a/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md b/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
new file mode 100644
index 0000000..d225506
--- /dev/null
+++ b/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
@@ -0,0 +1,142 @@
+# Colby v1.5.0 commit manifest
+
+This is the frozen scope inventory for `v1.4.1..v1.5.0`.
+
+- Baseline: `ecc8b307ac2f8a7d06bff02ee513c4ea2380b2f8`
+- Target: `ea72e1b190921232aa7bd02e96bef5bbe4fe0ab6`
+- Commit count: `86`
+- Source-list SHA-256:
+  `60746f77a9ce721c10b83bc5bb8804c153f7da84217c4afb96f26645c6aa33f7`
+- Reproduction: clone `https://github.com/colbymchenry/codegraph.git`, emit
+  `git log --reverse --format='%H|%s'` over the full baseline and target SHAs,
+  truncate each full SHA to exactly seven lowercase hex characters, and format
+  each pipe-delimited row with backticked `<short>` followed by the subject. The
+  pre-Red provenance gate requires exactly 86 lines and the hash above;
+  unavailable network is a named environment failure, not a skip.
+- Review provenance is external to this immutable file: both review prompts must
+  name the plan path + SHA-256 and this manifest path + SHA-256. Final verdicts
+  and those exact hashes are recorded in the implementation evidence ledger at
+  `docs/upstream-sync/V1_5_PORTABLE_FIXES.md`; embedding this file's own hash here
+  would make a reproducible hash impossible.
+
+`PORT` means behavior lands in the Rust implementation. `ALREADY-HAVE` means the
+current Rust architecture already supplies the behavior and keeps a regression
+contract. `DEFER` is portable but intentionally outside this release. `N/A`
+means implementation/runtime/tooling-specific or prose-only. All `N/A` and
+behavior-neutral performance rows have no golden effect.
+
+`Snapshot` is row-level provenance. Unchanged Revision 5 classifications retain
+`R5`; rows whose classification or evidence wording changed in Revision 6 use
+`R6`. The whole-file SHA, not a uniform row label, identifies the reviewed freeze.
+
+| # | Commit | Upstream change | Disposition | Rust landing/test and golden effect | Snapshot |
+|---:|---|---|---|---|---|
+| 1 | `6103f5e` | fix(cpp): resolve explicit operator calls (a.operator+(b)) to the operator method (#1268) | PORT | Batch B explicit-operator extraction/resolution; named C++ additions | R5 |
+| 2 | `e871c49` | fix(resolution): clean up processed refs by row id so batch boundaries can't drop sibling call sites (#1269) (#1270) | PORT | Batch C3 exact persisted row IDs; golden-neutral | R5 |
+| 3 | `2b0b4b5` | ci(release): publish npm packages with provenance and attest release bundles (#1296) | N/A | npm publishing is absent | R5 |
+| 4 | `a66683d` | feat(installer): offer CodeGraph Pro beta signup after install and upgrade (#1297) | N/A | product/UI-only | R5 |
+| 5 | `243ef1d` | ci(release): switch npm publishing to OIDC trusted publishing; document verified releases (#1298) | N/A | npm publishing is absent | R5 |
+| 6 | `ad5300a` | fix(ui): show synthesis as a 'Linking dynamic dispatch' phase; mute node:sqlite warning spam (#1299) | N/A | upstream UI-only | R5 |
+| 7 | `246aee8` | fix(ui): within-pass progress for the C fn-pointer linking pass (#1300) | N/A | upstream UI/progress-only | R5 |
+| 8 | `5736e24` | perf(index): faster fresh indexing + parallel reference resolution, byte-identical graphs (#1305) | N/A | Rust index pipeline architecture differs; behavior-neutral | R5 |
+| 9 | `d6efd43` | fix(cli): honor NO_COLOR/--no-color and go plain when stdout is piped (#1306) | DEFER | separate CLI presentation item; no graph effect | R5 |
+| 10 | `3042195` | fix(ui): consistent frame glyphs on Windows — agree with clack, keep raw path ASCII (#1307) | N/A | upstream terminal UI-only | R5 |
+| 11 | `e1f339f` | fix(go): require URL-shaped paths for route detection (#1308) | DEFER | separate route-extraction behavior; no v1.5 selected dependency | R5 |
+| 12 | `4dd29ea` | fix(cpp): strip template args from out-of-line method receiver qualifiers (#1309) | PORT | Batch B; named C++ additions | R5 |
+| 13 | `e437918` | fix(cpp): compose namespace prefix into out-of-line method qualified names (#1310) | PORT | Batch B; named C++ additions | R5 |
+| 14 | `b6a05d1` | fix(c): blank leading attribute macros so functions index under real names (#1311) | PORT | Batch B; named C++ corpus additions | R5 |
+| 15 | `18f0745` | perf(sync): defer WAL autocheckpoint for the whole incremental run (#1312) | DEFER | current WAL deferral is full-index-only; incremental performance work is outside this release | R5 |
+| 16 | `8dcf92f` | fix(watch): schedule a sync when a directory is deleted (#1313) | PORT | Batch M directory-removal event schedules one full sync; golden-neutral | R5 |
+| 17 | `ce983a0` | fix(cli): `node <symbol> -f <file>` includes the source body (#1314) | PORT | Batch A4 combined symbol/file disambiguation and source body; golden-neutral | R6 |
+| 18 | `2ec877b` | fix(resolution): calls through an imported singleton resolve to the method (#1315) | PORT | Batch C1; golden-neutral | R5 |
+| 19 | `41c2029` | fix(go): field-chain calls resolve via validated type inference, never bare-name guessing (#1316) | DEFER | separate multi-hop type analysis | R5 |
+| 20 | `c472cfb` | fix(resolution): literal-receiver builtins and nested locals stop fabricating call edges (#1317) | PORT | Batch C2; golden-neutral | R5 |
+| 21 | `a5a8942` | fix(scan): includeIgnored child patterns revive repos under a gitignored parent (#1318) | ALREADY-HAVE | behavioral reinclusion exists through `indexing.include`; upstream field name intentionally absent; regression evidence only | R6 |
+| 22 | `1de7e8f` | fix(retrieval): multi-hump field-name queries reach their definers (#1319) | PORT | Batch A2; golden-neutral | R5 |
+| 23 | `a2f3c31` | perf(resolution): defer checkpoints and double-buffer persist during resolution, byte-identical graphs (#1320) | N/A | upstream worker/DB architecture; byte-neutral perf | R5 |
+| 24 | `cf38ef6` | perf(synthesis): fan dynamic-dispatch passes across the resolver pool, byte-identical graphs (#1321) | N/A | upstream worker-pool architecture; byte-neutral perf | R5 |
+| 25 | `567b4ad` | perf(resolution): drop non-unique edge indexes during the bulk resolution window, byte-identical graphs (#1322) | N/A | upstream DB implementation detail; byte-neutral perf | R5 |
+| 26 | `4efc6c7` | fix(scale): kernel-scale hardening — OOM-safe pass skipping + watchdog-safe index recreate (#1323) | N/A | upstream Node+napi migration architecture | R5 |
+| 27 | `c5eebe6` | feat(kernel): R1 scaffold — napi-rs extraction kernel, buffer contract, routing + fallback, grammar-parity CI | N/A | product is already native Rust | R5 |
+| 28 | `9ad5cd7` | feat(kernel): R2 — full TypeScript/JavaScript extraction port, byte-parity with the wasm path | N/A | product is already native Rust | R5 |
+| 29 | `c8cca9a` | feat(kernel): R3 — TS/JS equivalence gate passed, kernel default-on | N/A | product is already native Rust | R5 |
+| 30 | `03d54e4` | feat(kernel): R4 — Java port with Lombok synthesis, gate passed, default-on | N/A | product is already native Rust | R5 |
+| 31 | `28068fa` | perf(kernel): direct-to-store decode — buffers flow to the store worker, main thread never materializes nodes | N/A | upstream napi/worker architecture | R5 |
+| 32 | `c2503e2` | feat(kernel): R5 — Python and Go ports, gates passed, default-on | N/A | product is already native Rust | R5 |
+| 33 | `f07fd54` | docs(kernel): record 2-CPU django/prometheus benchmarks in §4e | N/A | prose-only | R5 |
+| 34 | `2a79432` | docs(kernel): R6 — kernel-scale re-validation record (§4f) + parity-harness symlink robustness | N/A | prose-only | R5 |
+| 35 | `8060da2` | docs(kernel): make the migration plan a cold-start handoff — status checklist, §0a operational handoff, superseded-expectation annotations | N/A | prose-only | R5 |
+| 36 | `c1dc78d` | Merge pull request #1326 from colbymchenry/rust-kernel | N/A | merge record; constituent commits classified | R5 |
+| 37 | `9e18ac2` | docs(kernel): P1 first measurement round — premise correction (cpuset-blind pool), OOM + WAL-pinning findings, revised P1 order; O1 merged, O2 in progress (#1327) | N/A | prose-only | R5 |
+| 38 | `5e329ad` | fix(kernel): CRLF docstring parity — JS multiline ^ anchors after \r, regex crate's (?m)^ is \n-only (#1329) | N/A | upstream kernel regex quirk; Rust extractor path differs | R5 |
+| 39 | `04ab45c` | docs(kernel): O2 Windows VM validation closed — win32-arm64 native build + 33/33 suites, CRLF find credited (#1330) | N/A | prose-only | R5 |
+| 40 | `6e52295` | fix(resolution): WAL containment for the pooled superphase — writer backpressure at pool-idle boundaries (#1332) | N/A | upstream pooled resolver architecture | R5 |
+| 41 | `b8833fe` | feat(resolution): memory-aware, cgroup-honest worker-pool sizing + CODEGRAPH_RESOLVE_WORKERS (#1333) | N/A | upstream worker-pool architecture | R5 |
+| 42 | `8c1e821` | fix(db): WAL valve — TRUNCATE at parked barriers, futility latch, CODEGRAPH_WAL_VALVE_DEBUG (#1334) | ALREADY-HAVE | Rust WAL valve/maintenance controls already present | R5 |
+| 43 | `ca88d3b` | fix(db,resolution): WAL file cap + cgroup cache credit + pool/parse sizing corrections from the instrumented kernel-scale runs (#1335) | N/A | upstream cgroup/worker implementation | R5 |
+| 44 | `2adc7f6` | fix(db): WAL truncate at parked barriers ONLY — the timer-path truncate loses the race it was assumed to lose (#1336) | N/A | upstream worker barrier implementation | R5 |
+| 45 | `19cf1ec` | docs(kernel): P1 record runs — 2c 20.4min (-23%), 8c 18.3min no-OOM, WAL 14x contained; resolution measured core-invariant (#1338) | N/A | prose-only | R5 |
+| 46 | `7cc2366` | perf(resolution): batch-loop de-quadratic — keyset reads, changes-based guard, DB-scaled valve caps + resolve profiler (#1339) | N/A | upstream DB/pool performance implementation | R5 |
+| 47 | `9f10318` | docs(kernel): §7a.3 batch-loop profile round — countGuard quadratic eliminated, envelope 19.3min; two theories falsified by measurement (#1340) | N/A | prose-only | R5 |
+| 48 | `d510de4` | perf(synthesis): cFnPtrEdges 2.07x at kernel scale — probe-profiled, edge set hash-identical (#1341) | DEFER | behavior-neutral performance follow-up | R5 |
+| 49 | `636c74a` | docs(kernel): §7a.4 cFnPtr round record — 2.07x standalone, 17.6min envelope, LRU-cyclic-thrash lesson (#1342) | N/A | prose-only | R5 |
+| 50 | `705e501` | docs(kernel): sync §0 P1 checklist with the completed §7a.3/§7a.4 rounds (#1343) | N/A | prose-only | R5 |
+| 51 | `34ad080` | docs(kernel): R7a survey complete — the C/C++ bug-for-bug port checklist (#1344) | N/A | prose-only | R5 |
+| 52 | `44561b6` | feat(extraction): vendor current C/C++ grammars (R7a prep) — c v0.24.2 + cpp v0.23.4, sha-matched (#1345) | N/A | Rust uses crate-pinned native grammars | R5 |
+| 53 | `2d72891` | feat(kernel): R7a C/C++ walker — dual-lang ccpp module, preParse hoist, 7 new blanks, c/cpp default-routed (#1346) | N/A | product already has native C/C++ walker; selected fixes port separately | R5 |
+| 54 | `b9d0f57` | feat(extraction): C deferral round 2 — 8 new preParse passes, linux kernel/+mm/ deferral 58.6%→33.9% (#1353) | DEFER | performance/coverage program outside selected fixes | R5 |
+| 55 | `5955d04` | docs(kernel): §7a.6 per-ref measurement round — pool works, two cache theories killed, writes-under-readers named (#1354) | N/A | prose-only | R5 |
+| 56 | `971a5a0` | perf(resolution): worker connection recycling — WAL-depth writes-under-readers fix, superphase −11.4% at 8c (#1362) | N/A | upstream worker pool architecture | R5 |
+| 57 | `b877db6` | docs(kernel): §7a.8 cFnPtr calibration — strip rewrite killed by measurement, fuse-then-link is step 1 (#1363) | N/A | prose-only | R5 |
+| 58 | `c6850d7` | perf(resolution): cFnPtr fuse-then-link — one extraction sweep + filtered verbatim linking, pass −22% at kernel scale (#1364) | DEFER | behavior-neutral performance follow-up | R5 |
+| 59 | `69ea438` | perf(kernel): cFnPtr native extraction sweep — step 2, pass 230→151s across the arc (§7a.10) (#1365) | N/A | upstream napi kernel architecture | R5 |
+| 60 | `9647771` | docs(kernel): §7a.11 continuous-shallow WAL probe — killed by measurement, fold I/O is a fixed budget (#1366) | N/A | prose-only | R5 |
+| 61 | `f6d8e8f` | perf(store): parse-lane index deferral — dubbo fresh init −19%, kernel-scale envelope best-ever 14.2min (§4d round 1) (#1368) | N/A | upstream store performance implementation | R5 |
+| 62 | `ce0ae30` | perf(store): resolution ref-index window — kernel-scale resolution 423→276s, 8c envelope ≈11min (§4d round 2) (#1369) | N/A | upstream store performance implementation | R5 |
+| 63 | `f1ca991` | feat(kernel): R7b Rust walker — rustlang module, tree-sitter-rust 0.24.2 bump, rust default-routed (#1371) | N/A | product already has native Rust walker | R5 |
+| 64 | `286e9cc` | feat(kernel): R7b C# walker — csharp module, tree-sitter-c-sharp 0.23.5 pin, csharp default-routed (#1378) | N/A | product already has native C# walker | R5 |
+| 65 | `1909931` | feat(kernel): R7b Ruby walker — ruby module, tree-sitter-ruby 0.23.1 bump, ref-flag wire slot, ruby default-routed (#1379) | N/A | product already has native Ruby walker | R5 |
+| 66 | `a6c62d7` | feat(kernel): R7b PHP walker — php module, tree-sitter-php 0.24.2 bump, php default-routed (#1380) | N/A | product already has native PHP walker | R5 |
+| 67 | `09e301b` | feat(kernel): R7b Swift walker — swift module, tree-sitter-swift 0.7.3 bump, swift default-routed (#1381) | N/A | product already has native Swift walker | R5 |
+| 68 | `45a53eb` | feat(kernel): R7b Kotlin walker — kotlin module, vendored-grammar-C build, kotlin default-routed (#1382) | N/A | product already has native Kotlin walker | R5 |
+| 69 | `b2f9ab1` | feat(kernel): R7b R walker — rlang module, tree-sitter-r 1.2.0 crate pin, r default-routed (#1383) | N/A | product already has native R walker | R5 |
+| 70 | `e321351` | feat(kernel): R7b Lua+Luau walker — one lua module, vendored-grammar-C lua v0.4.1, tree-sitter-luau 1.2.0 pin, both default-routed (#1384) | N/A | product already has native Lua/Luau walker | R5 |
+| 71 | `bdd687b` | feat(kernel): R7b Scala walker — scala module, vendored-grammar-C master@0aca5d0a6f, scala default-routed (#1385) | N/A | product already has native Scala walker | R5 |
+| 72 | `d1b75a1` | feat(kernel): R7b Dart walker — dart module, vendored-grammar-C d4d8f3e + wasm byte-copy vendor, dart default-routed (#1386) | N/A | product already has native Dart walker | R5 |
+| 73 | `3c1f30a` | docs(kernel): mark R7b complete — 20 languages default-routed, Linux leg validated (#1387) | N/A | prose-only | R5 |
+| 74 | `27c3c55` | perf(resolution): darwin-honest memory budget — vm_stat-based availability unstrangles the resolver pool on macOS (#1388) | N/A | upstream worker-pool implementation | R5 |
+| 75 | `082ea65` | perf(synthesis): provably-empty pass gates + prefilters — render/expo/rn/mybatis stop scanning repos they can't match; iface memo (#1389) | DEFER | behavior-neutral performance follow-up | R5 |
+| 76 | `1aa4de6` | perf(resolution): adaptive pool engagement — projected-settle bar replaces the fixed 150k-ref gate for mid-run boot; tokio −23% (#1390) | N/A | upstream worker-pool implementation | R5 |
+| 77 | `abb0a91` | perf(resolution): per-context basename index for Lua/Luau require resolution — kong fresh index −16% (#1391) | DEFER | behavior-neutral resolver performance follow-up | R5 |
+| 78 | `974e6c8` | perf(resolution): incremental receiver-inference scan memo + compiled-pattern memo — kong −8% more (−23% cumulative), byte-identical (#1392) | DEFER | behavior-neutral resolver performance follow-up | R5 |
+| 79 | `157c8e7` | perf(resolution): generation-tagged supertype memo + method owner index — Swift compiler 185→98s, byte-identical (#1395) | DEFER | behavior-neutral resolver performance follow-up | R5 |
+| 80 | `c74e8b0` | perf(sync): adaptive quick-fire debounce + scoped watcher sync — save-to-graph well under a second at any scale (#1397) | DEFER | separate watcher latency program | R5 |
+| 81 | `f8e6f00` | chore: gitignore target-linux/ cross-build cache (two cache files slipped into #1397) (#1398) | N/A | upstream build-cache cleanup | R5 |
+| 82 | `0f1096e` | docs: Opus 4.8 benchmark re-validation + release-notes headline (#1399) | N/A | prose-only | R5 |
+| 83 | `7d4a3d0` | docs(release): README polish + v1.5.0 (#1400) | N/A | prose/release metadata | R5 |
+| 84 | `a6682c6` | ci(release): kernel builds required + full walker-parity gate (#1401) | N/A | upstream kernel-specific CI | R5 |
+| 85 | `9b1fd6d` | release: sync package-lock.json to 1.5.0 | N/A | npm lockfile release metadata | R5 |
+| 86 | `ea72e1b` | docs(changelog): promote [Unreleased] into [1.5.0] | N/A | release prose | R5 |
+
+## Issue-only selected behaviors
+
+These reviewed upstream issues are part of the selected Rust behavior release but
+do not appear as separate commits in the frozen `v1.4.1..v1.5.0` list.
+
+| Issue | Disposition | Rust landing/test | Golden effect |
+|---|---|---|---|
+| #1372 | PORT | Batch A1 Unicode search scoring + real CLI/MCP contracts | none |
+| #1359 | PORT | Batch A3 enqueue-once unit instrumentation | none |
+| #1348 | PORT | Batch D1 bounded React opening-tag scan | none |
+| #1350 | PORT | Batch D2 DFM nesting/end lines | none |
+| #1182/#1209 | PORT | Batch D3 MyBatis/iBatis forms and qualified refids | none |
+| #1349 | N/A | forbidden node-ID byte-offset/column discriminator | none |
+| #1243 | N/A | periodic MCP network update notice rejected by policy | none |
+| #1351 / `572d22b` | ALREADY-HAVE | TOML array-of-tables regression already present | none |
+
+## Review closeout
+
+This manifest is immutable once its SHA-256 is submitted for review. Record both
+review verdicts and the exact reviewed plan/manifest hashes plus the source-list
+hash in the implementation evidence ledger, not by modifying this file. Any
+manifest change requires a new plan/manifest freeze and both reviews again.
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
new file mode 100644
index 0000000..24f0efc
--- /dev/null
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -0,0 +1,109 @@
+# Colby v1.5 portable-fixes evidence ledger
+
+This ledger records the reviewed provenance bootstrap and will accumulate the
+Red/Green evidence for the selected colby v1.5 portable fixes. The frozen plan
+remains ignored and local; this file records its reviewed identity without
+tracking or modifying it.
+
+## Bootstrap provenance
+
+- Reviewed base and branch pre-bootstrap HEAD:
+  `aba40799ecacb94515f7e1690914d2accc4c8973`
+- Fetched `origin/main` at bootstrap:
+  `aba40799ecacb94515f7e1690914d2accc4c8973`
+- Frozen Revision 14 plan SHA-256:
+  `5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`
+- Frozen source-list SHA-256 (exact 86-row projection):
+  `60746f77a9ce721c10b83bc5bb8804c153f7da84217c4afb96f26645c6aa33f7`
+- No Cargo command has run yet. The first Cargo invocation remains reserved for
+  `scripts/check-workspace-versions.sh` after that script and its fixture are
+  introduced without invoking Cargo.
+
+### Frozen support-file hashes
+
+| File                                         | SHA-256                                                            |
+| -------------------------------------------- | ------------------------------------------------------------------ |
+| `.gitignore`                                 | `beb58777556b1e37354e5adb3ec15834683edaaba95f15bfed13d92dda42c13a` |
+| `.oxfmtignore`                               | `7fb05bd0552e6e383434d7b807f836eb8e1474e08e84adfaab09c8cd8553f103` |
+| `docs/upstream-sync/V1_5_COMMIT_MANIFEST.md` | `1bf8a9022b7702368a66f0159ce84dc6ba846e5aa9c8db32f3e2ecf83affbc96` |
+| `docs/upstream-sync/UPSTREAM.md`             | `e99826c37572235266299f49d206f7c441f822297cc2e5d66745a275d6bf129f` |
+| `docs/upstream-sync/KNOWN_DIFFS.md`          | `2c973b6f1407b409131c20849de44f15dc9989c1b47bb278e836daf3c682c07d` |
+
+## Complete Momus verdict
+
+```text
+**[OKAY]**
+Summary: The frozen plan, manifest, and source-list hashes match exactly. The plan is executable: all 15 PORT rows map to concrete batches, behavioral Red/Green evidence, commands, and expected outcomes, with no blocking contradiction.
+Verification evidence:
+- Plan: 5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450
+- Manifest: 1bf8a9022b7702368a66f0159ce84dc6ba846e5aa9c8db32f3e2ecf83affbc96
+- Source list: 60746f77a9ce721c10b83bc5bb8804c153f7da84217c4afb96f26645c6aa33f7
+PORT mapping and TDD: lines 166–184, 780–817, and 819–972; executable commands and invalid-Red exclusions are at lines 1263–1298.
+Revision 14’s interrupted-uninit sequence is complete at lines 386–431 and 590–612, with crash/recovery QA at lines 721–760. Dual-slot publication, Future precedence, and Corrupt fail-closed behavior are specified at lines 452–522.
+Namespace isolation, deterministic golden policy, Cargo-first-invocation gate, and terminal release DAG are covered at lines 246–287, 201–217, 1002–1081, and 1083–1257. Extraction/graph golden additions are limited to the four named C/C++ fixtures; the only separate exception is the explicitly scoped v2 MCP wording goldens.
+Finding classification: Blockers: 0 · Majors: 0 · Follow-ups: 0
+VERDICT: APPROVE
+Open Blockers: 0
+```
+
+## Complete Codex verdict
+
+```text
+Reviewed hashes:
+- Plan: 5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450
+- Manifest: 1bf8a9022b7702368a66f0159ce84dc6ba846e5aa9c8db32f3e2ecf83affbc96
+- Source list: 60746f77a9ce721c10b83bc5bb8804c153f7da84217c4afb96f26645c6aa33f7
+
+Summary: No implementation-blocking defect found. The base, manifest projection, migration design, dependency order, version gate, and release topology are feasible. Four Majors must be resolved within their named batches.
+
+Findings:
+1. [Major] Future storage-protocol classification is contradictory
+   Evidence: Plan lines 462-464 classify every unsupported storage protocol as `Corrupt`, while lines 468-490 classify newer extraction/storage protocols as `Future`. Tests at lines 516-520 and 740-745 require Future-protocol behavior.
+   Required action: Batch M must define directional precedence, preferably protocol greater than current as `Future` and malformed/lower unsupported protocol as `Corrupt`, with exact classification and byte-snapshot tests.
+
+2. [Major] Identical equal-sequence slots have no publication rule
+   Evidence: Plan lines 465-468 reject equal-sequence slots only when payloads differ, making identical duplicates valid. Lines 502-514 require replacing an older or missing inactive slot, but neither slot qualifies in this state.
+   Required action: Batch M must either classify every equal-sequence duplicate as `Corrupt` or select a fixed slot deterministically, then test the next publication and crash points.
+
+3. [Major] Red-commit sequencing is internally ambiguous
+   Evidence: Plan lines 805-809 permit API-dependent unit tests after minimal APIs compile, while lines 995-998 say each batch's tests precede its first Green edit. Repository `AGENTS.md` lines 124-134 also require running the normal verification gates before every commit.
+   Required action: The evidence ledger must distinguish initial behavioral Red tests from later API-level refinements and explicitly record the expected failing gate for test-first Red commits. Compile/setup failures remain invalid evidence.
+
+4. [Major] Already-published verification lacks an authoritative expected checksum source
+   Evidence: Plan lines 1137-1145 and 1212-1237 skip builds for `already_published` while requiring exact checksum verification. Lines 1361-1371 generate expected hashes only in the original publication path. A later run has no specified trusted prior digest.
+   Required action: E3 must persist an owner-bound checksum authority, such as artifact attestations keyed by release ID and tag SHA, and verify all six downloads against it without adding a seventh release asset.
+
+5. [Follow-up] `KNOWN_DIFFS.md` overstates oracle integration
+   Evidence: `KNOWN_DIFFS.md` line 3 says the file is parsed by the oracle, but all production equivalence calls pass `None`; `KnownDiffs::load` has no caller.
+   Required action: E1 should correct that statement or deliberately wire the file into the oracle. No active rules currently exist, so golden safety is unaffected.
+
+PORT coverage: complete. All 86 source rows match exactly; dispositions are 10 PORT, 2 ALREADY-HAVE, 12 DEFER, and 62 N/A. The five issue-only PORT groups produce 15 total behavior groups mapped to M/A/B/C/D with named Red and acceptance evidence.
+
+Revision 14 uninit assessment: safe. The plan requires exclusive lease, under-lease reclassification, durable owner-bound `uninitialized` publication, tombstone, owner-bound daemon drain, and cleanup preserving the lock and both slots. Invalid, Future, owner-mismatched, and no-valid-slot-plus-DB states remain nonmutating.
+
+TDD/verification assessment: adequate, subject to Finding 3. Reds are behaviorally defined, invalid setup/compile/network failures are excluded, and graph/golden determinism is explicitly gated.
+
+Release assessment: adequate, subject to Finding 4. The ten-package updater is feasible, Cargo ordering is gated, permissions and pins are constrained, historical workflow retirement is explicit, and the six-target terminal DAG includes draft and public smoke.
+
+VERDICT: APPROVE
+Open Blockers: 0
+```
+
+## Codex finding assignments
+
+| Finding                              | Assignment                               | Required closure                                                                                                                                                                                   |
+| ------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Future storage-protocol direction    | Batch M                                  | A protocol greater than the current protocol is `Future`; malformed or unsupported lower protocol is `Corrupt`. Snapshot every namespace byte and prove both classifications are byte-nonmutating. |
+| Identical equal-sequence slots       | Batch M                                  | Conservatively classify every equal-sequence duplicate as `Corrupt`, whether payloads are identical or different. Snapshot every byte and test publication/crash attempts remain byte-nonmutating. |
+| Red-commit evidence distinction      | Cross-batch ledger rule beginning with M | Record initial black-box behavioral Red evidence separately from later API-level refinements, including the expected failing behavioral assertion or gate.                                         |
+| Already-published checksum authority | E3                                       | Persist an owner-bound checksum authority keyed by immutable release ID and tag SHA; verify all six downloaded assets against it without creating a seventh release asset.                         |
+| `KNOWN_DIFFS.md` oracle wording      | E1                                       | Correct the overstatement or deliberately wire the file into the oracle, and record the exact closeout diff.                                                                                       |
+
+## Red-evidence rule
+
+Initial black-box behavioral Red commits may fail the expected behavior tests.
+Later API-level refinements follow minimal compiling scaffolding and retain the
+original black-box Red as the behavioral evidence. Every Red entry must identify
+the expected failing assertion, root ID, or behavior gate. Compile failures,
+setup failures, fixture/network failures, and unrelated failures are never valid
+Red evidence.

From 06d315eb24f51345d56752ea2eb6c3502d74e27b Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 04:59:11 +0800
Subject: [PATCH 02/91] test(release): add workspace version gate

---
 scripts/check-workspace-versions.sh           | 211 ++++++++++++++++++
 .../tests/check-workspace-versions.test.sh    | 204 +++++++++++++++++
 2 files changed, 415 insertions(+)
 create mode 100755 scripts/check-workspace-versions.sh
 create mode 100755 scripts/tests/check-workspace-versions.test.sh

diff --git a/scripts/check-workspace-versions.sh b/scripts/check-workspace-versions.sh
new file mode 100755
index 0000000..357067c
--- /dev/null
+++ b/scripts/check-workspace-versions.sh
@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+# check-workspace-versions.sh — deterministic workspace-version gate.
+#
+# Purpose
+#   Enforce that all four version surfaces of this workspace agree exactly, and
+#   that the workspace package set is identical between `cargo metadata` and the
+#   source-less entries of Cargo.lock. This is the release-please invariant that
+#   keeps the tag, binary, archive, and every in-repo version string in lockstep.
+#
+#   The four version surfaces:
+#     1. root  Cargo.toml  [workspace.package] version
+#     2. every source-less package version in  Cargo.lock  (the workspace members)
+#     3. version.txt
+#     4. the root ("."") entry in  .release-please-manifest.json
+#
+# Cargo ordering contract (see the frozen v1.5 plan, E2)
+#   * The FIRST operation snapshots the Cargo.lock bytes/hash.
+#   * The FIRST — and only — Cargo subprocess this gate runs is:
+#         cargo metadata --locked --no-deps --format-version 1
+#     It obtains the authoritative workspace package set from that non-mutating
+#     command and never resolves or mutates dependencies.
+#   * No Cargo command may precede this gate in scripts, Make, hooks, or
+#     workflows. Every later dependency-resolving Cargo command uses --locked.
+#
+# Determinism guarantee
+#   On EVERY exit path (success or failure) an EXIT trap re-hashes Cargo.lock and
+#   proves the bytes are byte-for-byte unchanged; a mutated lock is itself a
+#   hard failure (exit 90).
+#
+# Usage
+#   scripts/check-workspace-versions.sh [WORKSPACE_ROOT]
+#   WORKSPACE_ROOT defaults to the repository root (the script's parent dir).
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Resolve the workspace root (arg 1, else the repo root = script's ../).
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+WORKSPACE_ROOT="${1:-"$(cd -- "$SCRIPT_DIR/.." && pwd -P)"}"
+
+CARGO_TOML="$WORKSPACE_ROOT/Cargo.toml"
+CARGO_LOCK="$WORKSPACE_ROOT/Cargo.lock"
+VERSION_TXT="$WORKSPACE_ROOT/version.txt"
+RELEASE_MANIFEST="$WORKSPACE_ROOT/.release-please-manifest.json"
+
+fail() {
+    printf 'check-workspace-versions: ERROR: %s\n' "$1" >&2
+    exit 1
+}
+
+for f in "$CARGO_TOML" "$CARGO_LOCK" "$VERSION_TXT" "$RELEASE_MANIFEST"; do
+    [ -f "$f" ] || fail "required file not found: $f"
+done
+
+# ---------------------------------------------------------------------------
+# FIRST OPERATION: snapshot the Cargo.lock bytes/hash, then arm the EXIT trap
+# so the lock is proven unchanged on every subsequent exit path.
+# ---------------------------------------------------------------------------
+LOCK_SHA_PRE="$(sha256sum "$CARGO_LOCK" | awk '{print $1}')"
+
+verify_lock_unchanged() {
+    local rc=$?
+    local post
+    post="$(sha256sum "$CARGO_LOCK" 2>/dev/null | awk '{print $1}')"
+    if [ "$post" != "$LOCK_SHA_PRE" ]; then
+        printf 'check-workspace-versions: CRITICAL: Cargo.lock mutated during gate\n' >&2
+        printf '  pre : %s\n' "$LOCK_SHA_PRE" >&2
+        printf '  post: %s\n' "$post" >&2
+        exit 90
+    fi
+    exit "$rc"
+}
+trap verify_lock_unchanged EXIT
+
+# ---------------------------------------------------------------------------
+# FIRST CARGO SUBPROCESS: cargo metadata --locked --no-deps --format-version 1
+# Non-mutating; yields the authoritative workspace package set. If the lock is
+# stale relative to the manifests, --locked makes Cargo refuse (drift), which is
+# itself a version-consistency failure this gate must surface.
+# ---------------------------------------------------------------------------
+META_JSON=""
+META_ERR=""
+if ! META_JSON="$(cargo metadata --locked --no-deps --format-version 1 \
+    --manifest-path "$CARGO_TOML" 2>/tmp/cwv_meta_err.$$)"; then
+    META_ERR="$(cat "/tmp/cwv_meta_err.$$" 2>/dev/null || true)"
+    rm -f "/tmp/cwv_meta_err.$$"
+    printf 'check-workspace-versions: FAIL: cargo metadata --locked refused — Cargo.lock is\n' >&2
+    printf '  out of date relative to the manifests (version/package-set drift).\n' >&2
+    printf '  This means the lock and the workspace manifests disagree; regenerate the\n' >&2
+    printf '  lock so all workspace members match the workspace version.\n' >&2
+    if [ -n "$META_ERR" ]; then
+        printf '  cargo said:\n%s\n' "$META_ERR" | sed 's/^/    /' >&2
+    fi
+    exit 1
+fi
+rm -f "/tmp/cwv_meta_err.$$"
+
+# Authoritative workspace package names + versions (workspace members only).
+META_NAMES="$(printf '%s' "$META_JSON" | jq -r '.packages[].name' | sort)"
+META_VERSIONS="$(printf '%s' "$META_JSON" \
+    | jq -r '.packages[] | "\(.name)=\(.version)"' | sort)"
+
+# ---------------------------------------------------------------------------
+# Parse surface 1: root [workspace.package] version from Cargo.toml.
+# ---------------------------------------------------------------------------
+WORKSPACE_VERSION="$(awk '
+    /^\[/ { in_wp = ($0 == "[workspace.package]") ? 1 : 0; next }
+    in_wp && /^version[[:space:]]*=/ {
+        line = $0
+        sub(/^version[[:space:]]*=[[:space:]]*"/, "", line)
+        sub(/".*/, "", line)
+        print line
+        exit
+    }
+' "$CARGO_TOML")"
+[ -n "$WORKSPACE_VERSION" ] || fail "could not parse [workspace.package] version from Cargo.toml"
+
+# ---------------------------------------------------------------------------
+# Parse surface 2: source-less package name=version entries from Cargo.lock.
+# A source-less entry is a [[package]] block with no `source =` line — i.e. a
+# workspace member.
+# ---------------------------------------------------------------------------
+LOCK_ENTRIES="$(awk '
+    /^\[\[package\]\]/ { name=""; ver=""; src=0; next }
+    /^name = /   { match($0, /"[^"]*"/); name=substr($0, RSTART+1, RLENGTH-2); next }
+    /^version = /{ match($0, /"[^"]*"/); ver=substr($0, RSTART+1, RLENGTH-2); next }
+    /^source = / { src=1; next }
+    /^$/ { if (name != "" && src == 0) print name "=" ver; name=""; ver=""; src=0 }
+    END  { if (name != "" && src == 0) print name "=" ver }
+' "$CARGO_LOCK" | sort)"
+[ -n "$LOCK_ENTRIES" ] || fail "no source-less packages found in Cargo.lock"
+
+LOCK_NAMES="$(printf '%s\n' "$LOCK_ENTRIES" | sed 's/=.*//' | sort)"
+
+# ---------------------------------------------------------------------------
+# Parse surface 3: version.txt (trim all surrounding whitespace).
+# ---------------------------------------------------------------------------
+VERSION_TXT_VALUE="$(tr -d '[:space:]' < "$VERSION_TXT")"
+[ -n "$VERSION_TXT_VALUE" ] || fail "version.txt is empty"
+
+# ---------------------------------------------------------------------------
+# Parse surface 4: root "." entry in .release-please-manifest.json.
+# ---------------------------------------------------------------------------
+RELEASE_MANIFEST_VALUE="$(jq -r '."."' "$RELEASE_MANIFEST")"
+[ -n "$RELEASE_MANIFEST_VALUE" ] && [ "$RELEASE_MANIFEST_VALUE" != "null" ] \
+    || fail "no root \".\" entry in .release-please-manifest.json"
+
+# ---------------------------------------------------------------------------
+# Assertions. Collect every discrepancy for a precise, deterministic report.
+# ---------------------------------------------------------------------------
+FAILURES=0
+report() { printf 'check-workspace-versions: MISMATCH: %s\n' "$1" >&2; FAILURES=$((FAILURES + 1)); }
+
+# Package-set equality: cargo metadata members == source-less Cargo.lock entries.
+if [ "$META_NAMES" != "$LOCK_NAMES" ]; then
+    report "workspace package set differs between cargo metadata and Cargo.lock (source-less)"
+    printf '  only in cargo metadata:\n' >&2
+    comm -23 <(printf '%s\n' "$META_NAMES") <(printf '%s\n' "$LOCK_NAMES") | sed 's/^/    /' >&2
+    printf '  only in Cargo.lock (source-less):\n' >&2
+    comm -13 <(printf '%s\n' "$META_NAMES") <(printf '%s\n' "$LOCK_NAMES") | sed 's/^/    /' >&2
+fi
+
+# Surface 1 is the reference version; assert 2/3/4 (and metadata versions) match.
+if [ "$VERSION_TXT_VALUE" != "$WORKSPACE_VERSION" ]; then
+    report "version.txt = '$VERSION_TXT_VALUE' != [workspace.package] version = '$WORKSPACE_VERSION'"
+fi
+
+if [ "$RELEASE_MANIFEST_VALUE" != "$WORKSPACE_VERSION" ]; then
+    report ".release-please-manifest.json \".\" = '$RELEASE_MANIFEST_VALUE' != [workspace.package] version = '$WORKSPACE_VERSION'"
+fi
+
+while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    ename="${entry%%=*}"
+    ever="${entry#*=}"
+    if [ "$ever" != "$WORKSPACE_VERSION" ]; then
+        report "Cargo.lock package '$ename' = '$ever' != [workspace.package] version = '$WORKSPACE_VERSION'"
+    fi
+done <<EOF
+$LOCK_ENTRIES
+EOF
+
+while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    ename="${entry%%=*}"
+    ever="${entry#*=}"
+    if [ "$ever" != "$WORKSPACE_VERSION" ]; then
+        report "cargo metadata package '$ename' = '$ever' != [workspace.package] version = '$WORKSPACE_VERSION'"
+    fi
+done <<EOF
+$META_VERSIONS
+EOF
+
+if [ "$FAILURES" -ne 0 ]; then
+    printf 'check-workspace-versions: FAIL: %d version-surface mismatch(es)\n' "$FAILURES" >&2
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Success report (stdout — useful evidence for the release/CI logs).
+# ---------------------------------------------------------------------------
+PKG_COUNT="$(printf '%s\n' "$LOCK_NAMES" | grep -c .)"
+printf 'check-workspace-versions: OK\n'
+printf '  first cargo subprocess : cargo metadata --locked --no-deps --format-version 1\n'
+printf '  workspace version      : %s\n' "$WORKSPACE_VERSION"
+printf '  version.txt            : %s\n' "$VERSION_TXT_VALUE"
+printf '  release manifest "."   : %s\n' "$RELEASE_MANIFEST_VALUE"
+printf '  source-less packages   : %s (all at %s)\n' "$PKG_COUNT" "$WORKSPACE_VERSION"
+printf '%s\n' "$LOCK_NAMES" | sed 's/^/    /'
+# EXIT trap now proves Cargo.lock is byte-for-byte unchanged.
diff --git a/scripts/tests/check-workspace-versions.test.sh b/scripts/tests/check-workspace-versions.test.sh
new file mode 100755
index 0000000..6376de8
--- /dev/null
+++ b/scripts/tests/check-workspace-versions.test.sh
@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# check-workspace-versions.test.sh — fixture harness for the workspace-version gate.
+#
+# This harness is authored WITHOUT invoking Cargo. When EXECUTED it drives
+# scripts/check-workspace-versions.sh against hand-built temporary workspaces
+# (no external dependencies, so their Cargo.lock is trivially consistent and
+# `cargo metadata --locked` accepts them) plus the real repository.
+#
+# It proves the gate:
+#   * FAILS (nonzero, business assertion) on a manifest/lock version drift,
+#   * FAILS on a workspace package-set mismatch,
+#   * FAILS on a stale version.txt,
+#   * FAILS on a stale .release-please-manifest.json,
+#   * PASSES (zero) on the real repository lock,
+# and on EVERY scenario the fixture's Cargo.lock bytes are byte-for-byte
+# unchanged.
+#
+# Ordering contract: the very first Cargo invocation of the whole task must be
+# the gate run against the REAL repository. This harness must therefore only be
+# executed AFTER that first real gate run. It runs cargo (via the gate) on each
+# fixture, which are all later invocations.
+#
+# Usage: scripts/tests/check-workspace-versions.test.sh
+
+set -euo pipefail
+
+HARNESS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$HARNESS_DIR/../.." && pwd -P)"
+GATE="$REPO_ROOT/scripts/check-workspace-versions.sh"
+V="0.40.4"
+
+[ -x "$GATE" ] || { printf 'harness: gate not executable: %s\n' "$GATE" >&2; exit 2; }
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+note()  { printf '  %s\n' "$1"; }
+ok()    { printf 'PASS: %s\n' "$1"; PASS=$((PASS + 1)); }
+bad()   { printf 'FAIL: %s\n' "$1" >&2; FAIL=$((FAIL + 1)); }
+
+# ---------------------------------------------------------------------------
+# make_base_workspace DIR VERSION
+#   Writes a minimal, dependency-free two-member workspace whose Cargo.lock is
+#   consistent with its manifests. All four version surfaces are set to VERSION.
+# ---------------------------------------------------------------------------
+make_base_workspace() {
+    local dir="$1" ver="$2"
+    mkdir -p "$dir/pa/src" "$dir/pb/src"
+
+    cat > "$dir/Cargo.toml" <<EOF
+[workspace]
+members = ["pa", "pb"]
+resolver = "2"
+
+[workspace.package]
+version = "$ver"
+EOF
+
+    cat > "$dir/pa/Cargo.toml" <<'EOF'
+[package]
+name = "fixture-pa"
+version.workspace = true
+edition = "2021"
+EOF
+    printf '// fixture\n' > "$dir/pa/src/lib.rs"
+
+    cat > "$dir/pb/Cargo.toml" <<'EOF'
+[package]
+name = "fixture-pb"
+version.workspace = true
+edition = "2021"
+EOF
+    printf '// fixture\n' > "$dir/pb/src/lib.rs"
+
+    cat > "$dir/Cargo.lock" <<EOF
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "fixture-pa"
+version = "$ver"
+
+[[package]]
+name = "fixture-pb"
+version = "$ver"
+EOF
+
+    printf '%s\n' "$ver" > "$dir/version.txt"
+    printf '{\n  ".": "%s"\n}\n' "$ver" > "$dir/.release-please-manifest.json"
+}
+
+# ---------------------------------------------------------------------------
+# run_scenario NAME DIR EXPECT_EXIT EXPECT_STDERR_REGEX
+#   Snapshots the fixture lock, runs the gate, asserts exit code, asserts the
+#   expected diagnostic appears (business assertion — not a compile/setup
+#   error), and asserts the lock bytes are unchanged.
+# ---------------------------------------------------------------------------
+run_scenario() {
+    local name="$1" dir="$2" expect_exit="$3" expect_re="$4"
+    local pre post rc out err
+    pre="$(sha256sum "$dir/Cargo.lock" | awk '{print $1}')"
+    out="$WORK/$name.out"; err="$WORK/$name.err"
+    set +e
+    "$GATE" "$dir" >"$out" 2>"$err"
+    rc=$?
+    set -e
+    post="$(sha256sum "$dir/Cargo.lock" | awk '{print $1}')"
+
+    local scenario_ok=1
+    if [ "$rc" -ne "$expect_exit" ]; then
+        bad "$name: expected exit $expect_exit, got $rc"
+        note "stderr: $(tr '\n' '|' < "$err")"
+        scenario_ok=0
+    fi
+    if [ -n "$expect_re" ]; then
+        if ! grep -Eq "$expect_re" "$err" "$out"; then
+            bad "$name: expected diagnostic /$expect_re/ not found"
+            note "stderr: $(tr '\n' '|' < "$err")"
+            scenario_ok=0
+        fi
+    fi
+    if [ "$pre" != "$post" ]; then
+        bad "$name: Cargo.lock MUTATED (pre=$pre post=$post)"
+        scenario_ok=0
+    fi
+    if [ "$scenario_ok" -eq 1 ]; then
+        ok "$name (exit=$rc, lock unchanged: ${pre:0:12}…)"
+    fi
+}
+
+printf '=== workspace-version gate fixture harness ===\n'
+
+# Scenario A — manifest 0.40.4 / lock 0.40.3 drift.
+DIR_A="$WORK/drift"
+make_base_workspace "$DIR_A" "$V"
+# Rewrite ONLY the lock member versions to 0.40.3 (manifests stay 0.40.4).
+sed -i 's/^version = "0.40.4"$/version = "0.40.3"/' "$DIR_A/Cargo.lock"
+run_scenario "A_manifest_lock_drift" "$DIR_A" 1 "out of date|MISMATCH|0\.40\.3"
+
+# Scenario B — package-set mismatch: a source-less vendored crate exists in the
+# lock and is a path dependency of pa, but is NOT a workspace member, so
+# `cargo metadata --no-deps` omits it while the lock lists it.
+DIR_B="$WORK/pkgset"
+make_base_workspace "$DIR_B" "$V"
+mkdir -p "$DIR_B/vendored/src"
+cat > "$DIR_B/vendored/Cargo.toml" <<EOF
+[package]
+name = "fixture-vendored"
+version = "$V"
+edition = "2021"
+EOF
+printf '// fixture\n' > "$DIR_B/vendored/src/lib.rs"
+cat > "$DIR_B/pa/Cargo.toml" <<'EOF'
+[package]
+name = "fixture-pa"
+version.workspace = true
+edition = "2021"
+
+[dependencies]
+fixture-vendored = { path = "../vendored" }
+EOF
+cat > "$DIR_B/Cargo.lock" <<EOF
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "fixture-pa"
+version = "$V"
+dependencies = [
+ "fixture-vendored",
+]
+
+[[package]]
+name = "fixture-pb"
+version = "$V"
+
+[[package]]
+name = "fixture-vendored"
+version = "$V"
+EOF
+run_scenario "B_package_set_mismatch" "$DIR_B" 1 "package set differs|fixture-vendored"
+
+# Scenario C — stale version.txt (all else valid).
+DIR_C="$WORK/stale_version_txt"
+make_base_workspace "$DIR_C" "$V"
+printf '0.40.3\n' > "$DIR_C/version.txt"
+run_scenario "C_stale_version_txt" "$DIR_C" 1 "version\.txt"
+
+# Scenario D — stale release-please manifest (all else valid).
+DIR_D="$WORK/stale_release_manifest"
+make_base_workspace "$DIR_D" "$V"
+printf '{\n  ".": "0.40.3"\n}\n' > "$DIR_D/.release-please-manifest.json"
+run_scenario "D_stale_release_manifest" "$DIR_D" 1 "release-please-manifest"
+
+# Scenario E — the real repository lock (Green and unchanged).
+run_scenario "E_repository_green" "$REPO_ROOT" 0 "check-workspace-versions: OK"
+
+printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

From 745c5e7facfb718cf57f36d3a62d42e25da0e953 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 05:06:12 +0800
Subject: [PATCH 03/91] docs(release): record workspace version gate evidence

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 76 +++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 24f0efc..8b2db27 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -107,3 +107,79 @@ original black-box Red as the behavioral evidence. Every Red entry must identify
 the expected failing assertion, root ID, or behavior gate. Compile failures,
 setup failures, fixture/network failures, and unrelated failures are never valid
 Red evidence.
+
+## E2 workspace-version gate (first Cargo invocation)
+
+This section records the E2 prerequisite: `scripts/check-workspace-versions.sh`
+plus its fixture harness `scripts/tests/check-workspace-versions.test.sh`, both
+authored WITHOUT invoking Cargo. Executing the gate against the repository is the
+first Cargo invocation of the whole v1.5 implementation, and that gate's first
+Cargo subprocess is `cargo metadata --locked --no-deps --format-version 1`. No
+Batch M / behavioral Red or other Cargo command may run before this gate
+succeeds. This is not a behavioral Red; it is the release-invariant gate whose
+Green output authorizes all later Cargo use.
+
+### Cargo-ordering proof
+
+- Test-first commit landed with ZERO prior Cargo: the implementation worktree had
+  no `target/` directory and no Cargo command had run when
+  `test(release): add workspace version gate`
+  (`06d315eb24f51345d56752ea2eb6c3502d74e27b`) was committed on top of the
+  bootstrap `a877aa30269e2fcfe7d3a484540ab05fe60da27a`.
+- First-ever Cargo invocation of the task = the gate run below. A logging Cargo
+  shim placed first on `PATH` captured exactly one Cargo call during a gate run,
+  and it was the metadata command:
+
+  ```text
+  CARGO_INVOCATION: cargo metadata --locked --no-deps --format-version 1 --manifest-path /tmp/opencode/codegraph-rust-v15-impl/Cargo.toml
+  ```
+
+  That is the ONLY Cargo subprocess the gate spawns, and it is non-mutating.
+
+### First real gate run — repository Green
+
+- Command: `scripts/check-workspace-versions.sh` (no arg → repository root).
+- Exit status: `0`.
+- `Cargo.lock` SHA-256 pre-run:
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`
+- `Cargo.lock` SHA-256 post-run:
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`
+  (byte-for-byte unchanged; the EXIT trap re-hashes and enforces this on every
+  exit path.)
+- Four version surfaces, all equal to `0.40.4`:
+  - root `Cargo.toml` `[workspace.package] version` = `0.40.4`
+  - `version.txt` = `0.40.4`
+  - `.release-please-manifest.json` `"."` = `0.40.4`
+  - every source-less `Cargo.lock` package version = `0.40.4`
+- Ten source-less workspace packages identified (identical between
+  `cargo metadata --no-deps` and the source-less `Cargo.lock` entries):
+  `codegraph-bench`, `codegraph-core`, `codegraph-daemon`, `codegraph-extract`,
+  `codegraph-graph`, `codegraph-mcp`, `codegraph-resolve`, `codegraph-rs`,
+  `codegraph-store`, `codegraph-watch`.
+
+### Fixture harness — five scenarios, all as expected
+
+`scripts/tests/check-workspace-versions.test.sh` builds dependency-free temporary
+workspaces so their locks are trivially consistent (`cargo metadata --locked`
+accepts them), then drives the gate. Result: `5 passed, 0 failed`. Every failure
+scenario exits nonzero on a precise business assertion (never a
+compile/setup/environment failure), and every scenario leaves the fixture
+`Cargo.lock` byte-for-byte unchanged.
+
+| Scenario                   | Description                                                       | Expected | Observed exit | Diagnostic (business assertion)                                                                                              | Lock unchanged |
+| -------------------------- | ----------------------------------------------------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| A `manifest_lock_drift`    | manifest `0.40.4` / lock members `0.40.3`                         | nonzero  | `1`           | `Cargo.lock package 'fixture-pa' = '0.40.3' != [workspace.package] version = '0.40.4'` (and `fixture-pb`)                    | yes            |
+| B `package_set_mismatch`   | extra source-less lock entry (`vendored` excluded from workspace) | nonzero  | `1`           | `workspace package set differs between cargo metadata and Cargo.lock (source-less)` … only in Cargo.lock: `fixture-vendored` | yes            |
+| C `stale_version_txt`      | `version.txt` = `0.40.3`, all else `0.40.4`                       | nonzero  | `1`           | `version.txt = '0.40.3' != [workspace.package] version = '0.40.4'`                                                           | yes            |
+| D `stale_release_manifest` | manifest `"."` = `0.40.3`, all else `0.40.4`                      | nonzero  | `1`           | `.release-please-manifest.json "." = '0.40.3' != [workspace.package] version = '0.40.4'`                                     | yes            |
+| E `repository_green`       | the real repository lock                                          | zero     | `0`           | `check-workspace-versions: OK`                                                                                               | yes            |
+
+### Scope note
+
+This task adds only the gate and its fixture harness. It does NOT begin Batch M,
+does NOT touch the release-please `GenericToml`/`codegraph*` selector, the pinned
+Action commit, any GitHub/AWS workflow, the `Makefile`, hooks, or CI wiring — all
+of which remain E2 follow-up work. No version value in `Cargo.toml`, `Cargo.lock`,
+`version.txt`, or `.release-please-manifest.json` was modified. No third-party
+dependency was added; the gate uses only `bash`, `awk`, `sed`, `jq`, and
+`sha256sum` already present in the repository's toolchain.

From 10352ba0943622e665b0ff96c5b5f57589448c9c Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 05:19:15 +0800
Subject: [PATCH 04/91] fix(release): pin exact cargo metadata argv and harden
 lock trap

Run cargo metadata from the workspace root so its argv is exactly
'metadata --locked --no-deps --format-version 1' with no --manifest-path,
while still accepting any caller cwd. Make the EXIT trap treat a
deleted/unreadable Cargo.lock as changed so it deterministically exits 90
under set -e. Commit the Scenario B exclude fix and add argv-exactness and
trap mutation/deletion regressions. Correct the evidence ledger transcript.
---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  45 ++++---
 scripts/check-workspace-versions.sh           |  23 +++-
 .../tests/check-workspace-versions.test.sh    | 125 +++++++++++++++++-
 3 files changed, 167 insertions(+), 26 deletions(-)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 8b2db27..b8c1808 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -126,15 +126,23 @@ Green output authorizes all later Cargo use.
   `test(release): add workspace version gate`
   (`06d315eb24f51345d56752ea2eb6c3502d74e27b`) was committed on top of the
   bootstrap `a877aa30269e2fcfe7d3a484540ab05fe60da27a`.
-- First-ever Cargo invocation of the task = the gate run below. A logging Cargo
+- First-ever Cargo invocation of the task = the gate run below. The gate runs
+  Cargo with the workspace root as its current working directory (`cd
+"$WORKSPACE_ROOT"`), so the argv carries NO `--manifest-path`. A logging Cargo
   shim placed first on `PATH` captured exactly one Cargo call during a gate run,
-  and it was the metadata command:
+  and the captured argv was exactly:
 
   ```text
-  CARGO_INVOCATION: cargo metadata --locked --no-deps --format-version 1 --manifest-path /tmp/opencode/codegraph-rust-v15-impl/Cargo.toml
+  metadata --locked --no-deps --format-version 1
   ```
 
-  That is the ONLY Cargo subprocess the gate spawns, and it is non-mutating.
+  That is the ONLY Cargo subprocess the gate spawns, it is non-mutating, and the
+  argv is byte-exact — no `--manifest-path` or other extra argument. The gate
+  works from any caller cwd: it derives the workspace root (positional arg, else
+  the script's parent dir) and changes into it only to run this one command. The
+  fixture harness scenario `F_exact_cargo_argv` invokes the gate from a caller
+  cwd OTHER than the repo root and asserts this exact argv (one call, no
+  `--manifest-path`) mechanically.
 
 ### First real gate run — repository Green
 
@@ -157,22 +165,27 @@ Green output authorizes all later Cargo use.
   `codegraph-graph`, `codegraph-mcp`, `codegraph-resolve`, `codegraph-rs`,
   `codegraph-store`, `codegraph-watch`.
 
-### Fixture harness — five scenarios, all as expected
+### Fixture harness — eight scenarios, all as expected
 
 `scripts/tests/check-workspace-versions.test.sh` builds dependency-free temporary
 workspaces so their locks are trivially consistent (`cargo metadata --locked`
-accepts them), then drives the gate. Result: `5 passed, 0 failed`. Every failure
+accepts them), then drives the gate. Result: `8 passed, 0 failed`. Every failure
 scenario exits nonzero on a precise business assertion (never a
-compile/setup/environment failure), and every scenario leaves the fixture
-`Cargo.lock` byte-for-byte unchanged.
-
-| Scenario                   | Description                                                       | Expected | Observed exit | Diagnostic (business assertion)                                                                                              | Lock unchanged |
-| -------------------------- | ----------------------------------------------------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| A `manifest_lock_drift`    | manifest `0.40.4` / lock members `0.40.3`                         | nonzero  | `1`           | `Cargo.lock package 'fixture-pa' = '0.40.3' != [workspace.package] version = '0.40.4'` (and `fixture-pb`)                    | yes            |
-| B `package_set_mismatch`   | extra source-less lock entry (`vendored` excluded from workspace) | nonzero  | `1`           | `workspace package set differs between cargo metadata and Cargo.lock (source-less)` … only in Cargo.lock: `fixture-vendored` | yes            |
-| C `stale_version_txt`      | `version.txt` = `0.40.3`, all else `0.40.4`                       | nonzero  | `1`           | `version.txt = '0.40.3' != [workspace.package] version = '0.40.4'`                                                           | yes            |
-| D `stale_release_manifest` | manifest `"."` = `0.40.3`, all else `0.40.4`                      | nonzero  | `1`           | `.release-please-manifest.json "." = '0.40.3' != [workspace.package] version = '0.40.4'`                                     | yes            |
-| E `repository_green`       | the real repository lock                                          | zero     | `0`           | `check-workspace-versions: OK`                                                                                               | yes            |
+compile/setup/environment failure), and every scenario leaves its
+`Cargo.lock` byte-for-byte unchanged (the trap-regression scenarios G/H mutate or
+delete a TEMP fixture lock on purpose, and the harness verifies the REAL
+repository lock is never touched).
+
+| Scenario                   | Description                                                       | Expected  | Observed exit | Diagnostic / assertion                                                                                                       | Lock unchanged |
+| -------------------------- | ----------------------------------------------------------------- | --------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| A `manifest_lock_drift`    | manifest `0.40.4` / lock members `0.40.3`                         | nonzero   | `1`           | `Cargo.lock package 'fixture-pa' = '0.40.3' != [workspace.package] version = '0.40.4'` (and `fixture-pb`)                    | yes            |
+| B `package_set_mismatch`   | extra source-less lock entry (`vendored` excluded from workspace) | nonzero   | `1`           | `workspace package set differs between cargo metadata and Cargo.lock (source-less)` … only in Cargo.lock: `fixture-vendored` | yes            |
+| C `stale_version_txt`      | `version.txt` = `0.40.3`, all else `0.40.4`                       | nonzero   | `1`           | `version.txt = '0.40.3' != [workspace.package] version = '0.40.4'`                                                           | yes            |
+| D `stale_release_manifest` | manifest `"."` = `0.40.3`, all else `0.40.4`                      | nonzero   | `1`           | `.release-please-manifest.json "." = '0.40.3' != [workspace.package] version = '0.40.4'`                                     | yes            |
+| E `repository_green`       | the real repository lock                                          | zero      | `0`           | `check-workspace-versions: OK`                                                                                               | yes            |
+| F `exact_cargo_argv`       | argv shim + caller cwd ≠ repo root                                | argv-only | `0`           | captured Cargo argv is exactly `metadata --locked --no-deps --format-version 1` — one call, no `--manifest-path`             | yes (repo)     |
+| G `trap_mutation`          | shim appends bytes to a TEMP fixture lock mid-gate                | `90`      | `90`          | `CRITICAL: Cargo.lock mutated during gate`                                                                                   | repo untouched |
+| H `trap_deletion`          | shim deletes a TEMP fixture lock mid-gate (under `set -e`)        | `90`      | `90`          | `CRITICAL: Cargo.lock mutated during gate` + `MISSING-OR-UNREADABLE` (trap not short-circuited)                              | repo untouched |
 
 ### Scope note
 
diff --git a/scripts/check-workspace-versions.sh b/scripts/check-workspace-versions.sh
index 357067c..12b076b 100755
--- a/scripts/check-workspace-versions.sh
+++ b/scripts/check-workspace-versions.sh
@@ -61,8 +61,15 @@ LOCK_SHA_PRE="$(sha256sum "$CARGO_LOCK" | awk '{print $1}')"
 
 verify_lock_unchanged() {
     local rc=$?
-    local post
-    post="$(sha256sum "$CARGO_LOCK" 2>/dev/null | awk '{print $1}')"
+    local post=""
+    # Deterministic re-hash: a deleted or unreadable lock cannot match the
+    # snapshot, so treat any hashing failure as `post=<MISSING>` (i.e. changed).
+    # `|| true` keeps `set -e` from short-circuiting the trap before it can
+    # report exit 90.
+    if [ -f "$CARGO_LOCK" ] && [ -r "$CARGO_LOCK" ]; then
+        post="$(sha256sum "$CARGO_LOCK" 2>/dev/null | awk '{print $1}')" || post=""
+    fi
+    [ -n "$post" ] || post="<MISSING-OR-UNREADABLE>"
     if [ "$post" != "$LOCK_SHA_PRE" ]; then
         printf 'check-workspace-versions: CRITICAL: Cargo.lock mutated during gate\n' >&2
         printf '  pre : %s\n' "$LOCK_SHA_PRE" >&2
@@ -75,14 +82,16 @@ trap verify_lock_unchanged EXIT
 
 # ---------------------------------------------------------------------------
 # FIRST CARGO SUBPROCESS: cargo metadata --locked --no-deps --format-version 1
-# Non-mutating; yields the authoritative workspace package set. If the lock is
-# stale relative to the manifests, --locked makes Cargo refuse (drift), which is
-# itself a version-consistency failure this gate must surface.
+# Run from the workspace root (cwd) so the argv is EXACTLY that — no
+# `--manifest-path` — while still working from any caller cwd. Non-mutating;
+# yields the authoritative workspace package set. If the lock is stale relative
+# to the manifests, --locked makes Cargo refuse (drift), which is itself a
+# version-consistency failure this gate must surface.
 # ---------------------------------------------------------------------------
 META_JSON=""
 META_ERR=""
-if ! META_JSON="$(cargo metadata --locked --no-deps --format-version 1 \
-    --manifest-path "$CARGO_TOML" 2>/tmp/cwv_meta_err.$$)"; then
+if ! META_JSON="$(cd "$WORKSPACE_ROOT" && \
+    cargo metadata --locked --no-deps --format-version 1 2>/tmp/cwv_meta_err.$$)"; then
     META_ERR="$(cat "/tmp/cwv_meta_err.$$" 2>/dev/null || true)"
     rm -f "/tmp/cwv_meta_err.$$"
     printf 'check-workspace-versions: FAIL: cargo metadata --locked refused — Cargo.lock is\n' >&2
diff --git a/scripts/tests/check-workspace-versions.test.sh b/scripts/tests/check-workspace-versions.test.sh
index 6376de8..09636fb 100755
--- a/scripts/tests/check-workspace-versions.test.sh
+++ b/scripts/tests/check-workspace-versions.test.sh
@@ -31,6 +31,11 @@ V="0.40.4"
 
 [ -x "$GATE" ] || { printf 'harness: gate not executable: %s\n' "$GATE" >&2; exit 2; }
 
+# Absolute path to the REAL cargo, resolved BEFORE any shim dir is prepended to
+# PATH, so shims can delegate without a recursive PATH lookup.
+REAL_CARGO="$(command -v cargo)"
+[ -n "$REAL_CARGO" ] || { printf 'harness: cargo not found on PATH\n' >&2; exit 2; }
+
 WORK="$(mktemp -d)"
 cleanup() { rm -rf "$WORK"; }
 trap cleanup EXIT
@@ -141,9 +146,10 @@ make_base_workspace "$DIR_A" "$V"
 sed -i 's/^version = "0.40.4"$/version = "0.40.3"/' "$DIR_A/Cargo.lock"
 run_scenario "A_manifest_lock_drift" "$DIR_A" 1 "out of date|MISMATCH|0\.40\.3"
 
-# Scenario B — package-set mismatch: a source-less vendored crate exists in the
-# lock and is a path dependency of pa, but is NOT a workspace member, so
-# `cargo metadata --no-deps` omits it while the lock lists it.
+# Scenario B — package-set mismatch: a source-less vendored crate is listed in
+# Cargo.lock and is a path dependency of pa, but its directory is `exclude`d from
+# the workspace, so `cargo metadata --no-deps` omits it while the lock lists it.
+# The gate must flag the extra source-less lock entry.
 DIR_B="$WORK/pkgset"
 make_base_workspace "$DIR_B" "$V"
 mkdir -p "$DIR_B/vendored/src"
@@ -154,6 +160,15 @@ version = "$V"
 edition = "2021"
 EOF
 printf '// fixture\n' > "$DIR_B/vendored/src/lib.rs"
+cat > "$DIR_B/Cargo.toml" <<EOF
+[workspace]
+members = ["pa", "pb"]
+exclude = ["vendored"]
+resolver = "2"
+
+[workspace.package]
+version = "$V"
+EOF
 cat > "$DIR_B/pa/Cargo.toml" <<'EOF'
 [package]
 name = "fixture-pa"
@@ -200,5 +215,109 @@ run_scenario "D_stale_release_manifest" "$DIR_D" 1 "release-please-manifest"
 # Scenario E — the real repository lock (Green and unchanged).
 run_scenario "E_repository_green" "$REPO_ROOT" 0 "check-workspace-versions: OK"
 
+# ---------------------------------------------------------------------------
+# Scenario F — exact Cargo argv. A logging shim first on PATH records argv then
+# delegates to the ABSOLUTE real cargo (no recursive PATH lookup). Run the gate
+# from a caller cwd OTHER than the repo root (here: a temp dir) while passing the
+# repo root, and assert the captured first (and only) Cargo argv is exactly
+# `metadata --locked --no-deps --format-version 1` with NO `--manifest-path`.
+# ---------------------------------------------------------------------------
+SHIM_DIR="$WORK/shim"
+CARGO_LOG="$WORK/cargo-argv.log"
+mkdir -p "$SHIM_DIR"
+cat > "$SHIM_DIR/cargo" <<EOF
+#!/usr/bin/env bash
+printf '%s\n' "\$*" >> "$CARGO_LOG"
+exec "$REAL_CARGO" "\$@"
+EOF
+chmod +x "$SHIM_DIR/cargo"
+: > "$CARGO_LOG"
+
+f_pre="$(sha256sum "$REPO_ROOT/Cargo.lock" | awk '{print $1}')"
+f_ok=1
+# Deliberately invoke from a caller cwd that is NOT the repo root.
+( cd "$WORK" && PATH="$SHIM_DIR:$PATH" "$GATE" "$REPO_ROOT" ) >"$WORK/F.out" 2>"$WORK/F.err" || {
+    bad "F_exact_cargo_argv: gate exited nonzero"; note "stderr: $(tr '\n' '|' < "$WORK/F.err")"; f_ok=0;
+}
+f_post="$(sha256sum "$REPO_ROOT/Cargo.lock" | awk '{print $1}')"
+first_argv="$(head -1 "$CARGO_LOG")"
+argv_count="$(grep -c . "$CARGO_LOG" || true)"
+if [ "$first_argv" != "metadata --locked --no-deps --format-version 1" ]; then
+    bad "F_exact_cargo_argv: first argv was '$first_argv' (expected exactly 'metadata --locked --no-deps --format-version 1')"; f_ok=0
+fi
+if grep -q -- '--manifest-path' "$CARGO_LOG"; then
+    bad "F_exact_cargo_argv: --manifest-path appeared in captured Cargo argv"; f_ok=0
+fi
+if [ "$argv_count" -ne 1 ]; then
+    bad "F_exact_cargo_argv: expected exactly 1 Cargo call, captured $argv_count"; f_ok=0
+fi
+if [ "$f_pre" != "$f_post" ]; then
+    bad "F_exact_cargo_argv: repository Cargo.lock changed (pre=$f_pre post=$f_post)"; f_ok=0
+fi
+[ "$f_ok" -eq 1 ] && ok "F_exact_cargo_argv (argv='$first_argv', calls=$argv_count, from cwd=$WORK)"
+
+# ---------------------------------------------------------------------------
+# Scenario G — EXIT-trap mutation detection. A shim MUTATES a TEMP fixture's
+# Cargo.lock mid-gate (after the snapshot, during the metadata call), then
+# delegates to the real cargo. The gate's EXIT trap must detect the changed lock
+# and exit 90 with the CRITICAL message. Operates ONLY on the temp fixture; the
+# repository lock is never touched.
+# ---------------------------------------------------------------------------
+DIR_G="$WORK/trap_mutate"
+make_base_workspace "$DIR_G" "$V"
+SHIM_G="$WORK/shim_g"
+mkdir -p "$SHIM_G"
+cat > "$SHIM_G/cargo" <<EOF
+#!/usr/bin/env bash
+# Mutate the fixture lock AFTER the gate snapshotted it, then run real cargo.
+printf '\n# mutated by trap-regression shim\n' >> "$DIR_G/Cargo.lock"
+exec "$REAL_CARGO" "\$@"
+EOF
+chmod +x "$SHIM_G/cargo"
+g_ok=1
+set +e
+PATH="$SHIM_G:$PATH" "$GATE" "$DIR_G" >"$WORK/G.out" 2>"$WORK/G.err"
+g_rc=$?
+set -e
+if [ "$g_rc" -ne 90 ]; then
+    bad "G_trap_mutation: expected exit 90, got $g_rc"; note "stderr: $(tr '\n' '|' < "$WORK/G.err")"; g_ok=0
+fi
+if ! grep -q 'CRITICAL: Cargo.lock mutated during gate' "$WORK/G.err"; then
+    bad "G_trap_mutation: missing CRITICAL mutation diagnostic"; g_ok=0
+fi
+[ "$g_ok" -eq 1 ] && ok "G_trap_mutation (exit=$g_rc, CRITICAL reported)"
+
+# ---------------------------------------------------------------------------
+# Scenario H — EXIT-trap DELETION detection under `set -e`. A shim DELETES a
+# TEMP fixture's Cargo.lock mid-gate. The trap must treat the missing/unhashable
+# lock as changed and still deterministically exit 90 (not be short-circuited by
+# `set -e`). Operates ONLY on the temp fixture.
+# ---------------------------------------------------------------------------
+DIR_H="$WORK/trap_delete"
+make_base_workspace "$DIR_H" "$V"
+SHIM_H="$WORK/shim_h"
+mkdir -p "$SHIM_H"
+cat > "$SHIM_H/cargo" <<EOF
+#!/usr/bin/env bash
+rm -f "$DIR_H/Cargo.lock"
+exec "$REAL_CARGO" "\$@"
+EOF
+chmod +x "$SHIM_H/cargo"
+h_ok=1
+set +e
+PATH="$SHIM_H:$PATH" "$GATE" "$DIR_H" >"$WORK/H.out" 2>"$WORK/H.err"
+h_rc=$?
+set -e
+if [ "$h_rc" -ne 90 ]; then
+    bad "H_trap_deletion: expected exit 90, got $h_rc"; note "stderr: $(tr '\n' '|' < "$WORK/H.err")"; h_ok=0
+fi
+if ! grep -q 'CRITICAL: Cargo.lock mutated during gate' "$WORK/H.err"; then
+    bad "H_trap_deletion: missing CRITICAL diagnostic"; h_ok=0
+fi
+if ! grep -q 'MISSING-OR-UNREADABLE' "$WORK/H.err"; then
+    bad "H_trap_deletion: missing/unreadable lock not reported as changed"; h_ok=0
+fi
+[ "$h_ok" -eq 1 ] && ok "H_trap_deletion (exit=$h_rc, missing lock → 90)"
+
 printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
 [ "$FAIL" -eq 0 ]

From 31db6ab12a9ce769d9fae90ce400668160d16d15 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 05:59:51 +0800
Subject: [PATCH 05/91] test(index): add Batch M black-box Red for isolated v2
 namespace

Add the initial black-box behavioral Red for Batch M: `codegraph init`
must build the index in the isolated sibling `.codegraph-v2` namespace,
never the fixed legacy `.codegraph` root. The test uses only the shipped
public CLI surface and filesystem artifacts and imports no proposed Green
API. On the v0.40.4 base it fails behaviorally because init still writes
the legacy namespace. Record the pre-Red provenance/base gates, exact
command/exit status, and failing assertion in the evidence ledger.
---
 .../tests/batch_m_v2_namespace.rs             | 176 ++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  84 +++++++++
 2 files changed, 260 insertions(+)
 create mode 100644 crates/codegraph-cli/tests/batch_m_v2_namespace.rs

diff --git a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
new file mode 100644
index 0000000..fd0538d
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
@@ -0,0 +1,176 @@
+//! Batch M — initial black-box Red for the isolated v2 index namespace.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md` (Batch M, "Product boundary and
+//! selected storage layout", plan line ~262) makes an explicit product-level
+//! compatibility break: the default *current* index root is
+//! `project/.codegraph-v2`, a **sibling** of the fixed legacy `project/.codegraph`
+//! root, and new binaries never open, migrate, or write the legacy namespace
+//! (plan lines 288-291). Acceptance for the Red boundary (plan lines 805-817)
+//! requires black-box evidence that current v0.40.4 behavior "opens/writes the
+//! fixed legacy `.codegraph` namespace instead of an isolated `.codegraph-v2`
+//! namespace".
+//!
+//! This is the INITIAL black-box Red described at plan lines 805-809: it uses
+//! ONLY the shipped public CLI surface (`codegraph init`) and filesystem
+//! artifacts. It imports no proposed Green type (`IndexPaths`, `IndexLease`,
+//! `open_for_*`) — those are Green design, not compile-time Red prerequisites.
+//! It is NOT the later API-level refinement of the store/lease/path modes.
+//!
+//! Isolation mirrors `cli_commands.rs`: a private temp project plus an isolated
+//! `CODEGRAPH_HTTP_REGISTRY_DIR`, and `CODEGRAPH_NO_DAEMON=1` so no daemon
+//! rendezvous state leaks. The default `init` target is `none`, so no agent
+//! config is written.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-batchm-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    std::fs::create_dir_all(dst).unwrap();
+    for entry in std::fs::read_dir(src).unwrap() {
+        let entry = entry.unwrap();
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            std::fs::copy(&from, &to).unwrap();
+        }
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(registry_dir: &Path, args: &[&str]) -> Run {
+    let output = Command::new(bin())
+        .args(args)
+        .env("CODEGRAPH_HTTP_REGISTRY_DIR", registry_dir)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+/// Initial Batch M black-box Red: `init` must build the index in the isolated
+/// sibling `.codegraph-v2` namespace, never the fixed legacy `.codegraph` one.
+///
+/// Expected Red on the v0.40.4 base: `init` writes `.codegraph/codegraph.db`
+/// (the fixed legacy root) and never creates `.codegraph-v2`, so the named
+/// v2-namespace assertion fails behaviorally. The setup (`init` succeeds) and
+/// the byte snapshot below both reach the assertion, so this is a behavioral —
+/// not a compile/setup/panic — failure. The snapshot preserves the built DB
+/// bytes that later Green will assert remain a byte-usable legacy graph.
+#[test]
+fn init_writes_isolated_v2_namespace_not_legacy_codegraph() {
+    let dir = TestDir::new("v2-namespace");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    // Public shipped surface only.
+    let run = run_in(dir.path(), &["init", p]);
+    assert!(
+        run.ok,
+        "setup: `codegraph init` must succeed before the behavioral assertion \
+         (stdout={}, stderr={})",
+        run.stdout, run.stderr
+    );
+
+    let legacy_root = project.join(".codegraph");
+    let legacy_db = legacy_root.join("codegraph.db");
+    let v2_root = project.join(".codegraph-v2");
+    let v2_db = v2_root.join("codegraph.db");
+
+    // Byte snapshot of the DB the build actually produced (whichever namespace
+    // it landed in). Later Green preserves this as the byte-usable legacy graph;
+    // recording it here proves the build produced a non-empty DB and that the
+    // failure below is a namespace-placement failure, not an empty/failed build.
+    let built_db = if v2_db.is_file() {
+        v2_db.clone()
+    } else {
+        legacy_db.clone()
+    };
+    let built_bytes = std::fs::read(&built_db).unwrap_or_default();
+    assert!(
+        !built_bytes.is_empty(),
+        "setup: `init` must produce a non-empty index DB (checked {}); \
+         got legacy_db.is_file()={}, v2_db.is_file()={}",
+        built_db.display(),
+        legacy_db.is_file(),
+        v2_db.is_file()
+    );
+
+    // PRIMARY behavioral Red assertion (plan line 262 + lines 805-817): the DB
+    // must live in the isolated sibling v2 namespace, not the legacy root.
+    assert!(
+        v2_db.is_file(),
+        "Batch M: `init` must create the isolated v2 namespace at {} \
+         (a sibling of the legacy root, per plan line 262), but no v2 DB exists; \
+         current v0.40.4 behavior wrote the legacy namespace instead \
+         (.codegraph/codegraph.db present={})",
+        v2_db.display(),
+        legacy_db.is_file()
+    );
+
+    // Secondary behavioral Red assertion (plan lines 288-291): new binaries must
+    // never write the fixed legacy namespace. Reached only once the v2 assertion
+    // passes at Green; both are Green-stable (legacy root absent post-Green).
+    assert!(
+        !legacy_db.is_file(),
+        "Batch M: a new binary must not write the legacy namespace at {}; \
+         the fixed legacy `.codegraph` root is read-only to new binaries",
+        legacy_db.display()
+    );
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index b8c1808..e1fa9a9 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -196,3 +196,87 @@ of which remain E2 follow-up work. No version value in `Cargo.toml`, `Cargo.lock
 `version.txt`, or `.release-please-manifest.json` was modified. No third-party
 dependency was added; the gate uses only `bash`, `awk`, `sed`, `jq`, and
 `sha256sum` already present in the repository's toolchain.
+
+## Batch M initial black-box Red — isolated v2 namespace
+
+This is the INITIAL black-box behavioral Red for Batch M, exactly as scoped by the
+frozen plan (`upstream-v1.5-portable-fixes.md`) at line 805: "Batch M starts with
+behaviorally failing black-box CLI/MCP/process tests that use only existing public
+surfaces and filesystem artifacts." It is NOT a later API-level refinement; it
+imports no proposed Green type (`IndexPaths`, `IndexLease`, `open_for_*`), which
+plan lines 806-807 explicitly mark as Green design, not compile-time Red
+prerequisites. No production/Green code was written.
+
+### Pre-Red gates (all passed, in order)
+
+- Final pre-Red base gate (plan lines 87-91): `git fetch origin main`; peeled
+  remote tip `origin/main`, branch merge-base `HEAD..origin/main`, and reviewed
+  base all equal `aba40799ecacb94515f7e1690914d2accc4c8973`. Local `HEAD` before
+  Red = `10352ba0943622e665b0ff96c5b5f57589448c9c` (branch tip; its base is
+  `aba4079`). No divergence → Red authorized.
+- Network provenance gate (plan lines 40-47): fresh
+  `git clone https://github.com/colbymchenry/codegraph.git`; boundary commits
+  `ecc8b307ac2f8a7d06bff02ee513c4ea2380b2f8..ea72e1b190921232aa7bd02e96bef5bbe4fe0ab6`
+  present; `git log --reverse --format='%H|%s'` over the two boundary SHAs yields
+  exactly **86** rows; formatting each row as a numbered-free markdown table row
+  `| \`<short7>\` | <subject> |\n`(backticked seven-lowercase-hex short SHA +
+subject) reproduces source-list SHA-256`60746f77a9ce721c10b83bc5bb8804c153f7da84217c4afb96f26645c6aa33f7`. Match.
+- Frozen identities still match: plan SHA
+  `5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`; immutable
+  manifest SHA `1bf8a9022b7702368a66f0159ce84dc6ba846e5aa9c8db32f3e2ecf83affbc96`;
+  `.gitignore` `beb58777556b1e37354e5adb3ec15834683edaaba95f15bfed13d92dda42c13a`;
+  `.oxfmtignore` `7fb05bd0552e6e383434d7b807f836eb8e1474e08e84adfaab09c8cd8553f103`;
+  `UPSTREAM.md` `e99826c37572235266299f49d206f7c441f822297cc2e5d66745a275d6bf129f`;
+  `KNOWN_DIFFS.md` `2c973b6f1407b409131c20849de44f15dc9989c1b47bb278e836daf3c682c07d`.
+- Workspace-version gate `bash scripts/check-workspace-versions.sh` → exit `0`
+  ("check-workspace-versions: OK", workspace version `0.40.4`) run before Cargo
+  test discovery; repository `Cargo.lock` SHA-256 unchanged before/after every
+  Cargo invocation:
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+Legacy v0.40.4 asset fixture (plan lines 685-693) was NOT needed for this initial
+boundary: the selected Red proves the namespace-placement gap using only the
+current in-tree binary (`codegraph init`) and the committed `mini` corpus, with no
+downloaded legacy executable. The downloaded-asset manifest is reserved for the
+later legacy-isolation Red (plan tests 3/4) that actually runs the v0.40.4 binary.
+
+### Test added
+
+`crates/codegraph-cli/tests/batch_m_v2_namespace.rs` ::
+`init_writes_isolated_v2_namespace_not_legacy_codegraph`. Black-box: drives the
+shipped `codegraph init` against a private temp copy of the `mini` fixture, with
+isolated `CODEGRAPH_HTTP_REGISTRY_DIR` and `CODEGRAPH_NO_DAEMON=1`, then inspects
+filesystem artifacts only. The setup step (`init` succeeds) and a non-empty
+built-DB byte snapshot both reach the assertion, so the failure is behavioral, not
+a compile/setup/panic/network failure. The snapshot preserves the built DB bytes
+that later Green asserts remain a byte-usable legacy graph.
+
+### Discovery + execution
+
+- Owner discovery: `cargo test -p codegraph-rs --locked --test batch_m_v2_namespace -- --list`
+  → lists `init_writes_isolated_v2_namespace_not_legacy_codegraph: test`
+  (`1 test, 0 benchmarks`), confirming the test binary compiles and the target
+  owns the test (package `codegraph-rs`, test target `batch_m_v2_namespace`, per
+  plan line 1273 "M CLI").
+- Red run:
+  `cargo test -p codegraph-rs --locked --test batch_m_v2_namespace init_writes_isolated_v2_namespace_not_legacy_codegraph -- --exact`
+  → process exit `101` (`test result: FAILED. 0 passed; 1 failed`).
+- Exact failing assertion (behavioral, plan line 262 + lines 805-817):
+  "Batch M: `init` must create the isolated v2 namespace at
+  `<tmp>/mini/.codegraph-v2/codegraph.db` (a sibling of the legacy root, per plan
+  line 262), but no v2 DB exists; current v0.40.4 behavior wrote the legacy
+  namespace instead (.codegraph/codegraph.db present=true)". This is precisely the
+  Red-evidence requirement of plan lines 811-812 ("Red evidence must demonstrate
+  the current fixed legacy path …").
+
+### Classification
+
+Initial black-box behavioral Red (plan lines 805-809), NOT a later API-level
+refinement. Remaining Batch M Red is NOT yet landed and is explicitly deferred to
+subsequent commits: stale-row serving / hash-skip migration (tests 2, 9),
+extension-filtered folder delete (test 18), stamp/finalizer gap (test 8),
+absent typed/lease/path gates (tests 6, 7), legacy-binary storage isolation
+(tests 3, 4) which require the downloaded v0.40.4 asset fixture, and every
+lease/lifecycle/uninit-state test (tests 5, 11, 12, 13, 15, 16, 20, 21) whose
+deterministic form needs the minimal compiling Green scaffolding. This commit
+lands only the initial black-box namespace boundary.

From b5a66f256ae881d51aed3c55d5f410722a86cec9 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 07:51:36 +0800
Subject: [PATCH 06/91] feat(core): add IndexPaths v2 namespace path authority

Introduce codegraph-core::IndexPaths as the single path authority for the
isolated v2 index namespace (frozen plan Batch M, lines 236-338). It resolves,
for a project and optional CODEGRAPH_DIR override:

- the physical projectIdentity (full lowercase SHA-256 of a versioned binary
  payload: st_dev/st_ino on Unix, volume serial + 128-bit FileIdInfo on
  Windows), failing closed on unsupported filesystems with no lexical fallback;
- the normalized legacy-root set (fixed .codegraph plus the configured old CLI
  root) that new binaries never open;
- the isolated current root (.codegraph-v2 by default; a <name>-v2-<identity>
  sibling of a configured legacy root), plus every current-root artifact path
  (db, permanent lock, two fixed state slots, tombstone, config.toml,
  codegraph.json, daemon pid/log/socket).

Path identity is physical: canonicalize the project and legacy roots, anchor a
not-yet-created root on its nearest existing ancestor, and fail closed on
empty/root/dot/parent aliases, symlink/reparse components below that ancestor,
legacy equality, and ancestor/descendant overlap. Two distinct projects sharing
a configured root receive distinct identity-suffixed current roots.

Also adds infallible transitional helpers (current_root_lenient,
current_db_lenient) and is_reserved_index_dir for the data-plane wiring in the
next slice. This commit is the path layer only; the state-slot/lease/Store open
protocol that consumes these paths lands in a later Batch M task.
---
 crates/codegraph-core/src/index_paths.rs | 988 +++++++++++++++++++++++
 crates/codegraph-core/src/lib.rs         |   2 +
 2 files changed, 990 insertions(+)
 create mode 100644 crates/codegraph-core/src/index_paths.rs

diff --git a/crates/codegraph-core/src/index_paths.rs b/crates/codegraph-core/src/index_paths.rs
new file mode 100644
index 0000000..13e0c4b
--- /dev/null
+++ b/crates/codegraph-core/src/index_paths.rs
@@ -0,0 +1,988 @@
+//! Single source of truth for CodeGraph's on-disk index paths.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md`, Batch M ("Product boundary and
+//! selected storage layout", plan lines 236-338): `IndexPaths` is the ONE path
+//! authority shared by CLI, store, daemon, watch, and MCP. Production code must
+//! NOT reconstruct `.codegraph*` paths independently.
+//!
+//! This module implements the PATH LAYER ONLY (the first Batch M slice). It
+//! computes, for a given project and optional `CODEGRAPH_DIR` override:
+//!
+//! - the physical [`project_identity`](IndexPaths::project_identity) (full
+//!   lowercase SHA-256 of a versioned binary payload of the OS filesystem
+//!   identifiers — `st_dev`/`st_ino` on Unix, volume serial + 128-bit file id on
+//!   Windows). Unsupported filesystems fail closed; there is NO lexical-spelling
+//!   fallback;
+//! - the normalized [`legacy_roots`](IndexPaths::legacy_roots) set: the fixed
+//!   `<project>/.codegraph` root plus, when `CODEGRAPH_DIR` is set, the old CLI
+//!   root (relative-or-absolute), modeling v0.40.4's inconsistent env handling;
+//! - the isolated [`current_root`](IndexPaths::current_root) — `<project>/.codegraph-v2`
+//!   by default, or a `<name>-v2-<projectIdentity>` SIBLING of the normalized
+//!   legacy root when `CODEGRAPH_DIR` is set;
+//! - every current-root-owned artifact path (DB, permanent lock, the two fixed
+//!   state slots, the `uninitialized` tombstone, `config.toml`, `codegraph.json`,
+//!   and the daemon pid/log/socket identities).
+//!
+//! Path identity is PHYSICAL, not lexical: the project and each existing legacy
+//! root are canonicalized; a not-yet-created root canonicalizes its nearest
+//! existing ancestor and appends the normalized remainder. Empty/root/dot/parent
+//! aliases, symlink (or Windows reparse-point) components below the canonical
+//! ancestor, equality with any legacy identity, and any ancestor/descendant
+//! overlap with a legacy identity all fail closed with typed, stable diagnostics.
+//!
+//! This slice provides the path VALUES only; the state-slot / lease / Store open
+//! protocol that CONSUMES the state-slot, tombstone, and lock paths lands in a
+//! later Batch M task.
+
+use std::path::{Component, Path, PathBuf};
+
+use sha2::{Digest, Sha256};
+use thiserror::Error;
+
+/// Default current-root directory name (no `CODEGRAPH_DIR`): a sibling of the
+/// fixed legacy `.codegraph` root. This is the ONE place the `.codegraph-v2`
+/// literal is defined; every production consumer derives its default root from
+/// here (directly or via [`IndexPaths::current_root_lenient`]).
+pub const DEFAULT_CURRENT_DIR: &str = ".codegraph-v2";
+/// Fixed legacy root directory name used by old daemon/watch/MCP paths.
+pub const LEGACY_DIR: &str = ".codegraph";
+/// Infix inserted into a configured legacy root's final component to form the
+/// sibling current root (`<name>-v2-<projectIdentity>`).
+const CONFIGURED_SUFFIX_INFIX: &str = "-v2-";
+
+/// Version byte of the binary payload hashed into the project identity. Bump
+/// only with a deliberate, reviewed identity-format change.
+const IDENTITY_PAYLOAD_VERSION: u8 = 1;
+/// Magic prefix so the identity payload can never collide with an unrelated
+/// SHA-256 preimage.
+const IDENTITY_MAGIC: &[u8; 5] = b"cgpid";
+#[cfg(unix)]
+const IDENTITY_PLATFORM_UNIX: u8 = 1;
+#[cfg(windows)]
+const IDENTITY_PLATFORM_WINDOWS: u8 = 2;
+
+/// Errors from [`IndexPaths::resolve`]. All variants carry stable, deterministic
+/// diagnostics; there is never a fallback from physical identity to path
+/// spelling on unsupported filesystems.
+#[derive(Debug, Error)]
+pub enum IndexPathsError {
+    /// The project path could not be canonicalized (missing or inaccessible).
+    #[error("project path is not accessible: {path} ({source})")]
+    ProjectInaccessible {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+
+    /// The filesystem does not expose the stable physical identifiers required to
+    /// derive a project identity. Fail closed — never fall back to path spelling.
+    #[error(
+        "cannot derive a physical project identity for {path}: \
+         the filesystem does not expose stable identifiers ({detail})"
+    )]
+    UnsupportedFilesystem { path: PathBuf, detail: String },
+
+    /// A path component could not be canonicalized (an existing ancestor became
+    /// inaccessible mid-resolution).
+    #[error("cannot canonicalize index path component {path}: {source}")]
+    Canonicalize {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+
+    /// An empty/filesystem-root/`.`/`..` alias was supplied or derived.
+    #[error("refusing an unsafe index root {path}: {reason}")]
+    RootAlias { path: PathBuf, reason: String },
+
+    /// A symlink (or Windows reparse-point) component was found below the
+    /// canonical ancestor of an index root. Fail closed rather than follow it.
+    #[error(
+        "refusing index root: {path} is (or descends through) a symlink / \
+         reparse point below its canonical ancestor"
+    )]
+    SymlinkComponent { path: PathBuf },
+
+    /// The derived current root equals, contains, or is contained by a legacy
+    /// root. The current namespace must be fully disjoint from every legacy one.
+    #[error(
+        "refusing current index root {current}: it overlaps the legacy root \
+         {legacy} ({reason})"
+    )]
+    LegacyOverlap {
+        current: PathBuf,
+        legacy: PathBuf,
+        reason: String,
+    },
+}
+
+/// The resolved, physical, fail-closed set of index paths for one project.
+///
+/// Construct via [`IndexPaths::resolve`]. Every artifact path is derived from a
+/// single validated [`current_root`](IndexPaths::current_root); callers consume
+/// these accessors instead of rebuilding `.codegraph-v2` strings.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IndexPaths {
+    project: PathBuf,
+    project_identity: String,
+    legacy_roots: Vec<PathBuf>,
+    current_root: PathBuf,
+}
+
+impl IndexPaths {
+    /// Resolve the physical index paths for `project`, honoring an optional
+    /// `CODEGRAPH_DIR` override (relative or absolute). Production callers pass
+    /// `std::env::var("CODEGRAPH_DIR").ok().as_deref()`.
+    ///
+    /// `project` MUST exist (it is canonicalized to derive the physical
+    /// identity). Fails closed on unsafe roots, symlink aliases, overlap with a
+    /// legacy root, and unsupported filesystems.
+    pub fn resolve(project: &Path, codegraph_dir: Option<&str>) -> Result<Self, IndexPathsError> {
+        let project =
+            project
+                .canonicalize()
+                .map_err(|source| IndexPathsError::ProjectInaccessible {
+                    path: project.to_path_buf(),
+                    source,
+                })?;
+
+        let project_identity = physical_identity(&project)?;
+
+        // Legacy root #1: the fixed `<project>/.codegraph` (old daemon/watch/MCP).
+        let legacy_fixed = physical_normalize(&project, &project.join(LEGACY_DIR))?;
+        let mut legacy_roots = vec![legacy_fixed];
+
+        // Legacy root #2 + configured current root: only when CODEGRAPH_DIR is set.
+        let configured = codegraph_dir.filter(|value| !value.is_empty());
+        let current_root = if let Some(value) = configured {
+            let raw = Path::new(value);
+            let cli_root = if raw.is_absolute() {
+                raw.to_path_buf()
+            } else {
+                project.join(raw)
+            };
+            let cli_root = lexical_normalize(&cli_root);
+            reject_project_alias(&project, &cli_root, value)?;
+            let cli_root = physical_normalize(&project, &cli_root)?;
+
+            // Sibling `<name>-v2-<projectIdentity>`, never a child.
+            let parent = cli_root
+                .parent()
+                .ok_or_else(|| IndexPathsError::RootAlias {
+                    path: cli_root.clone(),
+                    reason: "configured legacy root has no parent directory".to_string(),
+                })?;
+            let name = cli_root
+                .file_name()
+                .ok_or_else(|| IndexPathsError::RootAlias {
+                    path: cli_root.clone(),
+                    reason: "configured legacy root has no final component".to_string(),
+                })?
+                .to_string_lossy()
+                .into_owned();
+            let sibling_name = format!("{name}{CONFIGURED_SUFFIX_INFIX}{project_identity}");
+            let current = parent.join(sibling_name);
+
+            if !legacy_roots.contains(&cli_root) {
+                legacy_roots.push(cli_root);
+            }
+            physical_normalize(&project, &current)?
+        } else {
+            physical_normalize(&project, &project.join(DEFAULT_CURRENT_DIR))?
+        };
+
+        // Fail closed on any equality or ancestor/descendant overlap with a
+        // legacy identity: the current namespace must be fully disjoint.
+        for legacy in &legacy_roots {
+            if let Some(reason) = overlap_reason(&current_root, legacy) {
+                return Err(IndexPathsError::LegacyOverlap {
+                    current: current_root.clone(),
+                    legacy: legacy.clone(),
+                    reason: reason.to_string(),
+                });
+            }
+        }
+
+        Ok(Self {
+            project,
+            project_identity,
+            legacy_roots,
+            current_root,
+        })
+    }
+
+    /// Infallible transitional current-root resolver for the data plane.
+    ///
+    /// [`IndexPaths::resolve`] is the fail-closed authority, but it canonicalizes
+    /// and therefore REQUIRES the project to already exist — CLI helpers such as
+    /// `status` on a not-yet-initialized directory must stay infallible. This
+    /// helper centralizes the default-root literal so no consumer reconstructs
+    /// `.codegraph-v2`:
+    ///
+    /// - No / empty `CODEGRAPH_DIR` → `<project>/.codegraph-v2` (the isolated v2
+    ///   default; this is the placement the Batch M black-box Red asserts).
+    /// - `CODEGRAPH_DIR=<value>` → `<project>/<value>` (the pre-v0.40.4 simple
+    ///   join, preserved byte-for-byte). The plan's identity-suffixed sibling for
+    ///   a configured root is fully implemented and tested in [`resolve`]; wiring
+    ///   that richer form into the infallible data-plane helpers is a later Batch
+    ///   M consumer task, so this slice keeps the configured-root override at its
+    ///   existing semantics rather than half-implementing the sibling here.
+    pub fn current_root_lenient(project: &Path, codegraph_dir: Option<&str>) -> PathBuf {
+        match codegraph_dir.filter(|value| !value.is_empty()) {
+            Some(value) => project.join(value),
+            None => project.join(DEFAULT_CURRENT_DIR),
+        }
+    }
+
+    /// `<current_root_lenient>/codegraph.db` — the infallible transitional DB
+    /// path used by the data plane (CLI, MCP, watch) in this slice.
+    pub fn current_db_lenient(project: &Path, codegraph_dir: Option<&str>) -> PathBuf {
+        Self::current_root_lenient(project, codegraph_dir).join("codegraph.db")
+    }
+
+    /// Whether a directory basename is a reserved CodeGraph index root that the
+    /// scanner/watcher must never descend into: the fixed legacy `.codegraph`
+    /// and any `.codegraph-*` sibling (including the `.codegraph-v2` default).
+    /// Mirrors the watcher policy's existing `.codegraph-` prefix exclusion.
+    pub fn is_reserved_index_dir(name: &str) -> bool {
+        name == LEGACY_DIR || name.starts_with(".codegraph-")
+    }
+
+    /// Canonical project root.
+    pub fn project(&self) -> &Path {
+        &self.project
+    }
+
+    /// Full lowercase SHA-256 (64 hex chars) of the versioned physical-identity
+    /// payload. Same value seeds state ownership and configured-root suffixes.
+    pub fn project_identity(&self) -> &str {
+        &self.project_identity
+    }
+
+    /// The normalized legacy-root set: the fixed `<project>/.codegraph` plus,
+    /// when `CODEGRAPH_DIR` is set, the old CLI root. New binaries never open,
+    /// migrate, or write these.
+    pub fn legacy_roots(&self) -> &[PathBuf] {
+        &self.legacy_roots
+    }
+
+    /// The isolated current index root (`.codegraph-v2` by default; a
+    /// `<name>-v2-<projectIdentity>` sibling of the configured legacy root when
+    /// `CODEGRAPH_DIR` is set).
+    pub fn current_root(&self) -> &Path {
+        &self.current_root
+    }
+
+    /// `<current_root>/codegraph.db`.
+    pub fn current_db(&self) -> PathBuf {
+        self.current_root.join("codegraph.db")
+    }
+
+    /// `<current_root>/index.lock` — the permanent lock file (never truncated or
+    /// deleted by normal operation).
+    pub fn permanent_lock(&self) -> PathBuf {
+        self.current_root.join("index.lock")
+    }
+
+    /// The two fixed state-slot files `index-state.{0,1}.json`, in slot order.
+    pub fn state_slots(&self) -> [PathBuf; 2] {
+        [
+            self.current_root.join("index-state.0.json"),
+            self.current_root.join("index-state.1.json"),
+        ]
+    }
+
+    /// A single fixed state slot by index (0 or 1); indices other than 0/1 are
+    /// clamped into range so callers cannot address a nonexistent slot.
+    pub fn state_slot(&self, slot: usize) -> PathBuf {
+        let [zero, one] = self.state_slots();
+        if slot.is_multiple_of(2) { zero } else { one }
+    }
+
+    /// `<current_root>/uninitialized` — the interrupted-uninit tombstone marker.
+    pub fn tombstone(&self) -> PathBuf {
+        self.current_root.join("uninitialized")
+    }
+
+    /// `<current_root>/config.toml` — the project-scoped default config.
+    pub fn config_toml(&self) -> PathBuf {
+        self.current_root.join("config.toml")
+    }
+
+    /// `<current_root>/codegraph.json` — the project-scoped custom-extension /
+    /// Godot DSL config.
+    pub fn extension_config(&self) -> PathBuf {
+        self.current_root.join("codegraph.json")
+    }
+
+    /// `<current_root>/daemon.pid`.
+    pub fn daemon_pid(&self) -> PathBuf {
+        self.current_root.join("daemon.pid")
+    }
+
+    /// `<current_root>/daemon.log`.
+    pub fn daemon_log(&self) -> PathBuf {
+        self.current_root.join("daemon.log")
+    }
+
+    /// `<current_root>/daemon.sock` — the in-root daemon socket identity. (The
+    /// POSIX tmp-socket fallback and Windows namespaced-pipe forms, which carry
+    /// the v2 protocol discriminator, are owned by the daemon lifecycle layer in
+    /// a later slice.)
+    pub fn daemon_socket(&self) -> PathBuf {
+        self.current_root.join("daemon.sock")
+    }
+}
+
+/// Lexically normalize an absolute path: drop `.` components and fold each `..`
+/// into the preceding normal component. Never touches the filesystem.
+fn lexical_normalize(path: &Path) -> PathBuf {
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if matches!(out.components().next_back(), Some(Component::Normal(_))) {
+                    out.pop();
+                } else {
+                    out.push(component);
+                }
+            }
+            other => out.push(other),
+        }
+    }
+    out
+}
+
+/// Reject a configured legacy root that aliases the project itself, an ancestor
+/// of the project, or the filesystem root — the `.`/`..`/root alias cases.
+fn reject_project_alias(
+    project: &Path,
+    cli_root: &Path,
+    raw_value: &str,
+) -> Result<(), IndexPathsError> {
+    if cli_root.parent().is_none() {
+        return Err(IndexPathsError::RootAlias {
+            path: cli_root.to_path_buf(),
+            reason: format!("CODEGRAPH_DIR={raw_value:?} resolves to the filesystem root"),
+        });
+    }
+    if cli_root == project {
+        return Err(IndexPathsError::RootAlias {
+            path: cli_root.to_path_buf(),
+            reason: format!("CODEGRAPH_DIR={raw_value:?} resolves to the project root itself"),
+        });
+    }
+    if project.starts_with(cli_root) {
+        return Err(IndexPathsError::RootAlias {
+            path: cli_root.to_path_buf(),
+            reason: format!("CODEGRAPH_DIR={raw_value:?} resolves to an ancestor of the project"),
+        });
+    }
+    Ok(())
+}
+
+/// The deepest ancestor of `path` (inclusive) that currently exists, if any.
+fn nearest_existing_ancestor(path: &Path) -> Option<PathBuf> {
+    let mut current: Option<&Path> = Some(path);
+    while let Some(candidate) = current {
+        if candidate.symlink_metadata().is_ok() {
+            return Some(candidate.to_path_buf());
+        }
+        current = candidate.parent();
+    }
+    None
+}
+
+/// Whether `path` currently exists AND is a symlink / reparse point.
+fn is_symlink(path: &Path) -> bool {
+    path.symlink_metadata()
+        .map(|meta| meta.file_type().is_symlink())
+        .unwrap_or(false)
+}
+
+/// Physically normalize an index root: reject empty/root aliases, reject any
+/// symlink component below the canonical ancestor, and return the path anchored
+/// on the canonicalized nearest-existing ancestor.
+fn physical_normalize(project: &Path, target: &Path) -> Result<PathBuf, IndexPathsError> {
+    let target = lexical_normalize(target);
+    if target.parent().is_none() {
+        return Err(IndexPathsError::RootAlias {
+            path: target.clone(),
+            reason: "path is the filesystem root".to_string(),
+        });
+    }
+
+    let existing =
+        nearest_existing_ancestor(&target).ok_or_else(|| IndexPathsError::RootAlias {
+            path: target.clone(),
+            reason: "no existing ancestor directory".to_string(),
+        })?;
+
+    // `project` is already canonical (no symlink components). For a target under
+    // the project, probe only the tail below it and reject symlink components —
+    // the components above are the trusted physical base.
+    if let Ok(tail) = existing.strip_prefix(project) {
+        let mut probe = project.to_path_buf();
+        for component in tail.components() {
+            probe.push(component);
+            if is_symlink(&probe) {
+                return Err(IndexPathsError::SymlinkComponent { path: probe });
+            }
+        }
+        let remainder = target
+            .strip_prefix(&existing)
+            .expect("existing is an ancestor of target");
+        return Ok(existing.join(remainder));
+    }
+
+    // Target outside the project (an absolute CODEGRAPH_DIR or its sibling):
+    // reject an existing root that is itself a symlink alias, then anchor on the
+    // canonicalized nearest-existing ancestor.
+    if is_symlink(&existing) {
+        return Err(IndexPathsError::SymlinkComponent { path: existing });
+    }
+    let base = existing
+        .canonicalize()
+        .map_err(|source| IndexPathsError::Canonicalize {
+            path: existing.clone(),
+            source,
+        })?;
+    let remainder = target
+        .strip_prefix(&existing)
+        .expect("existing is an ancestor of target");
+    Ok(base.join(remainder))
+}
+
+/// If `current` and `legacy` overlap (equal, or one contains the other), return
+/// a stable reason string; otherwise `None`.
+fn overlap_reason(current: &Path, legacy: &Path) -> Option<&'static str> {
+    if current == legacy {
+        Some("equal paths")
+    } else if current.starts_with(legacy) {
+        Some("current root is inside the legacy root")
+    } else if legacy.starts_with(current) {
+        Some("legacy root is inside the current root")
+    } else {
+        None
+    }
+}
+
+/// Compute the full lowercase SHA-256 of the versioned physical-identity payload
+/// for a canonical project path. Fails closed on unsupported filesystems.
+fn physical_identity(project: &Path) -> Result<String, IndexPathsError> {
+    let payload = identity_payload(project)?;
+    let mut hasher = Sha256::new();
+    hasher.update(&payload);
+    Ok(hex_lower(&hasher.finalize()))
+}
+
+#[cfg(unix)]
+fn identity_payload(project: &Path) -> Result<Vec<u8>, IndexPathsError> {
+    use std::os::unix::fs::MetadataExt as _;
+
+    // `st_dev` + `st_ino` uniquely identify a filesystem object on POSIX; std
+    // exposes them without an external crate. A path that cannot be stat'd fails
+    // closed rather than falling back to spelling.
+    let meta = project
+        .metadata()
+        .map_err(|source| IndexPathsError::UnsupportedFilesystem {
+            path: project.to_path_buf(),
+            detail: format!("stat failed: {source}"),
+        })?;
+    let dev = meta.dev();
+    let ino = meta.ino();
+
+    let mut payload = Vec::with_capacity(IDENTITY_MAGIC.len() + 2 + 16);
+    payload.extend_from_slice(IDENTITY_MAGIC);
+    payload.push(IDENTITY_PAYLOAD_VERSION);
+    payload.push(IDENTITY_PLATFORM_UNIX);
+    payload.extend_from_slice(&dev.to_le_bytes());
+    payload.extend_from_slice(&ino.to_le_bytes());
+    Ok(payload)
+}
+
+#[cfg(windows)]
+fn identity_payload(project: &Path) -> Result<Vec<u8>, IndexPathsError> {
+    // The volume serial number + 128-bit file id from
+    // GetFileInformationByHandleEx(FileIdInfo) are the stable physical
+    // identifiers on Windows (the 64-bit BY_HANDLE index is insufficient on
+    // ReFS). Raw kernel32 FFI avoids adding a dependency; the whole block is
+    // `cfg(windows)` and never compiled on Unix CI.
+    let (volume_serial, file_id) = windows_identity::file_id_info(project)?;
+
+    let mut payload = Vec::with_capacity(IDENTITY_MAGIC.len() + 2 + 8 + 16);
+    payload.extend_from_slice(IDENTITY_MAGIC);
+    payload.push(IDENTITY_PAYLOAD_VERSION);
+    payload.push(IDENTITY_PLATFORM_WINDOWS);
+    payload.extend_from_slice(&volume_serial.to_le_bytes());
+    payload.extend_from_slice(&file_id);
+    Ok(payload)
+}
+
+#[cfg(not(any(unix, windows)))]
+fn identity_payload(project: &Path) -> Result<Vec<u8>, IndexPathsError> {
+    // Fail closed: no stable physical identifier available. NEVER fall back to
+    // path spelling.
+    Err(IndexPathsError::UnsupportedFilesystem {
+        path: project.to_path_buf(),
+        detail: "platform exposes no stable filesystem object identifier".to_string(),
+    })
+}
+
+#[cfg(windows)]
+mod windows_identity {
+    //! Minimal raw kernel32 FFI for the physical file identity. Compiled only on
+    //! Windows; adds no crate dependency.
+
+    use std::os::windows::ffi::OsStrExt as _;
+    use std::path::Path;
+
+    use super::IndexPathsError;
+
+    // FILE_INFO_BY_HANDLE_CLASS::FileIdInfo
+    const FILE_ID_INFO_CLASS: i32 = 18;
+    const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
+    const OPEN_EXISTING: u32 = 3;
+    const FILE_SHARE_READ: u32 = 0x0000_0001;
+    const FILE_SHARE_WRITE: u32 = 0x0000_0002;
+    const FILE_SHARE_DELETE: u32 = 0x0000_0004;
+    const INVALID_HANDLE_VALUE: isize = -1;
+
+    #[repr(C)]
+    struct FileIdInfo {
+        volume_serial_number: u64,
+        file_id: [u8; 16],
+    }
+
+    #[link(name = "kernel32")]
+    unsafe extern "system" {
+        fn CreateFileW(
+            lp_file_name: *const u16,
+            dw_desired_access: u32,
+            dw_share_mode: u32,
+            lp_security_attributes: *mut core::ffi::c_void,
+            dw_creation_disposition: u32,
+            dw_flags_and_attributes: u32,
+            h_template_file: isize,
+        ) -> isize;
+        fn GetFileInformationByHandleEx(
+            h_file: isize,
+            file_information_class: i32,
+            lp_file_information: *mut core::ffi::c_void,
+            dw_buffer_size: u32,
+        ) -> i32;
+        fn CloseHandle(h_object: isize) -> i32;
+    }
+
+    /// Return `(volume_serial_number, 128-bit file id)` for `path`, failing
+    /// closed on any filesystem that does not support the query.
+    pub(super) fn file_id_info(path: &Path) -> Result<(u64, [u8; 16]), IndexPathsError> {
+        let mut wide: Vec<u16> = path.as_os_str().encode_wide().collect();
+        wide.push(0);
+
+        // SAFETY: `wide` is a NUL-terminated UTF-16 path; all other pointers are
+        // null/valid and the handle is closed on every path below.
+        let handle = unsafe {
+            CreateFileW(
+                wide.as_ptr(),
+                0,
+                FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+                core::ptr::null_mut(),
+                OPEN_EXISTING,
+                FILE_FLAG_BACKUP_SEMANTICS,
+                0,
+            )
+        };
+        if handle == INVALID_HANDLE_VALUE {
+            return Err(IndexPathsError::UnsupportedFilesystem {
+                path: path.to_path_buf(),
+                detail: format!("CreateFileW failed: {}", std::io::Error::last_os_error()),
+            });
+        }
+
+        let mut info = FileIdInfo {
+            volume_serial_number: 0,
+            file_id: [0u8; 16],
+        };
+        // SAFETY: `handle` is valid; `info` is a correctly sized FILE_ID_INFO.
+        let ok = unsafe {
+            GetFileInformationByHandleEx(
+                handle,
+                FILE_ID_INFO_CLASS,
+                (&mut info as *mut FileIdInfo).cast(),
+                core::mem::size_of::<FileIdInfo>() as u32,
+            )
+        };
+        // SAFETY: close the handle exactly once regardless of the query result.
+        unsafe {
+            CloseHandle(handle);
+        }
+
+        if ok == 0 {
+            return Err(IndexPathsError::UnsupportedFilesystem {
+                path: path.to_path_buf(),
+                detail: format!(
+                    "GetFileInformationByHandleEx(FileIdInfo) failed: {}",
+                    std::io::Error::last_os_error()
+                ),
+            });
+        }
+        Ok((info.volume_serial_number, info.file_id))
+    }
+}
+
+fn hex_lower(bytes: &[u8]) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for byte in bytes {
+        out.push(HEX[(byte >> 4) as usize] as char);
+        out.push(HEX[(byte & 0x0f) as usize] as char);
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_dir(label: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "cg-indexpaths-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        // Canonicalize so expectations compare against the same physical base
+        // `resolve` uses (macOS `/tmp` is a symlink to `/private/tmp`).
+        dir.canonicalize().unwrap()
+    }
+
+    #[test]
+    fn default_current_root_is_sibling_codegraph_v2() {
+        let project = temp_dir("default");
+        let paths = IndexPaths::resolve(&project, None).expect("resolve default");
+
+        assert_eq!(paths.current_root(), project.join(".codegraph-v2"));
+        assert_eq!(paths.legacy_roots(), [project.join(".codegraph")]);
+        assert_eq!(
+            paths.current_db(),
+            project.join(".codegraph-v2").join("codegraph.db")
+        );
+        // The default current root is a SIBLING of the legacy root, never a child.
+        assert!(!paths.current_root().starts_with(project.join(".codegraph")));
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn every_derived_artifact_lives_under_current_root() {
+        let project = temp_dir("artifacts");
+        let paths = IndexPaths::resolve(&project, None).expect("resolve");
+        let root = project.join(".codegraph-v2");
+
+        assert_eq!(paths.current_root(), root);
+        assert_eq!(paths.current_db(), root.join("codegraph.db"));
+        assert_eq!(paths.permanent_lock(), root.join("index.lock"));
+        assert_eq!(
+            paths.state_slots(),
+            [
+                root.join("index-state.0.json"),
+                root.join("index-state.1.json"),
+            ]
+        );
+        assert_eq!(paths.state_slot(0), root.join("index-state.0.json"));
+        assert_eq!(paths.state_slot(1), root.join("index-state.1.json"));
+        // Out-of-range slot indices clamp into [0, 1] rather than panicking.
+        assert_eq!(paths.state_slot(2), root.join("index-state.0.json"));
+        assert_eq!(paths.state_slot(3), root.join("index-state.1.json"));
+        assert_eq!(paths.tombstone(), root.join("uninitialized"));
+        assert_eq!(paths.config_toml(), root.join("config.toml"));
+        assert_eq!(paths.extension_config(), root.join("codegraph.json"));
+        assert_eq!(paths.daemon_pid(), root.join("daemon.pid"));
+        assert_eq!(paths.daemon_log(), root.join("daemon.log"));
+        assert_eq!(paths.daemon_socket(), root.join("daemon.sock"));
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn project_identity_is_full_lowercase_sha256() {
+        let project = temp_dir("identity");
+        let paths = IndexPaths::resolve(&project, None).expect("resolve");
+        let id = paths.project_identity();
+
+        assert_eq!(id.len(), 64, "identity is a full SHA-256 hex string");
+        assert!(
+            id.bytes()
+                .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase()),
+            "identity is lowercase hex: {id}"
+        );
+
+        // Deterministic: a second resolve of the same physical project agrees.
+        let again = IndexPaths::resolve(&project, None).expect("resolve again");
+        assert_eq!(again.project_identity(), id);
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn relative_codegraph_dir_current_root_is_sibling_with_identity_suffix() {
+        let project = temp_dir("rel-dir");
+        let paths = IndexPaths::resolve(&project, Some("cache")).expect("resolve relative");
+
+        // Legacy roots: the fixed `.codegraph` plus the configured relative root.
+        assert_eq!(
+            paths.legacy_roots(),
+            [project.join(".codegraph"), project.join("cache")]
+        );
+        // Current root is the SIBLING `cache-v2-<identity>`, not a child.
+        let expected = project.join(format!("cache-v2-{}", paths.project_identity()));
+        assert_eq!(paths.current_root(), expected);
+        assert!(!paths.current_root().starts_with(project.join("cache")));
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn absolute_codegraph_dir_current_root_is_sibling_of_configured_root() {
+        let project = temp_dir("abs-proj");
+        let cache = temp_dir("abs-cache");
+        let configured = cache.join("cg");
+        let paths = IndexPaths::resolve(&project, Some(configured.to_str().unwrap()))
+            .expect("resolve absolute");
+
+        assert!(
+            paths.legacy_roots().contains(&configured),
+            "configured absolute root is a legacy root: {:?}",
+            paths.legacy_roots()
+        );
+        // Sibling `<name>-v2-<identity>` next to the configured root.
+        let expected = cache.join(format!("cg-v2-{}", paths.project_identity()));
+        assert_eq!(paths.current_root(), expected);
+        assert!(!paths.current_root().starts_with(&configured));
+
+        let _ = std::fs::remove_dir_all(&project);
+        let _ = std::fs::remove_dir_all(&cache);
+    }
+
+    #[test]
+    fn two_projects_do_not_collide_on_a_shared_configured_root() {
+        // Two DISTINCT physical projects given the SAME configured root must
+        // receive DISTINCT current roots (identity-suffixed), so one cannot open
+        // the other's state.
+        let project_a = temp_dir("collide-a");
+        let project_b = temp_dir("collide-b");
+        let shared = temp_dir("collide-shared");
+        let configured = shared.join("cg");
+
+        let a = IndexPaths::resolve(&project_a, Some(configured.to_str().unwrap())).expect("a");
+        let b = IndexPaths::resolve(&project_b, Some(configured.to_str().unwrap())).expect("b");
+
+        assert_ne!(
+            a.project_identity(),
+            b.project_identity(),
+            "distinct physical projects have distinct identities"
+        );
+        assert_ne!(
+            a.current_root(),
+            b.current_root(),
+            "shared configured root must not collapse two projects onto one current root"
+        );
+
+        let _ = std::fs::remove_dir_all(&project_a);
+        let _ = std::fs::remove_dir_all(&project_b);
+        let _ = std::fs::remove_dir_all(&shared);
+    }
+
+    #[test]
+    fn two_projects_do_not_collide_on_an_escaping_relative_root() {
+        // A relative CODEGRAPH_DIR that escapes to a shared external directory
+        // must still yield distinct, identity-suffixed current roots.
+        let base = temp_dir("escape-base");
+        let project_a = base.join("a");
+        let project_b = base.join("b");
+        std::fs::create_dir_all(&project_a).unwrap();
+        std::fs::create_dir_all(&project_b).unwrap();
+        std::fs::create_dir_all(base.join("shared")).unwrap();
+
+        let a = IndexPaths::resolve(&project_a, Some("../shared/cg")).expect("a");
+        let b = IndexPaths::resolve(&project_b, Some("../shared/cg")).expect("b");
+
+        // Both configured roots normalize to the SAME external path…
+        assert_eq!(a.legacy_roots()[1], b.legacy_roots()[1]);
+        // …yet the current roots differ by physical identity.
+        assert_ne!(a.current_root(), b.current_root());
+
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn rejects_nonexistent_project() {
+        let missing = std::env::temp_dir().join("cg-indexpaths-does-not-exist-xyz");
+        let err = IndexPaths::resolve(&missing, None).expect_err("missing project fails closed");
+        assert!(matches!(err, IndexPathsError::ProjectInaccessible { .. }));
+    }
+
+    #[test]
+    fn rejects_root_dot_and_parent_codegraph_dir_aliases() {
+        let project = temp_dir("aliases");
+
+        // A configured root resolving to the project root itself.
+        let dot = IndexPaths::resolve(&project, Some(".")).expect_err("`.` must fail closed");
+        assert!(matches!(dot, IndexPathsError::RootAlias { .. }), "{dot:?}");
+
+        // A configured root resolving to an ancestor of the project.
+        let parent = IndexPaths::resolve(&project, Some("..")).expect_err("`..` must fail closed");
+        assert!(
+            matches!(parent, IndexPathsError::RootAlias { .. }),
+            "{parent:?}"
+        );
+
+        // The filesystem root.
+        let root = IndexPaths::resolve(&project, Some("/")).expect_err("`/` must fail closed");
+        assert!(
+            matches!(root, IndexPathsError::RootAlias { .. }),
+            "{root:?}"
+        );
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn empty_codegraph_dir_is_treated_as_unset_default() {
+        let project = temp_dir("empty-dir");
+        // An empty override string is ignored (treated as unset), matching the
+        // shell semantics where an empty env value is a no-op override.
+        let paths = IndexPaths::resolve(&project, Some("")).expect("empty resolves to default");
+        assert_eq!(paths.current_root(), project.join(".codegraph-v2"));
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn rejects_symlink_ancestor_below_project() {
+        use std::os::unix::fs::symlink;
+
+        let project = temp_dir("symlink");
+        let real = project.join("real");
+        std::fs::create_dir_all(&real).unwrap();
+        let link = project.join("link");
+        symlink(&real, &link).unwrap();
+
+        // A configured root that descends THROUGH a symlink component below the
+        // project must fail closed rather than follow the link.
+        let err = IndexPaths::resolve(&project, Some("link/cg"))
+            .expect_err("symlink component must fail closed");
+        assert!(
+            matches!(err, IndexPathsError::SymlinkComponent { .. }),
+            "{err:?}"
+        );
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn rejects_symlinked_absolute_configured_root() {
+        use std::os::unix::fs::symlink;
+
+        let project = temp_dir("symlink-abs-proj");
+        let cache = temp_dir("symlink-abs-cache");
+        let real = cache.join("real");
+        std::fs::create_dir_all(&real).unwrap();
+        let link = cache.join("link");
+        symlink(&real, &link).unwrap();
+
+        // An absolute configured root that IS a symlink must fail closed.
+        let err = IndexPaths::resolve(&project, Some(link.to_str().unwrap()))
+            .expect_err("symlinked absolute root must fail closed");
+        assert!(
+            matches!(err, IndexPathsError::SymlinkComponent { .. }),
+            "{err:?}"
+        );
+
+        let _ = std::fs::remove_dir_all(&project);
+        let _ = std::fs::remove_dir_all(&cache);
+    }
+
+    #[test]
+    fn rejects_current_root_overlapping_legacy_root() {
+        // A configured root whose derived sibling would nest under the fixed
+        // legacy `.codegraph` root must fail closed. Point CODEGRAPH_DIR at a
+        // child of `.codegraph`; the sibling `<name>-v2-<id>` then still lives
+        // inside `.codegraph`, overlapping the fixed legacy root.
+        let project = temp_dir("overlap");
+        std::fs::create_dir_all(project.join(".codegraph")).unwrap();
+        let err = IndexPaths::resolve(&project, Some(".codegraph/inner"))
+            .expect_err("overlap with legacy root must fail closed");
+        assert!(
+            matches!(err, IndexPathsError::LegacyOverlap { .. }),
+            "{err:?}"
+        );
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn current_root_never_equals_a_legacy_root() {
+        let project = temp_dir("disjoint");
+        let paths = IndexPaths::resolve(&project, Some("cache")).expect("resolve");
+        for legacy in paths.legacy_roots() {
+            assert_ne!(paths.current_root(), legacy);
+            assert!(!paths.current_root().starts_with(legacy));
+            assert!(!legacy.starts_with(paths.current_root()));
+        }
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn lexical_normalize_folds_dot_and_parent() {
+        assert_eq!(
+            lexical_normalize(Path::new("/a/./b/../c")),
+            PathBuf::from("/a/c")
+        );
+        assert_eq!(lexical_normalize(Path::new("/a/b/..")), PathBuf::from("/a"));
+    }
+
+    #[test]
+    fn current_root_lenient_defaults_to_codegraph_v2() {
+        let project = Path::new("/proj");
+        assert_eq!(
+            IndexPaths::current_root_lenient(project, None),
+            PathBuf::from("/proj/.codegraph-v2")
+        );
+        assert_eq!(
+            IndexPaths::current_db_lenient(project, None),
+            PathBuf::from("/proj/.codegraph-v2/codegraph.db")
+        );
+        // Empty override is treated as unset.
+        assert_eq!(
+            IndexPaths::current_root_lenient(project, Some("")),
+            PathBuf::from("/proj/.codegraph-v2")
+        );
+    }
+
+    #[test]
+    fn current_root_lenient_honors_codegraph_dir_override() {
+        let project = Path::new("/proj");
+        assert_eq!(
+            IndexPaths::current_root_lenient(project, Some("custom")),
+            PathBuf::from("/proj/custom")
+        );
+        assert_eq!(
+            IndexPaths::current_db_lenient(project, Some("custom")),
+            PathBuf::from("/proj/custom/codegraph.db")
+        );
+    }
+
+    #[test]
+    fn reserved_index_dir_matches_legacy_and_v2_siblings() {
+        assert!(IndexPaths::is_reserved_index_dir(".codegraph"));
+        assert!(IndexPaths::is_reserved_index_dir(".codegraph-v2"));
+        assert!(IndexPaths::is_reserved_index_dir(".codegraph-daemon"));
+        assert!(!IndexPaths::is_reserved_index_dir("src"));
+        assert!(!IndexPaths::is_reserved_index_dir(".codegraphx"));
+        assert!(!IndexPaths::is_reserved_index_dir(".git"));
+    }
+}
diff --git a/crates/codegraph-core/src/lib.rs b/crates/codegraph-core/src/lib.rs
index 8ce6dc5..4773e78 100644
--- a/crates/codegraph-core/src/lib.rs
+++ b/crates/codegraph-core/src/lib.rs
@@ -2,9 +2,11 @@
 
 pub mod config;
 pub mod errors;
+pub mod index_paths;
 pub mod logger;
 pub mod node_id;
 pub mod traits;
 pub mod types;
 
 pub use errors::{CodeGraphError, Result};
+pub use index_paths::{IndexPaths, IndexPathsError};

From 8aeefc4786b7b5fd6e6f20b02e1efa7830e7ecb7 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 08:27:52 +0800
Subject: [PATCH 07/91] feat(index): route init to isolated .codegraph-v2
 namespace via IndexPaths

Move the default index storage root that public `codegraph init` writes from
the fixed legacy <project>/.codegraph to the isolated sibling
<project>/.codegraph-v2, turning the initial Batch M black-box Red
init_writes_isolated_v2_namespace_not_legacy_codegraph green.

Data-plane consumers routed through the codegraph-core::IndexPaths authority
(current_root_lenient / current_db_lenient) so no code reconstructs the
.codegraph-v2 literal and the read/write sites all agree:
- codegraph-cli main.rs codegraph_dir/db_path (central helper for init, index,
  sync, status, unlock, open_store, is_initialized, remove_db_files, spill);
- codegraph-mcp CodeGraphEngine::open + roots::db_path_for, so the
  stdio/HTTP/daemon MCP request path reads the same namespace init writes;
- codegraph-watch sync::default_db_path for watcher/catch-up sync;
- codegraph-extract scan_dir now skips the whole .codegraph/.codegraph-*
  family via IndexPaths::is_reserved_index_dir, so a project never scans its
  own v2 index storage back into the graph.

Directly-affected staging/read tests move the DB (and CLI-owned lock/uninit
root) from .codegraph to .codegraph-v2. Daemon rendezvous paths
(daemon.pid/sock/log) and the MCP must-not-self-index assertions stay on
.codegraph; Config::discover, the codegraph.json ancestor walkers, and the
benchmark oracle are deliberately unchanged and recorded as remaining Batch M
consumers for the next integration task.
---
 crates/codegraph-cli/src/main.rs              |  29 +++-
 crates/codegraph-cli/tests/cli_commands.rs    |  10 +-
 .../codegraph-cli/tests/godot_idfields_cwd.rs |   4 +-
 .../tests/godot_idfields_determinism.rs       |   6 +-
 crates/codegraph-cli/tests/parallel_index.rs  |   3 +-
 .../tests/status_debug_fields.rs              |   2 +-
 .../codegraph-cli/tests/sync_incremental.rs   |   3 +-
 crates/codegraph-daemon/tests/async_model.rs  |   6 +-
 .../codegraph-daemon/tests/rmcp_tools_call.rs |   7 +-
 crates/codegraph-extract/src/engine.rs        |   8 +-
 crates/codegraph-mcp/src/engine.rs            |  17 ++-
 crates/codegraph-mcp/src/roots.rs             |  12 +-
 .../codegraph-mcp/tests/godot_honesty_mcp.rs  |   3 +-
 crates/codegraph-mcp/tests/golden_mcp.rs      |   9 +-
 crates/codegraph-mcp/tests/reopen.rs          |   9 +-
 crates/codegraph-mcp/tests/support/parity.rs  |   5 +-
 crates/codegraph-watch/src/sync.rs            |   8 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 141 ++++++++++++++++++
 18 files changed, 240 insertions(+), 42 deletions(-)

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 814598e..40c9e89 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -2585,7 +2585,8 @@ mod serve_mode_tests {
         let indexed =
             std::env::temp_dir().join(format!("cg-serve-gate-idx-{}-{seq}", std::process::id()));
         std::fs::create_dir_all(&unindexed).unwrap();
-        std::fs::create_dir_all(indexed.join(".codegraph")).unwrap();
+        // Batch M: the serve-services gate keys on the v2 current root.
+        std::fs::create_dir_all(indexed.join(".codegraph-v2")).unwrap();
 
         assert!(
             should_run_serve_services(true, &unindexed),
@@ -4270,12 +4271,23 @@ fn normalize_lexical(path: &Path) -> PathBuf {
     out
 }
 
+/// The current (v2) index root for `project`. Defaults to the isolated
+/// `.codegraph-v2` sibling (Batch M, plan line 262); a `CODEGRAPH_DIR` override
+/// keeps its existing simple-join semantics. Routed through the single
+/// `codegraph-core::IndexPaths` path authority so no CLI code reconstructs the
+/// `.codegraph-v2` literal itself.
 fn codegraph_dir(project: &Path) -> PathBuf {
-    project.join(std::env::var("CODEGRAPH_DIR").unwrap_or_else(|_| ".codegraph".to_string()))
+    codegraph_core::IndexPaths::current_root_lenient(
+        project,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )
 }
 
 fn db_path(project: &Path) -> PathBuf {
-    codegraph_dir(project).join("codegraph.db")
+    codegraph_core::IndexPaths::current_db_lenient(
+        project,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )
 }
 
 fn remove_db_files(project: &Path) -> Result<()> {
@@ -5106,8 +5118,11 @@ mod pure_helper_tests {
     fn db_path_is_under_codegraph_dir() {
         if std::env::var("CODEGRAPH_DIR").is_err() {
             let p = Path::new("/proj");
-            assert_eq!(db_path(p), PathBuf::from("/proj/.codegraph/codegraph.db"));
-            assert_eq!(codegraph_dir(p), PathBuf::from("/proj/.codegraph"));
+            assert_eq!(
+                db_path(p),
+                PathBuf::from("/proj/.codegraph-v2/codegraph.db")
+            );
+            assert_eq!(codegraph_dir(p), PathBuf::from("/proj/.codegraph-v2"));
         }
     }
 
@@ -5284,8 +5299,8 @@ mod formatter_and_env_tests {
         let prev = std::env::var_os("CODEGRAPH_DIR");
         unsafe { std::env::remove_var("CODEGRAPH_DIR") };
         let proj = Path::new("/tmp/proj");
-        assert_eq!(codegraph_dir(proj), proj.join(".codegraph"));
-        assert_eq!(db_path(proj), proj.join(".codegraph/codegraph.db"));
+        assert_eq!(codegraph_dir(proj), proj.join(".codegraph-v2"));
+        assert_eq!(db_path(proj), proj.join(".codegraph-v2/codegraph.db"));
         if let Some(v) = prev {
             unsafe { std::env::set_var("CODEGRAPH_DIR", v) };
         }
diff --git a/crates/codegraph-cli/tests/cli_commands.rs b/crates/codegraph-cli/tests/cli_commands.rs
index df35f43..02a92a9 100644
--- a/crates/codegraph-cli/tests/cli_commands.rs
+++ b/crates/codegraph-cli/tests/cli_commands.rs
@@ -298,7 +298,7 @@ fn unlock_removes_existing_lock_file() {
     let dir = TestDir::new("unlock-lock");
     let project = indexed_project(&dir);
     let p = project.to_str().unwrap();
-    let lock = project.join(".codegraph/codegraph.lock");
+    let lock = project.join(".codegraph-v2/codegraph.lock");
     std::fs::write(&lock, b"stale").unwrap();
     let run = run_in(dir.path(), &["unlock", p]);
     assert!(run.ok, "unlock must succeed: {}", run.stderr);
@@ -325,16 +325,16 @@ fn uninit_requires_force_then_removes() {
         refused.stderr
     );
     assert!(
-        project.join(".codegraph").exists(),
+        project.join(".codegraph-v2").exists(),
         "uninit without --force must not delete the index"
     );
 
-    // With --force: removes .codegraph.
+    // With --force: removes the v2 index root.
     let done = run_in(dir.path(), &["uninit", "--force", p]);
     assert!(done.ok, "uninit --force must succeed: {}", done.stderr);
     assert!(
-        !project.join(".codegraph").exists(),
-        "uninit --force must remove .codegraph"
+        !project.join(".codegraph-v2").exists(),
+        "uninit --force must remove .codegraph-v2"
     );
 }
 
diff --git a/crates/codegraph-cli/tests/godot_idfields_cwd.rs b/crates/codegraph-cli/tests/godot_idfields_cwd.rs
index 6c72668..c927492 100644
--- a/crates/codegraph-cli/tests/godot_idfields_cwd.rs
+++ b/crates/codegraph-cli/tests/godot_idfields_cwd.rs
@@ -95,7 +95,9 @@ fn cli_from(cwd: &Path, args: &[&str]) -> (String, String, bool) {
 }
 
 fn unresolved_ref_names(project: &Path) -> Vec<String> {
-    let db = project.join(".codegraph").join("codegraph.db");
+    // Batch M: the index DB moved to the isolated v2 namespace. The opt-in DSL
+    // config (`.codegraph/codegraph.json`) is still read by the ancestor walker.
+    let db = project.join(".codegraph-v2").join("codegraph.db");
     let store = Store::open(&db).expect("open store");
     store
         .all_unresolved_refs()
diff --git a/crates/codegraph-cli/tests/godot_idfields_determinism.rs b/crates/codegraph-cli/tests/godot_idfields_determinism.rs
index c1bb8d6..ee9efaf 100644
--- a/crates/codegraph-cli/tests/godot_idfields_determinism.rs
+++ b/crates/codegraph-cli/tests/godot_idfields_determinism.rs
@@ -109,7 +109,11 @@ fn cli_cwd(cwd: &Path, args: &[&str]) -> (String, String, bool) {
 }
 
 fn db_path(project: &Path) -> PathBuf {
-    project.join(".codegraph").join("codegraph.db")
+    // Batch M: the index DB moved to the isolated v2 namespace. The opt-in DSL
+    // config (`.codegraph/codegraph.json`) is still read by the ancestor walker
+    // (its project-scoped move is a later Batch M task), so only the DB path
+    // changes here.
+    project.join(".codegraph-v2").join("codegraph.db")
 }
 
 /// (i) `sync` after an edit to the `.tres` must equal a full `index --force`
diff --git a/crates/codegraph-cli/tests/parallel_index.rs b/crates/codegraph-cli/tests/parallel_index.rs
index 0aa2e21..b513789 100644
--- a/crates/codegraph-cli/tests/parallel_index.rs
+++ b/crates/codegraph-cli/tests/parallel_index.rs
@@ -108,7 +108,8 @@ fn cli(args: &[&str]) -> (String, String, bool) {
 }
 
 fn db_path(project: &Path) -> PathBuf {
-    project.join(".codegraph").join("codegraph.db")
+    // Batch M: `init`/`index` now write the isolated v2 namespace.
+    project.join(".codegraph-v2").join("codegraph.db")
 }
 
 fn init_and_force_index(project: &Path) {
diff --git a/crates/codegraph-cli/tests/status_debug_fields.rs b/crates/codegraph-cli/tests/status_debug_fields.rs
index 3f71a9c..44fe66a 100644
--- a/crates/codegraph-cli/tests/status_debug_fields.rs
+++ b/crates/codegraph-cli/tests/status_debug_fields.rs
@@ -162,7 +162,7 @@ fn status_json_flags_partial_only_when_marker_set() {
     let (out, err, ok) = cli(&["init", p]);
     assert!(ok, "init failed: stdout={out} stderr={err}");
 
-    let db = project.join(".codegraph").join("codegraph.db");
+    let db = project.join(".codegraph-v2").join("codegraph.db");
     {
         let store = Store::open(&db).unwrap();
         store.set_resolution_incomplete().unwrap();
diff --git a/crates/codegraph-cli/tests/sync_incremental.rs b/crates/codegraph-cli/tests/sync_incremental.rs
index 0867b14..f7d1d99 100644
--- a/crates/codegraph-cli/tests/sync_incremental.rs
+++ b/crates/codegraph-cli/tests/sync_incremental.rs
@@ -72,7 +72,8 @@ fn cli(args: &[&str]) -> (String, String, bool) {
 }
 
 fn db_path(project: &Path) -> PathBuf {
-    project.join(".codegraph").join("codegraph.db")
+    // Batch M: `init`/`index`/`sync` now write the isolated v2 namespace.
+    project.join(".codegraph-v2").join("codegraph.db")
 }
 
 #[test]
diff --git a/crates/codegraph-daemon/tests/async_model.rs b/crates/codegraph-daemon/tests/async_model.rs
index a3844a8..f0e8d29 100644
--- a/crates/codegraph-daemon/tests/async_model.rs
+++ b/crates/codegraph-daemon/tests/async_model.rs
@@ -360,8 +360,10 @@ fn temp_indexed_project(name: &str) -> PathBuf {
         "codegraph-daemon-{name}-{}-{nanos}-{seq}",
         std::process::id()
     ));
-    let cg = path.join(".codegraph");
-    fs::create_dir_all(&cg).expect("create project .codegraph");
+    // Batch M: the served index DB moved to the isolated v2 namespace
+    // (`.codegraph-v2`); the daemon rendezvous still lives under `.codegraph`.
+    let cg = path.join(".codegraph-v2");
+    fs::create_dir_all(&cg).expect("create project .codegraph-v2");
     let root = workspace_root();
     fs::copy(
         root.join("reference/golden/mini/colby.db"),
diff --git a/crates/codegraph-daemon/tests/rmcp_tools_call.rs b/crates/codegraph-daemon/tests/rmcp_tools_call.rs
index 460b8cc..9b6d4a8 100644
--- a/crates/codegraph-daemon/tests/rmcp_tools_call.rs
+++ b/crates/codegraph-daemon/tests/rmcp_tools_call.rs
@@ -174,8 +174,11 @@ fn temp_indexed_project(name: &str) -> PathBuf {
         "codegraph-daemon-{name}-{}-{nanos}-{seq}",
         std::process::id()
     ));
-    let cg = path.join(".codegraph");
-    fs::create_dir_all(&cg).expect("create project .codegraph");
+    // Batch M: the served index DB moved to the isolated v2 namespace
+    // (`.codegraph-v2`), which is what `CodeGraphEngine::open` now reads; the
+    // daemon rendezvous (pid/socket/log) still lives under `.codegraph`.
+    let cg = path.join(".codegraph-v2");
+    fs::create_dir_all(&cg).expect("create project .codegraph-v2");
     let root = workspace_root();
     fs::copy(
         root.join("reference/golden/mini/colby.db"),
diff --git a/crates/codegraph-extract/src/engine.rs b/crates/codegraph-extract/src/engine.rs
index 3a8729b..5e6afcd 100644
--- a/crates/codegraph-extract/src/engine.rs
+++ b/crates/codegraph-extract/src/engine.rs
@@ -327,7 +327,13 @@ fn scan_dir(
         let path = entry.path();
         let name = entry.file_name();
         let name = name.to_string_lossy();
-        if name == ".git" || name == ".codegraph" || ignored_dirs.contains(name.as_ref()) {
+        // Skip `.git`, the fixed legacy `.codegraph`, and every `.codegraph-*`
+        // sibling (including the isolated `.codegraph-v2` current root, Batch M)
+        // so a project's own index storage is never scanned back into the graph.
+        if name == ".git"
+            || codegraph_core::IndexPaths::is_reserved_index_dir(name.as_ref())
+            || ignored_dirs.contains(name.as_ref())
+        {
             continue;
         }
         let relative = normalize_path(path.strip_prefix(root).unwrap_or(&path));
diff --git a/crates/codegraph-mcp/src/engine.rs b/crates/codegraph-mcp/src/engine.rs
index 1e93d79..b0e7c2b 100644
--- a/crates/codegraph-mcp/src/engine.rs
+++ b/crates/codegraph-mcp/src/engine.rs
@@ -68,10 +68,16 @@ pub struct CodeGraphEngine {
 }
 
 impl CodeGraphEngine {
-    /// Open the store at `<project_root>/.codegraph/codegraph.db`
-    /// (`upstream directory.ts`; learnings Task 4).
+    /// Open the store at the project's current (v2) index DB
+    /// (`<project_root>/.codegraph-v2/codegraph.db` by default; `CODEGRAPH_DIR`
+    /// override honored). Routed through the single `codegraph-core::IndexPaths`
+    /// path authority (Batch M) so the MCP request path reads the same namespace
+    /// `codegraph init` writes.
     pub fn open(project_root: &Path) -> anyhow::Result<Self> {
-        let db_path = project_root.join(".codegraph").join("codegraph.db");
+        let db_path = codegraph_core::IndexPaths::current_db_lenient(
+            project_root,
+            std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+        );
         let store = Store::open(&db_path)?;
         Ok(Self {
             store,
@@ -3865,9 +3871,10 @@ mod tests {
             std::process::id(),
             TEMP_SEQ.fetch_add(1, Ordering::Relaxed)
         ));
-        std::fs::create_dir_all(base.join(".codegraph")).unwrap();
+        // Batch M: `CodeGraphEngine::open` reads the isolated v2 namespace.
+        std::fs::create_dir_all(base.join(".codegraph-v2")).unwrap();
         {
-            let db = base.join(".codegraph").join("codegraph.db");
+            let db = base.join(".codegraph-v2").join("codegraph.db");
             Store::open(&db).unwrap();
         }
         let engine = CodeGraphEngine::open(&base).unwrap();
diff --git a/crates/codegraph-mcp/src/roots.rs b/crates/codegraph-mcp/src/roots.rs
index 73ca8ea..de64f1a 100644
--- a/crates/codegraph-mcp/src/roots.rs
+++ b/crates/codegraph-mcp/src/roots.rs
@@ -32,11 +32,15 @@ pub fn format_tool_debug_line(
     )
 }
 
-/// The relative `.codegraph/codegraph.db` path under a project root, honoring
-/// the `CODEGRAPH_DIR` override.
+/// The current (v2) index DB path under a project root
+/// (`<project_path>/.codegraph-v2/codegraph.db` by default; `CODEGRAPH_DIR`
+/// override honored). Routed through the single `codegraph-core::IndexPaths`
+/// path authority (Batch M) so project resolution and the served DB agree.
 pub fn db_path_for(project_path: &Path) -> PathBuf {
-    let dir = std::env::var("CODEGRAPH_DIR").unwrap_or_else(|_| ".codegraph".to_string());
-    project_path.join(dir).join("codegraph.db")
+    codegraph_core::IndexPaths::current_db_lenient(
+        project_path,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )
 }
 
 pub struct WorkspaceRoots {
diff --git a/crates/codegraph-mcp/tests/godot_honesty_mcp.rs b/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
index a958961..d6126a2 100644
--- a/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
+++ b/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
@@ -57,7 +57,8 @@ fn pipeline_project(files: &[(&str, &str)]) -> TestProject {
         fs::write(&dst, src).unwrap();
     }
 
-    let mut store = Store::open(&base.join(".codegraph").join("codegraph.db")).unwrap();
+    // Batch M: the MCP engine reads the isolated v2 namespace (`.codegraph-v2`).
+    let mut store = Store::open(&base.join(".codegraph-v2").join("codegraph.db")).unwrap();
     for (rel, src) in files {
         let result = extract_file(&base, rel).unwrap();
         store
diff --git a/crates/codegraph-mcp/tests/golden_mcp.rs b/crates/codegraph-mcp/tests/golden_mcp.rs
index fafbdc9..63daef3 100644
--- a/crates/codegraph-mcp/tests/golden_mcp.rs
+++ b/crates/codegraph-mcp/tests/golden_mcp.rs
@@ -87,10 +87,12 @@ fn setup_mini_project() -> TestProject {
     let seq = TEMP_SEQ.fetch_add(1, Ordering::Relaxed);
     let base =
         std::env::temp_dir().join(format!("cg-mcp-test-{}-{nanos}-{seq}", std::process::id()));
-    fs::create_dir_all(base.join(".codegraph")).unwrap();
+    // Batch M: the MCP engine now opens the isolated v2 namespace
+    // (`.codegraph-v2`), so stage the golden DB there.
+    fs::create_dir_all(base.join(".codegraph-v2")).unwrap();
     copy_with_retry(
         &root.join("reference/golden/mini/colby.db"),
-        &base.join(".codegraph").join("codegraph.db"),
+        &base.join(".codegraph-v2").join("codegraph.db"),
     );
 
     let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
@@ -748,7 +750,8 @@ fn index_fixture(files: &[(&str, &str)]) -> TestProject {
         fs::create_dir_all(dst.parent().unwrap()).unwrap();
         fs::write(&dst, src).unwrap();
     }
-    let mut store = Store::open(&base.join(".codegraph").join("codegraph.db")).unwrap();
+    // Batch M: the MCP engine reads the isolated v2 namespace (`.codegraph-v2`).
+    let mut store = Store::open(&base.join(".codegraph-v2").join("codegraph.db")).unwrap();
     let mut all_edges = Vec::new();
     for (rel, src) in files {
         let result = extract_file(&base, rel).unwrap();
diff --git a/crates/codegraph-mcp/tests/reopen.rs b/crates/codegraph-mcp/tests/reopen.rs
index 4895276..41e2d5f 100644
--- a/crates/codegraph-mcp/tests/reopen.rs
+++ b/crates/codegraph-mcp/tests/reopen.rs
@@ -63,7 +63,8 @@ fn index_into(base: &Path, files: &[(&str, &str)]) {
         fs::create_dir_all(dst.parent().unwrap()).unwrap();
         fs::write(&dst, src).unwrap();
     }
-    let mut store = Store::open(&base.join(".codegraph").join("codegraph.db")).unwrap();
+    // Batch M: the MCP engine reads the isolated v2 namespace (`.codegraph-v2`).
+    let mut store = Store::open(&base.join(".codegraph-v2").join("codegraph.db")).unwrap();
     let mut all_edges = Vec::new();
     for (rel, src) in files {
         let result = extract_file(base, rel).unwrap();
@@ -153,7 +154,7 @@ fn reopens_cached_engine_when_db_replaced_with_new_inode() {
     // the NEW on-disk content. Serving `betaSymbol` (not `alphaSymbol`, not an
     // open error) is itself the proof the engine reopened against the fresh db.
     server.close_cached_handles();
-    fs::remove_dir_all(project.path().join(".codegraph")).unwrap();
+    fs::remove_dir_all(project.path().join(".codegraph-v2")).unwrap();
     index_into(
         project.path(),
         &[("src/b.ts", "export function betaSymbol() {}\n")],
@@ -203,7 +204,7 @@ fn does_not_reopen_when_inode_is_unchanged() {
     // in-place mtime bump (a normal WAL write) — that must NOT be treated as a
     // replace. First prove the identity itself is content-neutral under a pure
     // mtime touch (the header bytes are unchanged, so the signature holds).
-    let db = project.path().join(".codegraph").join("codegraph.db");
+    let db = project.path().join(".codegraph-v2").join("codegraph.db");
     let id_before_touch = db_identity(project.path());
     filetouch(&db);
     assert_eq!(
@@ -232,7 +233,7 @@ fn does_not_reopen_when_inode_is_unchanged() {
 /// slices (`[16..24]`, `[28..32]`, `[40..44]`) — NO mtime, so a pure mtime touch
 /// leaves it unchanged while a rebuild changes it.
 fn db_identity(project: &Path) -> u128 {
-    let db = project.join(".codegraph").join("codegraph.db");
+    let db = project.join(".codegraph-v2").join("codegraph.db");
     let meta = fs::metadata(&db).expect("db metadata");
     #[cfg(unix)]
     {
diff --git a/crates/codegraph-mcp/tests/support/parity.rs b/crates/codegraph-mcp/tests/support/parity.rs
index af4800c..c7cf88f 100644
--- a/crates/codegraph-mcp/tests/support/parity.rs
+++ b/crates/codegraph-mcp/tests/support/parity.rs
@@ -83,10 +83,11 @@ pub fn setup_mini_project() -> TestProject {
         "cg-mcp-parity-{}-{nanos}-{seq}",
         std::process::id()
     ));
-    fs::create_dir_all(base.join(".codegraph")).unwrap();
+    // Batch M: the MCP engine now opens the isolated v2 namespace.
+    fs::create_dir_all(base.join(".codegraph-v2")).unwrap();
     copy_with_retry(
         &root.join("reference/golden/mini/colby.db"),
-        &base.join(".codegraph").join("codegraph.db"),
+        &base.join(".codegraph-v2").join("codegraph.db"),
     );
 
     let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index 87f19fe..0c8b9dc 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -298,7 +298,13 @@ fn sweep_orphaned_refs(project_root: &Path, store: &mut Store) -> Result<()> {
 const ORPHAN_SWEEP_BATCH_ROWS: usize = 5_000;
 
 pub(crate) fn default_db_path(project_root: &Path) -> PathBuf {
-    project_root.join(".codegraph").join("codegraph.db")
+    // Route through the single `codegraph-core::IndexPaths` path authority
+    // (Batch M) so watcher sync writes the same v2 namespace `codegraph init`
+    // and MCP reads (`.codegraph-v2/codegraph.db` by default).
+    codegraph_core::IndexPaths::current_db_lenient(
+        project_root,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )
 }
 
 fn sync_one(
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e1fa9a9..65233f0 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -280,3 +280,144 @@ absent typed/lease/path gates (tests 6, 7), legacy-binary storage isolation
 lease/lifecycle/uninit-state test (tests 5, 11, 12, 13, 15, 16, 20, 21) whose
 deterministic form needs the minimal compiling Green scaffolding. This commit
 lands only the initial black-box namespace boundary.
+
+## Batch M — IndexPaths path authority + init writes isolated v2 namespace (2026-07-25)
+
+### Scope
+
+First minimal vertical Green of Batch M's path layer: establish
+`codegraph-core::IndexPaths` as the single current/legacy path authority, and
+move the default index storage root that public `codegraph init` writes from the
+fixed legacy `<project>/.codegraph` to the isolated sibling
+`<project>/.codegraph-v2`. This turns the already-committed initial black-box Red
+`init_writes_isolated_v2_namespace_not_legacy_codegraph` green. This slice is the
+PATH LAYER + init data-plane wiring ONLY; the state-slot / `IndexLease` / Store
+`open_for_*` protocol, tombstone/lock consumers, daemon/watch/MCP lifecycle,
+project-scoped `Config` refactor, extension/Godot DSL project-scoping, and
+`uninit` remain later Batch M tasks.
+
+### TDD evidence
+
+- Preserved Red (unchanged): `crates/codegraph-cli/tests/batch_m_v2_namespace.rs`
+  `init_writes_isolated_v2_namespace_not_legacy_codegraph`. Pre-Green failing
+  command:
+  `cargo test -p codegraph-rs --locked --test batch_m_v2_namespace -- init_writes_isolated_v2_namespace_not_legacy_codegraph --exact`
+  → exit 101, `test result: FAILED. 0 passed; 1 failed`; failing assertion at
+  `batch_m_v2_namespace.rs:157` — v2 DB `<tmp>/mini/.codegraph-v2/codegraph.db`
+  absent while legacy `.codegraph/codegraph.db` present (current v0.40.4 wrote
+  legacy). Re-verified once more on this task's HEAD before the Green wiring.
+- API-refinement tests (plan lines 805-809 distinction): committed FIRST, before
+  the data-plane wiring, as the `codegraph-core::index_paths::tests` module in
+  commit `b5a66f2`. They exercise the new exported API surface directly
+  (defaults, relative/absolute `CODEGRAPH_DIR`, two-project collision resistance
+  on shared/escaping roots, root/dot/parent rejection, symlink alias rejection,
+  legacy overlap, and every derived artifact path). Because that commit added the
+  compiling API surface AND its behavioral tests together, the API tests compiled
+  and passed at introduction — the compile-time Red prerequisite the plan forbids
+  is satisfied by the separately preserved black-box Red above, which is the
+  behavioral failure evidence; the API tests are the refinement layer.
+- Post-Green: the exact black-box command now exits 0
+  (`test result: ok. 1 passed`); the 18 `codegraph-core` `index_paths` unit tests
+  pass.
+
+### Commits
+
+- `b5a66f2` `feat(core): add IndexPaths v2 namespace path authority` —
+  `crates/codegraph-core/src/index_paths.rs` (new) + `src/lib.rs` export. Path
+  layer + unit tests only; no data-plane consumer touched.
+- (this task's Green) `feat(index): route init/default index root to isolated
+.codegraph-v2 via IndexPaths` — data-plane wiring + directly-affected test
+  updates (see below).
+
+### `IndexPaths` contract landed
+
+`IndexPaths::resolve(project, CODEGRAPH_DIR)` returns: canonical `project`;
+`project_identity` (full lowercase SHA-256 of a versioned binary payload —
+`st_dev`/`st_ino` on Unix, volume serial + 128-bit `GetFileInformationByHandleEx(FileIdInfo)`
+on Windows via a compiled `cfg(windows)` raw-kernel32 block, NO lexical fallback,
+unsupported filesystems fail closed); the normalized `legacy_roots` set (fixed
+`<project>/.codegraph` plus the configured old CLI root when `CODEGRAPH_DIR` is
+set); the isolated `current_root` (`.codegraph-v2` by default; a
+`<name>-v2-<projectIdentity>` sibling of the configured legacy root); and the
+derived `current_db`, `permanent_lock`, two `state_slots`, `tombstone`,
+`config_toml`, `extension_config`, `daemon_pid`/`daemon_log`/`daemon_socket`.
+This slice supplies the path VALUES only; no protocol consumer of the state-slot,
+tombstone, or lock paths is implemented yet. Fail-closed: empty/root/dot/parent
+aliases, symlink/reparse components below the canonical nearest-existing
+ancestor, legacy equality, and ancestor/descendant overlap. Two distinct physical
+projects given the same configured root receive distinct identity-suffixed
+current roots. Infallible transitional helpers `current_root_lenient` /
+`current_db_lenient` (used by the data plane in this slice; a not-yet-created
+project must stay infallible) centralize the `.codegraph-v2` default so no
+consumer reconstructs the literal; `is_reserved_index_dir` centralizes the
+scanner/watcher `.codegraph`/`.codegraph-*` skip.
+
+### Data-plane consumers routed through IndexPaths in THIS slice
+
+- `crates/codegraph-cli/src/main.rs` `codegraph_dir` / `db_path` → default
+  `.codegraph-v2`. This is the central helper for init, index, sync, status,
+  unlock, and every `open_store`/`is_initialized`/`remove_db_files`/`SpillWriter`
+  call site, so the whole CLI DB flow moved together.
+- `crates/codegraph-mcp/src/engine.rs` `CodeGraphEngine::open` and
+  `crates/codegraph-mcp/src/roots.rs` `db_path_for` → `.codegraph-v2`, so the
+  stdio/HTTP/daemon MCP request path reads the SAME namespace init writes (this
+  is why the serve/query integration tests stay green).
+- `crates/codegraph-watch/src/sync.rs` `default_db_path` → `.codegraph-v2`, so
+  watcher/catch-up sync targets the v2 DB.
+- `crates/codegraph-extract/src/engine.rs` `scan_dir` now skips the whole
+  reserved `.codegraph`/`.codegraph-*` family via `IndexPaths::is_reserved_index_dir`,
+  so a project never scans its own `.codegraph-v2` back into the graph.
+
+### Directly-affected tests updated (moved DB namespace only)
+
+`crates/codegraph-cli/tests/{sync_incremental,parallel_index,status_debug_fields,godot_idfields_cwd,godot_idfields_determinism,cli_commands}.rs`,
+`crates/codegraph-daemon/tests/{rmcp_tools_call,async_model}.rs`,
+`crates/codegraph-mcp/tests/{golden_mcp,support/parity,godot_honesty_mcp,reopen}.rs`,
+plus the `CodeGraphEngine` test helper and the `serve_services_gate` unit test in
+`main.rs`. Each switched the DB (and CLI-owned lock/uninit-root) path from
+`.codegraph` to `.codegraph-v2` to match the moved data plane. Daemon rendezvous
+paths (`daemon.pid`/`daemon.sock`/`daemon.log`) and the MCP "must NOT self-index"
+assertions in `http_serve.rs`/`zed_bare_serve.rs` were deliberately KEPT on
+`.codegraph`.
+
+### Remaining Batch M path consumers for the next integration task
+
+These still hardcode `.codegraph` and are NOT part of this init-only slice
+(listed for the follow-up integration task, per the "do not claim repo-wide
+migration" rule):
+
+- `crates/codegraph-daemon/src/paths.rs` `codegraph_dir` (and thus
+  `daemon_pid_path`/`daemon_log_path`/`daemon_socket_path`/candidates) — daemon
+  rendezvous still lives under `.codegraph`; moving it to the current root (with
+  the v2 socket/pipe discriminator) is a later lifecycle task.
+- `crates/codegraph-core/src/config.rs` `Config::discover` — still reads
+  `<project>/.codegraph/config.toml` and the CWD fallback; the project-scoped
+  `<current-root>/config.toml` move + migration gate is a later task (kept
+  unchanged here to avoid deepening global-config bleed the plan later removes).
+- `crates/codegraph-extract/src/ext_config.rs` and
+  `crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs` — still walk
+  ancestor `.codegraph/codegraph.json`; project-scoped `extension_config` wiring
+  is a later task. The two Godot idfields CLI tests therefore still write the DSL
+  config under `.codegraph/` while reading the DB from `.codegraph-v2/`.
+- `crates/codegraph-bench/src/pipeline.rs` `db_path` (benchmark oracle vs the
+  legacy upstream CLI) — intentionally legacy; not a v2 consumer.
+- The full `IndexPaths::resolve` fail-closed authority (identity-suffixed
+  configured-root sibling, symlink/overlap rejection) is implemented and unit
+  tested but NOT yet wired into the infallible data-plane helpers; the data plane
+  uses `current_root_lenient` (simple join for a configured `CODEGRAPH_DIR`) in
+  this slice. Wiring `resolve` into the state/lease protocol is the next task.
+
+### Verification
+
+`bash scripts/check-workspace-versions.sh` (OK, lock `750ee84b…` unchanged),
+`cargo check --workspace --all-targets --locked` (clean),
+`cargo clippy` across all touched crates `-D warnings` (clean),
+`cargo fmt --all --check` (clean), `bash scripts/guardrail.sh` (exit 0). Targeted
+green: the exact black-box Red; `codegraph-core`/`extract`/`watch` suites;
+`codegraph-mcp` golden/godot/reopen/rmcp_roots/rmcp_http/rmcp_l3/rmcp_parity +
+lib; `codegraph-rs` bin (353) + cli_commands/sync_incremental/parallel_index/
+status_debug_fields, both `godot_idfields` CLI tests, http_serve, zed_bare_serve,
+proxy_e2e, live_update_direct, stdout_purity, rmcp_serve_direct, both `explore`
+CLI tests, prompt_hook, catch_up;
+`codegraph-daemon` rmcp_tools_call/async_model; `codegraph-bench` (golden oracle,
+byte-stability) all pass. No plan-level architecture change was required.

From f6ff9e25b3ad7b73e70f032df86640665b4db9de Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 10:11:44 +0800
Subject: [PATCH 08/91] fix(index): enforce fail-closed IndexPaths in the v2
 data plane

Close the transitional configured-root bypass rejected in verification and
tighten the Batch M path authority:

- Delete current_root_lenient/current_db_lenient. CLI codegraph_dir/db_path,
  codegraph-mcp CodeGraphEngine::open, and codegraph-watch default_db_path now
  resolve through fail-closed IndexPaths::resolve, honoring the configured
  CODEGRAPH_DIR identity-suffixed sibling. CODEGRAPH_DIR=. / .. / root / overlap
  / symlink aliases now error before any root or DB creation and never mutate
  the legacy namespace; two projects sharing one configured root get distinct
  identity roots. Existence-probes that must stay infallible (CLI is_initialized
  and status, mcp roots::db_path_for) degrade to the safe default and never open
  a reconstructed configured-root path; the authoritative rejection is in
  CodeGraphEngine::open.
- Replace the over-broad is_reserved_index_dir(".codegraph-" prefix) with
  IndexPaths::reserved_child_dir_names, the exact resolved root set matched only
  as direct children of the project root, so a user .codegraph-sources/ stays
  scannable while .codegraph and .codegraph-v2 are excluded.
- Detect Windows junctions/reparse points via FILE_ATTRIBUTE_REPARSE_POINT in
  addition to FileType::is_symlink.
- Capture GetFileInformationByHandleEx's OS error before CloseHandle so the
  diagnostic is not masked.
- Remove the state_slot(usize) modulo-alias API; state_slots() is the exact
  0/1 contract for this slice.
- Create the .codegraph rendezvous parent before opening daemon.log in the
  parent-side detached-spawn redirect, since the current namespace is the
  sibling .codegraph-v2 and .codegraph may not exist yet.

Adds real public-surface CLI regressions (configured relative/absolute root
sibling, two-project collision, CODEGRAPH_DIR=. fails closed byte-nonmutating)
and a scanner regression proving .codegraph-sources is indexed. The initial
black-box Red stays green; cargo test --workspace --locked passes.
---
 crates/codegraph-cli/src/main.rs              | 138 +++++++++-----
 .../tests/batch_m_v2_namespace.rs             | 148 ++++++++++++++-
 crates/codegraph-core/src/index_paths.rs      | 174 +++++++++---------
 crates/codegraph-daemon/src/spawn.rs          |  11 +-
 crates/codegraph-extract/src/engine.rs        |  72 +++++++-
 crates/codegraph-mcp/src/engine.rs            |  15 +-
 crates/codegraph-mcp/src/roots.rs             |  20 +-
 crates/codegraph-watch/src/sync.rs            |  38 ++--
 crates/codegraph-watch/src/watcher.rs         |  12 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  97 ++++++++++
 10 files changed, 540 insertions(+), 185 deletions(-)

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 40c9e89..cf99df7 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1161,8 +1161,9 @@ fn cmd_init(path: Option<PathBuf>, target: &str) -> Result<()> {
         return installer::run_install_local_targets(project, target);
     }
     guard_indexable_root(&project)?;
-    fs::create_dir_all(codegraph_dir(&project))
-        .with_context(|| format!("creating {}", codegraph_dir(&project).display()))?;
+    let index_root = codegraph_dir(&project)?;
+    fs::create_dir_all(&index_root)
+        .with_context(|| format!("creating {}", index_root.display()))?;
     let result = index_project(&project, true, false)?;
     println!("Initialized in {}", project.display());
     print_index_result(&result);
@@ -1174,8 +1175,9 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
     if !force {
         bail!("refusing to delete .codegraph without --force");
     }
-    fs::remove_dir_all(codegraph_dir(&project))
-        .with_context(|| format!("removing {}", codegraph_dir(&project).display()))?;
+    let index_root = codegraph_dir(&project)?;
+    fs::remove_dir_all(&index_root)
+        .with_context(|| format!("removing {}", index_root.display()))?;
     println!("Removed CodeGraph from {}", project.display());
     Ok(())
 }
@@ -1233,7 +1235,18 @@ fn cmd_sync(path: Option<PathBuf>, quiet: bool) -> Result<()> {
 fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
     let project = resolve_project_path_optional(&start);
-    let db = db_path(&project);
+    // Status inspects an existing project; a resolvable index root reports its
+    // real paths, an unresolvable/aliased configured root reports the safe
+    // default so status still answers instead of erroring.
+    let resolved = index_paths(&project).ok();
+    let index_root = resolved
+        .as_ref()
+        .map(|p| p.current_root().to_path_buf())
+        .unwrap_or_else(|| project.join(".codegraph-v2"));
+    let db = resolved
+        .as_ref()
+        .map(|p| p.current_db())
+        .unwrap_or_else(|| index_root.join("codegraph.db"));
     let db_exists = db.is_file();
     let daemon_running = daemon_already_running(&project);
     let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project);
@@ -1245,7 +1258,7 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
                 "initialized": false,
                 "version": VERSION,
                 "projectPath": project,
-                "indexPath": codegraph_dir(&project),
+                "indexPath": index_root,
                 "lastIndexed": null,
                 "dbPath": db,
                 "dbExists": db_exists,
@@ -1272,9 +1285,7 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let counts = store.counts()?;
     let nodes_by_kind = store.node_counts_by_kind()?;
     let files_by_language = store.file_counts_by_language()?;
-    let db_size = fs::metadata(db_path(&project))
-        .map(|m| m.len())
-        .unwrap_or(0);
+    let db_size = fs::metadata(&db).map(|m| m.len()).unwrap_or(0);
     let last_indexed = latest_indexed_at(&store)?;
     let built_with_version = store.get_project_metadata("indexed_with_version")?;
     let built_with_extraction_version = store
@@ -1300,7 +1311,7 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
             "initialized": true,
             "version": VERSION,
             "projectPath": project,
-            "indexPath": codegraph_dir(&project),
+            "indexPath": index_root,
             "lastIndexed": last_indexed.map(iso_like_millis),
             "fileCount": counts.file_count,
             "nodeCount": counts.node_count,
@@ -1504,14 +1515,19 @@ fn emit_serve_startup_debug(
     let cwd = std::env::current_dir()
         .map(|p| p.display().to_string())
         .unwrap_or_else(|_| "(unknown)".to_string());
-    let db = db_path(project_root);
+    let db = db_path(project_root).ok();
+    let db_display = db
+        .as_ref()
+        .map(|p| p.display().to_string())
+        .unwrap_or_else(|| "(unresolved)".to_string());
+    let db_exists = db.as_ref().map(|p| p.is_file()).unwrap_or(false);
     tracing::debug!(
         %exe,
         %cwd,
         explicit_path,
         default_project = %project_root.display(),
-        db = %db.display(),
-        db_exists = db.is_file(),
+        db = %db_display,
+        db_exists,
         has_codegraph_dir = has_codegraph,
         mode = ?mode,
         "serve startup"
@@ -1560,7 +1576,9 @@ fn cmd_serve(
             );
             return serve_direct_no_services(project, &project_root, no_watch);
         }
-        let has_codegraph = codegraph_dir(&project_root).is_dir();
+        let has_codegraph = codegraph_dir(&project_root)
+            .map(|d| d.is_dir())
+            .unwrap_or(false);
         let mode = select_serve_mode(daemon_opt_out(), is_daemon_internal(), has_codegraph);
         emit_serve_startup_debug(&project_root, explicit_path, has_codegraph, &mode);
         match mode {
@@ -1614,7 +1632,7 @@ fn cmd_serve_http(path: Option<PathBuf>, http_addr: &str, detach: bool) -> Resul
     let (project, mode) = match path {
         Some(raw) => {
             let project = resolve_project_path_optional(&absolute_path(raw));
-            let db = db_path(&project);
+            let db = db_path(&project)?;
             if !db.is_file() {
                 anyhow::bail!(
                     "`serve --http --path` requires an indexed project, but no index was found at {}. Run `codegraph init {}` (or `codegraph index`) first.",
@@ -2033,7 +2051,10 @@ mod normalize_lexical_tests {
 /// self-indexes the cwd — keeping it unindexed and therefore adoptable when the
 /// client reports its real workspace root via `roots/list`.
 fn should_run_serve_services(explicit_path: bool, project_root: &Path) -> bool {
-    explicit_path || codegraph_dir(project_root).is_dir()
+    explicit_path
+        || codegraph_dir(project_root)
+            .map(|d| d.is_dir())
+            .unwrap_or(false)
 }
 
 fn serve_direct(
@@ -2153,7 +2174,10 @@ fn start_daemon_for_adopted_root(project_root: &Path, no_watch: bool) -> Option<
     if daemon_opt_out() || is_daemon_internal() || !should_run_daemon_services(project_root) {
         return None;
     }
-    if !codegraph_dir(project_root).is_dir() {
+    if !codegraph_dir(project_root)
+        .map(|d| d.is_dir())
+        .unwrap_or(false)
+    {
         return None;
     }
     if daemon_already_running(project_root) {
@@ -2687,7 +2711,7 @@ fn cmd_unlock(path: Option<PathBuf>) -> Result<()> {
     let project = resolve_required_project(path)?;
     let daemon_lock = codegraph_daemon::daemon_pid_path(&project);
     let daemon_removed = daemon_lock.exists() && codegraph_daemon::unlock_project(&project);
-    let lock = codegraph_dir(&project).join("codegraph.lock");
+    let lock = codegraph_dir(&project)?.join("codegraph.lock");
     if !lock.exists() && !daemon_removed {
         println!("No lock file found - nothing to do");
         return Ok(());
@@ -3435,7 +3459,8 @@ fn index_project_inner(
     if clear_first {
         remove_db_files(project)?;
     }
-    fs::create_dir_all(codegraph_dir(project))?;
+    let index_root = codegraph_dir(project)?;
+    fs::create_dir_all(&index_root)?;
     let config = codegraph_core::config::get_config();
     let options = ExtractOptions {
         max_file_size: config.indexing.max_file_size,
@@ -3457,7 +3482,7 @@ fn index_project_inner(
     // guard's own connection then runs wal_checkpoint(TRUNCATE)+NORMAL with no WAL
     // contention, leaving the file in the same shape a NORMAL run produces.
     let _pragma_guard = BulkIndexPragmaGuard {
-        db_path: db_path(project),
+        db_path: db_path(project)?,
     };
     let store = open_store(project)?;
     store.set_bulk_index_pragmas()?;
@@ -3484,7 +3509,7 @@ fn index_project_inner(
     const REF_FLUSH_ROWS: usize = 20_000;
     const RESOLVE_BATCH_ROWS: usize = 5_000;
 
-    let spill = SpillWriter::new(codegraph_dir(project))?;
+    let spill = SpillWriter::new(index_root.clone())?;
     let pending_nodes: Vec<Node> = Vec::with_capacity(NODE_FLUSH_ROWS);
 
     let bar = progress_bar(
@@ -4199,11 +4224,15 @@ fn exact_or_top_matches<'a>(matches: &'a [Node], symbol: &str) -> Vec<&'a Node>
 }
 
 fn open_store(project: &Path) -> Result<Store> {
-    Store::open(&db_path(project)).map_err(Into::into)
+    Store::open(&db_path(project)?).map_err(Into::into)
 }
 
+/// Whether `project` has a current-namespace index DB. An unsafe/aliased
+/// `CODEGRAPH_DIR` (a `resolve` failure) counts as NOT initialized here so
+/// project discovery keeps walking; the mutating command paths independently
+/// re-resolve fail-closed via [`db_path`]/[`codegraph_dir`] before touching disk.
 fn is_initialized(project: &Path) -> bool {
-    db_path(project).exists()
+    db_path(project).map(|p| p.exists()).unwrap_or(false)
 }
 
 fn resolve_required_project(path: Option<PathBuf>) -> Result<PathBuf> {
@@ -4271,28 +4300,31 @@ fn normalize_lexical(path: &Path) -> PathBuf {
     out
 }
 
-/// The current (v2) index root for `project`. Defaults to the isolated
-/// `.codegraph-v2` sibling (Batch M, plan line 262); a `CODEGRAPH_DIR` override
-/// keeps its existing simple-join semantics. Routed through the single
-/// `codegraph-core::IndexPaths` path authority so no CLI code reconstructs the
-/// `.codegraph-v2` literal itself.
-fn codegraph_dir(project: &Path) -> PathBuf {
-    codegraph_core::IndexPaths::current_root_lenient(
-        project,
-        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-    )
+/// Fail-closed resolution of the project's index paths through the single
+/// `codegraph-core::IndexPaths` authority, honoring `CODEGRAPH_DIR`. Errors on
+/// an unsafe/aliased/overlapping configured root or an inaccessible project;
+/// callers never fall back to a reconstructed path.
+fn index_paths(project: &Path) -> Result<codegraph_core::IndexPaths> {
+    codegraph_core::IndexPaths::resolve(project, std::env::var("CODEGRAPH_DIR").ok().as_deref())
+        .map_err(Into::into)
 }
 
-fn db_path(project: &Path) -> PathBuf {
-    codegraph_core::IndexPaths::current_db_lenient(
-        project,
-        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-    )
+/// The current (v2) index root for `project` (`.codegraph-v2` by default; a
+/// `<name>-v2-<projectIdentity>` sibling for a configured `CODEGRAPH_DIR`).
+/// Fail-closed via [`index_paths`].
+fn codegraph_dir(project: &Path) -> Result<PathBuf> {
+    Ok(index_paths(project)?.current_root().to_path_buf())
+}
+
+/// The current (v2) index DB path for `project`. Fail-closed via [`index_paths`].
+fn db_path(project: &Path) -> Result<PathBuf> {
+    Ok(index_paths(project)?.current_db())
 }
 
 fn remove_db_files(project: &Path) -> Result<()> {
+    let db = db_path(project)?;
     for suffix in ["", "-wal", "-shm"] {
-        let path = PathBuf::from(format!("{}{}", db_path(project).display(), suffix));
+        let path = PathBuf::from(format!("{}{}", db.display(), suffix));
         if path.exists() {
             fs::remove_file(&path).with_context(|| format!("removing {}", path.display()))?;
         }
@@ -5117,12 +5149,17 @@ mod pure_helper_tests {
     #[test]
     fn db_path_is_under_codegraph_dir() {
         if std::env::var("CODEGRAPH_DIR").is_err() {
-            let p = Path::new("/proj");
+            let dir = tmp("dbpath");
+            let canonical = dir.canonicalize().unwrap();
             assert_eq!(
-                db_path(p),
-                PathBuf::from("/proj/.codegraph-v2/codegraph.db")
+                db_path(&dir).unwrap(),
+                canonical.join(".codegraph-v2/codegraph.db")
             );
-            assert_eq!(codegraph_dir(p), PathBuf::from("/proj/.codegraph-v2"));
+            assert_eq!(
+                codegraph_dir(&dir).unwrap(),
+                canonical.join(".codegraph-v2")
+            );
+            let _ = fs::remove_dir_all(&dir);
         }
     }
 
@@ -5296,14 +5333,23 @@ mod formatter_and_env_tests {
 
     #[test]
     fn codegraph_dir_and_db_path_default_layout() {
+        let _lock = ENV_LOCK.lock().unwrap();
         let prev = std::env::var_os("CODEGRAPH_DIR");
         unsafe { std::env::remove_var("CODEGRAPH_DIR") };
-        let proj = Path::new("/tmp/proj");
-        assert_eq!(codegraph_dir(proj), proj.join(".codegraph-v2"));
-        assert_eq!(db_path(proj), proj.join(".codegraph-v2/codegraph.db"));
+        let proj = tmp("default-layout");
+        let canonical = proj.canonicalize().unwrap();
+        assert_eq!(
+            codegraph_dir(&proj).unwrap(),
+            canonical.join(".codegraph-v2")
+        );
+        assert_eq!(
+            db_path(&proj).unwrap(),
+            canonical.join(".codegraph-v2/codegraph.db")
+        );
         if let Some(v) = prev {
             unsafe { std::env::set_var("CODEGRAPH_DIR", v) };
         }
+        let _ = fs::remove_dir_all(&proj);
     }
 
     #[test]
diff --git a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
index fd0538d..18d508b 100644
--- a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
+++ b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
@@ -90,12 +90,18 @@ struct Run {
 }
 
 fn run_in(registry_dir: &Path, args: &[&str]) -> Run {
-    let output = Command::new(bin())
-        .args(args)
+    run_in_env(registry_dir, args, &[])
+}
+
+fn run_in_env(registry_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Run {
+    let mut cmd = Command::new(bin());
+    cmd.args(args)
         .env("CODEGRAPH_HTTP_REGISTRY_DIR", registry_dir)
-        .env("CODEGRAPH_NO_DAEMON", "1")
-        .output()
-        .expect("run codegraph binary");
+        .env("CODEGRAPH_NO_DAEMON", "1");
+    for (k, v) in envs {
+        cmd.env(k, v);
+    }
+    let output = cmd.output().expect("run codegraph binary");
     Run {
         stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
         stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
@@ -103,6 +109,14 @@ fn run_in(registry_dir: &Path, args: &[&str]) -> Run {
     }
 }
 
+fn indexed_names(project: &Path) -> Vec<String> {
+    std::fs::read_dir(project)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .map(|e| e.file_name().to_string_lossy().into_owned())
+        .collect()
+}
+
 /// Initial Batch M black-box Red: `init` must build the index in the isolated
 /// sibling `.codegraph-v2` namespace, never the fixed legacy `.codegraph` one.
 ///
@@ -174,3 +188,127 @@ fn init_writes_isolated_v2_namespace_not_legacy_codegraph() {
         legacy_db.display()
     );
 }
+
+/// The v2 current root for a relative `CODEGRAPH_DIR` must be the fail-closed
+/// `IndexPaths::resolve` identity-suffixed SIBLING `<name>-v2-<projectIdentity>`
+/// through the REAL CLI, never the old `<project>/<value>` simple-join. Proven
+/// by `status --json`'s `indexPath` and the on-disk DB placement after `init`.
+#[test]
+fn configured_relative_root_uses_identity_suffixed_sibling_via_cli() {
+    let dir = TestDir::new("cfg-rel");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    let run = run_in_env(dir.path(), &["init", p], &[("CODEGRAPH_DIR", "cache")]);
+    assert!(run.ok, "init must succeed: {} {}", run.stdout, run.stderr);
+
+    let names = indexed_names(&project);
+    // The simple-join `<project>/cache/codegraph.db` MUST NOT exist.
+    assert!(
+        !project.join("cache").join("codegraph.db").is_file(),
+        "configured root must NOT use the old simple-join `cache/`: dir={names:?}"
+    );
+    // Exactly one identity-suffixed sibling `cache-v2-<64hex>` holds the DB.
+    let sibling = names
+        .iter()
+        .find(|n| n.starts_with("cache-v2-"))
+        .unwrap_or_else(|| panic!("expected a `cache-v2-<identity>` sibling, got {names:?}"));
+    assert_eq!(
+        sibling.len(),
+        "cache-v2-".len() + 64,
+        "sibling must carry a full 64-hex projectIdentity: {sibling}"
+    );
+    assert!(
+        project.join(sibling).join("codegraph.db").is_file(),
+        "the identity-suffixed sibling must hold the DB: {names:?}"
+    );
+
+    let status = run_in_env(
+        dir.path(),
+        &["status", "--json", p],
+        &[("CODEGRAPH_DIR", "cache")],
+    );
+    assert!(status.ok, "status must succeed: {}", status.stderr);
+    assert!(
+        status.stdout.contains(sibling.as_str()),
+        "status indexPath must name the identity sibling {sibling}: {}",
+        status.stdout
+    );
+}
+
+/// Two DISTINCT physical projects given the SAME absolute `CODEGRAPH_DIR` must
+/// receive DISTINCT identity-suffixed current roots through the REAL CLI, so one
+/// project can never open the other's index.
+#[test]
+fn two_projects_sharing_absolute_configured_root_get_distinct_roots_via_cli() {
+    let dir = TestDir::new("cfg-abs");
+    let project_a = dir.path().join("a/mini");
+    let project_b = dir.path().join("b/mini");
+    copy_tree(&mini_fixture(), &project_a);
+    copy_tree(&mini_fixture(), &project_b);
+    let shared = dir.path().join("shared/cg");
+    std::fs::create_dir_all(dir.path().join("shared")).unwrap();
+    let shared_str = shared.to_str().unwrap();
+
+    let ra = run_in_env(
+        dir.path(),
+        &["init", project_a.to_str().unwrap()],
+        &[("CODEGRAPH_DIR", shared_str)],
+    );
+    assert!(ra.ok, "init a must succeed: {} {}", ra.stdout, ra.stderr);
+    let rb = run_in_env(
+        dir.path(),
+        &["init", project_b.to_str().unwrap()],
+        &[("CODEGRAPH_DIR", shared_str)],
+    );
+    assert!(rb.ok, "init b must succeed: {} {}", rb.stdout, rb.stderr);
+
+    let parent = dir.path().join("shared");
+    let siblings: Vec<String> = std::fs::read_dir(&parent)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .map(|e| e.file_name().to_string_lossy().into_owned())
+        .filter(|n| n.starts_with("cg-v2-"))
+        .collect();
+    assert_eq!(
+        siblings.len(),
+        2,
+        "two projects must produce two distinct identity siblings, got {siblings:?}"
+    );
+    assert_ne!(
+        siblings[0], siblings[1],
+        "the two current roots must differ"
+    );
+    // The shared simple-join `shared/cg/codegraph.db` must never exist.
+    assert!(
+        !shared.join("codegraph.db").is_file(),
+        "configured absolute root must NOT collapse two projects onto one simple-join DB"
+    );
+}
+
+/// A `CODEGRAPH_DIR` that aliases the project root (`.`) must fail closed
+/// through the REAL CLI, creating NO `<project>/codegraph.db` and NO legacy
+/// mutation — the fail-closed `resolve` contract, not the old simple-join.
+#[test]
+fn configured_dot_alias_fails_closed_without_mutation_via_cli() {
+    let dir = TestDir::new("cfg-dot");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    let run = run_in_env(dir.path(), &["init", p], &[("CODEGRAPH_DIR", ".")]);
+    assert!(
+        !run.ok,
+        "init with CODEGRAPH_DIR=. must fail closed: stdout={} stderr={}",
+        run.stdout, run.stderr
+    );
+    assert!(
+        !project.join("codegraph.db").is_file(),
+        "a `.` alias must not write `<project>/codegraph.db`"
+    );
+    assert!(
+        !project.join(".codegraph").join("codegraph.db").is_file(),
+        "a `.` alias must not mutate the legacy namespace"
+    );
+}
diff --git a/crates/codegraph-core/src/index_paths.rs b/crates/codegraph-core/src/index_paths.rs
index 13e0c4b..9118d5e 100644
--- a/crates/codegraph-core/src/index_paths.rs
+++ b/crates/codegraph-core/src/index_paths.rs
@@ -209,41 +209,39 @@ impl IndexPaths {
         })
     }
 
-    /// Infallible transitional current-root resolver for the data plane.
-    ///
-    /// [`IndexPaths::resolve`] is the fail-closed authority, but it canonicalizes
-    /// and therefore REQUIRES the project to already exist — CLI helpers such as
-    /// `status` on a not-yet-initialized directory must stay infallible. This
-    /// helper centralizes the default-root literal so no consumer reconstructs
-    /// `.codegraph-v2`:
-    ///
-    /// - No / empty `CODEGRAPH_DIR` → `<project>/.codegraph-v2` (the isolated v2
-    ///   default; this is the placement the Batch M black-box Red asserts).
-    /// - `CODEGRAPH_DIR=<value>` → `<project>/<value>` (the pre-v0.40.4 simple
-    ///   join, preserved byte-for-byte). The plan's identity-suffixed sibling for
-    ///   a configured root is fully implemented and tested in [`resolve`]; wiring
-    ///   that richer form into the infallible data-plane helpers is a later Batch
-    ///   M consumer task, so this slice keeps the configured-root override at its
-    ///   existing semantics rather than half-implementing the sibling here.
-    pub fn current_root_lenient(project: &Path, codegraph_dir: Option<&str>) -> PathBuf {
-        match codegraph_dir.filter(|value| !value.is_empty()) {
-            Some(value) => project.join(value),
-            None => project.join(DEFAULT_CURRENT_DIR),
+    /// Exact reserved index-root child-directory names the scanner/watcher must
+    /// exclude for `project`: the resolved physical root set (fixed + configured
+    /// legacy roots and the current root) reduced to basenames that are direct
+    /// children of the canonical project, always including the fixed
+    /// `.codegraph`. Exact names only — never a `.codegraph-*` prefix, so a user
+    /// `.codegraph-sources` stays scannable. On a `resolve` failure it degrades
+    /// to the safe fixed-legacy + default-current names rather than
+    /// reconstructing a configured-root path; the fail-closed DB contract is
+    /// enforced separately at the CLI/MCP/watch boundary by [`IndexPaths::resolve`].
+    pub fn reserved_child_dir_names(
+        project: &Path,
+        codegraph_dir: Option<&str>,
+    ) -> std::collections::BTreeSet<String> {
+        let mut names = std::collections::BTreeSet::new();
+        names.insert(LEGACY_DIR.to_string());
+        match Self::resolve(project, codegraph_dir) {
+            Ok(paths) => {
+                let canonical_project = paths.project();
+                let mut roots = paths.legacy_roots().to_vec();
+                roots.push(paths.current_root().to_path_buf());
+                for root in roots {
+                    if root.parent() == Some(canonical_project)
+                        && let Some(name) = root.file_name()
+                    {
+                        names.insert(name.to_string_lossy().into_owned());
+                    }
+                }
+            }
+            Err(_) => {
+                names.insert(DEFAULT_CURRENT_DIR.to_string());
+            }
         }
-    }
-
-    /// `<current_root_lenient>/codegraph.db` — the infallible transitional DB
-    /// path used by the data plane (CLI, MCP, watch) in this slice.
-    pub fn current_db_lenient(project: &Path, codegraph_dir: Option<&str>) -> PathBuf {
-        Self::current_root_lenient(project, codegraph_dir).join("codegraph.db")
-    }
-
-    /// Whether a directory basename is a reserved CodeGraph index root that the
-    /// scanner/watcher must never descend into: the fixed legacy `.codegraph`
-    /// and any `.codegraph-*` sibling (including the `.codegraph-v2` default).
-    /// Mirrors the watcher policy's existing `.codegraph-` prefix exclusion.
-    pub fn is_reserved_index_dir(name: &str) -> bool {
-        name == LEGACY_DIR || name.starts_with(".codegraph-")
+        names
     }
 
     /// Canonical project root.
@@ -290,13 +288,6 @@ impl IndexPaths {
         ]
     }
 
-    /// A single fixed state slot by index (0 or 1); indices other than 0/1 are
-    /// clamped into range so callers cannot address a nonexistent slot.
-    pub fn state_slot(&self, slot: usize) -> PathBuf {
-        let [zero, one] = self.state_slots();
-        if slot.is_multiple_of(2) { zero } else { one }
-    }
-
     /// `<current_root>/uninitialized` — the interrupted-uninit tombstone marker.
     pub fn tombstone(&self) -> PathBuf {
         self.current_root.join("uninitialized")
@@ -392,11 +383,27 @@ fn nearest_existing_ancestor(path: &Path) -> Option<PathBuf> {
     None
 }
 
-/// Whether `path` currently exists AND is a symlink / reparse point.
+/// Whether `path` currently exists AND is a symlink or reparse point.
+///
+/// On Windows `FileType::is_symlink` misses directory junctions and other
+/// reparse points, so the raw `FILE_ATTRIBUTE_REPARSE_POINT` attribute bit is
+/// checked as well; those are the alias forms an index root must refuse.
 fn is_symlink(path: &Path) -> bool {
-    path.symlink_metadata()
-        .map(|meta| meta.file_type().is_symlink())
-        .unwrap_or(false)
+    let Ok(meta) = path.symlink_metadata() else {
+        return false;
+    };
+    if meta.file_type().is_symlink() {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt as _;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0400;
+        if meta.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
+            return true;
+        }
+    }
+    false
 }
 
 /// Physically normalize an index root: reject empty/root aliases, reject any
@@ -612,18 +619,18 @@ mod windows_identity {
                 core::mem::size_of::<FileIdInfo>() as u32,
             )
         };
+        // Capture the query's OS error BEFORE CloseHandle, which itself sets the
+        // thread-local last-error and would otherwise mask the real failure.
+        let query_err = (ok == 0).then(std::io::Error::last_os_error);
         // SAFETY: close the handle exactly once regardless of the query result.
         unsafe {
             CloseHandle(handle);
         }
 
-        if ok == 0 {
+        if let Some(err) = query_err {
             return Err(IndexPathsError::UnsupportedFilesystem {
                 path: path.to_path_buf(),
-                detail: format!(
-                    "GetFileInformationByHandleEx(FileIdInfo) failed: {}",
-                    std::io::Error::last_os_error()
-                ),
+                detail: format!("GetFileInformationByHandleEx(FileIdInfo) failed: {err}"),
             });
         }
         Ok((info.volume_serial_number, info.file_id))
@@ -692,11 +699,6 @@ mod tests {
                 root.join("index-state.1.json"),
             ]
         );
-        assert_eq!(paths.state_slot(0), root.join("index-state.0.json"));
-        assert_eq!(paths.state_slot(1), root.join("index-state.1.json"));
-        // Out-of-range slot indices clamp into [0, 1] rather than panicking.
-        assert_eq!(paths.state_slot(2), root.join("index-state.0.json"));
-        assert_eq!(paths.state_slot(3), root.join("index-state.1.json"));
         assert_eq!(paths.tombstone(), root.join("uninitialized"));
         assert_eq!(paths.config_toml(), root.join("config.toml"));
         assert_eq!(paths.extension_config(), root.join("codegraph.json"));
@@ -946,43 +948,43 @@ mod tests {
     }
 
     #[test]
-    fn current_root_lenient_defaults_to_codegraph_v2() {
-        let project = Path::new("/proj");
-        assert_eq!(
-            IndexPaths::current_root_lenient(project, None),
-            PathBuf::from("/proj/.codegraph-v2")
-        );
-        assert_eq!(
-            IndexPaths::current_db_lenient(project, None),
-            PathBuf::from("/proj/.codegraph-v2/codegraph.db")
-        );
-        // Empty override is treated as unset.
-        assert_eq!(
-            IndexPaths::current_root_lenient(project, Some("")),
-            PathBuf::from("/proj/.codegraph-v2")
-        );
+    fn reserved_child_names_default_are_exactly_legacy_and_v2() {
+        let project = temp_dir("reserved-default");
+        let names = IndexPaths::reserved_child_dir_names(&project, None);
+        assert!(names.contains(".codegraph"));
+        assert!(names.contains(".codegraph-v2"));
+        // A user source directory sharing the `.codegraph-` prefix is NOT
+        // reserved and must remain scannable.
+        assert!(!names.contains(".codegraph-sources"));
+        let _ = std::fs::remove_dir_all(&project);
     }
 
     #[test]
-    fn current_root_lenient_honors_codegraph_dir_override() {
-        let project = Path::new("/proj");
-        assert_eq!(
-            IndexPaths::current_root_lenient(project, Some("custom")),
-            PathBuf::from("/proj/custom")
-        );
-        assert_eq!(
-            IndexPaths::current_db_lenient(project, Some("custom")),
-            PathBuf::from("/proj/custom/codegraph.db")
+    fn reserved_child_names_include_relative_configured_sibling() {
+        let project = temp_dir("reserved-configured");
+        let names = IndexPaths::reserved_child_dir_names(&project, Some("cache"));
+        let identity = IndexPaths::resolve(&project, Some("cache"))
+            .unwrap()
+            .project_identity()
+            .to_string();
+        assert!(names.contains(".codegraph"), "{names:?}");
+        assert!(names.contains("cache"), "configured legacy root: {names:?}");
+        assert!(
+            names.contains(&format!("cache-v2-{identity}")),
+            "configured current sibling: {names:?}"
         );
+        assert!(!names.contains(".codegraph-sources"));
+        let _ = std::fs::remove_dir_all(&project);
     }
 
     #[test]
-    fn reserved_index_dir_matches_legacy_and_v2_siblings() {
-        assert!(IndexPaths::is_reserved_index_dir(".codegraph"));
-        assert!(IndexPaths::is_reserved_index_dir(".codegraph-v2"));
-        assert!(IndexPaths::is_reserved_index_dir(".codegraph-daemon"));
-        assert!(!IndexPaths::is_reserved_index_dir("src"));
-        assert!(!IndexPaths::is_reserved_index_dir(".codegraphx"));
-        assert!(!IndexPaths::is_reserved_index_dir(".git"));
+    fn reserved_child_names_degrade_to_defaults_on_invalid_configured_root() {
+        let project = temp_dir("reserved-invalid");
+        // `.` resolves to the project root itself — an invalid alias. Name
+        // derivation must degrade to the safe defaults, never error.
+        let names = IndexPaths::reserved_child_dir_names(&project, Some("."));
+        assert!(names.contains(".codegraph"));
+        assert!(names.contains(".codegraph-v2"));
+        let _ = std::fs::remove_dir_all(&project);
     }
 }
diff --git a/crates/codegraph-daemon/src/spawn.rs b/crates/codegraph-daemon/src/spawn.rs
index cc13add..96d74f0 100644
--- a/crates/codegraph-daemon/src/spawn.rs
+++ b/crates/codegraph-daemon/src/spawn.rs
@@ -61,10 +61,19 @@ pub fn spawn_detached_daemon(exe: &Path, root: &Path, no_watch: bool) -> Result<
 }
 
 fn log_target(root: &Path) -> Stdio {
+    let path = daemon_log_path(root);
+    // The rendezvous dir (`.codegraph`) is created by the daemon's lock layer in
+    // the CHILD, but this log redirect is set up in the PARENT before spawn. The
+    // current index namespace is the sibling `.codegraph-v2`, so `.codegraph`
+    // may not exist yet — create the log's parent here so the redirect lands in
+    // a file instead of silently falling back to a null sink.
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
     OpenOptions::new()
         .create(true)
         .append(true)
-        .open(daemon_log_path(root))
+        .open(path)
         .map_or_else(|_| Stdio::null(), Stdio::from)
 }
 
diff --git a/crates/codegraph-extract/src/engine.rs b/crates/codegraph-extract/src/engine.rs
index 5e6afcd..c40ed27 100644
--- a/crates/codegraph-extract/src/engine.rs
+++ b/crates/codegraph-extract/src/engine.rs
@@ -301,10 +301,19 @@ pub fn scan_project(root: &Path, options: &ExtractOptions) -> Result<Vec<String>
     // later `!pattern` negation re-includes a path an earlier set excluded.
     let pattern_sets: Vec<&[String]> = vec![&options.ignore_paths, &options.exclude, &gitignore];
     let include = IncludeSet::new(&options.include, &options.exclude);
+    // The exact reserved index-root child names for THIS project (fixed legacy
+    // `.codegraph`, the configured legacy root, and the resolved current root),
+    // resolved once so scan_dir excludes only those directories — never an
+    // arbitrary `.codegraph-*`-prefixed user directory.
+    let reserved_roots = codegraph_core::IndexPaths::reserved_child_dir_names(
+        root,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    );
     scan_dir(
         root,
         root,
         &ignored_dirs,
+        &reserved_roots,
         &pattern_sets,
         &include,
         &mut files,
@@ -317,6 +326,7 @@ fn scan_dir(
     root: &Path,
     dir: &Path,
     ignored_dirs: &HashSet<&str>,
+    reserved_roots: &std::collections::BTreeSet<String>,
     pattern_sets: &[&[String]],
     include: &IncludeSet,
     files: &mut Vec<String>,
@@ -327,13 +337,13 @@ fn scan_dir(
         let path = entry.path();
         let name = entry.file_name();
         let name = name.to_string_lossy();
-        // Skip `.git`, the fixed legacy `.codegraph`, and every `.codegraph-*`
-        // sibling (including the isolated `.codegraph-v2` current root, Batch M)
-        // so a project's own index storage is never scanned back into the graph.
-        if name == ".git"
-            || codegraph_core::IndexPaths::is_reserved_index_dir(name.as_ref())
-            || ignored_dirs.contains(name.as_ref())
-        {
+        // Skip `.git` and the exact reserved index roots (fixed/configured legacy
+        // + resolved current) — but ONLY when they are direct children of the
+        // project root, so a `.codegraph`-named directory deeper in the tree is
+        // still governed by the normal ignore rules, not this exclusion.
+        let is_reserved_root_here =
+            dir == root && (name == ".git" || reserved_roots.contains(name.as_ref()));
+        if is_reserved_root_here || ignored_dirs.contains(name.as_ref()) {
             continue;
         }
         let relative = normalize_path(path.strip_prefix(root).unwrap_or(&path));
@@ -347,7 +357,15 @@ fn scan_dir(
             if ignored && !include.wants_descend(&relative) {
                 continue;
             }
-            scan_dir(root, &path, ignored_dirs, pattern_sets, include, files)?;
+            scan_dir(
+                root,
+                &path,
+                ignored_dirs,
+                reserved_roots,
+                pattern_sets,
+                include,
+                files,
+            )?;
         } else if file_type.is_file() && is_extractable_source_path(&relative) {
             // Post-model include decision: a model-ignored file is force-included
             // iff it matches `include` and is NOT overridden by an explicit
@@ -599,6 +617,44 @@ mod tests {
         fs::write(&path, contents).expect("write file");
     }
 
+    /// The scanner excludes ONLY the exact reserved index roots (the fixed
+    /// legacy `.codegraph` and the resolved current `.codegraph-v2`), never an
+    /// arbitrary `.codegraph-*`-prefixed user directory. A first-party source
+    /// dir named `.codegraph-sources` must still be indexed.
+    #[test]
+    fn scan_keeps_user_codegraph_prefixed_dir_but_excludes_reserved_roots() {
+        let project = unique_project("reserved_roots");
+        touch(
+            &project,
+            ".codegraph-sources/kept.ts",
+            "export const a = 1;",
+        );
+        touch(&project, ".codegraph/codegraph.db", "reserved");
+        touch(&project, ".codegraph-v2/codegraph.db", "reserved");
+        touch(&project, "src/app.ts", "export const b = 2;");
+
+        let files = scan_project(&project, &ExtractOptions::default()).expect("scan project");
+
+        assert!(
+            files.contains(&".codegraph-sources/kept.ts".to_string()),
+            "a user `.codegraph-sources` dir must stay scannable: {files:?}"
+        );
+        assert!(
+            files.contains(&"src/app.ts".to_string()),
+            "ordinary source must be indexed: {files:?}"
+        );
+        assert!(
+            !files.iter().any(|f| f.starts_with(".codegraph/")),
+            "the fixed legacy `.codegraph` root must be excluded: {files:?}"
+        );
+        assert!(
+            !files.iter().any(|f| f.starts_with(".codegraph-v2/")),
+            "the resolved current `.codegraph-v2` root must be excluded: {files:?}"
+        );
+
+        fs::remove_dir_all(&project).ok();
+    }
+
     /// A real directory scan of a Godot project skips the regenerated `.godot/`
     /// engine cache and the vendored `addons/` plugin tree while still finding
     /// first-party `.gd` business code.
diff --git a/crates/codegraph-mcp/src/engine.rs b/crates/codegraph-mcp/src/engine.rs
index b0e7c2b..b8272a2 100644
--- a/crates/codegraph-mcp/src/engine.rs
+++ b/crates/codegraph-mcp/src/engine.rs
@@ -68,16 +68,17 @@ pub struct CodeGraphEngine {
 }
 
 impl CodeGraphEngine {
-    /// Open the store at the project's current (v2) index DB
-    /// (`<project_root>/.codegraph-v2/codegraph.db` by default; `CODEGRAPH_DIR`
-    /// override honored). Routed through the single `codegraph-core::IndexPaths`
-    /// path authority (Batch M) so the MCP request path reads the same namespace
-    /// `codegraph init` writes.
+    /// Open the store at the project's current (v2) index DB, resolved
+    /// fail-closed through the single `codegraph-core::IndexPaths` authority
+    /// (`.codegraph-v2/codegraph.db` by default; a `<name>-v2-<projectIdentity>`
+    /// sibling for a configured `CODEGRAPH_DIR`). An unsafe/aliased/overlapping
+    /// configured root errors here rather than opening a reconstructed path.
     pub fn open(project_root: &Path) -> anyhow::Result<Self> {
-        let db_path = codegraph_core::IndexPaths::current_db_lenient(
+        let db_path = codegraph_core::IndexPaths::resolve(
             project_root,
             std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-        );
+        )?
+        .current_db();
         let store = Store::open(&db_path)?;
         Ok(Self {
             store,
diff --git a/crates/codegraph-mcp/src/roots.rs b/crates/codegraph-mcp/src/roots.rs
index de64f1a..0cc241c 100644
--- a/crates/codegraph-mcp/src/roots.rs
+++ b/crates/codegraph-mcp/src/roots.rs
@@ -32,15 +32,23 @@ pub fn format_tool_debug_line(
     )
 }
 
-/// The current (v2) index DB path under a project root
-/// (`<project_path>/.codegraph-v2/codegraph.db` by default; `CODEGRAPH_DIR`
-/// override honored). Routed through the single `codegraph-core::IndexPaths`
-/// path authority (Batch M) so project resolution and the served DB agree.
+/// The current (v2) index DB path under a project root, resolved fail-closed
+/// through the single `codegraph-core::IndexPaths` authority so it agrees with
+/// [`crate::CodeGraphEngine::open`]. This is an EXISTENCE-probe helper (callers
+/// do `db_path_for(p).is_file()`), so an unsafe/aliased configured root degrades
+/// to the safe `.codegraph-v2` default whose file simply will not exist — it
+/// NEVER reconstructs a configured-root path that could shadow another project.
+/// The authoritative fail-closed rejection happens in `CodeGraphEngine::open`.
 pub fn db_path_for(project_path: &Path) -> PathBuf {
-    codegraph_core::IndexPaths::current_db_lenient(
+    match codegraph_core::IndexPaths::resolve(
         project_path,
         std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-    )
+    ) {
+        Ok(paths) => paths.current_db(),
+        Err(_) => project_path
+            .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
+            .join("codegraph.db"),
+    }
 }
 
 pub struct WorkspaceRoots {
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index 0c8b9dc..e64b434 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -50,7 +50,7 @@ pub fn sync_project_once_with_progress(
     let started = std::time::Instant::now();
     let mut candidates = codegraph_extract::engine::scan_project(project_root, &options)?;
 
-    let db_path = default_db_path(project_root);
+    let db_path = default_db_path(project_root)?;
     let mut store = Store::open(&db_path).with_context(|| format!("open {}", db_path.display()))?;
 
     // Cold CLI sync has no watcher event list, so deletions are found by diffing
@@ -297,14 +297,12 @@ fn sweep_orphaned_refs(project_root: &Path, store: &mut Store) -> Result<()> {
 /// (`RESOLVE_BATCH_ROWS`) so a healed index is byte-equal to `index --force`.
 const ORPHAN_SWEEP_BATCH_ROWS: usize = 5_000;
 
-pub(crate) fn default_db_path(project_root: &Path) -> PathBuf {
-    // Route through the single `codegraph-core::IndexPaths` path authority
-    // (Batch M) so watcher sync writes the same v2 namespace `codegraph init`
-    // and MCP reads (`.codegraph-v2/codegraph.db` by default).
-    codegraph_core::IndexPaths::current_db_lenient(
+pub(crate) fn default_db_path(project_root: &Path) -> Result<PathBuf> {
+    Ok(codegraph_core::IndexPaths::resolve(
         project_root,
         std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-    )
+    )?
+    .current_db())
 }
 
 fn sync_one(
@@ -506,7 +504,7 @@ pub(crate) mod tests {
             "export function answer() { return 42; }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
 
         let first = sync_changed_paths(dir.path(), &db, ["src/app.ts"]).unwrap();
         assert_eq!(first.files_reindexed, 1);
@@ -535,7 +533,7 @@ pub(crate) mod tests {
             "export function alpha() { return 2; }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
 
         // When: a sync processes them in reverse-sorted input order.
         let first = sync_changed_paths(dir.path(), &db, ["src/zeta.ts", "src/alpha.ts"]).unwrap();
@@ -572,7 +570,7 @@ pub(crate) mod tests {
             "export function answer() { return 42; }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         let _ = sync_changed_paths(dir.path(), &db, ["src/app.ts"]).unwrap();
 
         // When: a sync re-checks the same unchanged file.
@@ -600,7 +598,7 @@ pub(crate) mod tests {
             "export const x = 1;\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
 
         // When: the input mixes an escaping path (ignored via normalize),
         // a node_modules path (ignored via policy), a non-source file
@@ -637,7 +635,7 @@ pub(crate) mod tests {
         fs::create_dir_all(dir.path().join("src")).unwrap();
         let file = dir.path().join("src/app.ts");
         fs::write(&file, "export function answer() { return 42; }\n").unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         let first = sync_changed_paths(dir.path(), &db, ["src/app.ts"]).unwrap();
         assert_eq!(first.files_reindexed, 1);
 
@@ -671,7 +669,7 @@ pub(crate) mod tests {
             "import { help } from './helper';\nexport function use() { return help(); }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         sync_changed_paths(dir.path(), &db, ["src/helper.ts", "src/consumer.ts"]).unwrap();
 
         // When: only the helper changes (adds a symbol) and is re-synced alone,
@@ -718,7 +716,7 @@ pub(crate) mod tests {
             "extends Node\n\nfunc _ready() -> void:\n\tvar button := Button.new()\n\tbutton.pressed.connect(_on_pressed.bind(button))\n\nfunc _goto_map() -> void:\n\tGameFlow.return_to_map()\n\nfunc _on_pressed(source) -> void:\n\tpass\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         sync_project_once(dir.path()).unwrap();
 
         let baseline = {
@@ -823,7 +821,7 @@ pub(crate) mod tests {
             "export function answer() { return 42; }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         sync_changed_paths(dir.path(), &db, ["src/app.ts"]).unwrap();
 
         // When: the stored node names for that file are queried.
@@ -856,7 +854,7 @@ pub(crate) mod tests {
             "import { add } from './math';\nexport function run(): number { return add(1, 2); }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
 
         // Index both files so nodes exist, then simulate the interruption by
         // deleting the resolved Calls edge, re-parking its unresolved ref, and
@@ -923,7 +921,7 @@ pub(crate) mod tests {
             "export function run(): void { externalMissing(); }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         sync_changed_paths(dir.path(), &db, ["src/app.ts"]).unwrap();
 
         // When: a bare no-change sync runs.
@@ -988,7 +986,7 @@ pub(crate) mod tests {
                     .changed_paths
                     .contains(&"Tools/helper.ts".to_string())
             );
-            let store = Store::open(&default_db_path(dir.path())).unwrap();
+            let store = Store::open(&default_db_path(dir.path()).unwrap()).unwrap();
             assert!(
                 store.file_by_path("Tools/helper.ts").unwrap().is_some(),
                 "gitignored Tools/ named in include must be indexed on sync"
@@ -1009,7 +1007,7 @@ pub(crate) mod tests {
             "export function help() { return 1; }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
 
         // Without include: the gitignored file is ignored by the policy gate.
         let plain = sync_changed_paths(dir.path(), &db, ["Tools/helper.ts"]).unwrap();
@@ -1049,7 +1047,7 @@ pub(crate) mod tests {
             "import { help } from './helper';\nexport function use() { return help(); }\n",
         )
         .unwrap();
-        let db = default_db_path(dir.path());
+        let db = default_db_path(dir.path()).unwrap();
         sync_changed_paths(dir.path(), &db, ["src/helper.ts", "src/consumer.ts"]).unwrap();
 
         // When: the helper is deleted and re-synced, driving the delete branch
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index 70d4a99..dba2996 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -338,10 +338,10 @@ impl ProjectWatcher {
             return Ok(None);
         }
         let policy = WatchPolicy::with_config(&project_root, &options.include, &options.exclude);
-        let db_path = options
-            .db_path
-            .clone()
-            .unwrap_or_else(|| default_db_path(&project_root));
+        let db_path = match options.db_path.clone() {
+            Some(db) => db,
+            None => default_db_path(&project_root)?,
+        };
         let sync_fn = options.sync_fn.clone().unwrap_or_else(|| {
             let project_root = project_root.clone();
             let include = options.include.clone();
@@ -783,7 +783,7 @@ mod tests {
     fn rapid_save_burst_triggers_exactly_one_reindex() {
         let dir = crate::sync::tests::TestDir::new("watch-debounce");
         fs::create_dir_all(dir.path().join("src")).unwrap();
-        let db = crate::sync::default_db_path(dir.path());
+        let db = crate::sync::default_db_path(dir.path()).unwrap();
         let outcomes = Arc::new(Mutex::new(Vec::new()));
         let seen = Arc::clone(&outcomes);
         let watcher = ProjectWatcher::start(
@@ -1159,7 +1159,7 @@ mod tests {
         // Given: an inert watcher with a long debounce so events stay pending.
         let dir = crate::sync::tests::TestDir::new("watch-pending");
         fs::create_dir_all(dir.path().join("src")).unwrap();
-        let db = crate::sync::default_db_path(dir.path());
+        let db = crate::sync::default_db_path(dir.path()).unwrap();
         let watcher = ProjectWatcher::start(
             dir.path(),
             WatchOptions {
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 65233f0..8df4cac 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -421,3 +421,100 @@ proxy_e2e, live_update_direct, stdout_purity, rmcp_serve_direct, both `explore`
 CLI tests, prompt_hook, catch_up;
 `codegraph-daemon` rmcp_tools_call/async_model; `codegraph-bench` (golden oracle,
 byte-stability) all pass. No plan-level architecture change was required.
+
+## Batch M — path-authority correction: close the transitional bypass (2026-07-25)
+
+### Why this follow-up exists
+
+Manual verification of the prior two commits (`b5a66f2` + `8aeefc4`) REJECTED
+the transitional `current_root_lenient`/`current_db_lenient` bypass: for a
+configured `CODEGRAPH_DIR` those helpers did a raw `project.join(value)`
+simple-join, bypassing `IndexPaths::resolve`'s physical identity, alias
+validation, legacy disjointness, and the identity-suffixed sibling. That let
+`CODEGRAPH_DIR=.` select the project root and write `<project>/codegraph.db`,
+directly contradicting the frozen configured-root contract (plan lines 246-287,
+330-338). The earlier ledger's implication that the configured-root override was
+merely "deferred" was wrong; this commit CLOSES the bypass. Four correctness
+defects are fixed together.
+
+### Fixes
+
+1. **Production data plane now consumes fail-closed `IndexPaths::resolve`.**
+   Deleted `current_root_lenient`/`current_db_lenient`. CLI `codegraph_dir`/
+   `db_path` (main.rs) are now `Result`-returning wrappers over a new
+   `index_paths()` = `IndexPaths::resolve(project, CODEGRAPH_DIR)`; every
+   mutating/opening call site threads `?`. `codegraph-mcp`
+   `CodeGraphEngine::open` resolves fail-closed before `Store::open`.
+   `codegraph-watch` `default_db_path` returns `Result` and resolves fail-closed.
+   Consequently `CODEGRAPH_DIR=.`/`..`/root/overlap/symlink alias errors BEFORE
+   any root/DB creation and never mutates the legacy namespace; a configured
+   relative or absolute root gets the identity-suffixed sibling
+   `<name>-v2-<projectIdentity>` through the REAL CLI and MCP paths, and two
+   projects sharing one configured root get distinct roots. New black-box CLI
+   regressions in `batch_m_v2_namespace.rs` prove all three via `init` +
+   `status --json` on-disk placement.
+   - Deliberate non-fail-closed exceptions, both existence-probes that must stay
+     infallible and cannot open a wrong DB: CLI `is_initialized` (a `resolve`
+     failure ⇒ "not initialized", so discovery keeps walking; the mutating paths
+     re-resolve fail-closed before touching disk) and `status` (reports the safe
+     `.codegraph-v2` default when a configured root is unresolvable, so status
+     still answers). `codegraph-mcp` `roots::db_path_for` is likewise an
+     `is_file()` probe: on a `resolve` failure it degrades to the default whose
+     file simply won't exist, NEVER a reconstructed configured-root path that
+     could shadow another project — the authoritative rejection is in
+     `CodeGraphEngine::open`.
+
+2. **Scanner excludes only the EXACT resolved physical root set.** Deleted the
+   over-broad `is_reserved_index_dir(name.starts_with(".codegraph-"))`. New
+   `IndexPaths::reserved_child_dir_names(project, CODEGRAPH_DIR)` returns the
+   exact child-directory names of the resolved fixed/configured legacy roots and
+   current root (always including `.codegraph`); `scan_dir` excludes those names
+   ONLY as direct children of the project root. A user `.codegraph-sources/`
+   directory is now indexed; `.codegraph` and the resolved `.codegraph-v2` are
+   excluded. Proven by `scan_keeps_user_codegraph_prefixed_dir_but_excludes_reserved_roots`.
+
+3. **Windows reparse-point detection.** `is_symlink` now also checks the raw
+   `FILE_ATTRIBUTE_REPARSE_POINT` attribute bit under `cfg(windows)` (directory
+   junctions are not caught by `FileType::is_symlink`). Verified compilable via
+   `cargo check -p codegraph-core --target x86_64-pc-windows-msvc --all-targets
+--locked` (both windows targets are installed on this host; this is a
+   cross-compile check, NOT native Windows runtime validation).
+
+4. **FFI last-error ordering.** In the Windows `GetFileInformationByHandleEx`
+   path the query's `std::io::Error::last_os_error()` is now captured BEFORE
+   `CloseHandle`, which itself sets the thread-local last-error and would
+   otherwise mask the real failure diagnostic.
+
+5. **Removed the `state_slot(usize)` modulo alias.** It documented "clamp" but
+   implemented `is_multiple_of(2)` parity, silently aliasing `state_slot(2)` to
+   slot 0. It is not needed by this slice; `state_slots() -> [PathBuf; 2]` is the
+   exact contract. Dropped the API and its test.
+
+Also fixed a consequential parent-dir bug surfaced by moving init off
+`.codegraph`: the detached daemon's `log_target` (parent-side, pre-spawn) now
+creates the `.codegraph` rendezvous parent before opening `daemon.log`, since
+the current index namespace is the sibling `.codegraph-v2` and `.codegraph` may
+not exist yet (the child's lock layer creates it, but too late for the parent's
+stdout/stderr redirect). Daemon rendezvous stays under `.codegraph` by design.
+
+### Correction to the prior ledger entry
+
+The previous entry's "Remaining Batch M path consumers" bullet claiming the data
+plane "uses `current_root_lenient` (simple join for a configured `CODEGRAPH_DIR`)
+in this slice" is SUPERSEDED: that bypass is deleted. The data plane now honors
+the configured-root fail-closed contract in full. Still legitimately unchanged
+(NOT the DB data plane): daemon rendezvous paths, `Config::discover`,
+`ext_config`/`godot_dsl_config` ancestor `codegraph.json` walk, and the
+`codegraph-bench` legacy oracle — these remain later Batch M tasks.
+
+### Verification
+
+`bash scripts/check-workspace-versions.sh` (OK, lock `750ee84b…` unchanged);
+`cargo check --workspace --all-targets --locked` clean;
+`cargo check -p codegraph-core --target x86_64-pc-windows-msvc --all-targets --locked` clean;
+`cargo clippy` across all touched crates `-D warnings` clean;
+`cargo fmt --all --check` clean; `bash scripts/guardrail.sh` exit 0;
+`cargo test --workspace --locked` — 0 failures (incl. the preserved initial
+black-box Red, the new configured-root + `.` alias + scanner regressions, and
+`codegraph-bench` golden byte-stability). No plan-level architecture change was
+required.

From 76522670112d79ceb2289eeb5d91be36acfccc20 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 12:36:40 +0800
Subject: [PATCH 09/91] fix(index): close IndexPaths path-authority
 verification defects

---
 crates/codegraph-cli/src/main.rs              |  20 +-
 .../tests/batch_m_v2_namespace.rs             | 126 ++++++++++++
 crates/codegraph-core/src/index_paths.rs      | 192 +++++++++++++-----
 crates/codegraph-extract/src/engine.rs        |  56 ++++-
 crates/codegraph-mcp/src/rmcp_handler.rs      |  24 ++-
 crates/codegraph-mcp/src/roots.rs             |  98 ++++++---
 crates/codegraph-mcp/src/server.rs            |  26 ++-
 .../tests/mcp_configured_root.rs              | 180 ++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  87 ++++++++
 9 files changed, 689 insertions(+), 120 deletions(-)
 create mode 100644 crates/codegraph-mcp/tests/mcp_configured_root.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index cf99df7..f270734 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1235,18 +1235,14 @@ fn cmd_sync(path: Option<PathBuf>, quiet: bool) -> Result<()> {
 fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
     let project = resolve_project_path_optional(&start);
-    // Status inspects an existing project; a resolvable index root reports its
-    // real paths, an unresolvable/aliased configured root reports the safe
-    // default so status still answers instead of erroring.
-    let resolved = index_paths(&project).ok();
-    let index_root = resolved
-        .as_ref()
-        .map(|p| p.current_root().to_path_buf())
-        .unwrap_or_else(|| project.join(".codegraph-v2"));
-    let db = resolved
-        .as_ref()
-        .map(|p| p.current_db())
-        .unwrap_or_else(|| index_root.join("codegraph.db"));
+    // Fail closed on an unsafe/aliased/overlapping configured root: status must
+    // surface the stable diagnostic, NOT mask an invalid `CODEGRAPH_DIR` as a
+    // default `.codegraph-v2` layout (which would report a bogus "not
+    // initialized"). A genuinely absent index still resolves fine and reports
+    // uninitialized below.
+    let resolved = index_paths(&project)?;
+    let index_root = resolved.current_root().to_path_buf();
+    let db = resolved.current_db();
     let db_exists = db.is_file();
     let daemon_running = daemon_already_running(&project);
     let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project);
diff --git a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
index 18d508b..26d6ea8 100644
--- a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
+++ b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
@@ -312,3 +312,129 @@ fn configured_dot_alias_fails_closed_without_mutation_via_cli() {
         "a `.` alias must not mutate the legacy namespace"
     );
 }
+
+/// Recursively snapshot every file path + byte length under `root`, sorted, so a
+/// command can be proven byte-nonmutating by comparing the before/after set.
+fn tree_snapshot(root: &Path) -> Vec<(String, u64)> {
+    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, u64)>) {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return;
+        };
+        for entry in entries.filter_map(Result::ok) {
+            let path = entry.path();
+            let meta = match entry.metadata() {
+                Ok(m) => m,
+                Err(_) => continue,
+            };
+            if meta.is_dir() {
+                walk(&path, base, out);
+            } else {
+                let rel = path
+                    .strip_prefix(base)
+                    .unwrap_or(&path)
+                    .to_string_lossy()
+                    .into_owned();
+                out.push((rel, meta.len()));
+            }
+        }
+    }
+    let mut out = Vec::new();
+    walk(root, root, &mut out);
+    out.sort();
+    out
+}
+
+/// `status` under an invalid/aliasing `CODEGRAPH_DIR` must FAIL CLOSED through
+/// the REAL CLI — surfacing the stable diagnostic instead of masking the bad
+/// configuration behind a default `.codegraph-v2` "not initialized" report — and
+/// must leave the project tree byte-for-byte unchanged (a read command never
+/// mutates). This is the CLI-side proof of the status fail-closed correction.
+#[test]
+fn status_fails_closed_on_invalid_configured_root_without_mutation_via_cli() {
+    let dir = TestDir::new("status-invalid");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    let before = tree_snapshot(&project);
+
+    for json in [false, true] {
+        let mut args = vec!["status"];
+        if json {
+            args.push("--json");
+        }
+        args.push(p);
+        let run = run_in_env(dir.path(), &args, &[("CODEGRAPH_DIR", ".")]);
+        assert!(
+            !run.ok,
+            "status (json={json}) with CODEGRAPH_DIR=. must fail closed, not report a \
+             default layout: stdout={} stderr={}",
+            run.stdout, run.stderr
+        );
+        assert!(
+            !run.stdout.contains(".codegraph-v2"),
+            "status must NOT mask an invalid configured root as a `.codegraph-v2` \
+             default: stdout={}",
+            run.stdout
+        );
+    }
+
+    let after = tree_snapshot(&project);
+    assert_eq!(
+        before, after,
+        "a fail-closed `status` must leave the project tree byte-for-byte unchanged"
+    );
+}
+
+/// An escaping relative `CODEGRAPH_DIR` (`../shared/cg`) is a VALID configured
+/// root that escapes the project; two sibling projects given the same escaping
+/// value must each `init` into their own identity-suffixed sibling under the
+/// shared external parent, never a single shared simple-join DB — the REAL-CLI
+/// counterpart of the absolute-root isolation case.
+#[test]
+fn two_projects_sharing_escaping_relative_root_get_distinct_roots_via_cli() {
+    let dir = TestDir::new("cfg-escape");
+    let base = dir.path();
+    let project_a = base.join("a");
+    let project_b = base.join("b");
+    copy_tree(&mini_fixture(), &project_a);
+    copy_tree(&mini_fixture(), &project_b);
+    std::fs::create_dir_all(base.join("shared")).unwrap();
+
+    for project in [&project_a, &project_b] {
+        let run = run_in_env(
+            base,
+            &["init", project.to_str().unwrap()],
+            &[("CODEGRAPH_DIR", "../shared/cg")],
+        );
+        assert!(
+            run.ok,
+            "init with escaping CODEGRAPH_DIR must succeed for {}: {} {}",
+            project.display(),
+            run.stdout,
+            run.stderr
+        );
+    }
+
+    let shared_parent = base.join("shared");
+    let siblings: Vec<String> = std::fs::read_dir(&shared_parent)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .map(|e| e.file_name().to_string_lossy().into_owned())
+        .filter(|n| n.starts_with("cg-v2-"))
+        .collect();
+    assert_eq!(
+        siblings.len(),
+        2,
+        "two projects sharing an escaping relative root must produce two distinct \
+         identity siblings, got {siblings:?}"
+    );
+    assert_ne!(
+        siblings[0], siblings[1],
+        "the two current roots must differ"
+    );
+    assert!(
+        !shared_parent.join("cg").join("codegraph.db").is_file(),
+        "the escaping simple-join `shared/cg/codegraph.db` must never exist"
+    );
+}
diff --git a/crates/codegraph-core/src/index_paths.rs b/crates/codegraph-core/src/index_paths.rs
index 9118d5e..ac06bad 100644
--- a/crates/codegraph-core/src/index_paths.rs
+++ b/crates/codegraph-core/src/index_paths.rs
@@ -42,7 +42,7 @@ use thiserror::Error;
 /// Default current-root directory name (no `CODEGRAPH_DIR`): a sibling of the
 /// fixed legacy `.codegraph` root. This is the ONE place the `.codegraph-v2`
 /// literal is defined; every production consumer derives its default root from
-/// here (directly or via [`IndexPaths::current_root_lenient`]).
+/// [`IndexPaths::resolve`].
 pub const DEFAULT_CURRENT_DIR: &str = ".codegraph-v2";
 /// Fixed legacy root directory name used by old daemon/watch/MCP paths.
 pub const LEGACY_DIR: &str = ".codegraph";
@@ -209,39 +209,47 @@ impl IndexPaths {
         })
     }
 
-    /// Exact reserved index-root child-directory names the scanner/watcher must
-    /// exclude for `project`: the resolved physical root set (fixed + configured
-    /// legacy roots and the current root) reduced to basenames that are direct
-    /// children of the canonical project, always including the fixed
-    /// `.codegraph`. Exact names only — never a `.codegraph-*` prefix, so a user
-    /// `.codegraph-sources` stays scannable. On a `resolve` failure it degrades
-    /// to the safe fixed-legacy + default-current names rather than
-    /// reconstructing a configured-root path; the fail-closed DB contract is
-    /// enforced separately at the CLI/MCP/watch boundary by [`IndexPaths::resolve`].
-    pub fn reserved_child_dir_names(
+    /// The EXACT resolved physical index-root PATHS the scanner/watcher must
+    /// exclude before descending: every fixed/configured legacy root plus the
+    /// current root, as full normalized paths (not basenames). The scanner
+    /// compares each candidate directory path against this set, so a nested
+    /// configured root such as `<project>/cache/index` is excluded at its true
+    /// depth while an unrelated directory that merely shares a basename is not.
+    ///
+    /// In-project roots are re-anchored onto the caller's `project` spelling
+    /// (`resolve` canonicalizes) so scanner candidates compare directly; roots
+    /// outside the project keep their absolute form. Always includes the fixed
+    /// `<project>/.codegraph`. On a `resolve` failure it degrades to just the two
+    /// safe default paths (fixed `.codegraph` and the default `.codegraph-v2`)
+    /// rather than reconstructing a configured-root path; the fail-closed DB
+    /// contract is enforced separately at the CLI/MCP/watch boundary by
+    /// [`IndexPaths::resolve`].
+    pub fn reserved_index_roots(
         project: &Path,
         codegraph_dir: Option<&str>,
-    ) -> std::collections::BTreeSet<String> {
-        let mut names = std::collections::BTreeSet::new();
-        names.insert(LEGACY_DIR.to_string());
+    ) -> std::collections::BTreeSet<PathBuf> {
+        let mut roots = std::collections::BTreeSet::new();
         match Self::resolve(project, codegraph_dir) {
             Ok(paths) => {
-                let canonical_project = paths.project();
-                let mut roots = paths.legacy_roots().to_vec();
-                roots.push(paths.current_root().to_path_buf());
-                for root in roots {
-                    if root.parent() == Some(canonical_project)
-                        && let Some(name) = root.file_name()
-                    {
-                        names.insert(name.to_string_lossy().into_owned());
+                let canonical = paths.project();
+                let reanchor = |root: &Path| -> PathBuf {
+                    match root.strip_prefix(canonical) {
+                        Ok(rel) => project.join(rel),
+                        Err(_) => root.to_path_buf(),
                     }
+                };
+                roots.insert(project.join(LEGACY_DIR));
+                for legacy in paths.legacy_roots() {
+                    roots.insert(reanchor(legacy));
                 }
+                roots.insert(reanchor(paths.current_root()));
             }
             Err(_) => {
-                names.insert(DEFAULT_CURRENT_DIR.to_string());
+                roots.insert(project.join(LEGACY_DIR));
+                roots.insert(project.join(DEFAULT_CURRENT_DIR));
             }
         }
-        names
+        roots
     }
 
     /// Canonical project root.
@@ -442,10 +450,17 @@ fn physical_normalize(project: &Path, target: &Path) -> Result<PathBuf, IndexPat
     }
 
     // Target outside the project (an absolute CODEGRAPH_DIR or its sibling):
-    // reject an existing root that is itself a symlink alias, then anchor on the
-    // canonicalized nearest-existing ancestor.
-    if is_symlink(&existing) {
-        return Err(IndexPathsError::SymlinkComponent { path: existing });
+    // reject an alias in ANY existing component, not just the last one.
+    // `<base>/link/child` where `link` is a symlink/junction reaches an ordinary
+    // `child` directory through the alias, so checking only `existing` would
+    // silently follow it. Walk every prefix from the filesystem root down to
+    // `existing` and reject the first symlink/reparse component.
+    let mut probe = PathBuf::new();
+    for component in existing.components() {
+        probe.push(component);
+        if is_symlink(&probe) {
+            return Err(IndexPathsError::SymlinkComponent { path: probe });
+        }
     }
     let base = existing
         .canonicalize()
@@ -885,6 +900,32 @@ mod tests {
         let _ = std::fs::remove_dir_all(&project);
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn rejects_in_project_root_reached_through_intermediate_symlink() {
+        use std::os::unix::fs::symlink;
+
+        // In-project spelling of the intermediate-alias case: `<project>/link`
+        // is a symlink to `<project>/real`, so `<project>/link/child` EXISTS as
+        // an ordinary directory reached THROUGH the alias. A relative
+        // `CODEGRAPH_DIR=link/child/cg` must fail closed on the `link` component
+        // even though the nearest existing ancestor (`.../child`) is ordinary.
+        let project = temp_dir("symlink-inproj-mid");
+        let real = project.join("real");
+        std::fs::create_dir_all(real.join("child")).unwrap();
+        let link = project.join("link");
+        symlink(&real, &link).unwrap();
+
+        let err = IndexPaths::resolve(&project, Some("link/child/cg"))
+            .expect_err("in-project intermediate symlink must fail closed");
+        assert!(
+            matches!(err, IndexPathsError::SymlinkComponent { .. }),
+            "{err:?}"
+        );
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
     #[cfg(unix)]
     #[test]
     fn rejects_symlinked_absolute_configured_root() {
@@ -909,6 +950,35 @@ mod tests {
         let _ = std::fs::remove_dir_all(&cache);
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn rejects_external_configured_root_reached_through_intermediate_symlink() {
+        use std::os::unix::fs::symlink;
+
+        // `<cache>/link` is a symlink to `<cache>/real`; `<cache>/link/child`
+        // therefore EXISTS as an ordinary directory reached through the alias.
+        // An absolute CODEGRAPH_DIR of `<cache>/link/child/cg` must fail closed
+        // even though its nearest existing ancestor (`.../child`) is itself an
+        // ordinary directory — the intermediate `link` component is the alias.
+        let project = temp_dir("symlink-mid-proj");
+        let cache = temp_dir("symlink-mid-cache");
+        let real = cache.join("real");
+        std::fs::create_dir_all(real.join("child")).unwrap();
+        let link = cache.join("link");
+        symlink(&real, &link).unwrap();
+
+        let configured = link.join("child").join("cg");
+        let err = IndexPaths::resolve(&project, Some(configured.to_str().unwrap()))
+            .expect_err("intermediate symlink component must fail closed");
+        assert!(
+            matches!(err, IndexPathsError::SymlinkComponent { .. }),
+            "{err:?}"
+        );
+
+        let _ = std::fs::remove_dir_all(&project);
+        let _ = std::fs::remove_dir_all(&cache);
+    }
+
     #[test]
     fn rejects_current_root_overlapping_legacy_root() {
         // A configured root whose derived sibling would nest under the fixed
@@ -948,43 +1018,69 @@ mod tests {
     }
 
     #[test]
-    fn reserved_child_names_default_are_exactly_legacy_and_v2() {
+    fn reserved_roots_default_are_exactly_legacy_and_v2_paths() {
         let project = temp_dir("reserved-default");
-        let names = IndexPaths::reserved_child_dir_names(&project, None);
-        assert!(names.contains(".codegraph"));
-        assert!(names.contains(".codegraph-v2"));
-        // A user source directory sharing the `.codegraph-` prefix is NOT
-        // reserved and must remain scannable.
-        assert!(!names.contains(".codegraph-sources"));
+        let roots = IndexPaths::reserved_index_roots(&project, None);
+        assert!(roots.contains(&project.join(".codegraph")));
+        assert!(roots.contains(&project.join(".codegraph-v2")));
+        // A user source directory sharing the `.codegraph-` prefix is NOT a
+        // reserved root and must remain scannable.
+        assert!(!roots.contains(&project.join(".codegraph-sources")));
         let _ = std::fs::remove_dir_all(&project);
     }
 
     #[test]
-    fn reserved_child_names_include_relative_configured_sibling() {
+    fn reserved_roots_include_relative_configured_sibling_as_full_path() {
         let project = temp_dir("reserved-configured");
-        let names = IndexPaths::reserved_child_dir_names(&project, Some("cache"));
+        let roots = IndexPaths::reserved_index_roots(&project, Some("cache"));
         let identity = IndexPaths::resolve(&project, Some("cache"))
             .unwrap()
             .project_identity()
             .to_string();
-        assert!(names.contains(".codegraph"), "{names:?}");
-        assert!(names.contains("cache"), "configured legacy root: {names:?}");
+        assert!(roots.contains(&project.join(".codegraph")), "{roots:?}");
+        assert!(
+            roots.contains(&project.join("cache")),
+            "configured legacy root: {roots:?}"
+        );
+        assert!(
+            roots.contains(&project.join(format!("cache-v2-{identity}"))),
+            "configured current sibling: {roots:?}"
+        );
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn reserved_roots_include_nested_configured_roots_at_true_depth() {
+        // A nested `CODEGRAPH_DIR=cache/index` puts the legacy root at
+        // `<project>/cache/index` and the current root at
+        // `<project>/cache/index-v2-<identity>`; both must be reserved as their
+        // full nested paths, so the scanner prunes them at depth rather than
+        // descending into and indexing the index's own storage.
+        let project = temp_dir("reserved-nested");
+        let roots = IndexPaths::reserved_index_roots(&project, Some("cache/index"));
+        let identity = IndexPaths::resolve(&project, Some("cache/index"))
+            .unwrap()
+            .project_identity()
+            .to_string();
+        assert!(
+            roots.contains(&project.join("cache").join("index")),
+            "nested configured legacy root: {roots:?}"
+        );
         assert!(
-            names.contains(&format!("cache-v2-{identity}")),
-            "configured current sibling: {names:?}"
+            roots.contains(&project.join("cache").join(format!("index-v2-{identity}"))),
+            "nested configured current sibling: {roots:?}"
         );
-        assert!(!names.contains(".codegraph-sources"));
         let _ = std::fs::remove_dir_all(&project);
     }
 
     #[test]
-    fn reserved_child_names_degrade_to_defaults_on_invalid_configured_root() {
+    fn reserved_roots_degrade_to_default_paths_on_invalid_configured_root() {
         let project = temp_dir("reserved-invalid");
-        // `.` resolves to the project root itself — an invalid alias. Name
-        // derivation must degrade to the safe defaults, never error.
-        let names = IndexPaths::reserved_child_dir_names(&project, Some("."));
-        assert!(names.contains(".codegraph"));
-        assert!(names.contains(".codegraph-v2"));
+        // `.` resolves to the project root itself — an invalid alias. Root
+        // derivation degrades to the safe default paths, never errors.
+        let roots = IndexPaths::reserved_index_roots(&project, Some("."));
+        assert!(roots.contains(&project.join(".codegraph")));
+        assert!(roots.contains(&project.join(".codegraph-v2")));
         let _ = std::fs::remove_dir_all(&project);
     }
 }
diff --git a/crates/codegraph-extract/src/engine.rs b/crates/codegraph-extract/src/engine.rs
index c40ed27..7961451 100644
--- a/crates/codegraph-extract/src/engine.rs
+++ b/crates/codegraph-extract/src/engine.rs
@@ -301,11 +301,13 @@ pub fn scan_project(root: &Path, options: &ExtractOptions) -> Result<Vec<String>
     // later `!pattern` negation re-includes a path an earlier set excluded.
     let pattern_sets: Vec<&[String]> = vec![&options.ignore_paths, &options.exclude, &gitignore];
     let include = IncludeSet::new(&options.include, &options.exclude);
-    // The exact reserved index-root child names for THIS project (fixed legacy
-    // `.codegraph`, the configured legacy root, and the resolved current root),
-    // resolved once so scan_dir excludes only those directories — never an
-    // arbitrary `.codegraph-*`-prefixed user directory.
-    let reserved_roots = codegraph_core::IndexPaths::reserved_child_dir_names(
+    // The EXACT resolved reserved index-root PATHS for THIS project (fixed
+    // legacy `.codegraph`, the configured legacy root, and the resolved current
+    // root — including nested configured roots at their true depth), resolved
+    // once. scan_dir prunes a directory iff its FULL path equals one of these,
+    // never by basename, so a user `.codegraph-sources/` stays scannable and an
+    // unrelated same-basename directory is never mis-excluded.
+    let reserved_roots = codegraph_core::IndexPaths::reserved_index_roots(
         root,
         std::env::var("CODEGRAPH_DIR").ok().as_deref(),
     );
@@ -326,7 +328,7 @@ fn scan_dir(
     root: &Path,
     dir: &Path,
     ignored_dirs: &HashSet<&str>,
-    reserved_roots: &std::collections::BTreeSet<String>,
+    reserved_roots: &std::collections::BTreeSet<PathBuf>,
     pattern_sets: &[&[String]],
     include: &IncludeSet,
     files: &mut Vec<String>,
@@ -337,12 +339,12 @@ fn scan_dir(
         let path = entry.path();
         let name = entry.file_name();
         let name = name.to_string_lossy();
-        // Skip `.git` and the exact reserved index roots (fixed/configured legacy
-        // + resolved current) — but ONLY when they are direct children of the
-        // project root, so a `.codegraph`-named directory deeper in the tree is
-        // still governed by the normal ignore rules, not this exclusion.
+        // Skip `.git` (a direct child of the scan root) and any directory whose
+        // FULL path is a resolved reserved index root — matched at any depth, so
+        // a nested configured root like `<root>/cache/index` is pruned exactly,
+        // while a same-basename user directory elsewhere is not.
         let is_reserved_root_here =
-            dir == root && (name == ".git" || reserved_roots.contains(name.as_ref()));
+            (dir == root && name == ".git") || reserved_roots.contains(&path);
         if is_reserved_root_here || ignored_dirs.contains(name.as_ref()) {
             continue;
         }
@@ -655,6 +657,38 @@ mod tests {
         fs::remove_dir_all(&project).ok();
     }
 
+    /// Exclusion is by EXACT resolved root PATH, not basename: a directory that
+    /// merely SHARES the reserved basename but lives at a different path (nested
+    /// under a source subtree) is NOT a resolved root and stays scannable.
+    #[test]
+    fn scan_excludes_only_top_level_root_paths_not_same_named_nested_dirs() {
+        let project = unique_project("reserved_nested");
+        // A `.ts` under the real top-level reserved current root is excluded…
+        touch(&project, ".codegraph-v2/inner.ts", "export const r = 0;");
+        // …but a `.codegraph-v2`-named directory NESTED under `src/` is a user
+        // path (not the resolved current root) and must be indexed.
+        touch(
+            &project,
+            "src/.codegraph-v2/nested.ts",
+            "export const a = 1;",
+        );
+        touch(&project, "src/app.ts", "export const b = 2;");
+
+        let files = scan_project(&project, &ExtractOptions::default()).expect("scan project");
+
+        assert!(
+            files.contains(&"src/.codegraph-v2/nested.ts".to_string()),
+            "a same-basename dir nested off the root is NOT the reserved root: {files:?}"
+        );
+        assert!(files.contains(&"src/app.ts".to_string()), "{files:?}");
+        assert!(
+            !files.iter().any(|f| f.starts_with(".codegraph-v2/")),
+            "the top-level `.codegraph-v2` root is still excluded: {files:?}"
+        );
+
+        fs::remove_dir_all(&project).ok();
+    }
+
     /// A real directory scan of a Godot project skips the regenerated `.godot/`
     /// engine cache and the vendored `addons/` plugin tree while still finding
     /// first-party `.gd` business code.
diff --git a/crates/codegraph-mcp/src/rmcp_handler.rs b/crates/codegraph-mcp/src/rmcp_handler.rs
index 851fe34..c0ac111 100644
--- a/crates/codegraph-mcp/src/rmcp_handler.rs
+++ b/crates/codegraph-mcp/src/rmcp_handler.rs
@@ -40,7 +40,7 @@ use serde_json::{Value, json};
 use crate::engine::CodeGraphEngine;
 use crate::instructions::SERVER_INSTRUCTIONS;
 use crate::protocol::ToolResult;
-use crate::roots::{WorkspaceRoots, db_path_for};
+use crate::roots::{WorkspaceRoots, db_exists_for, db_path_for};
 use crate::schemas;
 
 const SERVER_NAME: &str = "codegraph";
@@ -178,7 +178,7 @@ impl CodeGraphHandler {
     fn has_default_codegraph(&self) -> bool {
         self.default_project_snapshot()
             .as_ref()
-            .is_some_and(|p| db_path_for(p).is_file())
+            .is_some_and(|p| db_exists_for(p))
     }
 
     /// Resolve a caller's `projectPath` to an INDEXED project dir, byte-for-byte
@@ -188,7 +188,7 @@ impl CodeGraphHandler {
     fn resolve_project_arg(&self, raw: Option<&str>) -> Option<PathBuf> {
         let default_project = self.default_project_snapshot();
         let Some(raw) = raw else {
-            return default_project.filter(|p| db_path_for(p).is_file());
+            return default_project.filter(|p| db_exists_for(p));
         };
         let raw_path = PathBuf::from(raw);
         let mut candidates: Vec<PathBuf> = Vec::new();
@@ -207,7 +207,7 @@ impl CodeGraphHandler {
         }
         candidates
             .into_iter()
-            .find(|candidate| db_path_for(candidate).is_file())
+            .find(|candidate| db_exists_for(candidate))
     }
 
     /// Adopt an indexed client workspace root when the current default is
@@ -629,11 +629,15 @@ pub fn serve_http(
         match &default_project {
             Some(project) => {
                 let db = db_path_for(project);
+                let db_display = db
+                    .as_ref()
+                    .map(|d| d.display().to_string())
+                    .unwrap_or_else(|| "(invalid CODEGRAPH_DIR)".to_string());
                 tracing::info!(
                     %addr,
                     project = %project.display(),
-                    db = %db.display(),
-                    db_exists = db.is_file(),
+                    db = %db_display,
+                    db_exists = db.as_ref().is_some_and(|d| d.is_file()),
                     "streamable-HTTP serving on http://{addr}/mcp"
                 );
             }
@@ -855,11 +859,11 @@ mod handler_tests {
         TempDir { path }
     }
 
-    /// Write a placeholder (non-SQLite) db file so `db_path_for(p).is_file()` is
-    /// true — resolution treats the dir as indexed, but a real engine open fails.
+    /// Write a placeholder (non-SQLite) db file so `db_exists_for(p)` is true —
+    /// resolution treats the dir as indexed, but a real engine open fails.
     fn placeholder_indexed(tag: &str) -> TempDir {
         let dir = unique_dir(tag);
-        let db = db_path_for(&dir.path);
+        let db = db_path_for(&dir.path).expect("default project resolves");
         std::fs::create_dir_all(db.parent().unwrap()).unwrap();
         std::fs::write(&db, b"not a real sqlite db").unwrap();
         dir
@@ -1162,7 +1166,7 @@ mod handler_tests {
     /// + `engine.execute` success arm of `execute_owned`.
     fn real_indexed_project(tag: &str) -> TempDir {
         let dir = unique_dir(tag);
-        let db = db_path_for(&dir.path);
+        let db = db_path_for(&dir.path).expect("default project resolves");
         std::fs::create_dir_all(db.parent().unwrap()).unwrap();
         let root = workspace_root();
         std::fs::copy(root.join("reference/golden/mini/colby.db"), &db).unwrap();
diff --git a/crates/codegraph-mcp/src/roots.rs b/crates/codegraph-mcp/src/roots.rs
index 0cc241c..ed35975 100644
--- a/crates/codegraph-mcp/src/roots.rs
+++ b/crates/codegraph-mcp/src/roots.rs
@@ -16,14 +16,14 @@ pub fn format_tool_debug_line(
     default_project: Option<&Path>,
 ) -> String {
     let raw = raw_project.unwrap_or("(none)");
-    let (resolved_str, db_str, db_exists) = match resolved {
-        Some(p) => {
-            let db = db_path_for(p);
-            let exists = db.is_file();
-            (p.display().to_string(), db.display().to_string(), exists)
-        }
-        None => ("(unresolved)".to_string(), "(none)".to_string(), false),
-    };
+    let (resolved_str, db_str, db_exists) =
+        match resolved.and_then(|p| db_path_for(p).map(|db| (p, db))) {
+            Some((p, db)) => {
+                let exists = db.is_file();
+                (p.display().to_string(), db.display().to_string(), exists)
+            }
+            None => ("(unresolved)".to_string(), "(none)".to_string(), false),
+        };
     let cwd_str = cwd.map_or_else(|| "(none)".to_string(), |p| p.display().to_string());
     let default_str =
         default_project.map_or_else(|| "(none)".to_string(), |p| p.display().to_string());
@@ -34,21 +34,25 @@ pub fn format_tool_debug_line(
 
 /// The current (v2) index DB path under a project root, resolved fail-closed
 /// through the single `codegraph-core::IndexPaths` authority so it agrees with
-/// [`crate::CodeGraphEngine::open`]. This is an EXISTENCE-probe helper (callers
-/// do `db_path_for(p).is_file()`), so an unsafe/aliased configured root degrades
-/// to the safe `.codegraph-v2` default whose file simply will not exist — it
-/// NEVER reconstructs a configured-root path that could shadow another project.
-/// The authoritative fail-closed rejection happens in `CodeGraphEngine::open`.
-pub fn db_path_for(project_path: &Path) -> PathBuf {
-    match codegraph_core::IndexPaths::resolve(
+/// [`crate::CodeGraphEngine::open`]. Returns `None` when the configured root is
+/// unsafe/aliased/overlapping (a `resolve` failure): callers treat that as "not
+/// an indexed project", which is DISTINCT from a reconstructed default path that
+/// could shadow another project. The authoritative fail-closed error is surfaced
+/// by `CodeGraphEngine::open` when a tool actually runs.
+pub fn db_path_for(project_path: &Path) -> Option<PathBuf> {
+    codegraph_core::IndexPaths::resolve(
         project_path,
         std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-    ) {
-        Ok(paths) => paths.current_db(),
-        Err(_) => project_path
-            .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
-            .join("codegraph.db"),
-    }
+    )
+    .ok()
+    .map(|paths| paths.current_db())
+}
+
+/// Whether `project_path` resolves to an existing current-namespace index DB.
+/// `false` for both an unresolvable configured root and a resolvable-but-absent
+/// index — the shared adoption/probe predicate.
+pub fn db_exists_for(project_path: &Path) -> bool {
+    db_path_for(project_path).is_some_and(|db| db.is_file())
 }
 
 pub struct WorkspaceRoots {
@@ -157,7 +161,7 @@ fn adopt_path(
     if !default_is_adoptable(default_project.as_ref(), cwd) {
         return None;
     }
-    if db_path_for(&path).is_file() {
+    if db_exists_for(&path) {
         let adopted = path.clone();
         *default_project = Some(path);
         return Some(adopted);
@@ -184,7 +188,7 @@ fn default_is_adoptable(default_project: Option<&PathBuf>, cwd: Option<&Path>) -
     let (Some(current), Some(cwd)) = (default_project, cwd) else {
         return false;
     };
-    !db_path_for(current).is_file() && canonicalize_lenient(current) == canonicalize_lenient(cwd)
+    !db_exists_for(current) && canonicalize_lenient(current) == canonicalize_lenient(cwd)
 }
 
 fn file_uri_to_path(uri: &str) -> Option<PathBuf> {
@@ -260,7 +264,10 @@ mod tests {
         let seq = SEQ.fetch_add(1, Ordering::Relaxed);
         let path =
             std::env::temp_dir().join(format!("cg-mcp-roots-{tag}-{}-{seq}", std::process::id()));
-        let db = db_path_for(&path);
+        // The project dir must exist before `db_path_for` (which resolves the
+        // physical identity) can succeed.
+        std::fs::create_dir_all(&path).unwrap();
+        let db = db_path_for(&path).expect("default project resolves");
         std::fs::create_dir_all(db.parent().unwrap()).unwrap();
         std::fs::write(&db, b"placeholder").unwrap();
         TempProject { path }
@@ -453,7 +460,7 @@ mod tests {
         let expected = format!(
             "[codegraph debug] tool=codegraph_search projectPath_raw=codegraph-rust resolved={} db={} db_exists=true cwd=/tmp/cwd default_project=/tmp/default",
             project.path().display(),
-            db_path_for(project.path()).display(),
+            db_path_for(project.path()).unwrap().display(),
         );
         assert_eq!(line, expected);
     }
@@ -622,12 +629,43 @@ mod tests {
 
     #[test]
     fn db_path_for_honors_codegraph_dir_default() {
-        let p = Path::new("/proj");
-        let db = db_path_for(p);
+        // A real dir so `resolve` (which canonicalizes) succeeds; the default
+        // current DB is `<project>/.codegraph-v2/codegraph.db`.
+        let dir = std::env::temp_dir().join(format!(
+            "cg-roots-dbpath-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let db = db_path_for(&dir).expect("resolve default");
+        assert!(
+            db.ends_with(".codegraph-v2/codegraph.db"),
+            "default db is under .codegraph-v2: {}",
+            db.display()
+        );
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// A `resolve` failure (here a nonexistent project) must yield `None`, not a
+    /// reconstructed `.codegraph-v2` default that could shadow another project.
+    /// Race-free: it never mutates the process-global `CODEGRAPH_DIR`, unlike an
+    /// env-set test. The invalid-`CODEGRAPH_DIR` path is covered end-to-end by
+    /// the real CLI/MCP black-box regressions.
+    #[test]
+    fn db_path_for_returns_none_on_resolve_failure() {
+        let missing = std::env::temp_dir().join(format!(
+            "cg-roots-dbpath-missing-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        assert!(!missing.exists(), "sanity: the probe path must not exist");
+        assert!(
+            db_path_for(&missing).is_none(),
+            "a resolve failure must not resolve to a reconstructed default path"
+        );
         assert!(
-            db.ends_with("codegraph.db"),
-            "db path ends with codegraph.db"
+            !db_exists_for(&missing),
+            "db_exists_for must be false when resolution fails"
         );
-        assert!(db.starts_with("/proj"), "under the project root");
     }
 }
diff --git a/crates/codegraph-mcp/src/server.rs b/crates/codegraph-mcp/src/server.rs
index 7bbd3e4..edbb5cd 100644
--- a/crates/codegraph-mcp/src/server.rs
+++ b/crates/codegraph-mcp/src/server.rs
@@ -19,7 +19,8 @@ use crate::engine::CodeGraphEngine;
 use crate::instructions::SERVER_INSTRUCTIONS;
 use crate::protocol::{JsonRpcRequest, JsonRpcResponse, ToolResult, error_codes};
 use crate::roots::{
-    ROOTS_LIST_REQUEST_ID, WorkspaceRoots, db_path_for, format_tool_debug_line, roots_list_request,
+    ROOTS_LIST_REQUEST_ID, WorkspaceRoots, db_exists_for, db_path_for, format_tool_debug_line,
+    roots_list_request,
 };
 use crate::schemas;
 
@@ -221,7 +222,7 @@ impl McpServer {
         let Some(project) = &self.default_project else {
             return false;
         };
-        db_path_for(project).is_file()
+        db_exists_for(project)
     }
 
     /// Run the stdio loop until the broad-root daemon handoff adopts a project
@@ -502,10 +503,7 @@ impl McpServer {
     /// error, not mask itself behind the default.
     fn resolve_project_arg(&self, raw: Option<&str>) -> Option<PathBuf> {
         let Some(raw) = raw else {
-            return self
-                .default_project
-                .clone()
-                .filter(|p| db_path_for(p).is_file());
+            return self.default_project.clone().filter(|p| db_exists_for(p));
         };
 
         let raw_path = PathBuf::from(raw);
@@ -526,7 +524,7 @@ impl McpServer {
 
         candidates
             .into_iter()
-            .find(|candidate| db_path_for(candidate).is_file())
+            .find(|candidate| db_exists_for(candidate))
     }
 
     /// Open-on-demand + cache the engine for a project path
@@ -536,7 +534,14 @@ impl McpServer {
     /// one (inode/file-index changed). An in-place write keeps the same identity,
     /// so the common path returns the cached engine without reopening.
     fn engine_for(&mut self, project_path: &PathBuf) -> anyhow::Result<&CodeGraphEngine> {
-        let db_path = db_path_for(project_path);
+        // A resolvable configured root yields its DB path; an invalid one fails
+        // closed here (Engine::open re-resolves and surfaces the stable error).
+        let db_path = db_path_for(project_path).ok_or_else(|| {
+            anyhow::anyhow!(
+                "invalid CODEGRAPH_DIR configuration for project {}",
+                project_path.display()
+            )
+        })?;
         let current = DbIdentity::read(&db_path);
 
         let stale = match self.engines.get(project_path) {
@@ -677,7 +682,10 @@ mod tests {
         let seq = SEQ.fetch_add(1, Ordering::Relaxed);
         let path =
             std::env::temp_dir().join(format!("cg-mcp-init-{tag}-{}-{seq}", std::process::id()));
-        let db = db_path_for(&path);
+        // The project dir must exist before `db_path_for` (which resolves the
+        // physical identity) can succeed.
+        std::fs::create_dir_all(&path).unwrap();
+        let db = db_path_for(&path).expect("default project resolves");
         std::fs::create_dir_all(db.parent().unwrap()).unwrap();
         std::fs::write(&db, b"placeholder").unwrap();
         TempProject { path }
diff --git a/crates/codegraph-mcp/tests/mcp_configured_root.rs b/crates/codegraph-mcp/tests/mcp_configured_root.rs
new file mode 100644
index 0000000..7b39b51
--- /dev/null
+++ b/crates/codegraph-mcp/tests/mcp_configured_root.rs
@@ -0,0 +1,180 @@
+//! Real MCP public-surface regressions for a configured `CODEGRAPH_DIR`.
+//!
+//! Isolated in its OWN test binary (a separate process) because these tests set
+//! the process-global `CODEGRAPH_DIR`; keeping them out of `golden_mcp.rs` avoids
+//! racing that binary's env-sensitive default-surface readers. Each test drives
+//! the REAL `McpServer` over an in-memory stdio pipe and proves the MCP request
+//! path opens the SAME identity-suffixed DB the CLI `init` writes.
+
+use std::fs;
+use std::io::Cursor;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use codegraph_mcp::McpServer;
+use serde_json::{Value, json};
+
+static SEQ: AtomicU64 = AtomicU64::new(0);
+// Both tests mutate the PROCESS-GLOBAL `CODEGRAPH_DIR`; cargo runs a binary's
+// tests multi-threaded in ONE process, so they must serialize the set→read→
+// restore window against each other.
+static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .canonicalize()
+        .expect("workspace root")
+}
+
+struct TempDir {
+    path: PathBuf,
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+fn unique_dir(tag: &str) -> TempDir {
+    let path = std::env::temp_dir().join(format!(
+        "cg-mcp-cfgroot-{tag}-{}-{}",
+        std::process::id(),
+        SEQ.fetch_add(1, Ordering::Relaxed)
+    ));
+    fs::create_dir_all(&path).unwrap();
+    TempDir { path }
+}
+
+fn stage_mini_db_at(db: &Path, project: &Path) {
+    let root = workspace_root();
+    fs::create_dir_all(db.parent().unwrap()).unwrap();
+    fs::copy(root.join("reference/golden/mini/colby.db"), db).unwrap();
+    let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
+    for rel in ["src/app.ts", "src/math.ts"] {
+        let dst = project.join(rel);
+        fs::create_dir_all(dst.parent().unwrap()).unwrap();
+        fs::copy(fixtures.join(rel), &dst).unwrap();
+    }
+}
+
+fn tool_call_search(project: &Path, project_path_arg: &str) -> Value {
+    let request = json!({
+        "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+        "params": {
+            "name": "codegraph_search",
+            "arguments": { "query": "add", "projectPath": project_path_arg }
+        }
+    });
+    let frame = format!("{}\n", serde_json::to_string(&request).unwrap());
+    let mut output = Vec::new();
+    let mut server = McpServer::new(Some(project.to_path_buf()));
+    server
+        .run_until_adoption(Cursor::new(frame.into_bytes()), &mut output)
+        .expect("server run");
+    let text = String::from_utf8(output).expect("utf8");
+    let line = text.lines().next().expect("one response line");
+    serde_json::from_str(line).expect("response json")
+}
+
+/// A relative `CODEGRAPH_DIR` is honored through `resolve`'s identity-suffixed
+/// sibling: staging the golden DB at `<parent>/<name>-v2-<identity>/codegraph.db`
+/// (NOT the simple-join `<project>/<name>`) makes a real `tools/call` resolve and
+/// return results — proving the MCP path opens the DB the CLI init would write.
+#[test]
+fn configured_relative_root_mcp_opens_identity_sibling_db() {
+    let _env = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+    let dir = unique_dir("rel");
+    let base = &dir.path;
+
+    let prev = std::env::var_os("CODEGRAPH_DIR");
+    // SAFETY: this test binary runs single-threaded per test process; the env is
+    // set before any resolve/DB access and restored before returning.
+    unsafe { std::env::set_var("CODEGRAPH_DIR", "cache") };
+
+    let paths = codegraph_core::IndexPaths::resolve(base, Some("cache")).expect("resolve");
+    stage_mini_db_at(&paths.current_db(), base);
+    assert!(
+        !base.join("cache").join("codegraph.db").is_file(),
+        "configured root must resolve to the identity sibling, not the simple-join"
+    );
+
+    let resp = tool_call_search(base, base.to_str().unwrap());
+
+    match prev {
+        Some(v) => unsafe { std::env::set_var("CODEGRAPH_DIR", v) },
+        None => unsafe { std::env::remove_var("CODEGRAPH_DIR") },
+    }
+
+    let text = resp["result"]["content"][0]["text"]
+        .as_str()
+        .expect("tool content text");
+    assert_ne!(
+        resp["result"]["isError"],
+        json!(true),
+        "configured-root tool call must not error: {text}"
+    );
+    assert!(
+        text.contains("add"),
+        "search against the identity-sibling DB must return results: {text}"
+    );
+}
+
+/// Two DISTINCT projects sharing ONE absolute `CODEGRAPH_DIR` cannot cross-read:
+/// each resolves to its OWN identity-suffixed sibling, so staging only project
+/// A's DB leaves project B unindexed — B can never open A's graph through the
+/// shared absolute root.
+#[test]
+fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
+    let _env = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+    let dir = unique_dir("abs");
+    let holder = &dir.path;
+    let project_a = holder.join("a");
+    let project_b = holder.join("b");
+    let shared = holder.join("shared").join("cg");
+    fs::create_dir_all(&project_a).unwrap();
+    fs::create_dir_all(&project_b).unwrap();
+    fs::create_dir_all(holder.join("shared")).unwrap();
+
+    let prev = std::env::var_os("CODEGRAPH_DIR");
+    let shared_str = shared.to_string_lossy().into_owned();
+    // SAFETY: single-threaded test process; restored before returning.
+    unsafe { std::env::set_var("CODEGRAPH_DIR", &shared_str) };
+
+    let paths_a = codegraph_core::IndexPaths::resolve(&project_a, Some(&shared_str)).expect("a");
+    stage_mini_db_at(&paths_a.current_db(), &project_a);
+
+    let paths_b = codegraph_core::IndexPaths::resolve(&project_b, Some(&shared_str)).expect("b");
+    assert_ne!(
+        paths_a.current_root(),
+        paths_b.current_root(),
+        "two projects sharing an absolute root must get distinct identity siblings"
+    );
+    assert!(
+        !paths_b.current_db().is_file(),
+        "project B must NOT resolve to project A's staged DB"
+    );
+
+    let resp_a = tool_call_search(&project_a, project_a.to_str().unwrap());
+    let resp_b = tool_call_search(&project_b, project_b.to_str().unwrap());
+
+    match prev {
+        Some(v) => unsafe { std::env::set_var("CODEGRAPH_DIR", v) },
+        None => unsafe { std::env::remove_var("CODEGRAPH_DIR") },
+    }
+
+    let text_a = resp_a["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or("");
+    assert!(
+        resp_a["result"]["isError"] != json!(true) && text_a.contains("add"),
+        "project A must read its own graph: {text_a}"
+    );
+    let text_b = serde_json::to_string(&resp_b).unwrap();
+    assert!(
+        !text_b.contains("Greeter") && !text_b.contains("Counter"),
+        "project B must NOT surface project A's indexed symbols: {text_b}"
+    );
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 8df4cac..c6f0e78 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -518,3 +518,90 @@ the configured-root fail-closed contract in full. Still legitimately unchanged
 black-box Red, the new configured-root + `.` alias + scanner regressions, and
 `codegraph-bench` golden byte-stability). No plan-level architecture change was
 required.
+
+## Batch M — path-authority correction #2: close verification defects (2026-07-25)
+
+### Why this follow-up exists
+
+Verification REJECTED the prior correction (commit `f6ff9e2`) on five concrete
+defects. This commit closes each; the earlier claims are SUPERSEDED here, never
+erased. Commits `b5a66f2`, `8aeefc4`, `f6ff9e2` stay intact; this is a NEW
+correction commit (no amend). Frozen plan/manifest/support hashes, `UPSTREAM.md`,
+`KNOWN_DIFFS.md`, `.gitignore`, `.oxfmtignore`, and `Cargo.lock` are all
+untouched (`Cargo.lock` still `750ee84b…`).
+
+### Rejected defects and their fixes
+
+1. **External normalization checked only the nearest existing node, not every
+   existing component.** `physical_normalize`'s out-of-project arm rejected a
+   symlink only at `existing` (the nearest-existing ancestor), so an
+   intermediate-link-then-existing-child path such as
+   `<cache>/link/child/cg` (where `link` is a symlink to a real dir and `child`
+   is an ordinary directory reached THROUGH it) would follow the alias silently.
+   Fixed: the out-of-project arm now walks EVERY prefix component from the
+   filesystem root down to `existing` and rejects the first symlink / Windows
+   reparse-point component. The in-project arm already probed the whole tail
+   below the (already-canonical) project. Both spellings are now locked by tests
+   `rejects_external_configured_root_reached_through_intermediate_symlink` and
+   the new `rejects_in_project_root_reached_through_intermediate_symlink`.
+
+2. **Scanner exclusions were lossy / direct-child basename based.** The prior
+   `reserved_child_dir_names` reduced roots to basenames and `scan_dir` only
+   pruned them when `dir == root`, so a nested configured root
+   (`CODEGRAPH_DIR=cache/index` → `<project>/cache/index`) was never excluded at
+   its true depth, and a same-basename user dir could be mis-excluded. Fixed:
+   `IndexPaths::reserved_index_roots` now returns the EXACT resolved physical
+   root PATHS (full `PathBuf`s, re-anchored onto the caller's `project` spelling
+   for in-project roots, absolute for external ones); `scan_dir` prunes a
+   directory iff its FULL path equals one of them (at any depth), keeping the
+   `.git`-at-root rule. New tests: `reserved_roots_include_nested_configured_roots_at_true_depth`,
+   `scan_excludes_only_top_level_root_paths_not_same_named_nested_dirs`; the
+   default/relative/degrade tests were rewritten to assert full paths.
+
+3. **CLI/MCP fallbacks masked invalid configuration.** `cmd_status` degraded an
+   unresolvable/aliased `CODEGRAPH_DIR` to a default `.codegraph-v2` layout and
+   reported "not initialized"; `roots::db_path_for` returned a reconstructed
+   default path. Fixed: `cmd_status` now propagates the `IndexPaths::resolve`
+   error (fail closed) instead of masking it; `roots::db_path_for` returns
+   `Option<PathBuf>` (`None` on a resolve failure) with a shared
+   `db_exists_for` probe, and `server.rs engine_for` maps `None` to a stable
+   error rather than opening a reconstructed path. `is_initialized` stays an
+   infallible discovery probe by design (a resolve failure ⇒ "not initialized",
+   discovery keeps walking; the mutating/opening paths re-resolve fail-closed).
+   New CLI regression `status_fails_closed_on_invalid_configured_root_without_mutation_via_cli`
+   proves both text and `--json` status fail closed and mutate zero bytes.
+
+4. **Real MCP configured-root / cross-project tests were missing.** Added a
+   dedicated test binary `crates/codegraph-mcp/tests/mcp_configured_root.rs`
+   (separate process; serializes the process-global `CODEGRAPH_DIR` via an
+   `ENV_LOCK`): `configured_relative_root_mcp_opens_identity_sibling_db` proves a
+   real `McpServer` `tools/call` opens the identity-suffixed sibling DB (not the
+   simple-join), and `two_projects_sharing_absolute_root_cannot_cross_read_via_mcp`
+   proves two projects on ONE absolute configured root get distinct roots and
+   cannot cross-read. Added a CLI-surface counterpart
+   `two_projects_sharing_escaping_relative_root_get_distinct_roots_via_cli`.
+
+5. **A stale rustdoc link.** `DEFAULT_CURRENT_DIR`'s doc referenced the removed
+   `IndexPaths::current_root_lenient`; retargeted to `IndexPaths::resolve`.
+
+Also replaced the previous `db_path_for_returns_none_on_invalid_configured_root`
+unit test — which mutated the process-global `CODEGRAPH_DIR` and could race the
+crate's env-sensitive readers — with the race-free
+`db_path_for_returns_none_on_resolve_failure` (a nonexistent project triggers the
+same `resolve` failure without touching the env); the invalid-`CODEGRAPH_DIR`
+path is covered end-to-end by the real CLI/MCP black-box regressions. Removed the
+now-unused `ENV_LOCK` from `roots.rs`.
+
+### Verification
+
+`bash scripts/check-workspace-versions.sh` (OK, lock `750ee84b…` unchanged);
+`cargo fmt --all --check` clean; `cargo check --workspace --all-targets --locked`
+clean; `cargo check -p codegraph-core --target x86_64-pc-windows-msvc
+--all-targets --locked` clean (cross-compile only, NOT native Windows runtime);
+`cargo clippy --workspace --all-targets --locked -- -D warnings` clean;
+`cargo test --workspace --locked` — 0 failures across all 106 suites (incl. the
+preserved initial black-box Red, the new intermediate-symlink / nested-root /
+status-fail-closed / MCP-configured-root regressions, and `codegraph-bench`
+golden byte-stability); `bash scripts/guardrail.sh` exit 0. No plan-level
+architecture change was required; state-slot / lease / Store `open_for_*` /
+uninit lifecycle and Batches A–E remain out of scope.

From 7d95634c5d34f541e290303ee7ba1452979249da Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 14:01:44 +0800
Subject: [PATCH 10/91] fix(index): prove byte nonmutation and surface invalid
 CODEGRAPH_DIR via MCP

Correction #3 for Batch M IndexPaths verification. Two claims of 7652267 were
overclaims and are superseded here (no amend; prior commits preserved).

Byte-proof snapshots: the CLI nonmutation oracle captured (path, byte LENGTH),
so an equal-length in-place write was invisible. tree_snapshot now captures the
COMPLETE bytes per file via symlink_metadata, comparison moved into
assert_tree_bytes_unchanged (reports only changed paths), and a harness self-test
flips one byte at constant length to prove the assertion fails.

Reachable invalid-config state: db_exists_for collapsed unsafe-configured-root
and absent-DB into one bool that both MCP front-ends consumed before
CodeGraphEngine::open, so CODEGRAPH_DIR=. emitted the generic "No indexed
project" and the actionable IndexPaths diagnostic was unreachable. roots.rs now
carries typed RootStatus/ProjectArg states discriminated by error VARIANT (never
by parsing rendered strings), with one shared resolve_project_arg both front-ends
delegate to; candidate order is unchanged and an indexed candidate still wins
over an earlier invalid one.

New public-surface regressions stage a trap DB at the default .codegraph-v2
namespace under a refused CODEGRAPH_DIR=. and prove both the hand-rolled and the
shipped rmcp tool call fail closed with the stable reason, serve no trap symbol,
and mutate zero project bytes. Test env mutation is now panic-safe via an RAII
EnvGuard holding the serializing lock.

No dependency, schema, node-id, or golden change; Cargo.lock byte-identical.
---
 .../tests/batch_m_v2_namespace.rs             | 103 +++++-
 crates/codegraph-mcp/src/rmcp_handler.rs      |  61 ++--
 crates/codegraph-mcp/src/roots.rs             | 340 +++++++++++++++++-
 crates/codegraph-mcp/src/server.rs            |  63 ++--
 .../tests/mcp_configured_root.rs              | 276 ++++++++++++--
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 139 +++++++
 6 files changed, 880 insertions(+), 102 deletions(-)

diff --git a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
index 26d6ea8..fcb05cf 100644
--- a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
+++ b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
@@ -313,16 +313,20 @@ fn configured_dot_alias_fails_closed_without_mutation_via_cli() {
     );
 }
 
-/// Recursively snapshot every file path + byte length under `root`, sorted, so a
-/// command can be proven byte-nonmutating by comparing the before/after set.
-fn tree_snapshot(root: &Path) -> Vec<(String, u64)> {
-    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, u64)>) {
+/// Recursively snapshot every file path plus its COMPLETE bytes under `root`,
+/// sorted, so a command can be proven byte-nonmutating by comparing the
+/// before/after set. The full byte content — not the file LENGTH — is captured:
+/// an equal-length in-place byte mutation leaves the length identical and would
+/// slip past a size-only snapshot, so size equality is NOT evidence of byte
+/// identity. Comparing the bytes themselves detects same-length content changes.
+fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
+    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, Vec<u8>)>) {
         let Ok(entries) = std::fs::read_dir(dir) else {
             return;
         };
         for entry in entries.filter_map(Result::ok) {
             let path = entry.path();
-            let meta = match entry.metadata() {
+            let meta = match std::fs::symlink_metadata(&path) {
                 Ok(m) => m,
                 Err(_) => continue,
             };
@@ -334,7 +338,8 @@ fn tree_snapshot(root: &Path) -> Vec<(String, u64)> {
                     .unwrap_or(&path)
                     .to_string_lossy()
                     .into_owned();
-                out.push((rel, meta.len()));
+                let bytes = std::fs::read(&path).unwrap_or_default();
+                out.push((rel, bytes));
             }
         }
     }
@@ -344,6 +349,43 @@ fn tree_snapshot(root: &Path) -> Vec<(String, u64)> {
     out
 }
 
+/// Assert two [`tree_snapshot`]s are byte-identical, reporting only the CHANGED
+/// paths (added / removed / same-path-different-bytes). A bare `assert_eq!` on
+/// the snapshots would dump every file's full contents into the failure message;
+/// this compares the same complete bytes but names just the offending paths.
+fn assert_tree_bytes_unchanged(
+    before: &[(String, Vec<u8>)],
+    after: &[(String, Vec<u8>)],
+    context: &str,
+) {
+    let mut diffs: Vec<String> = Vec::new();
+    let before_map: std::collections::BTreeMap<&str, &Vec<u8>> =
+        before.iter().map(|(p, b)| (p.as_str(), b)).collect();
+    let after_map: std::collections::BTreeMap<&str, &Vec<u8>> =
+        after.iter().map(|(p, b)| (p.as_str(), b)).collect();
+    for (path, bytes) in &before_map {
+        match after_map.get(path) {
+            None => diffs.push(format!("removed: {path}")),
+            Some(other) if other != bytes => diffs.push(format!(
+                "bytes changed: {path} ({} -> {} bytes)",
+                bytes.len(),
+                other.len()
+            )),
+            Some(_) => {}
+        }
+    }
+    for path in after_map.keys() {
+        if !before_map.contains_key(path) {
+            diffs.push(format!("created: {path}"));
+        }
+    }
+    assert!(
+        diffs.is_empty(),
+        "{context}: project tree must be byte-for-byte unchanged (complete file \
+         bytes compared, NOT sizes), but changed: {diffs:?}"
+    );
+}
+
 /// `status` under an invalid/aliasing `CODEGRAPH_DIR` must FAIL CLOSED through
 /// the REAL CLI — surfacing the stable diagnostic instead of masking the bad
 /// configuration behind a default `.codegraph-v2` "not initialized" report — and
@@ -377,12 +419,59 @@ fn status_fails_closed_on_invalid_configured_root_without_mutation_via_cli() {
              default: stdout={}",
             run.stdout
         );
+        // The actionable `IndexPaths` diagnostic must reach the user (on stderr,
+        // where the CLI prints `Error: …`). Assert the STABLE reason phrasing —
+        // `.` aliases the project root — not merely "some error".
+        let combined = format!("{}{}", run.stdout, run.stderr);
+        assert!(
+            combined.contains("project root itself"),
+            "status (json={json}) must surface the stable unsafe-root diagnostic \
+             (the `.` alias resolves to the project root itself): stdout={} stderr={}",
+            run.stdout,
+            run.stderr
+        );
     }
 
     let after = tree_snapshot(&project);
+    assert_tree_bytes_unchanged(&before, &after, "a fail-closed `status`");
+}
+
+/// The byte snapshot must catch an EQUAL-LENGTH in-place mutation — the exact
+/// hole a size-only snapshot left open. Self-test of the harness: mutating one
+/// byte without changing any file length must be reported as changed.
+#[test]
+fn tree_snapshot_detects_equal_length_byte_mutation() {
+    let dir = TestDir::new("snap-selftest");
+    let project = dir.path().join("mini");
+    std::fs::create_dir_all(&project).unwrap();
+    let victim = project.join("a.txt");
+    std::fs::write(&victim, b"AAAA").unwrap();
+
+    let before = tree_snapshot(&project);
+    std::fs::write(&victim, b"AAAB").unwrap();
+    let after = tree_snapshot(&project);
+
     assert_eq!(
+        before.len(),
+        after.len(),
+        "sanity: the mutation must keep the file set identical"
+    );
+    assert_eq!(
+        before[0].1.len(),
+        after[0].1.len(),
+        "sanity: the mutation must keep the byte LENGTH identical, so only a \
+         full-byte comparison can detect it"
+    );
+    assert_ne!(
         before, after,
-        "a fail-closed `status` must leave the project tree byte-for-byte unchanged"
+        "a same-length byte mutation must change the snapshot"
+    );
+    let panicked = std::panic::catch_unwind(|| {
+        assert_tree_bytes_unchanged(&before, &after, "self-test");
+    });
+    assert!(
+        panicked.is_err(),
+        "the nonmutation assertion must FAIL on a same-length byte mutation"
     );
 }
 
diff --git a/crates/codegraph-mcp/src/rmcp_handler.rs b/crates/codegraph-mcp/src/rmcp_handler.rs
index c0ac111..dc64d19 100644
--- a/crates/codegraph-mcp/src/rmcp_handler.rs
+++ b/crates/codegraph-mcp/src/rmcp_handler.rs
@@ -181,33 +181,17 @@ impl CodeGraphHandler {
             .is_some_and(|p| db_exists_for(p))
     }
 
-    /// Resolve a caller's `projectPath` to an INDEXED project dir, byte-for-byte
-    /// the same candidate order as [`crate::McpServer`]'s `resolve_project_arg`
-    /// (server.rs:568): absolute raw → cwd-join → bare raw → default-by-basename;
-    /// `None` raw → the indexed default. Returns `None` when nothing resolves.
-    fn resolve_project_arg(&self, raw: Option<&str>) -> Option<PathBuf> {
-        let default_project = self.default_project_snapshot();
-        let Some(raw) = raw else {
-            return default_project.filter(|p| db_exists_for(p));
-        };
-        let raw_path = PathBuf::from(raw);
-        let mut candidates: Vec<PathBuf> = Vec::new();
-        if raw_path.is_absolute() {
-            candidates.push(raw_path.clone());
-        } else {
-            if let Some(cwd) = &self.cwd {
-                candidates.push(cwd.join(&raw_path));
-            }
-            candidates.push(raw_path.clone());
-        }
-        if let Some(default) = &default_project
-            && raw_path.file_name() == default.file_name()
-        {
-            candidates.push(default.clone());
-        }
-        candidates
-            .into_iter()
-            .find(|candidate| db_exists_for(candidate))
+    /// Resolve a caller's `projectPath` through the shared
+    /// [`crate::roots::resolve_project_arg`], so both front-ends agree on
+    /// candidate order AND on the invalid-config vs absent-index distinction: an
+    /// unsafe configured root fails closed with the real diagnostic instead of a
+    /// generic miss (the Failure-B fix).
+    fn resolve_project_arg(&self, raw: Option<&str>) -> crate::roots::ProjectArg {
+        crate::roots::resolve_project_arg(
+            raw,
+            self.cwd.as_deref(),
+            self.default_project_snapshot().as_deref(),
+        )
     }
 
     /// Adopt an indexed client workspace root when the current default is
@@ -420,8 +404,13 @@ impl ServerHandler for CodeGraphHandler {
 
         let raw_project = args.get("projectPath").and_then(Value::as_str);
         let project_path = match self.resolve_project_arg(raw_project) {
-            Some(p) => p,
-            None => {
+            crate::roots::ProjectArg::Resolved(p) => p,
+            crate::roots::ProjectArg::InvalidConfig(detail) => {
+                return Ok(tool_result_to_call_result(&ToolResult::error(
+                    crate::roots::invalid_config_message(&detail),
+                )));
+            }
+            crate::roots::ProjectArg::NotIndexed => {
                 let message = match raw_project {
                     Some(raw) => format!(
                         "No indexed project found for projectPath {raw:?}. Pass an absolute path to an indexed project, or run `codegraph init` there."
@@ -1066,7 +1055,7 @@ mod handler_tests {
         let project = placeholder_indexed("resolve-none");
         let handler = CodeGraphHandler::new_with_cwd(Some(project.path.clone()), None);
         assert_eq!(
-            handler.resolve_project_arg(None).as_deref(),
+            handler.resolve_project_arg(None).resolved(),
             Some(project.path.as_path())
         );
     }
@@ -1075,7 +1064,7 @@ mod handler_tests {
     fn resolve_project_arg_none_unindexed_default_is_none() {
         let dir = unique_dir("resolve-none-unidx");
         let handler = CodeGraphHandler::new_with_cwd(Some(dir.path.clone()), None);
-        assert_eq!(handler.resolve_project_arg(None), None);
+        assert_eq!(handler.resolve_project_arg(None).resolved(), None);
     }
 
     #[test]
@@ -1084,7 +1073,7 @@ mod handler_tests {
         let raw = project.path.display().to_string();
         let handler = CodeGraphHandler::new_with_cwd(None, None);
         assert_eq!(
-            handler.resolve_project_arg(Some(&raw)).as_deref(),
+            handler.resolve_project_arg(Some(&raw)).resolved(),
             Some(project.path.as_path())
         );
     }
@@ -1096,7 +1085,7 @@ mod handler_tests {
         let name = project.path.file_name().and_then(|s| s.to_str()).unwrap();
         let handler = CodeGraphHandler::new_with_cwd(None, Some(parent));
         assert_eq!(
-            handler.resolve_project_arg(Some(name)).as_deref(),
+            handler.resolve_project_arg(Some(name)).resolved(),
             Some(project.path.as_path())
         );
     }
@@ -1113,7 +1102,7 @@ mod handler_tests {
         let cwd = std::env::temp_dir().join("cg-mcp-h-basename-elsewhere");
         let handler = CodeGraphHandler::new_with_cwd(Some(project.path.clone()), Some(cwd));
         assert_eq!(
-            handler.resolve_project_arg(Some(&name)).as_deref(),
+            handler.resolve_project_arg(Some(&name)).resolved(),
             Some(project.path.as_path())
         );
     }
@@ -1123,7 +1112,9 @@ mod handler_tests {
         let project = placeholder_indexed("resolve-bogus");
         let handler = CodeGraphHandler::new_with_cwd(Some(project.path.clone()), None);
         assert_eq!(
-            handler.resolve_project_arg(Some("no-such-project-xyz")),
+            handler
+                .resolve_project_arg(Some("no-such-project-xyz"))
+                .resolved(),
             None
         );
     }
diff --git a/crates/codegraph-mcp/src/roots.rs b/crates/codegraph-mcp/src/roots.rs
index ed35975..a026b99 100644
--- a/crates/codegraph-mcp/src/roots.rs
+++ b/crates/codegraph-mcp/src/roots.rs
@@ -50,9 +50,173 @@ pub fn db_path_for(project_path: &Path) -> Option<PathBuf> {
 
 /// Whether `project_path` resolves to an existing current-namespace index DB.
 /// `false` for both an unresolvable configured root and a resolvable-but-absent
-/// index — the shared adoption/probe predicate.
+/// index — the shared adoption / `tools/list`-schema predicate. Adoption and the
+/// schema selector only ask "is there a usable index here?", so collapsing the
+/// invalid-config and absent cases to `false` is correct FOR THEM. A tool CALL
+/// needs the finer [`probe_root`] to tell an unsafe configured root apart from an
+/// absent index and surface the actionable diagnostic instead of a generic miss.
 pub fn db_exists_for(project_path: &Path) -> bool {
-    db_path_for(project_path).is_some_and(|db| db.is_file())
+    matches!(probe_root(project_path), RootStatus::Indexed)
+}
+
+/// Fail-closed classification of one project-root candidate under the current
+/// `CODEGRAPH_DIR`. Distinguishes an UNSAFE configured root (an
+/// [`codegraph_core::IndexPaths::resolve`] failure — the actionable diagnostic
+/// is carried verbatim, NEVER re-parsed from a rendered string) from a valid
+/// root whose DB is merely ABSENT, so a tool call can fail closed with the real
+/// configuration error rather than a generic "not indexed" miss that would let
+/// an invalid root masquerade as an un-init'd one.
+#[derive(Debug)]
+pub enum RootStatus {
+    /// Valid configured root AND its current-namespace DB exists on disk.
+    Indexed,
+    /// Valid configured root, but its current-namespace DB does not exist yet.
+    Absent,
+    /// The configured `CODEGRAPH_DIR` is unsafe/aliased/overlapping; the string
+    /// is the stable `IndexPaths` diagnostic (its `Display`).
+    Invalid(String),
+}
+
+/// Classify `project_path` via the single `IndexPaths` authority. NEVER
+/// reconstructs a default path on a resolve failure — an invalid configured root
+/// yields [`RootStatus::Invalid`], not a fabricated `.codegraph-v2` fallback that
+/// could open an unrelated project's database.
+pub fn probe_root(project_path: &Path) -> RootStatus {
+    classify_resolve(codegraph_core::IndexPaths::resolve(
+        project_path,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    ))
+}
+
+/// Pure classifier for an [`codegraph_core::IndexPaths::resolve`] outcome, split
+/// out so the invalid/absent decision is unit-tested WITHOUT mutating the
+/// process-global `CODEGRAPH_DIR`.
+fn classify_resolve(
+    resolved: Result<codegraph_core::IndexPaths, codegraph_core::IndexPathsError>,
+) -> RootStatus {
+    use codegraph_core::IndexPathsError;
+    match resolved {
+        Ok(paths) => {
+            if paths.current_db().is_file() {
+                RootStatus::Indexed
+            } else {
+                RootStatus::Absent
+            }
+        }
+        // A project directory that cannot be canonicalized is MISSING, not a bad
+        // configuration — a bogus `projectPath` must stay a generic "not indexed"
+        // miss (the `codegraph init` case), never an "invalid CODEGRAPH_DIR"
+        // error. Every OTHER variant is a genuinely unsafe/aliased/overlapping
+        // configured root and fails closed with its stable diagnostic.
+        Err(IndexPathsError::ProjectInaccessible { .. }) => RootStatus::Absent,
+        Err(err) => RootStatus::Invalid(err.to_string()),
+    }
+}
+
+/// The outcome of resolving a tool call's `projectPath` argument to a project
+/// directory, preserving the invalid-config vs absent-index distinction the
+/// caller needs to emit an actionable error rather than a generic miss.
+#[derive(Debug)]
+pub enum ProjectArg {
+    /// Resolved to an indexed project directory.
+    Resolved(PathBuf),
+    /// A candidate's configured `CODEGRAPH_DIR` is unsafe/aliased/overlapping;
+    /// carries the stable `IndexPaths` diagnostic. Fail closed with this rather
+    /// than masking it as a generic miss.
+    InvalidConfig(String),
+    /// Nothing resolved to an existing index (valid roots with absent DBs, or no
+    /// candidate matched) — the genuine "run `codegraph init`" case.
+    NotIndexed,
+}
+
+impl ProjectArg {
+    /// The resolved indexed path, if any — for the debug trace and the existing
+    /// resolution unit tests (which only assert the resolved/none outcome).
+    pub fn resolved(&self) -> Option<&Path> {
+        match self {
+            ProjectArg::Resolved(p) => Some(p.as_path()),
+            _ => None,
+        }
+    }
+}
+
+/// Resolve a caller's `projectPath` to an INDEXED project dir, in the SAME
+/// candidate order both server front-ends use: absolute raw → cwd-join → bare
+/// raw → default-by-basename; `None` raw → the default project. An INDEXED
+/// candidate wins immediately (a valid configured root is honored even if an
+/// earlier candidate carried a bad config); otherwise the FIRST invalid-config
+/// diagnostic is surfaced (fail closed); otherwise [`ProjectArg::NotIndexed`].
+pub fn resolve_project_arg(
+    raw: Option<&str>,
+    cwd: Option<&Path>,
+    default_project: Option<&Path>,
+) -> ProjectArg {
+    resolve_project_arg_with(raw, cwd, default_project, &probe_root)
+}
+
+/// [`resolve_project_arg`] with the per-candidate classifier injected, so the
+/// candidate ORDER and the indexed/absent/invalid decision are unit-tested
+/// without mutating the process-global `CODEGRAPH_DIR`. Production callers use
+/// [`resolve_project_arg`], which injects [`probe_root`].
+fn resolve_project_arg_with(
+    raw: Option<&str>,
+    cwd: Option<&Path>,
+    default_project: Option<&Path>,
+    probe: &dyn Fn(&Path) -> RootStatus,
+) -> ProjectArg {
+    let Some(raw) = raw else {
+        return match default_project {
+            Some(p) => match probe(p) {
+                RootStatus::Indexed => ProjectArg::Resolved(p.to_path_buf()),
+                RootStatus::Invalid(detail) => ProjectArg::InvalidConfig(detail),
+                RootStatus::Absent => ProjectArg::NotIndexed,
+            },
+            None => ProjectArg::NotIndexed,
+        };
+    };
+
+    let raw_path = PathBuf::from(raw);
+    let mut candidates: Vec<PathBuf> = Vec::new();
+    if raw_path.is_absolute() {
+        candidates.push(raw_path.clone());
+    } else {
+        if let Some(cwd) = cwd {
+            candidates.push(cwd.join(&raw_path));
+        }
+        candidates.push(raw_path.clone());
+    }
+    if let Some(default) = default_project
+        && raw_path.file_name() == default.file_name()
+    {
+        candidates.push(default.to_path_buf());
+    }
+
+    let mut first_invalid: Option<String> = None;
+    for candidate in &candidates {
+        match probe(candidate) {
+            RootStatus::Indexed => return ProjectArg::Resolved(candidate.clone()),
+            RootStatus::Invalid(detail) if first_invalid.is_none() => {
+                first_invalid = Some(detail);
+            }
+            _ => {}
+        }
+    }
+    match first_invalid {
+        Some(detail) => ProjectArg::InvalidConfig(detail),
+        None => ProjectArg::NotIndexed,
+    }
+}
+
+/// The actionable tool-error text for an unsafe/aliased configured root, shared
+/// by both front-ends so the wording (and the "unsafe configured root" naming
+/// the regressions assert) stays identical.
+pub fn invalid_config_message(detail: &str) -> String {
+    format!(
+        "Invalid CODEGRAPH_DIR configuration: {detail}. The configured index root is \
+         unsafe — fix or unset CODEGRAPH_DIR (it must not alias the project root, an \
+         ancestor, a symlink/reparse component, or overlap the legacy `.codegraph` \
+         root), then re-run `codegraph init`."
+    )
 }
 
 pub struct WorkspaceRoots {
@@ -668,4 +832,176 @@ mod tests {
             "db_exists_for must be false when resolution fails"
         );
     }
+
+    /// `classify_resolve` on a VALID configured root whose DB is present →
+    /// [`RootStatus::Indexed`]. Race-free: `IndexPaths::resolve` is called with an
+    /// explicit `codegraph_dir` argument, never the process-global env.
+    #[test]
+    fn classify_resolve_valid_present_is_indexed() {
+        let dir = std::env::temp_dir().join(format!(
+            "cg-roots-classify-present-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let paths = codegraph_core::IndexPaths::resolve(&dir, None).expect("resolve default");
+        let db = paths.current_db();
+        std::fs::create_dir_all(db.parent().unwrap()).unwrap();
+        std::fs::write(&db, b"placeholder").unwrap();
+        assert!(matches!(
+            classify_resolve(codegraph_core::IndexPaths::resolve(&dir, None)),
+            RootStatus::Indexed
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// `classify_resolve` on a VALID configured root whose DB is ABSENT →
+    /// [`RootStatus::Absent`] (the genuine un-init'd case, not an error).
+    #[test]
+    fn classify_resolve_valid_absent_is_absent() {
+        let dir = std::env::temp_dir().join(format!(
+            "cg-roots-classify-absent-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        assert!(matches!(
+            classify_resolve(codegraph_core::IndexPaths::resolve(&dir, None)),
+            RootStatus::Absent
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// `classify_resolve` on an UNSAFE configured root (`.` aliases the project
+    /// root) → [`RootStatus::Invalid`] carrying the stable diagnostic. Race-free:
+    /// the bad value is passed as an argument, not via the global env.
+    #[test]
+    fn classify_resolve_invalid_config_is_invalid_with_diagnostic() {
+        let dir = std::env::temp_dir().join(format!(
+            "cg-roots-classify-invalid-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        match classify_resolve(codegraph_core::IndexPaths::resolve(&dir, Some("."))) {
+            RootStatus::Invalid(detail) => assert!(
+                detail.contains("project root"),
+                "invalid diagnostic must name the aliasing reason: {detail}"
+            ),
+            other => panic!("`.` alias must classify Invalid, got {other:?}"),
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// A MISSING project directory is not a bad configuration: it classifies
+    /// [`RootStatus::Absent`] (generic "not indexed"), never `Invalid`.
+    #[test]
+    fn classify_resolve_missing_project_is_absent_not_invalid() {
+        let missing = std::env::temp_dir().join(format!(
+            "cg-roots-classify-missing-{}-{}",
+            std::process::id(),
+            SEQ.fetch_add(1, Ordering::Relaxed)
+        ));
+        assert!(!missing.exists(), "sanity: probe path must not exist");
+        assert!(matches!(
+            classify_resolve(codegraph_core::IndexPaths::resolve(&missing, None)),
+            RootStatus::Absent
+        ));
+    }
+
+    /// A stub classifier keyed by path, so candidate ORDER and the three typed
+    /// states are asserted without touching the filesystem or the env.
+    fn stub_probe(map: Vec<(PathBuf, RootStatus)>) -> impl Fn(&Path) -> RootStatus {
+        move |candidate: &Path| {
+            for (path, status) in &map {
+                if path == candidate {
+                    return match status {
+                        RootStatus::Indexed => RootStatus::Indexed,
+                        RootStatus::Absent => RootStatus::Absent,
+                        RootStatus::Invalid(d) => RootStatus::Invalid(d.clone()),
+                    };
+                }
+            }
+            RootStatus::Absent
+        }
+    }
+
+    /// `raw = None` + an INVALID default root ⇒ [`ProjectArg::InvalidConfig`]
+    /// carrying the diagnostic — NOT `NotIndexed`. This is the exact Failure-B
+    /// masking: a bad `CODEGRAPH_DIR` used to collapse into "no indexed project".
+    #[test]
+    fn resolve_project_arg_none_invalid_default_is_invalid_config() {
+        let default = PathBuf::from("/tmp/cg-stub-default");
+        let probe = stub_probe(vec![(
+            default.clone(),
+            RootStatus::Invalid("unsafe root: project root itself".to_string()),
+        )]);
+        match resolve_project_arg_with(None, None, Some(&default), &probe) {
+            ProjectArg::InvalidConfig(detail) => {
+                assert!(detail.contains("project root itself"), "{detail}")
+            }
+            other => panic!("invalid default must fail closed, got {other:?}"),
+        }
+    }
+
+    /// An INDEXED candidate wins over an EARLIER invalid one: a valid configured
+    /// root must still resolve, so the fail-closed behavior cannot regress into
+    /// refusing every call whenever any candidate happens to be misconfigured.
+    #[test]
+    fn resolve_project_arg_indexed_candidate_wins_over_earlier_invalid() {
+        let cwd = PathBuf::from("/tmp/cg-stub-cwd");
+        let bare = PathBuf::from("proj");
+        let joined = cwd.join(&bare);
+        let probe = stub_probe(vec![
+            (joined, RootStatus::Invalid("bad".to_string())),
+            (bare.clone(), RootStatus::Indexed),
+        ]);
+        assert_eq!(
+            resolve_project_arg_with(Some("proj"), Some(&cwd), None, &probe).resolved(),
+            Some(bare.as_path()),
+            "an indexed later candidate must win over an earlier invalid one"
+        );
+    }
+
+    /// With NO indexed candidate, the FIRST invalid diagnostic is surfaced (in
+    /// candidate order: cwd-join before bare raw), so the reported reason belongs
+    /// to the highest-priority misconfigured candidate.
+    #[test]
+    fn resolve_project_arg_reports_first_invalid_in_candidate_order() {
+        let cwd = PathBuf::from("/tmp/cg-stub-cwd2");
+        let bare = PathBuf::from("proj");
+        let joined = cwd.join(&bare);
+        let probe = stub_probe(vec![
+            (joined, RootStatus::Invalid("first-invalid".to_string())),
+            (bare, RootStatus::Invalid("second-invalid".to_string())),
+        ]);
+        match resolve_project_arg_with(Some("proj"), Some(&cwd), None, &probe) {
+            ProjectArg::InvalidConfig(detail) => assert_eq!(detail, "first-invalid"),
+            other => panic!("expected InvalidConfig, got {other:?}"),
+        }
+    }
+
+    /// All-absent candidates stay the genuine [`ProjectArg::NotIndexed`] "run
+    /// `codegraph init`" case — an absent index is not a bad configuration.
+    #[test]
+    fn resolve_project_arg_all_absent_is_not_indexed() {
+        let probe = stub_probe(vec![]);
+        assert!(matches!(
+            resolve_project_arg_with(Some("/tmp/cg-stub-absolute"), None, None, &probe),
+            ProjectArg::NotIndexed
+        ));
+    }
+
+    /// The shared invalid-config message embeds the verbatim diagnostic AND the
+    /// actionable remedy both front-ends surface.
+    #[test]
+    fn invalid_config_message_carries_detail_and_remedy() {
+        let msg = invalid_config_message("refusing an unsafe index root /p: reason");
+        assert!(
+            msg.contains("refusing an unsafe index root /p: reason"),
+            "{msg}"
+        );
+        assert!(msg.contains("CODEGRAPH_DIR"), "{msg}");
+        assert!(msg.contains("unsafe"), "{msg}");
+    }
 }
diff --git a/crates/codegraph-mcp/src/server.rs b/crates/codegraph-mcp/src/server.rs
index edbb5cd..e2107ab 100644
--- a/crates/codegraph-mcp/src/server.rs
+++ b/crates/codegraph-mcp/src/server.rs
@@ -445,14 +445,22 @@ impl McpServer {
             format_tool_debug_line(
                 &tool_name,
                 raw_project,
-                resolved.as_deref(),
+                resolved.resolved(),
                 self.cwd.as_deref(),
                 self.default_project.as_deref(),
             )
         );
         let project_path = match resolved {
-            Some(p) => p,
-            None => {
+            crate::roots::ProjectArg::Resolved(p) => p,
+            crate::roots::ProjectArg::InvalidConfig(detail) => {
+                return Dispatch::Reply(
+                    serde_json::to_value(ToolResult::error(crate::roots::invalid_config_message(
+                        &detail,
+                    )))
+                    .expect("ToolResult serializes"),
+                );
+            }
+            crate::roots::ProjectArg::NotIndexed => {
                 let message = match raw_project {
                     Some(raw) => format!(
                         "No indexed project found for projectPath {raw:?}. Pass an absolute path to an indexed project, or run `codegraph init` there."
@@ -498,33 +506,14 @@ impl McpServer {
     /// - `raw = None`: the `default_project` (existing behavior).
     ///
     /// Honesty rule: when `raw` is given but resolves to nothing AND its basename
-    /// does not match `default_project`, this returns `None` rather than silently
-    /// falling back to `default_project` — a genuinely wrong path must surface an
-    /// error, not mask itself behind the default.
-    fn resolve_project_arg(&self, raw: Option<&str>) -> Option<PathBuf> {
-        let Some(raw) = raw else {
-            return self.default_project.clone().filter(|p| db_exists_for(p));
-        };
-
-        let raw_path = PathBuf::from(raw);
-        let mut candidates: Vec<PathBuf> = Vec::new();
-        if raw_path.is_absolute() {
-            candidates.push(raw_path.clone());
-        } else {
-            if let Some(cwd) = &self.cwd {
-                candidates.push(cwd.join(&raw_path));
-            }
-            candidates.push(raw_path.clone());
-        }
-        if let Some(default) = &self.default_project
-            && raw_path.file_name() == default.file_name()
-        {
-            candidates.push(default.clone());
-        }
-
-        candidates
-            .into_iter()
-            .find(|candidate| db_exists_for(candidate))
+    /// does not match `default_project`, this yields `NotIndexed` rather than
+    /// silently falling back to `default_project` — a genuinely wrong path must
+    /// surface an error, not mask itself behind the default. An unsafe configured
+    /// root yields `InvalidConfig` (the Failure-B fix), not a generic miss.
+    /// Delegates to the shared [`crate::roots::resolve_project_arg`] so this
+    /// front-end and the rmcp handler stay byte-identical.
+    fn resolve_project_arg(&self, raw: Option<&str>) -> crate::roots::ProjectArg {
+        crate::roots::resolve_project_arg(raw, self.cwd.as_deref(), self.default_project.as_deref())
     }
 
     /// Open-on-demand + cache the engine for a project path
@@ -839,7 +828,7 @@ mod tests {
         let cwd = std::env::temp_dir().join("cg-mcp-basename-cwd-elsewhere");
         let server = McpServer::new_with_cwd(Some(project.path().to_path_buf()), Some(cwd));
         assert_eq!(
-            server.resolve_project_arg(Some(&name)).as_deref(),
+            server.resolve_project_arg(Some(&name)).resolved(),
             Some(project.path()),
         );
     }
@@ -855,7 +844,7 @@ mod tests {
         // default_project unset so ONLY the cwd-join candidate can resolve.
         let server = McpServer::new_with_cwd(None, Some(parent));
         assert_eq!(
-            server.resolve_project_arg(Some(name)).as_deref(),
+            server.resolve_project_arg(Some(name)).resolved(),
             Some(project.path()),
         );
     }
@@ -867,7 +856,7 @@ mod tests {
         let raw = project.path().display().to_string();
         let server = McpServer::new_with_cwd(None, None);
         assert_eq!(
-            server.resolve_project_arg(Some(&raw)).as_deref(),
+            server.resolve_project_arg(Some(&raw)).resolved(),
             Some(project.path()),
         );
     }
@@ -881,7 +870,9 @@ mod tests {
         let cwd = std::env::temp_dir().join("cg-mcp-bogus-cwd-elsewhere");
         let server = McpServer::new_with_cwd(Some(project.path().to_path_buf()), Some(cwd));
         assert_eq!(
-            server.resolve_project_arg(Some("definitely-not-a-real-project-xyz")),
+            server
+                .resolve_project_arg(Some("definitely-not-a-real-project-xyz"))
+                .resolved(),
             None,
         );
     }
@@ -893,7 +884,7 @@ mod tests {
         let project = indexed_project("none-default");
         let server = McpServer::new_with_cwd(Some(project.path().to_path_buf()), None);
         assert_eq!(
-            server.resolve_project_arg(None).as_deref(),
+            server.resolve_project_arg(None).resolved(),
             Some(project.path()),
         );
     }
@@ -909,7 +900,7 @@ mod tests {
         ));
         std::fs::create_dir_all(&dir).unwrap();
         let server = McpServer::new_with_cwd(Some(dir.clone()), None);
-        assert_eq!(server.resolve_project_arg(None), None);
+        assert_eq!(server.resolve_project_arg(None).resolved(), None);
         let _ = std::fs::remove_dir_all(&dir);
     }
 
diff --git a/crates/codegraph-mcp/tests/mcp_configured_root.rs b/crates/codegraph-mcp/tests/mcp_configured_root.rs
index 7b39b51..aab59c0 100644
--- a/crates/codegraph-mcp/tests/mcp_configured_root.rs
+++ b/crates/codegraph-mcp/tests/mcp_configured_root.rs
@@ -15,11 +15,44 @@ use codegraph_mcp::McpServer;
 use serde_json::{Value, json};
 
 static SEQ: AtomicU64 = AtomicU64::new(0);
-// Both tests mutate the PROCESS-GLOBAL `CODEGRAPH_DIR`; cargo runs a binary's
-// tests multi-threaded in ONE process, so they must serialize the set→read→
-// restore window against each other.
+// Every test here mutates the PROCESS-GLOBAL `CODEGRAPH_DIR`; cargo runs a
+// binary's tests multi-threaded in ONE process, so they must serialize the
+// set→read→restore window against each other.
 static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
 
+/// RAII guard for the process-global `CODEGRAPH_DIR`: sets it on construction and
+/// restores the PREVIOUS value (or removes it) in `Drop`. Manual restore lines
+/// are skipped when an assertion panics mid-test, leaking a bad `CODEGRAPH_DIR`
+/// into every later test in this binary; `Drop` runs on the unwind path too, so
+/// the restoration is panic-safe. Holds the [`ENV_LOCK`] for its whole lifetime.
+struct EnvGuard {
+    prev: Option<std::ffi::OsString>,
+    _lock: std::sync::MutexGuard<'static, ()>,
+}
+
+impl EnvGuard {
+    fn set(value: &str) -> Self {
+        let lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let prev = std::env::var_os("CODEGRAPH_DIR");
+        // SAFETY: the ENV_LOCK held for this guard's lifetime serializes every
+        // `CODEGRAPH_DIR` mutation in this test binary, and `Drop` restores the
+        // prior value on both the normal and the unwind path.
+        unsafe { std::env::set_var("CODEGRAPH_DIR", value) };
+        Self { prev, _lock: lock }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        // SAFETY: still holding the ENV_LOCK, so no other test thread is reading
+        // or writing `CODEGRAPH_DIR` while it is restored.
+        match self.prev.take() {
+            Some(v) => unsafe { std::env::set_var("CODEGRAPH_DIR", v) },
+            None => unsafe { std::env::remove_var("CODEGRAPH_DIR") },
+        }
+    }
+}
+
 fn workspace_root() -> PathBuf {
     Path::new(env!("CARGO_MANIFEST_DIR"))
         .join("..")
@@ -85,14 +118,10 @@ fn tool_call_search(project: &Path, project_path_arg: &str) -> Value {
 /// return results — proving the MCP path opens the DB the CLI init would write.
 #[test]
 fn configured_relative_root_mcp_opens_identity_sibling_db() {
-    let _env = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
     let dir = unique_dir("rel");
     let base = &dir.path;
 
-    let prev = std::env::var_os("CODEGRAPH_DIR");
-    // SAFETY: this test binary runs single-threaded per test process; the env is
-    // set before any resolve/DB access and restored before returning.
-    unsafe { std::env::set_var("CODEGRAPH_DIR", "cache") };
+    let _env = EnvGuard::set("cache");
 
     let paths = codegraph_core::IndexPaths::resolve(base, Some("cache")).expect("resolve");
     stage_mini_db_at(&paths.current_db(), base);
@@ -103,11 +132,6 @@ fn configured_relative_root_mcp_opens_identity_sibling_db() {
 
     let resp = tool_call_search(base, base.to_str().unwrap());
 
-    match prev {
-        Some(v) => unsafe { std::env::set_var("CODEGRAPH_DIR", v) },
-        None => unsafe { std::env::remove_var("CODEGRAPH_DIR") },
-    }
-
     let text = resp["result"]["content"][0]["text"]
         .as_str()
         .expect("tool content text");
@@ -128,7 +152,6 @@ fn configured_relative_root_mcp_opens_identity_sibling_db() {
 /// shared absolute root.
 #[test]
 fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
-    let _env = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
     let dir = unique_dir("abs");
     let holder = &dir.path;
     let project_a = holder.join("a");
@@ -138,10 +161,8 @@ fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
     fs::create_dir_all(&project_b).unwrap();
     fs::create_dir_all(holder.join("shared")).unwrap();
 
-    let prev = std::env::var_os("CODEGRAPH_DIR");
     let shared_str = shared.to_string_lossy().into_owned();
-    // SAFETY: single-threaded test process; restored before returning.
-    unsafe { std::env::set_var("CODEGRAPH_DIR", &shared_str) };
+    let _env = EnvGuard::set(&shared_str);
 
     let paths_a = codegraph_core::IndexPaths::resolve(&project_a, Some(&shared_str)).expect("a");
     stage_mini_db_at(&paths_a.current_db(), &project_a);
@@ -160,11 +181,6 @@ fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
     let resp_a = tool_call_search(&project_a, project_a.to_str().unwrap());
     let resp_b = tool_call_search(&project_b, project_b.to_str().unwrap());
 
-    match prev {
-        Some(v) => unsafe { std::env::set_var("CODEGRAPH_DIR", v) },
-        None => unsafe { std::env::remove_var("CODEGRAPH_DIR") },
-    }
-
     let text_a = resp_a["result"]["content"][0]["text"]
         .as_str()
         .unwrap_or("");
@@ -178,3 +194,219 @@ fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
         "project B must NOT surface project A's indexed symbols: {text_b}"
     );
 }
+
+/// Snapshot every file path plus its COMPLETE bytes under `root`, sorted — the
+/// nonmutation oracle. Full bytes, never lengths: an equal-length in-place write
+/// keeps the size identical and would slip past a size-only snapshot.
+fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
+    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, Vec<u8>)>) {
+        let Ok(entries) = fs::read_dir(dir) else {
+            return;
+        };
+        for entry in entries.filter_map(Result::ok) {
+            let path = entry.path();
+            let Ok(meta) = fs::symlink_metadata(&path) else {
+                continue;
+            };
+            if meta.is_dir() {
+                walk(&path, base, out);
+            } else {
+                let rel = path
+                    .strip_prefix(base)
+                    .unwrap_or(&path)
+                    .to_string_lossy()
+                    .into_owned();
+                out.push((rel, fs::read(&path).unwrap_or_default()));
+            }
+        }
+    }
+    let mut out = Vec::new();
+    walk(root, root, &mut out);
+    out.sort();
+    out
+}
+
+/// An INVALID `CODEGRAPH_DIR` must fail closed on the REAL MCP public surface —
+/// it must not silently fall back to the default `.codegraph-v2` namespace.
+///
+/// A TRAP database is staged at the default location `<project>/.codegraph-v2/
+/// codegraph.db` (the very path a `.`-alias fallback would open) and
+/// `CODEGRAPH_DIR=.` is set, which `IndexPaths::resolve` refuses because it
+/// aliases the project root. A real `tools/call codegraph_search` must then:
+/// surface the actionable invalid-configuration diagnostic, NOT the generic "No
+/// indexed project" miss; serve NONE of the trap DB's symbols; and mutate zero
+/// bytes of the project tree (trap DB included).
+#[test]
+fn invalid_configured_root_mcp_fails_closed_and_never_serves_trap_default_db() {
+    let dir = unique_dir("trap");
+    let project = dir.path.join("mini");
+    fs::create_dir_all(&project).unwrap();
+
+    let trap_db = project
+        .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
+        .join("codegraph.db");
+    stage_mini_db_at(&trap_db, &project);
+    assert!(
+        trap_db.is_file(),
+        "sanity: the trap DB must exist at the default namespace a fallback would open"
+    );
+
+    let _env = EnvGuard::set(".");
+    assert!(
+        codegraph_core::IndexPaths::resolve(&project, Some(".")).is_err(),
+        "sanity: `CODEGRAPH_DIR=.` must be refused by the path authority"
+    );
+
+    let before = tree_snapshot(&project);
+    let resp = tool_call_search(&project, project.to_str().unwrap());
+    let after = tree_snapshot(&project);
+
+    let text = resp["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string();
+    let whole = serde_json::to_string(&resp).unwrap();
+
+    assert_eq!(
+        resp["result"]["isError"],
+        json!(true),
+        "an invalid configured root must make the tool call fail closed: {whole}"
+    );
+    assert!(
+        text.contains("CODEGRAPH_DIR"),
+        "the error must name the offending configuration: {text}"
+    );
+    assert!(
+        text.contains("project root itself"),
+        "the error must carry the STABLE `IndexPaths` reason (the `.` alias \
+         resolves to the project root itself), not a generic message: {text}"
+    );
+    assert!(
+        !text.contains("No indexed project"),
+        "an invalid configuration must NOT masquerade as an un-init'd project: {text}"
+    );
+    assert!(
+        !whole.contains("Counter") && !whole.contains("increment") && !whole.contains("math.ts"),
+        "the trap DB at the default namespace must NEVER be served: {whole}"
+    );
+
+    let mut diffs: Vec<String> = Vec::new();
+    let before_map: std::collections::BTreeMap<&str, &Vec<u8>> =
+        before.iter().map(|(p, b)| (p.as_str(), b)).collect();
+    let after_map: std::collections::BTreeMap<&str, &Vec<u8>> =
+        after.iter().map(|(p, b)| (p.as_str(), b)).collect();
+    for (path, bytes) in &before_map {
+        match after_map.get(path) {
+            None => diffs.push(format!("removed: {path}")),
+            Some(other) if other != bytes => diffs.push(format!("bytes changed: {path}")),
+            Some(_) => {}
+        }
+    }
+    for path in after_map.keys() {
+        if !before_map.contains_key(path) {
+            diffs.push(format!("created: {path}"));
+        }
+    }
+    assert!(
+        diffs.is_empty(),
+        "a fail-closed tool call must leave the project tree (trap DB included) \
+         byte-for-byte unchanged, but changed: {diffs:?}"
+    );
+}
+
+/// The rmcp front-end (the SHIPPED transport) must fail closed identically: the
+/// same trap DB at the default namespace, the same refused `CODEGRAPH_DIR=.`, a
+/// real rmcp `tools/call` over a duplex transport. Proves the invalid-config
+/// state survives BOTH tool-call paths, not just the hand-rolled one.
+#[test]
+fn invalid_configured_root_rmcp_fails_closed_and_never_serves_trap_default_db() {
+    let dir = unique_dir("trap-rmcp");
+    let project = dir.path.join("mini");
+    fs::create_dir_all(&project).unwrap();
+    stage_mini_db_at(
+        &project
+            .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
+            .join("codegraph.db"),
+        &project,
+    );
+
+    let _env = EnvGuard::set(".");
+
+    let before = tree_snapshot(&project);
+    let resp = rmcp_tool_call_search(&project);
+    let after = tree_snapshot(&project);
+
+    let whole = serde_json::to_string(&resp).unwrap();
+    assert_eq!(
+        resp["isError"],
+        json!(true),
+        "rmcp must fail closed on an invalid configured root: {whole}"
+    );
+    let text = resp["content"][0]["text"].as_str().unwrap_or_default();
+    assert!(
+        text.contains("CODEGRAPH_DIR") && text.contains("project root itself"),
+        "rmcp must surface the actionable IndexPaths diagnostic: {text}"
+    );
+    assert!(
+        !text.contains("No indexed project"),
+        "rmcp must not mask an invalid configuration as an un-init'd project: {text}"
+    );
+    assert!(
+        !whole.contains("Counter") && !whole.contains("increment") && !whole.contains("math.ts"),
+        "rmcp must NEVER serve the trap DB at the default namespace: {whole}"
+    );
+    assert_eq!(
+        before, after,
+        "a fail-closed rmcp tool call must mutate zero project bytes"
+    );
+}
+
+/// Drive ONE real rmcp `tools/call codegraph_search` against `project` over a
+/// `tokio::io::duplex` transport, returning the serialized `CallToolResult`.
+fn rmcp_tool_call_search(project: &Path) -> Value {
+    use rmcp::ServiceExt;
+    use rmcp::model::{
+        CallToolRequestParams, ClientCapabilities, ClientInfo, Implementation, ProtocolVersion,
+    };
+
+    let project = project.to_path_buf();
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .expect("tokio runtime");
+    rt.block_on(async move {
+        let (client_io, server_io) = tokio::io::duplex(1024 * 1024);
+        let handler =
+            codegraph_mcp::rmcp_handler::CodeGraphHandler::new(Some(project.to_path_buf()));
+        let server = tokio::spawn(async move {
+            if let Ok(running) = handler.serve(server_io).await {
+                let _ = running.waiting().await;
+            }
+        });
+        let client = ClientInfo::new(
+            ClientCapabilities::default(),
+            Implementation::new("cfgroot", "0"),
+        )
+        .with_protocol_version(ProtocolVersion::V_2024_11_05)
+        .serve(client_io)
+        .await
+        .expect("rmcp handshake");
+
+        let mut args = serde_json::Map::new();
+        args.insert("query".to_string(), json!("add"));
+        args.insert(
+            "projectPath".to_string(),
+            json!(project.to_str().expect("utf8 project path")),
+        );
+        let result = client
+            .call_tool(
+                CallToolRequestParams::new("codegraph_search".to_string()).with_arguments(args),
+            )
+            .await
+            .expect("rmcp call_tool");
+        let value = serde_json::to_value(&result).expect("serialize CallToolResult");
+        let _ = client.cancel().await;
+        let _ = server.await;
+        value
+    })
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index c6f0e78..c99f197 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -605,3 +605,142 @@ status-fail-closed / MCP-configured-root regressions, and `codegraph-bench`
 golden byte-stability); `bash scripts/guardrail.sh` exit 0. No plan-level
 architecture change was required; state-slot / lease / Store `open_for_*` /
 uninit lifecycle and Batches A–E remain out of scope.
+
+## Batch M — path-authority correction #3: byte-proof snapshots + reachable invalid-config state (2026-07-25)
+
+### Why this follow-up exists
+
+Verification of correction #2 (commit `7652267`) rejected TWO of its claims as
+overclaims. This entry SUPERSEDES those two claims; nothing above is erased, and
+commits `b5a66f2`, `8aeefc4`, `f6ff9e2`, `7652267` all stay intact — this is a
+NEW correction commit (no amend). Frozen plan/manifest/support hashes,
+`UPSTREAM.md`, `KNOWN_DIFFS.md`, goldens, schema, and node-id logic are
+untouched; `Cargo.lock` is still `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+### Superseded overclaims
+
+1. **"mutate zero bytes" was not byte proof.** Correction #2's
+   `status_fails_closed_on_invalid_configured_root_without_mutation_via_cli`
+   compared a `tree_snapshot` of `(relative path, byte LENGTH)` pairs. An
+   equal-length in-place write leaves every length identical, so the assertion
+   could not distinguish "unchanged" from "same-size content swap": size equality
+   is NOT evidence of byte identity. The prior wording claiming the command
+   "mutates zero bytes" therefore claimed more than the oracle proved.
+
+2. **The invalid-`CODEGRAPH_DIR` state was still masked on the MCP surface.**
+   Correction #2 made `roots::db_path_for` return `None` on a resolve failure and
+   routed both MCP front-ends through the `db_exists_for` predicate, which
+   collapsed "unsafe configured root" and "valid root, absent DB" into one
+   `false`. Both `McpServer::handle_tools_call` and the rmcp
+   `CodeGraphHandler::call_tool` consumed that boolean BEFORE
+   `CodeGraphEngine::open` could run, so an invalid root emitted the generic
+   `No indexed project …, or run codegraph init there.` message and the
+   actionable `IndexPaths` diagnostic was unreachable through either front-end.
+   Correction #2's claim that the fail-closed error "is surfaced by
+   `CodeGraphEngine::open` when a tool actually runs" was therefore false for the
+   invalid-config case: the call never reached `open`.
+
+### Fixes
+
+1. **Byte-complete nonmutation oracle.** `tree_snapshot` (CLI
+   `batch_m_v2_namespace.rs`) now captures `(relative path, COMPLETE file bytes)`
+   using `symlink_metadata` (a symlink is recorded as an entry, never followed).
+   The comparison moved into `assert_tree_bytes_unchanged`, which diffs the byte
+   maps and reports only the offending paths (created / removed / bytes changed)
+   instead of dumping every file's contents into the failure message. New harness
+   self-test `tree_snapshot_detects_equal_length_byte_mutation` flips ONE byte
+   without changing any length and asserts (via `catch_unwind`) that the
+   nonmutation assertion FAILS — proving the oracle now detects exactly the
+   mutation class the size-only snapshot missed.
+
+2. **Typed root state, reachable through both front-ends.** `roots.rs` gained
+   `RootStatus { Indexed, Absent, Invalid(String) }` and `probe_root`, built on a
+   pure `classify_resolve` over the `IndexPaths::resolve` RESULT — the state is
+   discriminated by the error VARIANT, never by parsing a rendered string. An
+   `IndexPathsError::ProjectInaccessible` stays `Absent` (a bogus `projectPath` is
+   a missing project, not a bad configuration); every other variant is
+   `Invalid`, carrying the stable diagnostic verbatim. `db_exists_for` is now
+   `matches!(probe_root(..), Indexed)`, so adoption and the `tools/list` schema
+   selector keep their unchanged boolean semantics.
+
+   `roots::resolve_project_arg` is the single shared resolver both front-ends
+   call, returning `ProjectArg { Resolved, InvalidConfig(String), NotIndexed }`.
+   Candidate ORDER is preserved exactly (absolute raw → cwd-join → bare raw →
+   default-by-basename; `None` raw → default): an INDEXED candidate still wins
+   immediately, so a valid configured root resolves normally even when an earlier
+   candidate is misconfigured; only when NO candidate is indexed is the FIRST
+   invalid diagnostic surfaced (fail closed), and an all-absent candidate set
+   stays the genuine `NotIndexed` "run `codegraph init`" case.
+   `McpServer::handle_tools_call` and the rmcp `call_tool` both map
+   `InvalidConfig` to the shared `roots::invalid_config_message`, which embeds the
+   verbatim `IndexPaths` reason plus the remedy. `server.rs` / `rmcp_handler.rs`
+   deleted their duplicated candidate loops in favor of the shared resolver, so
+   the two front-ends cannot drift.
+
+3. **Real public-surface trap-DB regressions.** `mcp_configured_root.rs` gained
+   a panic-safe RAII `EnvGuard` that holds the `ENV_LOCK` and restores the prior
+   `CODEGRAPH_DIR` in `Drop` (the previous manual restore lines were skipped on an
+   assertion panic, leaking a bad value into every later test in the binary); both
+   pre-existing tests were converted to it. Two new tests stage a TRAP copy of the
+   golden mini DB at the DEFAULT namespace `<project>/.codegraph-v2/codegraph.db`
+   — precisely the path a silent fallback would open — set the refused
+   `CODEGRAPH_DIR=.`, and drive a real `codegraph_search` tool call:
+   `invalid_configured_root_mcp_fails_closed_and_never_serves_trap_default_db`
+   (hand-rolled `McpServer` over stdio) and
+   `invalid_configured_root_rmcp_fails_closed_and_never_serves_trap_default_db`
+   (the SHIPPED rmcp handler over a duplex transport with a real rmcp client).
+   Each asserts `isError == true`; that the text carries the stable reason
+   (`CODEGRAPH_DIR` + `project root itself`); that it is NOT the generic
+   `No indexed project` message; that NONE of the trap DB's symbols
+   (`Counter`, `increment`, `math.ts`) appear in the response; and that the whole
+   project tree — trap DB included — is byte-for-byte unchanged.
+
+   Both trap tests were confirmed to be REAL regressions: reverting
+   `classify_resolve`'s non-`ProjectInaccessible` arm to `Absent` makes both fail
+   with the exact pre-fix `No indexed project found for projectPath …` text, and
+   restoring the arm makes them pass.
+
+4. **Race-free unit coverage for the typed states.** `roots.rs` added a
+   `resolve_project_arg_with` seam taking the per-candidate classifier as an
+   argument, so candidate order and the three states are asserted with a stub
+   probe — no filesystem, no `CODEGRAPH_DIR` mutation. New tests:
+   `classify_resolve_{valid_present_is_indexed, valid_absent_is_absent,
+invalid_config_is_invalid_with_diagnostic, missing_project_is_absent_not_invalid}`,
+   `resolve_project_arg_none_invalid_default_is_invalid_config`,
+   `resolve_project_arg_indexed_candidate_wins_over_earlier_invalid`,
+   `resolve_project_arg_reports_first_invalid_in_candidate_order`,
+   `resolve_project_arg_all_absent_is_not_indexed`, and
+   `invalid_config_message_carries_detail_and_remedy`.
+
+No existing test was weakened or deleted; the pre-existing resolution unit tests
+were adapted to the typed return via `ProjectArg::resolved()`, keeping their
+original assertions. No dependency was added. State slots, `IndexLease`, Store
+`open_for_*`, migration, uninit/daemon lifecycle, project-scoped `Config`,
+extension/Godot config relocation, and Batches A–E all remain out of scope.
+
+### Verification
+
+All commands run in the implementation worktree on
+`feat/upstream-v1.5-portable-fixes`, each Cargo batch preceded by
+`bash scripts/check-workspace-versions.sh` (OK at 0.40.4 every time):
+
+- `cargo fmt --all --check` — clean.
+- `cargo test -p codegraph-rs --test batch_m_v2_namespace --locked` — 7 passed,
+  0 failed (incl. the new byte-oracle self-test).
+- `cargo test -p codegraph-mcp --test mcp_configured_root --locked` — 4 passed,
+  0 failed (incl. both new trap-DB regressions).
+- `cargo test -p codegraph-mcp --lib --locked` — 256 passed, 0 failed.
+- `cargo check --workspace --all-targets --locked` — clean.
+- `cargo check -p codegraph-core --target x86_64-pc-windows-msvc --all-targets
+--locked` — clean. CROSS-COMPILATION ONLY; no native Windows runtime coverage
+  is claimed.
+- `cargo clippy --workspace --all-targets --locked -- -D warnings` — clean.
+- `cargo test --workspace --locked` — exit 0; 105 suites reporting
+  `test result: ok`, 2671 tests passed, 0 failures (incl. the preserved initial
+  black-box Red and `codegraph-bench` golden byte-stability).
+- `bash scripts/guardrail.sh` — exit 0.
+- `sha256sum Cargo.lock` — `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`
+  (byte-identical).
+
+Red-proof for the invalid-config fix is recorded in Fix 3 above (temporary revert
+⇒ both trap tests fail with the pre-fix generic message; revert restored ⇒ pass).

From a6eac9e0bcb5126c3d74f3af7dd9d9c4c68e2ecc Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 14:29:26 +0800
Subject: [PATCH 11/91] fix(index): make the byte-nonmutation oracle
 fail-closed

The nonmutation oracle added in 7d95634 stat'd entries with
symlink_metadata but read them with fs::read, which follows the link, so
the "never follows links" claim was false. It also converted I/O errors
into false "unchanged" results (read_dir early-return, entry
filter_map(Result::ok), read().unwrap_or_default()) and recorded only
files, hiding empty-directory mutations.

Both oracles now build typed entries: an OS-native relative PathBuf plus
Directory | RegularFile(complete bytes) | Symlink(read_link target).
Every I/O step panics with a path-naming message instead of skipping or
defaulting, and an entry kind without a deterministic exact
representation panics rather than being omitted. Failure messages stay
bounded, naming paths and kind labels but never file bytes.

New cfg(unix)-gated self-tests prove the properties mechanically:
empty-directory creation/removal is detected, a symlink retarget is
detected while an out-of-tree write to its target is not (proving no
follow), and a special entry kind makes the snapshot panic.

Also removes the stale documentation left by the previous correction:
roots::db_path_for and McpServer::engine_for no longer claim
CodeGraphEngine::open surfaces the authoritative invalid-config error,
which the shared typed resolver now raises before any engine is opened,
and the MCP test module doc describes both server front-ends.

Test-only plus comments; no production behavior, dependency, schema,
node-id, or golden change.
---
 .../tests/batch_m_v2_namespace.rs             | 333 +++++++++++++++---
 crates/codegraph-mcp/src/roots.rs             |   6 +-
 crates/codegraph-mcp/src/server.rs            |   8 +-
 .../tests/mcp_configured_root.rs              | 208 ++++++++---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 139 ++++++++
 5 files changed, 591 insertions(+), 103 deletions(-)

diff --git a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
index fcb05cf..4e901a8 100644
--- a/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
+++ b/crates/codegraph-cli/tests/batch_m_v2_namespace.rs
@@ -313,33 +313,129 @@ fn configured_dot_alias_fails_closed_without_mutation_via_cli() {
     );
 }
 
-/// Recursively snapshot every file path plus its COMPLETE bytes under `root`,
-/// sorted, so a command can be proven byte-nonmutating by comparing the
-/// before/after set. The full byte content — not the file LENGTH — is captured:
-/// an equal-length in-place byte mutation leaves the length identical and would
-/// slip past a size-only snapshot, so size equality is NOT evidence of byte
-/// identity. Comparing the bytes themselves detects same-length content changes.
-fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
-    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, Vec<u8>)>) {
-        let Ok(entries) = std::fs::read_dir(dir) else {
-            return;
-        };
-        for entry in entries.filter_map(Result::ok) {
+/// The exact, deterministic representation of ONE filesystem entry in the
+/// nonmutation oracle. Every supported entry kind carries its complete payload,
+/// so equality of two snapshots is real evidence — not a proxy:
+///
+/// - [`EntryKind::Directory`] — presence itself is the payload, so creating or
+///   removing an EMPTY directory is detectable (a file-only snapshot misses it).
+/// - [`EntryKind::RegularFile`] — the COMPLETE bytes, never the length: an
+///   equal-length in-place write keeps the size identical, so size equality is
+///   NOT evidence of byte identity.
+/// - [`EntryKind::Symlink`] — the link TARGET, read with `read_link`; the link
+///   is never followed, so the oracle neither reads through it nor mistakes a
+///   change of the pointed-to file for a mutation of this tree.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+enum EntryKind {
+    Directory,
+    RegularFile(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+/// One snapshot entry: the OS-native relative path (a [`PathBuf`], so the
+/// equality key is never a lossy `to_string_lossy` rendering) plus its exact
+/// payload.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+struct TreeEntry {
+    rel: PathBuf,
+    kind: EntryKind,
+}
+
+/// A bounded, byte-free label for a failure message: names the KIND (and a
+/// length or link target), never the file contents.
+fn kind_label(kind: &EntryKind) -> String {
+    match kind {
+        EntryKind::Directory => "directory".to_string(),
+        EntryKind::RegularFile(bytes) => format!("file[{} bytes]", bytes.len()),
+        EntryKind::Symlink(target) => format!("symlink -> {}", target.display()),
+    }
+}
+
+/// Recursively snapshot EVERY filesystem entry under `root` — directories,
+/// regular files (complete bytes), and symlinks (their targets) — sorted, so a
+/// command can be proven nonmutating by comparing the before/after sets.
+///
+/// FAIL-CLOSED: every I/O step is unwrapped with an explicit panic instead of
+/// being skipped or defaulted. A swallowed `read_dir`/entry error would silently
+/// drop a whole subtree from BOTH snapshots (making a mutation inside it
+/// invisible), and `fs::read(..).unwrap_or_default()` would map an unreadable
+/// file to empty bytes on both sides — each turns a real mutation into a false
+/// "unchanged". An entry kind with no deterministic exact representation (fifo,
+/// socket, device, …) panics rather than being silently omitted.
+fn tree_snapshot(root: &Path) -> Vec<TreeEntry> {
+    fn walk(dir: &Path, base: &Path, out: &mut Vec<TreeEntry>) {
+        let entries = std::fs::read_dir(dir).unwrap_or_else(|e| {
+            panic!(
+                "nonmutation oracle: read_dir({}) failed: {e} — the oracle must fail \
+                 loudly, never silently skip a subtree",
+                dir.display()
+            )
+        });
+        for entry in entries {
+            let entry = entry.unwrap_or_else(|e| {
+                panic!(
+                    "nonmutation oracle: a directory entry of {} could not be read: {e}",
+                    dir.display()
+                )
+            });
             let path = entry.path();
-            let meta = match std::fs::symlink_metadata(&path) {
-                Ok(m) => m,
-                Err(_) => continue,
-            };
-            if meta.is_dir() {
+            let rel = path
+                .strip_prefix(base)
+                .unwrap_or_else(|_| {
+                    panic!(
+                        "nonmutation oracle: {} is not under the snapshot base {}",
+                        path.display(),
+                        base.display()
+                    )
+                })
+                .to_path_buf();
+            // `symlink_metadata` describes the LINK itself, so a symlink is never
+            // resolved to its destination here.
+            let meta = std::fs::symlink_metadata(&path).unwrap_or_else(|e| {
+                panic!(
+                    "nonmutation oracle: symlink_metadata({}) failed: {e}",
+                    path.display()
+                )
+            });
+            let file_type = meta.file_type();
+            if file_type.is_symlink() {
+                let target = std::fs::read_link(&path).unwrap_or_else(|e| {
+                    panic!(
+                        "nonmutation oracle: read_link({}) failed: {e}",
+                        path.display()
+                    )
+                });
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::Symlink(target),
+                });
+            } else if file_type.is_dir() {
+                // Record the directory ITSELF before descending, so an empty
+                // directory's creation/removal is visible.
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::Directory,
+                });
                 walk(&path, base, out);
+            } else if file_type.is_file() {
+                let bytes = std::fs::read(&path).unwrap_or_else(|e| {
+                    panic!(
+                        "nonmutation oracle: read({}) failed: {e} — an unreadable file \
+                         must not be recorded as empty bytes",
+                        path.display()
+                    )
+                });
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::RegularFile(bytes),
+                });
             } else {
-                let rel = path
-                    .strip_prefix(base)
-                    .unwrap_or(&path)
-                    .to_string_lossy()
-                    .into_owned();
-                let bytes = std::fs::read(&path).unwrap_or_default();
-                out.push((rel, bytes));
+                panic!(
+                    "nonmutation oracle: unsupported entry kind at {} ({file_type:?}); no \
+                     deterministic exact representation exists, so the oracle refuses to \
+                     omit it",
+                    path.display()
+                );
             }
         }
     }
@@ -349,40 +445,47 @@ fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
     out
 }
 
-/// Assert two [`tree_snapshot`]s are byte-identical, reporting only the CHANGED
-/// paths (added / removed / same-path-different-bytes). A bare `assert_eq!` on
-/// the snapshots would dump every file's full contents into the failure message;
-/// this compares the same complete bytes but names just the offending paths.
-fn assert_tree_bytes_unchanged(
-    before: &[(String, Vec<u8>)],
-    after: &[(String, Vec<u8>)],
-    context: &str,
-) {
+/// Assert two [`tree_snapshot`]s are EXACTLY equal, reporting only the CHANGED
+/// entries (created / removed / same-path-different-payload). A bare `assert_eq!`
+/// on the snapshots would dump every file's full contents into the failure
+/// message; this compares the same exact payloads but names just the offending
+/// paths and kinds.
+fn assert_tree_bytes_unchanged(before: &[TreeEntry], after: &[TreeEntry], context: &str) {
     let mut diffs: Vec<String> = Vec::new();
-    let before_map: std::collections::BTreeMap<&str, &Vec<u8>> =
-        before.iter().map(|(p, b)| (p.as_str(), b)).collect();
-    let after_map: std::collections::BTreeMap<&str, &Vec<u8>> =
-        after.iter().map(|(p, b)| (p.as_str(), b)).collect();
-    for (path, bytes) in &before_map {
+    let before_map: std::collections::BTreeMap<&Path, &EntryKind> =
+        before.iter().map(|e| (e.rel.as_path(), &e.kind)).collect();
+    let after_map: std::collections::BTreeMap<&Path, &EntryKind> =
+        after.iter().map(|e| (e.rel.as_path(), &e.kind)).collect();
+    for (path, kind) in &before_map {
         match after_map.get(path) {
-            None => diffs.push(format!("removed: {path}")),
-            Some(other) if other != bytes => diffs.push(format!(
-                "bytes changed: {path} ({} -> {} bytes)",
-                bytes.len(),
-                other.len()
+            None => diffs.push(format!(
+                "removed: {} ({})",
+                path.display(),
+                kind_label(kind)
+            )),
+            Some(other) if other != kind => diffs.push(format!(
+                "changed: {} ({} -> {})",
+                path.display(),
+                kind_label(kind),
+                kind_label(other)
             )),
             Some(_) => {}
         }
     }
-    for path in after_map.keys() {
+    for (path, kind) in &after_map {
         if !before_map.contains_key(path) {
-            diffs.push(format!("created: {path}"));
+            diffs.push(format!(
+                "created: {} ({})",
+                path.display(),
+                kind_label(kind)
+            ));
         }
     }
     assert!(
         diffs.is_empty(),
-        "{context}: project tree must be byte-for-byte unchanged (complete file \
-         bytes compared, NOT sizes), but changed: {diffs:?}"
+        "{context}: project tree must be EXACTLY unchanged (complete file bytes, \
+         directory presence, and symlink targets compared — never sizes), but \
+         changed: {diffs:?}"
     );
 }
 
@@ -456,9 +559,13 @@ fn tree_snapshot_detects_equal_length_byte_mutation() {
         after.len(),
         "sanity: the mutation must keep the file set identical"
     );
+    let byte_len = |entry: &TreeEntry| match &entry.kind {
+        EntryKind::RegularFile(bytes) => bytes.len(),
+        other => panic!("sanity: the victim must be a regular file, got {other:?}"),
+    };
     assert_eq!(
-        before[0].1.len(),
-        after[0].1.len(),
+        byte_len(&before[0]),
+        byte_len(&after[0]),
         "sanity: the mutation must keep the byte LENGTH identical, so only a \
          full-byte comparison can detect it"
     );
@@ -466,12 +573,132 @@ fn tree_snapshot_detects_equal_length_byte_mutation() {
         before, after,
         "a same-length byte mutation must change the snapshot"
     );
-    let panicked = std::panic::catch_unwind(|| {
-        assert_tree_bytes_unchanged(&before, &after, "self-test");
+    assert_oracle_rejects(&before, &after, "a same-length byte mutation");
+}
+
+/// The oracle must FAIL on the mutation described by `what`. Wrapped in
+/// `catch_unwind` because [`assert_tree_bytes_unchanged`] proves itself by
+/// panicking; a silent pass here would mean the oracle degraded again.
+fn assert_oracle_rejects(before: &[TreeEntry], after: &[TreeEntry], what: &str) {
+    let outcome = std::panic::catch_unwind(|| {
+        assert_tree_bytes_unchanged(before, after, "self-test");
     });
     assert!(
-        panicked.is_err(),
-        "the nonmutation assertion must FAIL on a same-length byte mutation"
+        outcome.is_err(),
+        "the nonmutation assertion must FAIL on {what}"
+    );
+}
+
+/// Creating or removing an EMPTY directory must be detected. A file-only
+/// snapshot records nothing for an empty directory, so such a mutation would be
+/// invisible — the oracle therefore snapshots directories themselves.
+#[test]
+fn tree_snapshot_detects_empty_directory_mutation() {
+    let dir = TestDir::new("snap-emptydir");
+    let project = dir.path().join("mini");
+    std::fs::create_dir_all(&project).unwrap();
+    std::fs::write(project.join("a.txt"), b"AAAA").unwrap();
+
+    let before = tree_snapshot(&project);
+    let empty = project.join("scratch");
+    std::fs::create_dir(&empty).unwrap();
+    let after_create = tree_snapshot(&project);
+
+    assert_ne!(
+        before, after_create,
+        "creating an EMPTY directory must change the snapshot (no file changed)"
+    );
+    assert_oracle_rejects(&before, &after_create, "an empty-directory creation");
+
+    std::fs::remove_dir(&empty).unwrap();
+    let after_remove = tree_snapshot(&project);
+    assert_eq!(
+        before, after_remove,
+        "removing the empty directory must restore the exact snapshot"
+    );
+    assert_oracle_rejects(&after_create, &after_remove, "an empty-directory removal");
+}
+
+/// A symlink is snapshotted as its TARGET, never followed. Retargeting the link
+/// mutates this tree and must be detected; and because the link is not followed,
+/// a change to the pointed-to file OUTSIDE the tree must NOT be reported as a
+/// mutation of the tree.
+#[cfg(unix)]
+#[test]
+fn tree_snapshot_detects_symlink_target_mutation_without_following() {
+    let dir = TestDir::new("snap-symlink");
+    let outside = dir.path().join("outside");
+    std::fs::create_dir_all(&outside).unwrap();
+    let target_a = outside.join("a.bin");
+    let target_b = outside.join("b.bin");
+    std::fs::write(&target_a, b"AAAA").unwrap();
+    std::fs::write(&target_b, b"BBBB").unwrap();
+
+    let project = dir.path().join("mini");
+    std::fs::create_dir_all(&project).unwrap();
+    let link = project.join("link");
+    std::os::unix::fs::symlink(&target_a, &link).unwrap();
+
+    let before = tree_snapshot(&project);
+    assert_eq!(
+        before,
+        vec![TreeEntry {
+            rel: PathBuf::from("link"),
+            kind: EntryKind::Symlink(target_a.clone()),
+        }],
+        "a symlink must be recorded as its target, not as the pointed-to bytes"
+    );
+
+    // Retarget the link: the tree itself changed.
+    std::fs::remove_file(&link).unwrap();
+    std::os::unix::fs::symlink(&target_b, &link).unwrap();
+    let retargeted = tree_snapshot(&project);
+    assert_ne!(
+        before, retargeted,
+        "retargeting a symlink must change the snapshot"
+    );
+    assert_oracle_rejects(&before, &retargeted, "a symlink retarget");
+
+    // Mutating the pointed-to file outside the tree must NOT read through the
+    // link, so the tree snapshot stays identical.
+    std::fs::remove_file(&link).unwrap();
+    std::os::unix::fs::symlink(&target_a, &link).unwrap();
+    let restored = tree_snapshot(&project);
+    assert_eq!(before, restored, "sanity: the link points at A again");
+    std::fs::write(&target_a, b"ZZZZ").unwrap();
+    let after_outside_write = tree_snapshot(&project);
+    assert_eq!(
+        restored, after_outside_write,
+        "the oracle must NOT follow the link: an outside-the-tree write is not a \
+         mutation of this tree"
+    );
+    assert_tree_bytes_unchanged(&restored, &after_outside_write, "self-test");
+}
+
+/// An entry with no deterministic exact representation must make the oracle
+/// PANIC, never be silently omitted: a skipped entry disappears from BOTH
+/// snapshots, so a mutation of it would read as "unchanged". A unix domain
+/// socket file is the portable-in-std way to create such an entry.
+#[cfg(unix)]
+#[test]
+fn tree_snapshot_fails_loudly_on_unsupported_entry_kind() {
+    let dir = TestDir::new("snap-special");
+    let project = dir.path().join("mini");
+    std::fs::create_dir_all(&project).unwrap();
+    let sock = project.join("s.sock");
+    let _listener = std::os::unix::net::UnixListener::bind(&sock).unwrap();
+
+    let outcome = std::panic::catch_unwind(|| tree_snapshot(&project));
+    let message = outcome
+        .err()
+        .map(|payload| match payload.downcast::<String>() {
+            Ok(s) => *s,
+            Err(_) => "<non-string panic>".to_string(),
+        })
+        .expect("the oracle must PANIC on an unsupported entry kind, not skip it");
+    assert!(
+        message.contains("unsupported entry kind"),
+        "the panic must name the unsupported entry kind: {message}"
     );
 }
 
diff --git a/crates/codegraph-mcp/src/roots.rs b/crates/codegraph-mcp/src/roots.rs
index a026b99..8c60637 100644
--- a/crates/codegraph-mcp/src/roots.rs
+++ b/crates/codegraph-mcp/src/roots.rs
@@ -37,8 +37,10 @@ pub fn format_tool_debug_line(
 /// [`crate::CodeGraphEngine::open`]. Returns `None` when the configured root is
 /// unsafe/aliased/overlapping (a `resolve` failure): callers treat that as "not
 /// an indexed project", which is DISTINCT from a reconstructed default path that
-/// could shadow another project. The authoritative fail-closed error is surfaced
-/// by `CodeGraphEngine::open` when a tool actually runs.
+/// could shadow another project. This helper is for path DISPLAY only and
+/// deliberately drops the reason; the authoritative fail-closed diagnostic comes
+/// from the typed [`probe_root`] / [`resolve_project_arg`] states, which reject
+/// an invalid configured root BEFORE any engine is opened.
 pub fn db_path_for(project_path: &Path) -> Option<PathBuf> {
     codegraph_core::IndexPaths::resolve(
         project_path,
diff --git a/crates/codegraph-mcp/src/server.rs b/crates/codegraph-mcp/src/server.rs
index e2107ab..0d6e25b 100644
--- a/crates/codegraph-mcp/src/server.rs
+++ b/crates/codegraph-mcp/src/server.rs
@@ -523,8 +523,12 @@ impl McpServer {
     /// one (inode/file-index changed). An in-place write keeps the same identity,
     /// so the common path returns the cached engine without reopening.
     fn engine_for(&mut self, project_path: &PathBuf) -> anyhow::Result<&CodeGraphEngine> {
-        // A resolvable configured root yields its DB path; an invalid one fails
-        // closed here (Engine::open re-resolves and surfaces the stable error).
+        // A resolvable configured root yields its DB path. An invalid one is
+        // already rejected upstream by `roots::resolve_project_arg`, which carries
+        // the stable `IndexPaths` diagnostic to the caller before a tool call ever
+        // reaches here; this arm is the defensive backstop for an unresolved DB
+        // path (e.g. a non-tool-call caller), so it fails closed rather than
+        // reconstructing a default namespace.
         let db_path = db_path_for(project_path).ok_or_else(|| {
             anyhow::anyhow!(
                 "invalid CODEGRAPH_DIR configuration for project {}",
diff --git a/crates/codegraph-mcp/tests/mcp_configured_root.rs b/crates/codegraph-mcp/tests/mcp_configured_root.rs
index aab59c0..fd6d5b5 100644
--- a/crates/codegraph-mcp/tests/mcp_configured_root.rs
+++ b/crates/codegraph-mcp/tests/mcp_configured_root.rs
@@ -2,9 +2,11 @@
 //!
 //! Isolated in its OWN test binary (a separate process) because these tests set
 //! the process-global `CODEGRAPH_DIR`; keeping them out of `golden_mcp.rs` avoids
-//! racing that binary's env-sensitive default-surface readers. Each test drives
-//! the REAL `McpServer` over an in-memory stdio pipe and proves the MCP request
-//! path opens the SAME identity-suffixed DB the CLI `init` writes.
+//! racing that binary's env-sensitive default-surface readers. The tests drive a
+//! REAL server front-end — most over an in-memory stdio pipe against `McpServer`,
+//! and one against the SHIPPED rmcp handler over a duplex transport — and prove
+//! the MCP request path opens the SAME identity-suffixed DB the CLI `init`
+//! writes, and fails closed identically on an invalid configured root.
 
 use std::fs;
 use std::io::Cursor;
@@ -195,28 +197,116 @@ fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
     );
 }
 
-/// Snapshot every file path plus its COMPLETE bytes under `root`, sorted — the
-/// nonmutation oracle. Full bytes, never lengths: an equal-length in-place write
-/// keeps the size identical and would slip past a size-only snapshot.
-fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
-    fn walk(dir: &Path, base: &Path, out: &mut Vec<(String, Vec<u8>)>) {
-        let Ok(entries) = fs::read_dir(dir) else {
-            return;
-        };
-        for entry in entries.filter_map(Result::ok) {
+/// The exact payload of ONE filesystem entry in the nonmutation oracle: a
+/// directory's mere presence (so an EMPTY directory's creation/removal is
+/// detectable), a regular file's COMPLETE bytes (never its length — an
+/// equal-length in-place write keeps the size identical), or a symlink's TARGET
+/// (the link is never followed).
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+enum EntryKind {
+    Directory,
+    RegularFile(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+/// One snapshot entry keyed by its OS-native relative path, so the equality key
+/// is never a lossy `to_string_lossy` rendering.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+struct TreeEntry {
+    rel: PathBuf,
+    kind: EntryKind,
+}
+
+fn kind_label(kind: &EntryKind) -> String {
+    match kind {
+        EntryKind::Directory => "directory".to_string(),
+        EntryKind::RegularFile(bytes) => format!("file[{} bytes]", bytes.len()),
+        EntryKind::Symlink(target) => format!("symlink -> {}", target.display()),
+    }
+}
+
+/// Snapshot EVERY filesystem entry under `root` — directories, regular files
+/// (complete bytes) and symlinks (their targets) — sorted; the nonmutation
+/// oracle, identical in semantics to the CLI-side one.
+///
+/// FAIL-CLOSED: every I/O step panics on error instead of skipping or
+/// defaulting. A swallowed `read_dir`/entry error would drop a whole subtree
+/// from BOTH snapshots and `fs::read(..).unwrap_or_default()` would record an
+/// unreadable file as empty on both sides — each turns a real mutation into a
+/// false "unchanged". An entry kind with no deterministic exact representation
+/// panics rather than being silently omitted.
+fn tree_snapshot(root: &Path) -> Vec<TreeEntry> {
+    fn walk(dir: &Path, base: &Path, out: &mut Vec<TreeEntry>) {
+        let entries = fs::read_dir(dir).unwrap_or_else(|e| {
+            panic!(
+                "nonmutation oracle: read_dir({}) failed: {e} — the oracle must fail \
+                 loudly, never silently skip a subtree",
+                dir.display()
+            )
+        });
+        for entry in entries {
+            let entry = entry.unwrap_or_else(|e| {
+                panic!(
+                    "nonmutation oracle: a directory entry of {} could not be read: {e}",
+                    dir.display()
+                )
+            });
             let path = entry.path();
-            let Ok(meta) = fs::symlink_metadata(&path) else {
-                continue;
-            };
-            if meta.is_dir() {
+            let rel = path
+                .strip_prefix(base)
+                .unwrap_or_else(|_| {
+                    panic!(
+                        "nonmutation oracle: {} is not under the snapshot base {}",
+                        path.display(),
+                        base.display()
+                    )
+                })
+                .to_path_buf();
+            // `symlink_metadata` describes the LINK itself, so a symlink is never
+            // resolved to its destination here.
+            let meta = fs::symlink_metadata(&path).unwrap_or_else(|e| {
+                panic!(
+                    "nonmutation oracle: symlink_metadata({}) failed: {e}",
+                    path.display()
+                )
+            });
+            let file_type = meta.file_type();
+            if file_type.is_symlink() {
+                let target = fs::read_link(&path).unwrap_or_else(|e| {
+                    panic!(
+                        "nonmutation oracle: read_link({}) failed: {e}",
+                        path.display()
+                    )
+                });
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::Symlink(target),
+                });
+            } else if file_type.is_dir() {
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::Directory,
+                });
                 walk(&path, base, out);
+            } else if file_type.is_file() {
+                let bytes = fs::read(&path).unwrap_or_else(|e| {
+                    panic!(
+                        "nonmutation oracle: read({}) failed: {e} — an unreadable file \
+                         must not be recorded as empty bytes",
+                        path.display()
+                    )
+                });
+                out.push(TreeEntry {
+                    rel,
+                    kind: EntryKind::RegularFile(bytes),
+                });
             } else {
-                let rel = path
-                    .strip_prefix(base)
-                    .unwrap_or(&path)
-                    .to_string_lossy()
-                    .into_owned();
-                out.push((rel, fs::read(&path).unwrap_or_default()));
+                panic!(
+                    "nonmutation oracle: unsupported entry kind at {} ({file_type:?}); no \
+                     deterministic exact representation exists, so the oracle refuses to \
+                     omit it",
+                    path.display()
+                );
             }
         }
     }
@@ -226,6 +316,48 @@ fn tree_snapshot(root: &Path) -> Vec<(String, Vec<u8>)> {
     out
 }
 
+/// Assert two [`tree_snapshot`]s are EXACTLY equal, naming only the changed
+/// entries: a bare `assert_eq!` would dump every file's contents (the golden DB
+/// included) into the failure message.
+fn assert_tree_unchanged(before: &[TreeEntry], after: &[TreeEntry], context: &str) {
+    let mut diffs: Vec<String> = Vec::new();
+    let before_map: std::collections::BTreeMap<&Path, &EntryKind> =
+        before.iter().map(|e| (e.rel.as_path(), &e.kind)).collect();
+    let after_map: std::collections::BTreeMap<&Path, &EntryKind> =
+        after.iter().map(|e| (e.rel.as_path(), &e.kind)).collect();
+    for (path, kind) in &before_map {
+        match after_map.get(path) {
+            None => diffs.push(format!(
+                "removed: {} ({})",
+                path.display(),
+                kind_label(kind)
+            )),
+            Some(other) if other != kind => diffs.push(format!(
+                "changed: {} ({} -> {})",
+                path.display(),
+                kind_label(kind),
+                kind_label(other)
+            )),
+            Some(_) => {}
+        }
+    }
+    for (path, kind) in &after_map {
+        if !before_map.contains_key(path) {
+            diffs.push(format!(
+                "created: {} ({})",
+                path.display(),
+                kind_label(kind)
+            ));
+        }
+    }
+    assert!(
+        diffs.is_empty(),
+        "{context}: the project tree must be EXACTLY unchanged (complete file bytes, \
+         directory presence, and symlink targets compared — never sizes), but \
+         changed: {diffs:?}"
+    );
+}
+
 /// An INVALID `CODEGRAPH_DIR` must fail closed on the REAL MCP public surface —
 /// it must not silently fall back to the default `.codegraph-v2` namespace.
 ///
@@ -290,27 +422,10 @@ fn invalid_configured_root_mcp_fails_closed_and_never_serves_trap_default_db() {
         "the trap DB at the default namespace must NEVER be served: {whole}"
     );
 
-    let mut diffs: Vec<String> = Vec::new();
-    let before_map: std::collections::BTreeMap<&str, &Vec<u8>> =
-        before.iter().map(|(p, b)| (p.as_str(), b)).collect();
-    let after_map: std::collections::BTreeMap<&str, &Vec<u8>> =
-        after.iter().map(|(p, b)| (p.as_str(), b)).collect();
-    for (path, bytes) in &before_map {
-        match after_map.get(path) {
-            None => diffs.push(format!("removed: {path}")),
-            Some(other) if other != bytes => diffs.push(format!("bytes changed: {path}")),
-            Some(_) => {}
-        }
-    }
-    for path in after_map.keys() {
-        if !before_map.contains_key(path) {
-            diffs.push(format!("created: {path}"));
-        }
-    }
-    assert!(
-        diffs.is_empty(),
-        "a fail-closed tool call must leave the project tree (trap DB included) \
-         byte-for-byte unchanged, but changed: {diffs:?}"
+    assert_tree_unchanged(
+        &before,
+        &after,
+        "a fail-closed tool call must leave the project tree (trap DB included) unchanged",
     );
 }
 
@@ -355,9 +470,10 @@ fn invalid_configured_root_rmcp_fails_closed_and_never_serves_trap_default_db()
         !whole.contains("Counter") && !whole.contains("increment") && !whole.contains("math.ts"),
         "rmcp must NEVER serve the trap DB at the default namespace: {whole}"
     );
-    assert_eq!(
-        before, after,
-        "a fail-closed rmcp tool call must mutate zero project bytes"
+    assert_tree_unchanged(
+        &before,
+        &after,
+        "a fail-closed rmcp tool call must mutate zero project bytes",
     );
 }
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index c99f197..cfeeec9 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -744,3 +744,142 @@ All commands run in the implementation worktree on
 
 Red-proof for the invalid-config fix is recorded in Fix 3 above (temporary revert
 ⇒ both trap tests fail with the pre-fix generic message; revert restored ⇒ pass).
+
+## Batch M — path-authority correction #4: fail-closed nonmutation oracle + stale-doc cleanup (2026-07-25)
+
+### Why this follow-up exists
+
+Manual review of commit `7d95634` (correction #3) found the byte-nonmutation
+oracle it introduced was still not fail-closed, and that correction #3 left two
+superseded `Engine::open` claims in the source docs. This is an APPEND-ONLY
+correction; `7d95634` and every earlier commit are preserved unamended.
+
+### Superseded overclaims (from correction #3)
+
+1. **"a symlink is recorded as an entry, never followed" — FALSE.** The helper
+   stat'd with `symlink_metadata` but then read the payload with
+   `fs::read(&path)`, which FOLLOWS the link. A symlink's recorded bytes were the
+   pointed-to file's bytes, so an out-of-tree write showed up as a mutation of
+   the tree, while a retarget between two same-content files did not.
+
+2. **"whole-tree byte proof" — TOO STRONG.** Four holes could each produce a
+   FALSE "unchanged":
+   - `let Ok(entries) = read_dir(dir) else { return }` silently dropped an entire
+     subtree from BOTH snapshots.
+   - `entries.filter_map(Result::ok)` silently dropped individual entries.
+   - `fs::read(..).unwrap_or_default()` recorded an unreadable file as EMPTY
+     bytes on both sides.
+   - Only FILES were recorded, so creating or removing an EMPTY directory was
+     invisible.
+     Special entry kinds (fifo, socket, device) also fell into the "else" file arm
+     and were read as bytes or silently defaulted.
+
+3. **`roots::db_path_for` rustdoc and `McpServer::engine_for` comment** still
+   said the authoritative fail-closed error "is surfaced by
+   `CodeGraphEngine::open` when a tool actually runs". Correction #3 itself moved
+   that rejection EARLIER, into the shared typed resolver, so the sentences
+   described behavior that no longer exists.
+
+4. **`mcp_configured_root.rs` module doc** said "Each test drives the REAL
+   `McpServer` over an in-memory stdio pipe", but correction #3 added an rmcp
+   handler test over a duplex transport.
+
+### Fixes
+
+1. **Typed, exact, fail-closed snapshot entries.** Both oracles (CLI
+   `batch_m_v2_namespace.rs` and MCP `mcp_configured_root.rs`) now build
+   `Vec<TreeEntry>` where `TreeEntry { rel: PathBuf, kind: EntryKind }` and
+   `EntryKind ∈ { Directory, RegularFile(Vec<u8>), Symlink(PathBuf) }`:
+   - `rel` is an OS-native `PathBuf`, so the equality key is never a lossy
+     `to_string_lossy()` rendering.
+   - `Directory` records presence itself, so an EMPTY directory's creation or
+     removal is detectable.
+   - `RegularFile` carries the COMPLETE bytes (never a length).
+   - `Symlink` carries the target from `read_link`; the link is NEVER read
+     through, so an out-of-tree write to the target is correctly NOT a mutation
+     of this tree, and a retarget IS.
+
+2. **Fail loudly, never skip.** Every I/O step (`read_dir`, each entry,
+   `symlink_metadata`, `read_link`, `read`, `strip_prefix`) now panics with a
+   path-naming message instead of `return` / `filter_map(Result::ok)` /
+   `unwrap_or_default()`. An entry kind with no deterministic exact
+   representation panics rather than being omitted.
+
+3. **Bounded failure messages.** `assert_tree_bytes_unchanged` (CLI) and the new
+   `assert_tree_unchanged` (MCP) diff the typed maps and report only
+   `created/removed/changed: <path> (<kind label>)`, where the label is
+   `directory` / `file[N bytes]` / `symlink -> <target>` — never file contents.
+   The MCP trap tests' inline diff loop and the rmcp test's bare
+   `assert_eq!(before, after)` (which would have dumped the whole golden DB into
+   a failure message) both now call that helper.
+
+4. **New oracle self-tests** (CLI), each proving a property mechanically:
+   - `tree_snapshot_detects_empty_directory_mutation` — creating an empty
+     directory changes the snapshot and the assertion FAILS; removing it restores
+     the exact snapshot.
+   - `tree_snapshot_detects_symlink_target_mutation_without_following`
+     (`#[cfg(unix)]`) — the link is recorded as `Symlink(target)`; a retarget
+     FAILS the assertion; a write to the pointed-to file OUTSIDE the tree leaves
+     the snapshot identical (proving no follow).
+   - `tree_snapshot_fails_loudly_on_unsupported_entry_kind` (`#[cfg(unix)]`) — a
+     unix-socket file makes `tree_snapshot` PANIC with "unsupported entry kind".
+   - The pre-existing `tree_snapshot_detects_equal_length_byte_mutation` is
+     preserved, now asserting the byte length through `EntryKind::RegularFile`.
+     The `#[cfg(unix)]` gating keeps portable compilation intact; no Windows
+     runtime behavior is claimed.
+
+5. **Stale docs corrected.** `roots::db_path_for`'s rustdoc now says it is for
+   path DISPLAY only and that the authoritative diagnostic comes from the typed
+   `probe_root` / `resolve_project_arg` states, which reject an invalid configured
+   root BEFORE any engine is opened. `McpServer::engine_for`'s comment now says
+   the invalid root is already rejected upstream by `roots::resolve_project_arg`
+   and that this arm is the defensive backstop for an unresolved DB path.
+   `mcp_configured_root.rs`'s module doc now describes both front-ends.
+
+No production behavior changed: fixes 1–4 are test-only and fix 5 is comments
+plus rustdoc. No dependency was added, no assertion was weakened, and no
+extraction / schema / node-id / golden surface was touched.
+
+### Red proof for the new oracle properties
+
+Each property was proven to be a REAL regression by temporarily reverting the
+production arm and observing the failure, then restoring it:
+
+- Removing the `EntryKind::Directory` push (pre-fix file-only walk) ⇒
+  `tree_snapshot_detects_empty_directory_mutation` FAILS with
+  `assertion left != right failed: creating an EMPTY directory must change the
+snapshot (no file changed)`, both sides `[TreeEntry { rel: "a.txt", … }]`.
+- Restoring the pre-fix follow-the-link read (`fs::read` in the symlink arm,
+  `unwrap_or_default`) ⇒
+  `tree_snapshot_detects_symlink_target_mutation_without_following` FAILS with
+  `left: [TreeEntry { rel: "link", kind: RegularFile([65, 65, 65, 65]) }]` vs
+  `right: [… kind: Symlink("…/outside/a.bin") }]` — the verbatim evidence that
+  the old helper read THROUGH the link.
+- Both reverts were undone; the full suite is green below.
+
+### Verification
+
+All commands run in the implementation worktree on
+`feat/upstream-v1.5-portable-fixes`, each Cargo batch preceded by
+`bash scripts/check-workspace-versions.sh` (OK at 0.40.4 every time):
+
+- `cargo fmt --all --check` — clean.
+- `cargo test -p codegraph-rs --test batch_m_v2_namespace --locked` — 10 passed,
+  0 failed (7 pre-existing + 3 new oracle self-tests).
+- `cargo test -p codegraph-mcp --test mcp_configured_root --locked` — 4 passed,
+  0 failed.
+- `cargo test -p codegraph-mcp --lib --locked` — 256 passed, 0 failed.
+- `cargo check --workspace --all-targets --locked` — clean.
+- `cargo check -p codegraph-core --target x86_64-pc-windows-msvc --all-targets
+--locked` — clean. CROSS-COMPILATION ONLY; no native Windows runtime coverage is
+  claimed. (A wider Windows `--all-targets` check across `codegraph-rs` /
+  `codegraph-mcp` is not runnable in this environment: their C dependencies need
+  the MSVC `lib.exe`, absent on this Linux host.)
+- `cargo clippy --workspace --all-targets --locked -- -D warnings` — clean.
+- `cargo test --workspace --locked` — exit 0; 105 suites reporting
+  `test result: ok`, 2674 tests passed, 0 failures (2671 before + the 3 new
+  oracle self-tests), incl. the preserved initial black-box Red and
+  `codegraph-bench` golden byte-stability.
+- `bash scripts/guardrail.sh` — exit 0.
+- `sha256sum Cargo.lock` — `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`
+  (byte-identical before and after).

From 4d5a39ccad50e557bc84af25512d109f2d006d7f Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 15:36:16 +0800
Subject: [PATCH 12/91] feat(index): add read-only state classifier

---
 crates/codegraph-cli/src/main.rs            |  14 +-
 crates/codegraph-store/src/index_state.rs   | 895 ++++++++++++++++++++
 crates/codegraph-store/src/lib.rs           |   6 +
 crates/codegraph-store/tests/index_state.rs | 657 ++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md   |  37 +
 5 files changed, 1602 insertions(+), 7 deletions(-)
 create mode 100644 crates/codegraph-store/src/index_state.rs
 create mode 100644 crates/codegraph-store/tests/index_state.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index f270734..bc8ade4 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -40,7 +40,6 @@ mod segments;
 mod structural_gate;
 
 const VERSION: &str = env!("CARGO_PKG_VERSION");
-const EXTRACTION_VERSION: i64 = 1;
 
 fn main() {
     let cli = Cli::parse();
@@ -1285,17 +1284,18 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let last_indexed = latest_indexed_at(&store)?;
     let built_with_version = store.get_project_metadata("indexed_with_version")?;
     let built_with_extraction_version = store
-        .get_project_metadata("indexed_with_extraction_version")?
-        .and_then(|v| v.parse::<i64>().ok());
+        .get_project_metadata(codegraph_store::EXTRACTION_VERSION_KEY)?
+        .and_then(|v| v.parse::<u64>().ok());
     let reindex_recommended = last_indexed.is_some()
-        && built_with_extraction_version.is_none_or(|v| v < EXTRACTION_VERSION);
+        && built_with_extraction_version
+            .is_none_or(|v| v < codegraph_store::CURRENT_EXTRACTION_VERSION);
     let resolution_incomplete = store.is_resolution_incomplete()?;
 
     if json_output {
         let mut index_obj = json!({
             "builtWithVersion": built_with_version,
             "builtWithExtractionVersion": built_with_extraction_version,
-            "currentExtractionVersion": EXTRACTION_VERSION,
+            "currentExtractionVersion": codegraph_store::CURRENT_EXTRACTION_VERSION,
             "reindexRecommended": reindex_recommended,
         });
         // #1187: surface the interrupted-index state ONLY when the marker is set,
@@ -3808,8 +3808,8 @@ fn index_project_inner(
     finish_phase(&pb, "Finalized frameworks");
     store.set_project_metadata("indexed_with_version", VERSION)?;
     store.set_project_metadata(
-        "indexed_with_extraction_version",
-        &EXTRACTION_VERSION.to_string(),
+        codegraph_store::EXTRACTION_VERSION_KEY,
+        &codegraph_store::CURRENT_EXTRACTION_VERSION.to_string(),
     )?;
     let pb = phase_spinner("Compacting database", quiet);
     store.compact()?;
diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
new file mode 100644
index 0000000..c8b37b1
--- /dev/null
+++ b/crates/codegraph-store/src/index_state.rs
@@ -0,0 +1,895 @@
+//! Read-only index-state authority: the dual fixed state slots and the typed
+//! classification derived from them.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md`, Batch M ("Store ownership,
+//! version gate, and final publication", plan lines 452-522). This module owns
+//! the SINGLE SOURCE OF TRUTH for the storage protocol / extraction version and
+//! the persisted state-slot contract, plus the classifier that turns the two
+//! fixed slots into an [`ExtractionStatus`].
+//!
+//! # Scope of this slice: READ-ONLY
+//!
+//! This slice is deliberately NONMUTATING and self-contained:
+//!
+//! - it never creates, truncates, renames, or deletes any file or directory
+//!   (not the current root, the permanent lock, a state slot, a temp file, the
+//!   database, a sidecar, or the tombstone);
+//! - it never opens SQLite, so it cannot run schema setup, migrations, WAL
+//!   changes, or `ANALYZE`;
+//! - it exposes NO publication API. State publication, `IndexLease`,
+//!   `Store::open_for_read` / `open_for_status` / `open_for_write`,
+//!   `Store::stamp_extraction_version`, DB-stamp corroboration, migration mode,
+//!   uninit lifecycle, and the daemon/watcher lifecycle all land in LATER Batch M
+//!   slices and are NOT implemented here.
+//!
+//! [`checksum_hex`] and [`canonical_checksum_payload`] are pure functions (no
+//! I/O); they define the byte representation a future publisher must reproduce,
+//! and the tests use them to author fixture slots.
+//!
+//! # Persisted slot contract
+//!
+//! The two fixed files [`IndexPaths::state_slots`] returns —
+//! `<current_root>/index-state.0.json` and `<current_root>/index-state.1.json` —
+//! each hold ONE JSON object with these canonical fields:
+//!
+//! ```json
+//! {
+//!   "sequence": 7,
+//!   "storageProtocol": 2,
+//!   "extractionVersion": 2,
+//!   "phase": "current",
+//!   "projectIdentity": "<64 lowercase hex>",
+//!   "checksum": "<64 lowercase hex>"
+//! }
+//! ```
+//!
+//! - `sequence`, `storageProtocol`, `extractionVersion` are JSON unsigned
+//!   integers (`u64`); `phase`, `projectIdentity`, `checksum` are JSON strings.
+//!   These six names and their JSON types are PROTOCOL-STABLE: a future storage
+//!   protocol may add fields and may add `phase` vocabulary, but must keep these
+//!   six readable so an older binary can still recognize a future namespace.
+//! - Unknown fields are IGNORED (forward compatibility). Missing or wrong-typed
+//!   required fields are `Corrupt`.
+//! - `phase` is exactly one of `building`, `current`, `uninitialized` for
+//!   storage protocol [`CURRENT_STORAGE_PROTOCOL`]; any other value is `Corrupt`.
+//! - `checksum` is the lowercase 64-hex SHA-256 of [`canonical_checksum_payload`],
+//!   which is a fixed ASCII, LF-terminated, field-ordered byte string. It does
+//!   NOT depend on JSON key order, whitespace, pretty-printing, host endianness,
+//!   locale, or line-ending conventions.
+//!
+//! # Classification order (deterministic, typed, never string-matched)
+//!
+//! 1. **Structural defects dominate.** A present slot that cannot be stat'd or
+//!    read, is not a regular file (a directory or symlink at a fixed slot path is
+//!    an INVALID slot, never followed), or whose bytes are not a JSON object with
+//!    the six canonical fields at their canonical types ⇒ [`ExtractionStatus::Corrupt`].
+//!    A present invalid slot is NEVER ignored because the other slot is valid:
+//!    a future writer may have authored it, so it is security-relevant.
+//! 2. **Stable fields are validated before protocol trust.** Every parsed slot,
+//!    including a future-protocol slot, must carry lowercase 64-hex owner and
+//!    checksum strings, a checksum matching the canonical payload (which hashes
+//!    the RAW phase text), and the expected owner. A lower/zero storage protocol
+//!    is unsupported. The first defect, scanning slot 0 then slot 1, is `Corrupt`.
+//!    Current protocol accepts exactly the three known phases; future protocol
+//!    may use an unknown phase only after those stable checks pass.
+//! 3. No validated record at all ⇒ [`ExtractionStatus::Missing`]. A missing
+//!    INACTIVE slot is allowed.
+//! 4. Two validated records with the SAME `sequence` ⇒ `Corrupt`, whether they
+//!    are current/current, future/future, or mixed, and regardless of raw JSON
+//!    formatting.
+//! 5. A validated future-protocol record dominates a current-protocol companion
+//!    regardless of sequence (the highest future sequence wins). Otherwise the
+//!    highest current-protocol record is AUTHORITATIVE. An
+//!    authoritative sequence of [`u64::MAX`] is sequence exhaustion ⇒ `Corrupt`
+//!    (and nonmutating, like every other outcome).
+//! 6. Future storage protocol ⇒ [`ExtractionStatus::Future`]. Otherwise,
+//!    `extractionVersion` above [`CURRENT_EXTRACTION_VERSION`] ⇒
+//!    [`ExtractionStatus::Future`] for EVERY phase, `uninitialized` included.
+//!    Below ⇒ [`ExtractionStatus::Outdated`] preserving the built version. Equal
+//!    ⇒ [`ExtractionStatus::Current`], [`ExtractionStatus::Building`], or
+//!    [`ExtractionStatus::Uninitialized`] by phase.
+//!
+//! Callers must branch on the typed variants and on [`CorruptReason`]; the
+//! `Display` renderings exist for operator messages only and are never parsed.
+
+use std::fmt;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use codegraph_core::IndexPaths;
+use serde::Deserialize;
+
+/// The on-disk storage-protocol version this binary defines. A slot above this
+/// is [`ExtractionStatus::Future`]; below (or zero) is `Corrupt`.
+pub const CURRENT_STORAGE_PROTOCOL: u64 = 2;
+
+/// The extraction-pipeline version this binary produces. This is the single
+/// source of truth: no other crate may define its own copy.
+pub const CURRENT_EXTRACTION_VERSION: u64 = 2;
+
+/// The `project_metadata` key under which a built index records the extraction
+/// version it was produced with. Single source of truth for the key spelling.
+pub const EXTRACTION_VERSION_KEY: &str = "indexed_with_extraction_version";
+
+/// Domain-separation prefix of the canonical checksum payload. Bumping it would
+/// invalidate every existing checksum, so it is versioned independently of the
+/// storage protocol.
+const CHECKSUM_DOMAIN: &str = "codegraph-index-state-v1";
+
+/// The lifecycle phase a state slot records.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum StatePhase {
+    /// A destructive (re)build is in progress; the DB may be absent or partial.
+    Building,
+    /// The namespace holds a completely published index.
+    Current,
+    /// A `uninit --force` was in progress when the namespace last advanced.
+    Uninitialized,
+}
+
+impl StatePhase {
+    /// The exact wire spelling stored in `phase` and hashed into the checksum.
+    #[must_use]
+    pub const fn as_wire(self) -> &'static str {
+        match self {
+            Self::Building => "building",
+            Self::Current => "current",
+            Self::Uninitialized => "uninitialized",
+        }
+    }
+
+    /// Parse a wire `phase` value. `None` for any value outside the exactly
+    /// three supported phases (the caller turns that into `Corrupt`).
+    #[must_use]
+    pub fn from_wire(value: &str) -> Option<Self> {
+        match value {
+            "building" => Some(Self::Building),
+            "current" => Some(Self::Current),
+            "uninitialized" => Some(Self::Uninitialized),
+            _ => None,
+        }
+    }
+}
+
+impl fmt::Display for StatePhase {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_wire())
+    }
+}
+
+/// The canonical byte representation the [`checksum_hex`] digest covers.
+///
+/// It is a pure ASCII, LF-separated, LF-terminated, fixed-field-order string:
+///
+/// ```text
+/// codegraph-index-state-v1\n
+/// sequence=<decimal u64>\n
+/// storageProtocol=<decimal u64>\n
+/// extractionVersion=<decimal u64>\n
+/// phase=<raw JSON phase string>\n
+/// projectIdentity=<64 lowercase hex>\n
+/// ```
+///
+/// The labels, separators, decimal integers, and line endings are exactly the
+/// ASCII bytes shown above. `phase` and `projectIdentity` are inserted verbatim
+/// as UTF-8 (current phases and valid identities are ASCII); no escaping or
+/// normalization is performed. The final byte is one LF. Integer rendering is
+/// locale-independent, so the payload is unaffected by JSON key order,
+/// whitespace, pretty-printing, endianness, or host line-ending conventions.
+#[must_use]
+pub fn canonical_checksum_payload(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    project_identity: &str,
+) -> String {
+    format!(
+        "{CHECKSUM_DOMAIN}\nsequence={sequence}\nstorageProtocol={storage_protocol}\n\
+         extractionVersion={extraction_version}\nphase={phase}\nprojectIdentity={project_identity}\n"
+    )
+}
+
+/// The lowercase 64-hex SHA-256 of [`canonical_checksum_payload`].
+///
+/// The digest comes from `codegraph_core::node_id::hash_content`, the workspace's
+/// existing public exact-SHA-256-hex utility. Reusing it keeps this crate free of
+/// a direct `sha2` dependency (and therefore leaves `Cargo.lock` byte-identical)
+/// without weakening the hash: `hash_content` is a plain SHA-256 over the UTF-8
+/// bytes of its argument, and the canonical payload is pure ASCII.
+#[must_use]
+pub fn checksum_hex(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    project_identity: &str,
+) -> String {
+    codegraph_core::node_id::hash_content(&canonical_checksum_payload(
+        sequence,
+        storage_protocol,
+        extraction_version,
+        phase,
+        project_identity,
+    ))
+}
+
+fn is_lowercase_sha256(value: &str) -> bool {
+    value.len() == 64
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
+
+/// The canonical fields of one parsed slot.
+///
+/// `phase` is `None` only for a future-storage-protocol slot, whose phase
+/// vocabulary this binary does not define; for a current-protocol slot it is
+/// always `Some` (an unknown phase is `Corrupt`, never a valid record).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StateSlotRecord {
+    /// Monotonic publication sequence; the highest valid one is authoritative.
+    pub sequence: u64,
+    /// On-disk storage protocol of this slot.
+    pub storage_protocol: u64,
+    /// Extraction-pipeline version the namespace was built with.
+    pub extraction_version: u64,
+    /// Parsed phase, or `None` for a future-protocol slot.
+    pub phase: Option<StatePhase>,
+    /// The verbatim `phase` string as stored.
+    pub phase_raw: String,
+    /// Owning project identity (`IndexPaths::project_identity`).
+    pub project_identity: String,
+    /// The verbatim `checksum` string as stored.
+    pub checksum: String,
+}
+
+/// Why a namespace is [`ExtractionStatus::Corrupt`]. Typed so callers branch on
+/// the variant; the `Display` rendering is for operator messages only.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CorruptReason {
+    /// A present slot could not be stat'd or read.
+    UnreadableSlot {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// Stable I/O detail.
+        detail: String,
+    },
+    /// The fixed slot path exists but is not a regular file (for example a
+    /// directory or a symlink, which is recorded and refused, never followed).
+    NotARegularFile {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The observed entry kind.
+        kind: &'static str,
+    },
+    /// The bytes are not a JSON object carrying the six canonical fields at
+    /// their canonical JSON types.
+    MalformedJson {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// Stable parser detail.
+        detail: String,
+    },
+    /// `projectIdentity` is not exactly 64 lowercase hexadecimal characters.
+    InvalidOwnerEncoding {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The rejected identity.
+        found: String,
+    },
+    /// `checksum` is not exactly 64 lowercase hexadecimal characters.
+    InvalidChecksumEncoding {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The rejected checksum.
+        found: String,
+    },
+    /// `phase` is outside the three supported values.
+    UnknownPhase {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The verbatim rejected `phase` value.
+        phase: String,
+    },
+    /// The stored `checksum` does not equal the recomputed one.
+    ChecksumMismatch {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// Recomputed checksum.
+        expected: String,
+        /// Checksum found in the file.
+        found: String,
+    },
+    /// `storageProtocol` is below [`CURRENT_STORAGE_PROTOCOL`] (zero included);
+    /// such a slot is unsupported, not merely old.
+    UnsupportedStorageProtocol {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The rejected protocol value.
+        found: u64,
+        /// The protocol this binary defines.
+        supported: u64,
+    },
+    /// `projectIdentity` does not match the owner identity of the namespace.
+    OwnerMismatch {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// The owner identity this binary computed.
+        expected: String,
+        /// The identity stored in the slot.
+        found: String,
+    },
+    /// Both slots are valid and carry the same `sequence`. This is `Corrupt`
+    /// whether the payload bytes are identical or different: the publication
+    /// protocol never produces two slots at one sequence, so the namespace's
+    /// history is unreconstructible either way.
+    EqualSequence {
+        /// The duplicated sequence.
+        sequence: u64,
+        /// Whether the two slots' bytes are identical.
+        identical_payload: bool,
+    },
+    /// The authoritative sequence is [`u64::MAX`], so no successor can be
+    /// published. Reported without mutating anything.
+    SequenceExhausted {
+        /// The exhausted sequence.
+        sequence: u64,
+    },
+}
+
+impl fmt::Display for CorruptReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::UnreadableSlot { slot, path, detail } => write!(
+                f,
+                "index state slot {slot} ({}) could not be read: {detail}",
+                path.display()
+            ),
+            Self::NotARegularFile { slot, path, kind } => write!(
+                f,
+                "index state slot {slot} ({}) is a {kind}, not a regular file",
+                path.display()
+            ),
+            Self::MalformedJson { slot, path, detail } => write!(
+                f,
+                "index state slot {slot} ({}) is malformed: {detail}",
+                path.display()
+            ),
+            Self::InvalidOwnerEncoding { slot, path, found } => write!(
+                f,
+                "index state slot {slot} ({}) has invalid project identity encoding {found:?}",
+                path.display()
+            ),
+            Self::InvalidChecksumEncoding { slot, path, found } => write!(
+                f,
+                "index state slot {slot} ({}) has invalid checksum encoding {found:?}",
+                path.display()
+            ),
+            Self::UnknownPhase { slot, path, phase } => write!(
+                f,
+                "index state slot {slot} ({}) has unknown phase {phase:?}",
+                path.display()
+            ),
+            Self::ChecksumMismatch {
+                slot,
+                path,
+                expected,
+                found,
+            } => write!(
+                f,
+                "index state slot {slot} ({}) checksum mismatch: expected {expected}, found {found}",
+                path.display()
+            ),
+            Self::UnsupportedStorageProtocol {
+                slot,
+                path,
+                found,
+                supported,
+            } => write!(
+                f,
+                "index state slot {slot} ({}) has unsupported storage protocol {found} \
+                 (this binary supports {supported})",
+                path.display()
+            ),
+            Self::OwnerMismatch {
+                slot,
+                path,
+                expected,
+                found,
+            } => write!(
+                f,
+                "index state slot {slot} ({}) belongs to project identity {found}, not {expected}",
+                path.display()
+            ),
+            Self::EqualSequence {
+                sequence,
+                identical_payload,
+            } => {
+                let payload = if *identical_payload {
+                    "identical"
+                } else {
+                    "differing"
+                };
+                write!(
+                    f,
+                    "both index state slots are valid at sequence {sequence} with {payload} payloads"
+                )
+            }
+            Self::SequenceExhausted { sequence } => write!(
+                f,
+                "index state sequence is exhausted at {sequence}; no successor can be published"
+            ),
+        }
+    }
+}
+
+/// The typed classification of a v2 namespace, derived from the two fixed slots
+/// alone. Equivalent to the frozen plan's `ExtractionStatus`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ExtractionStatus {
+    /// A complete index built by this extraction version.
+    Current,
+    /// A destructive build was in progress at this extraction version.
+    Building {
+        /// The extraction version the interrupted build was producing.
+        built: u64,
+    },
+    /// A `uninit --force` was in progress when the namespace last advanced.
+    Uninitialized,
+    /// No state slot exists at all.
+    Missing,
+    /// Built by an older extraction version; a rebuild is required.
+    Outdated {
+        /// The older extraction version the namespace was built with.
+        built: u64,
+    },
+    /// Written by a newer extraction version or storage protocol. This binary
+    /// must not read, migrate, or delete the namespace.
+    Future {
+        /// The newer extraction version recorded on disk.
+        built: u64,
+    },
+    /// The namespace cannot be interpreted; manual recovery is required.
+    Corrupt {
+        /// The typed reason.
+        reason: CorruptReason,
+    },
+}
+
+impl fmt::Display for ExtractionStatus {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Current => f.write_str("current"),
+            Self::Building { built } => write!(f, "building (extraction version {built})"),
+            Self::Uninitialized => f.write_str("uninitialized (interrupted uninit)"),
+            Self::Missing => f.write_str("missing"),
+            Self::Outdated { built } => {
+                write!(f, "outdated (built with extraction version {built})")
+            }
+            Self::Future { built } => write!(f, "future (built with extraction version {built})"),
+            Self::Corrupt { reason } => write!(f, "corrupt: {reason}"),
+        }
+    }
+}
+
+/// The slot the classification treated as authoritative, with enough metadata
+/// for the later lease / `Store::open_for_*` slices to re-verify it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthoritativeSlot {
+    /// Slot index (0 or 1).
+    pub index: u8,
+    /// Absolute slot path.
+    pub path: PathBuf,
+    /// The parsed record.
+    pub record: StateSlotRecord,
+}
+
+/// The per-slot outcome, kept for inspection independently of the aggregate
+/// [`ExtractionStatus`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SlotOutcome {
+    /// The slot file does not exist (allowed for the inactive slot).
+    Absent,
+    /// The slot parsed and passed every current-protocol check.
+    Valid(StateSlotRecord),
+    /// The slot parsed but declares a storage protocol above this binary's.
+    FutureProtocol(StateSlotRecord),
+    /// The slot is present and invalid.
+    Invalid(CorruptReason),
+}
+
+/// The complete result of one read-only classification.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct IndexStateClassification {
+    status: ExtractionStatus,
+    authoritative: Option<AuthoritativeSlot>,
+    slots: [SlotOutcome; 2],
+}
+
+impl IndexStateClassification {
+    /// The aggregate status.
+    #[must_use]
+    pub fn status(&self) -> &ExtractionStatus {
+        &self.status
+    }
+
+    /// The authoritative slot, when one was selected. `None` for
+    /// [`ExtractionStatus::Missing`] and for a `Corrupt` outcome caused by a
+    /// defective or duplicated slot.
+    #[must_use]
+    pub fn authoritative(&self) -> Option<&AuthoritativeSlot> {
+        self.authoritative.as_ref()
+    }
+
+    /// The per-slot outcome for slot `index` (0 or 1).
+    ///
+    /// # Panics
+    ///
+    /// Panics if `index` is not 0 or 1; the slot layout is a fixed pair.
+    #[must_use]
+    pub fn slot(&self, index: usize) -> &SlotOutcome {
+        assert!(index < 2, "index state has exactly two fixed slots");
+        &self.slots[index]
+    }
+}
+
+/// Classify the namespace owned by `paths`, reading ONLY the two fixed slots.
+///
+/// Consumes [`IndexPaths::state_slots`] and [`IndexPaths::project_identity`]
+/// rather than reconstructing paths or owner identity. Nonmutating: see the
+/// module docs.
+#[must_use]
+pub fn classify(paths: &IndexPaths) -> IndexStateClassification {
+    classify_slots(&paths.state_slots(), paths.project_identity())
+}
+
+/// Classify from exact slot paths and an exact owner identity.
+///
+/// The unit-test seam for [`classify`], and the form later slices use when they
+/// already hold the resolved slot pair. Nonmutating: see the module docs.
+#[must_use]
+pub fn classify_slots(slots: &[PathBuf; 2], owner_identity: &str) -> IndexStateClassification {
+    let raw = [read_slot(0, &slots[0]), read_slot(1, &slots[1])];
+    classify_raw(&raw, slots, owner_identity)
+}
+
+/// One slot as observed on disk, before semantic validation.
+#[derive(Debug, Clone)]
+enum RawSlot {
+    Absent,
+    Invalid(CorruptReason),
+    Parsed { wire: WireSlot, bytes: Vec<u8> },
+}
+
+/// The wire form. Unknown fields are ignored; every canonical field is required
+/// at its canonical JSON type.
+#[derive(Debug, Clone, Deserialize)]
+struct WireSlot {
+    sequence: u64,
+    #[serde(rename = "storageProtocol")]
+    storage_protocol: u64,
+    #[serde(rename = "extractionVersion")]
+    extraction_version: u64,
+    phase: String,
+    #[serde(rename = "projectIdentity")]
+    project_identity: String,
+    checksum: String,
+}
+
+fn read_slot(index: u8, path: &Path) -> RawSlot {
+    let meta = match std::fs::symlink_metadata(path) {
+        Ok(meta) => meta,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return RawSlot::Absent,
+        Err(err) => {
+            return RawSlot::Invalid(CorruptReason::UnreadableSlot {
+                slot: index,
+                path: path.to_path_buf(),
+                detail: err.to_string(),
+            });
+        }
+    };
+    let file_type = meta.file_type();
+    if !file_type.is_file() {
+        let kind = if file_type.is_dir() {
+            "directory"
+        } else if file_type.is_symlink() {
+            "symlink"
+        } else {
+            "non-regular filesystem entry"
+        };
+        return RawSlot::Invalid(CorruptReason::NotARegularFile {
+            slot: index,
+            path: path.to_path_buf(),
+            kind,
+        });
+    }
+    let bytes = match std::fs::read(path) {
+        Ok(bytes) => bytes,
+        Err(err) => {
+            return RawSlot::Invalid(CorruptReason::UnreadableSlot {
+                slot: index,
+                path: path.to_path_buf(),
+                detail: err.to_string(),
+            });
+        }
+    };
+    match serde_json::from_slice::<WireSlot>(&bytes) {
+        Ok(wire) => RawSlot::Parsed { wire, bytes },
+        Err(err) => RawSlot::Invalid(CorruptReason::MalformedJson {
+            slot: index,
+            path: path.to_path_buf(),
+            detail: err.to_string(),
+        }),
+    }
+}
+
+/// Semantically validate ONE parsed slot into a [`SlotOutcome`].
+///
+/// Order is fixed and typed: owner encoding → checksum encoding → checksum over
+/// the raw phase text → owner equality → supported protocol → current-protocol
+/// phase vocabulary. A future protocol is trusted only after every stable field
+/// check; its phase vocabulary may be unknown.
+fn validate_parsed(index: u8, path: &Path, wire: &WireSlot, owner_identity: &str) -> SlotOutcome {
+    if !is_lowercase_sha256(&wire.project_identity) {
+        return SlotOutcome::Invalid(CorruptReason::InvalidOwnerEncoding {
+            slot: index,
+            path: path.to_path_buf(),
+            found: wire.project_identity.clone(),
+        });
+    }
+    if !is_lowercase_sha256(&wire.checksum) {
+        return SlotOutcome::Invalid(CorruptReason::InvalidChecksumEncoding {
+            slot: index,
+            path: path.to_path_buf(),
+            found: wire.checksum.clone(),
+        });
+    }
+
+    let expected = checksum_hex(
+        wire.sequence,
+        wire.storage_protocol,
+        wire.extraction_version,
+        &wire.phase,
+        &wire.project_identity,
+    );
+    if expected != wire.checksum {
+        return SlotOutcome::Invalid(CorruptReason::ChecksumMismatch {
+            slot: index,
+            path: path.to_path_buf(),
+            expected,
+            found: wire.checksum.clone(),
+        });
+    }
+
+    if wire.project_identity != owner_identity {
+        return SlotOutcome::Invalid(CorruptReason::OwnerMismatch {
+            slot: index,
+            path: path.to_path_buf(),
+            expected: owner_identity.to_string(),
+            found: wire.project_identity.clone(),
+        });
+    }
+
+    if wire.storage_protocol < CURRENT_STORAGE_PROTOCOL {
+        return SlotOutcome::Invalid(CorruptReason::UnsupportedStorageProtocol {
+            slot: index,
+            path: path.to_path_buf(),
+            found: wire.storage_protocol,
+            supported: CURRENT_STORAGE_PROTOCOL,
+        });
+    }
+
+    let phase = StatePhase::from_wire(&wire.phase);
+    let record = StateSlotRecord {
+        sequence: wire.sequence,
+        storage_protocol: wire.storage_protocol,
+        extraction_version: wire.extraction_version,
+        phase,
+        phase_raw: wire.phase.clone(),
+        project_identity: wire.project_identity.clone(),
+        checksum: wire.checksum.clone(),
+    };
+
+    if wire.storage_protocol > CURRENT_STORAGE_PROTOCOL {
+        return SlotOutcome::FutureProtocol(record);
+    }
+
+    if phase.is_none() {
+        return SlotOutcome::Invalid(CorruptReason::UnknownPhase {
+            slot: index,
+            path: path.to_path_buf(),
+            phase: wire.phase.clone(),
+        });
+    }
+
+    SlotOutcome::Valid(record)
+}
+
+/// Aggregate two observed slots into one classification.
+///
+/// Dominance order, applied before any authority selection:
+///
+/// 1. A present INVALID slot (unreadable, non-regular, malformed, unknown phase,
+///    checksum mismatch, unsupported lower protocol, owner mismatch) is
+///    `Corrupt`. It dominates even a future-protocol companion: a defective
+///    present fixed slot always requires manual recovery, and both outcomes are
+///    equally nonmutating, so the stricter one is reported. Slot 0 is inspected
+///    before slot 1 so the reason is deterministic.
+/// 2. Equal sequence across ANY two validated records is `Corrupt`, before
+///    future dominance and without relying on raw JSON byte equality.
+/// 3. A future-STORAGE-PROTOCOL slot dominates a valid current-protocol
+///    companion regardless of sequence; otherwise current records decide.
+/// 4. The selected authority is rejected at `u64::MAX` before Future/status
+///    mapping; then protocol/extraction version/phase maps the status.
+fn classify_raw(
+    raw: &[RawSlot; 2],
+    slots: &[PathBuf; 2],
+    owner_identity: &str,
+) -> IndexStateClassification {
+    let outcomes: [SlotOutcome; 2] = [
+        observe(0, &slots[0], &raw[0], owner_identity),
+        observe(1, &slots[1], &raw[1], owner_identity),
+    ];
+
+    for outcome in &outcomes {
+        if let SlotOutcome::Invalid(reason) = outcome {
+            return IndexStateClassification {
+                status: ExtractionStatus::Corrupt {
+                    reason: reason.clone(),
+                },
+                authoritative: None,
+                slots: outcomes,
+            };
+        }
+    }
+
+    let validated: Vec<(u8, &StateSlotRecord)> = outcomes
+        .iter()
+        .enumerate()
+        .filter_map(|(index, outcome)| match outcome {
+            SlotOutcome::Valid(record) | SlotOutcome::FutureProtocol(record) => {
+                Some((u8::try_from(index).unwrap_or(u8::MAX), record))
+            }
+            _ => None,
+        })
+        .collect();
+
+    if validated.is_empty() {
+        return IndexStateClassification {
+            status: ExtractionStatus::Missing,
+            authoritative: None,
+            slots: outcomes,
+        };
+    }
+
+    if let [(_, first), (_, second)] = validated.as_slice()
+        && first.sequence == second.sequence
+    {
+        let identical_payload = match (&raw[0], &raw[1]) {
+            (RawSlot::Parsed { bytes: left, .. }, RawSlot::Parsed { bytes: right, .. }) => {
+                left == right
+            }
+            _ => false,
+        };
+        return IndexStateClassification {
+            status: ExtractionStatus::Corrupt {
+                reason: CorruptReason::EqualSequence {
+                    sequence: first.sequence,
+                    identical_payload,
+                },
+            },
+            authoritative: None,
+            slots: outcomes,
+        };
+    }
+
+    let future = pick_highest(&outcomes, slots, |outcome| match outcome {
+        SlotOutcome::FutureProtocol(record) => Some(record),
+        _ => None,
+    });
+    let authoritative = future.unwrap_or_else(|| {
+        pick_highest(&outcomes, slots, |outcome| match outcome {
+            SlotOutcome::Valid(record) => Some(record),
+            _ => None,
+        })
+        .expect("at least one validated slot exists here")
+    });
+
+    if authoritative.record.sequence == u64::MAX {
+        return IndexStateClassification {
+            status: ExtractionStatus::Corrupt {
+                reason: CorruptReason::SequenceExhausted {
+                    sequence: authoritative.record.sequence,
+                },
+            },
+            authoritative: Some(authoritative),
+            slots: outcomes,
+        };
+    }
+
+    let built = authoritative.record.extraction_version;
+    let status = if authoritative.record.storage_protocol > CURRENT_STORAGE_PROTOCOL
+        || built > CURRENT_EXTRACTION_VERSION
+    {
+        // Future dominance applies to EVERY phase, `uninitialized` included: a
+        // future-extraction `uninitialized` slot is never treated as a
+        // recoverable interrupted uninit.
+        ExtractionStatus::Future { built }
+    } else if built < CURRENT_EXTRACTION_VERSION {
+        ExtractionStatus::Outdated { built }
+    } else {
+        match authoritative.record.phase {
+            Some(StatePhase::Current) => ExtractionStatus::Current,
+            Some(StatePhase::Building) => ExtractionStatus::Building { built },
+            Some(StatePhase::Uninitialized) => ExtractionStatus::Uninitialized,
+            // Unreachable: a current-protocol valid slot always carries a phase.
+            None => ExtractionStatus::Corrupt {
+                reason: CorruptReason::UnknownPhase {
+                    slot: authoritative.index,
+                    path: authoritative.path.clone(),
+                    phase: authoritative.record.phase_raw.clone(),
+                },
+            },
+        }
+    };
+
+    IndexStateClassification {
+        status,
+        authoritative: Some(authoritative),
+        slots: outcomes,
+    }
+}
+
+fn observe(index: u8, path: &Path, raw: &RawSlot, owner_identity: &str) -> SlotOutcome {
+    match raw {
+        RawSlot::Absent => SlotOutcome::Absent,
+        RawSlot::Invalid(reason) => SlotOutcome::Invalid(reason.clone()),
+        RawSlot::Parsed { wire, .. } => validate_parsed(index, path, wire, owner_identity),
+    }
+}
+
+/// Select the highest-sequence slot among the outcomes `select` accepts; ties
+/// cannot occur here because equal sequences are rejected earlier, so slot 0
+/// wins a hypothetical tie deterministically.
+fn pick_highest<'a>(
+    outcomes: &'a [SlotOutcome; 2],
+    slots: &[PathBuf; 2],
+    select: impl Fn(&'a SlotOutcome) -> Option<&'a StateSlotRecord>,
+) -> Option<AuthoritativeSlot> {
+    let mut best: Option<AuthoritativeSlot> = None;
+    for (index, outcome) in outcomes.iter().enumerate() {
+        let Some(record) = select(outcome) else {
+            continue;
+        };
+        let replace = best
+            .as_ref()
+            .is_none_or(|current| record.sequence > current.record.sequence);
+        if replace {
+            best = Some(AuthoritativeSlot {
+                index: u8::try_from(index).unwrap_or(u8::MAX),
+                path: slots[index].clone(),
+                record: record.clone(),
+            });
+        }
+    }
+    best
+}
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index a667970..cf2c479 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -1,9 +1,15 @@
 pub mod connection;
+pub mod index_state;
 pub mod migrations;
 pub mod queries;
 pub mod schema;
 
 pub use connection::Store;
+pub use index_state::{
+    AuthoritativeSlot, CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, CorruptReason,
+    EXTRACTION_VERSION_KEY, ExtractionStatus, IndexStateClassification, SlotOutcome, StatePhase,
+    StateSlotRecord, canonical_checksum_payload, checksum_hex, classify, classify_slots,
+};
 pub use queries::{
     CODEGRAPH_NO_WAL_DEFER, CODEGRAPH_WAL_VALVE_MB, DEFAULT_WAL_VALVE_MB, wal_valve_threshold_bytes,
 };
diff --git a/crates/codegraph-store/tests/index_state.rs b/crates/codegraph-store/tests/index_state.rs
new file mode 100644
index 0000000..a48c5c1
--- /dev/null
+++ b/crates/codegraph-store/tests/index_state.rs
@@ -0,0 +1,657 @@
+//! Public-surface contract tests for the read-only dual-slot classifier.
+
+use std::collections::BTreeMap;
+use std::ffi::OsString;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, CorruptReason, EXTRACTION_VERSION_KEY,
+    ExtractionStatus, SlotOutcome, StatePhase, canonical_checksum_payload, checksum_hex, classify,
+    classify_slots,
+};
+use serde_json::{Value, json};
+
+const OWNER: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const OTHER_OWNER: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+struct TempTree(PathBuf);
+
+impl TempTree {
+    fn new(label: &str) -> Self {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-index-state-{label}-{}-{serial}",
+            std::process::id()
+        ));
+        std::fs::create_dir(&path)
+            .unwrap_or_else(|err| panic!("create temp tree {}: {err}", path.display()));
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn slots(&self) -> [PathBuf; 2] {
+        [
+            self.0.join("index-state.0.json"),
+            self.0.join("index-state.1.json"),
+        ]
+    }
+}
+
+impl Drop for TempTree {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.0)
+            .unwrap_or_else(|err| panic!("remove temp tree {}: {err}", self.0.display()));
+    }
+}
+
+fn wire_value(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) -> Value {
+    json!({
+        "sequence": sequence,
+        "storageProtocol": storage_protocol,
+        "extractionVersion": extraction_version,
+        "phase": phase,
+        "projectIdentity": owner,
+        "checksum": checksum_hex(sequence, storage_protocol, extraction_version, phase, owner),
+    })
+}
+
+fn wire_bytes(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) -> Vec<u8> {
+    serde_json::to_vec(&wire_value(
+        sequence,
+        storage_protocol,
+        extraction_version,
+        phase,
+        owner,
+    ))
+    .expect("serialize state fixture")
+}
+
+fn write_bytes(path: &Path, bytes: &[u8]) {
+    std::fs::write(path, bytes)
+        .unwrap_or_else(|err| panic!("write state fixture {}: {err}", path.display()));
+}
+
+fn write_wire(
+    path: &Path,
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) {
+    write_bytes(
+        path,
+        &wire_bytes(sequence, storage_protocol, extraction_version, phase, owner),
+    );
+}
+
+fn assert_corrupt(
+    classification: &codegraph_store::IndexStateClassification,
+    expected: impl FnOnce(&CorruptReason) -> bool,
+) {
+    match classification.status() {
+        ExtractionStatus::Corrupt { reason } => {
+            assert!(expected(reason), "unexpected corruption reason: {reason:?}");
+        }
+        status => panic!("expected Corrupt, got {status:?}"),
+    }
+}
+
+#[test]
+fn index_state_constants_and_canonical_payload_are_exact() {
+    assert_eq!(CURRENT_STORAGE_PROTOCOL, 2);
+    assert_eq!(CURRENT_EXTRACTION_VERSION, 2);
+    assert_eq!(EXTRACTION_VERSION_KEY, "indexed_with_extraction_version");
+    assert_eq!(
+        canonical_checksum_payload(7, 2, 2, "future-phase", OWNER),
+        format!(
+            "codegraph-index-state-v1\nsequence=7\nstorageProtocol=2\n\
+             extractionVersion=2\nphase=future-phase\nprojectIdentity={OWNER}\n"
+        )
+    );
+    let digest = checksum_hex(7, 2, 2, "future-phase", OWNER);
+    assert_eq!(digest.len(), 64);
+    assert!(
+        digest
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+    );
+}
+
+#[test]
+fn index_state_both_missing_is_missing() {
+    let tree = TempTree::new("missing");
+    let result = classify_slots(&tree.slots(), OWNER);
+    assert_eq!(result.status(), &ExtractionStatus::Missing);
+    assert_eq!(result.authoritative(), None);
+    assert!(matches!(result.slot(0), SlotOutcome::Absent));
+    assert!(matches!(result.slot(1), SlotOutcome::Absent));
+}
+
+#[test]
+fn index_state_current_protocol_maps_each_phase() {
+    for (phase, expected) in [
+        ("current", ExtractionStatus::Current),
+        (
+            "building",
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+        ),
+        ("uninitialized", ExtractionStatus::Uninitialized),
+    ] {
+        let tree = TempTree::new(phase);
+        write_wire(
+            &tree.slots()[0],
+            1,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION,
+            phase,
+            OWNER,
+        );
+        assert_eq!(classify_slots(&tree.slots(), OWNER).status(), &expected);
+    }
+}
+
+#[test]
+fn index_state_extraction_version_maps_outdated_and_future_for_every_phase() {
+    for phase in ["building", "current", "uninitialized"] {
+        let old = TempTree::new("outdated");
+        write_wire(
+            &old.slots()[0],
+            1,
+            CURRENT_STORAGE_PROTOCOL,
+            1,
+            phase,
+            OWNER,
+        );
+        assert_eq!(
+            classify_slots(&old.slots(), OWNER).status(),
+            &ExtractionStatus::Outdated { built: 1 }
+        );
+
+        let future = TempTree::new("future-extraction");
+        write_wire(
+            &future.slots()[0],
+            1,
+            CURRENT_STORAGE_PROTOCOL,
+            3,
+            phase,
+            OWNER,
+        );
+        assert_eq!(
+            classify_slots(&future.slots(), OWNER).status(),
+            &ExtractionStatus::Future { built: 3 },
+            "future extraction must dominate phase {phase}"
+        );
+    }
+}
+
+#[test]
+fn index_state_unknown_fields_key_order_and_whitespace_are_ignored() {
+    let tree = TempTree::new("formatting");
+    let checksum = checksum_hex(9, 2, 2, "current", OWNER);
+    let formatted = format!(
+        "{{\n  \"unknownFutureField\": {{\"nested\": true}},\n  \
+         \"checksum\": \"{checksum}\", \"projectIdentity\": \"{OWNER}\",\n  \
+         \"phase\": \"current\", \"extractionVersion\": 2,\n  \
+         \"storageProtocol\": 2, \"sequence\": 9\n}}\n"
+    );
+    write_bytes(&tree.slots()[1], formatted.as_bytes());
+    let result = classify_slots(&tree.slots(), OWNER);
+    assert_eq!(result.status(), &ExtractionStatus::Current);
+    assert_eq!(result.authoritative().expect("authority").index, 1);
+}
+
+#[test]
+fn index_state_missing_and_wrong_typed_required_fields_are_malformed() {
+    for value in [
+        json!({
+            "storageProtocol": 2,
+            "extractionVersion": 2,
+            "phase": "current",
+            "projectIdentity": OWNER,
+            "checksum": "0".repeat(64),
+        }),
+        json!({
+            "sequence": "1",
+            "storageProtocol": 2,
+            "extractionVersion": 2,
+            "phase": "current",
+            "projectIdentity": OWNER,
+            "checksum": "0".repeat(64),
+        }),
+        json!([]),
+    ] {
+        let tree = TempTree::new("malformed-shape");
+        write_bytes(&tree.slots()[0], &serde_json::to_vec(&value).unwrap());
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_corrupt(&result, |reason| {
+            matches!(reason, CorruptReason::MalformedJson { .. })
+        });
+    }
+}
+
+#[test]
+fn index_state_bad_owner_and_checksum_shapes_are_typed_corruption() {
+    let bad_owners = [
+        "abc",
+        "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+    ];
+    for owner in bad_owners {
+        let tree = TempTree::new("bad-owner-shape");
+        write_wire(&tree.slots()[0], 1, 3, 2, "future-phase", owner);
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_corrupt(&result, |reason| {
+            matches!(reason, CorruptReason::InvalidOwnerEncoding { .. })
+        });
+    }
+
+    for checksum in ["abc".to_string(), "A".repeat(64), "g".repeat(64)] {
+        let tree = TempTree::new("bad-checksum-shape");
+        let mut value = wire_value(1, 3, 2, "future-phase", OWNER);
+        value["checksum"] = Value::String(checksum);
+        write_bytes(&tree.slots()[0], &serde_json::to_vec(&value).unwrap());
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_corrupt(&result, |reason| {
+            matches!(reason, CorruptReason::InvalidChecksumEncoding { .. })
+        });
+    }
+}
+
+#[test]
+fn index_state_checksum_and_owner_mismatch_are_corrupt_even_for_future_protocol() {
+    let checksum_tree = TempTree::new("checksum-mismatch");
+    let mut value = wire_value(1, 3, 2, "future-phase", OWNER);
+    value["checksum"] = Value::String("0".repeat(64));
+    write_bytes(
+        &checksum_tree.slots()[0],
+        &serde_json::to_vec(&value).unwrap(),
+    );
+    let result = classify_slots(&checksum_tree.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::ChecksumMismatch { .. })
+    });
+
+    let owner_tree = TempTree::new("owner-mismatch");
+    write_wire(&owner_tree.slots()[0], 1, 3, 2, "future-phase", OTHER_OWNER);
+    let result = classify_slots(&owner_tree.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::OwnerMismatch { .. })
+    });
+}
+
+#[test]
+fn index_state_current_unknown_phase_is_corrupt_but_future_unknown_phase_is_valid() {
+    let current = TempTree::new("unknown-current-phase");
+    write_wire(&current.slots()[0], 1, 2, 2, "future-phase", OWNER);
+    let result = classify_slots(&current.slots(), OWNER);
+    assert_corrupt(
+        &result,
+        |reason| matches!(reason, CorruptReason::UnknownPhase { phase, .. } if phase == "future-phase"),
+    );
+
+    let future = TempTree::new("unknown-future-phase");
+    write_wire(&future.slots()[0], 1, 3, 44, "future-phase", OWNER);
+    let result = classify_slots(&future.slots(), OWNER);
+    assert_eq!(result.status(), &ExtractionStatus::Future { built: 44 });
+    let authority = result.authoritative().expect("future authority");
+    assert_eq!(authority.record.phase, None);
+    assert_eq!(authority.record.phase_raw, "future-phase");
+    assert!(matches!(result.slot(0), SlotOutcome::FutureProtocol(_)));
+}
+
+#[test]
+fn index_state_lower_and_zero_storage_protocol_are_corrupt() {
+    for protocol in [0, 1] {
+        let tree = TempTree::new("lower-protocol");
+        write_wire(&tree.slots()[0], 1, protocol, 2, "current", OWNER);
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_corrupt(
+            &result,
+            |reason| matches!(reason, CorruptReason::UnsupportedStorageProtocol { found, .. } if *found == protocol),
+        );
+    }
+}
+
+#[test]
+fn index_state_any_malformed_present_slot_dominates_a_valid_companion() {
+    let tree = TempTree::new("invalid-dominance");
+    write_bytes(&tree.slots()[0], b"not json");
+    write_wire(&tree.slots()[1], 99, 2, 2, "current", OWNER);
+    let result = classify_slots(&tree.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::MalformedJson { slot: 0, .. })
+    });
+    assert_eq!(result.authoritative(), None);
+}
+
+#[test]
+fn index_state_non_regular_and_unreadable_slots_are_corrupt() {
+    let directory = TempTree::new("slot-directory");
+    std::fs::create_dir(&directory.slots()[0]).unwrap();
+    let result = classify_slots(&directory.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(
+            reason,
+            CorruptReason::NotARegularFile {
+                kind: "directory",
+                ..
+            }
+        )
+    });
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::symlink;
+        let link = TempTree::new("slot-symlink");
+        let target = link.path().join("target.json");
+        write_wire(&target, 1, 2, 2, "current", OWNER);
+        symlink(&target, &link.slots()[0]).unwrap();
+        let result = classify_slots(&link.slots(), OWNER);
+        assert_corrupt(&result, |reason| {
+            matches!(
+                reason,
+                CorruptReason::NotARegularFile {
+                    kind: "symlink",
+                    ..
+                }
+            )
+        });
+    }
+
+    let unreadable = TempTree::new("slot-unreadable");
+    let too_long = unreadable.path().join(OsString::from("x".repeat(4096)));
+    let result = classify_slots(&[too_long, unreadable.slots()[1].clone()], OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::UnreadableSlot { slot: 0, .. })
+    });
+}
+
+#[test]
+fn index_state_future_protocol_dominates_current_in_both_sequence_directions() {
+    for (future_sequence, current_sequence) in [(1, 100), (100, 1)] {
+        let tree = TempTree::new("future-dominance");
+        write_wire(&tree.slots()[0], current_sequence, 2, 2, "current", OWNER);
+        write_wire(
+            &tree.slots()[1],
+            future_sequence,
+            3,
+            77,
+            "future-phase",
+            OWNER,
+        );
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_eq!(result.status(), &ExtractionStatus::Future { built: 77 });
+        assert_eq!(result.authoritative().expect("future authority").index, 1);
+    }
+}
+
+#[test]
+fn index_state_equal_current_sequences_are_corrupt_for_identical_and_reformatted_json() {
+    let identical = TempTree::new("equal-identical");
+    let bytes = wire_bytes(7, 2, 2, "current", OWNER);
+    write_bytes(&identical.slots()[0], &bytes);
+    write_bytes(&identical.slots()[1], &bytes);
+    let result = classify_slots(&identical.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(
+            reason,
+            CorruptReason::EqualSequence {
+                sequence: 7,
+                identical_payload: true
+            }
+        )
+    });
+
+    let reformatted = TempTree::new("equal-reformatted");
+    write_bytes(&reformatted.slots()[0], &bytes);
+    let checksum = checksum_hex(7, 2, 2, "current", OWNER);
+    let other = format!(
+        "{{ \"checksum\":\"{checksum}\", \"phase\":\"current\", \
+         \"projectIdentity\":\"{OWNER}\", \"extractionVersion\":2, \
+         \"storageProtocol\":2, \"sequence\":7 }}"
+    );
+    write_bytes(&reformatted.slots()[1], other.as_bytes());
+    let result = classify_slots(&reformatted.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(
+            reason,
+            CorruptReason::EqualSequence {
+                sequence: 7,
+                identical_payload: false
+            }
+        )
+    });
+}
+
+#[test]
+fn index_state_equal_future_and_mixed_sequences_are_corrupt_before_future_dominance() {
+    let future = TempTree::new("equal-future");
+    write_wire(&future.slots()[0], 8, 3, 9, "alpha", OWNER);
+    write_wire(&future.slots()[1], 8, 4, 10, "beta", OWNER);
+    let result = classify_slots(&future.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::EqualSequence { sequence: 8, .. })
+    });
+
+    let mixed = TempTree::new("equal-mixed");
+    write_wire(&mixed.slots()[0], 8, 2, 2, "current", OWNER);
+    write_wire(&mixed.slots()[1], 8, 3, 10, "future-phase", OWNER);
+    let result = classify_slots(&mixed.slots(), OWNER);
+    assert_corrupt(&result, |reason| {
+        matches!(reason, CorruptReason::EqualSequence { sequence: 8, .. })
+    });
+}
+
+#[test]
+fn index_state_selected_max_sequence_is_corrupt_before_status_mapping() {
+    for (protocol, extraction, phase) in [(2, 2, "current"), (3, 99, "future-phase")] {
+        let tree = TempTree::new("max-sequence");
+        write_wire(
+            &tree.slots()[0],
+            u64::MAX,
+            protocol,
+            extraction,
+            phase,
+            OWNER,
+        );
+        let result = classify_slots(&tree.slots(), OWNER);
+        assert_corrupt(
+            &result,
+            |reason| matches!(reason, CorruptReason::SequenceExhausted { sequence } if *sequence == u64::MAX),
+        );
+        assert_eq!(
+            result
+                .authoritative()
+                .expect("selected authority")
+                .record
+                .sequence,
+            u64::MAX
+        );
+    }
+}
+
+#[test]
+fn index_state_highest_ordinary_current_slot_is_authoritative_with_full_metadata() {
+    let tree = TempTree::new("authority");
+    write_wire(&tree.slots()[0], 4, 2, 1, "building", OWNER);
+    write_wire(&tree.slots()[1], 5, 2, 2, "current", OWNER);
+    let result = classify_slots(&tree.slots(), OWNER);
+    assert_eq!(result.status(), &ExtractionStatus::Current);
+    let authority = result.authoritative().expect("authority");
+    assert_eq!(authority.index, 1);
+    assert_eq!(authority.path, tree.slots()[1]);
+    assert_eq!(authority.record.sequence, 5);
+    assert_eq!(authority.record.storage_protocol, 2);
+    assert_eq!(authority.record.extraction_version, 2);
+    assert_eq!(authority.record.phase, Some(StatePhase::Current));
+    assert_eq!(authority.record.phase_raw, "current");
+    assert_eq!(authority.record.project_identity, OWNER);
+    assert_eq!(
+        authority.record.checksum,
+        checksum_hex(5, 2, 2, "current", OWNER)
+    );
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum SnapshotKind {
+    Directory,
+    File(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
+    fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, SnapshotKind>) {
+        let entries = std::fs::read_dir(directory)
+            .unwrap_or_else(|err| panic!("snapshot read_dir {}: {err}", directory.display()));
+        let mut paths = entries
+            .map(|entry| {
+                entry
+                    .unwrap_or_else(|err| {
+                        panic!("snapshot entry in {}: {err}", directory.display())
+                    })
+                    .path()
+            })
+            .collect::<Vec<_>>();
+        paths.sort();
+        for path in paths {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|err| panic!("snapshot strip {}: {err}", path.display()))
+                .to_path_buf();
+            let metadata = std::fs::symlink_metadata(&path)
+                .unwrap_or_else(|err| panic!("snapshot metadata {}: {err}", path.display()));
+            let file_type = metadata.file_type();
+            let kind = if file_type.is_dir() {
+                SnapshotKind::Directory
+            } else if file_type.is_file() {
+                SnapshotKind::File(
+                    std::fs::read(&path)
+                        .unwrap_or_else(|err| panic!("snapshot read {}: {err}", path.display())),
+                )
+            } else if file_type.is_symlink() {
+                SnapshotKind::Symlink(
+                    std::fs::read_link(&path).unwrap_or_else(|err| {
+                        panic!("snapshot read_link {}: {err}", path.display())
+                    }),
+                )
+            } else {
+                panic!("snapshot unsupported entry kind: {}", path.display());
+            };
+            assert!(
+                out.insert(relative, kind).is_none(),
+                "duplicate snapshot path"
+            );
+            if file_type.is_dir() {
+                walk(root, &path, out);
+            }
+        }
+    }
+
+    let mut out = BTreeMap::new();
+    walk(root, root, &mut out);
+    out
+}
+
+fn assert_snapshot_unchanged(
+    before: &BTreeMap<PathBuf, SnapshotKind>,
+    after: &BTreeMap<PathBuf, SnapshotKind>,
+) {
+    let changed = before
+        .keys()
+        .chain(after.keys())
+        .filter(|path| before.get(*path) != after.get(*path))
+        .cloned()
+        .collect::<Vec<_>>();
+    assert!(
+        changed.is_empty(),
+        "filesystem snapshot changed at {changed:?}"
+    );
+}
+
+#[test]
+fn index_state_classifier_is_exactly_byte_nonmutating_and_never_opens_sqlite() {
+    let project = TempTree::new("nonmutation");
+    let paths = IndexPaths::resolve(project.path(), None).expect("resolve paths");
+    std::fs::create_dir_all(paths.current_root().join("empty-directory")).unwrap();
+    write_bytes(&paths.current_db(), b"not sqlite; immutable trap bytes");
+    write_bytes(&paths.permanent_lock(), b"lock trap");
+    write_wire(
+        &paths.state_slots()[0],
+        1,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        "current",
+        paths.project_identity(),
+    );
+    #[cfg(unix)]
+    std::os::unix::fs::symlink("codegraph.db", paths.current_root().join("db-link")).unwrap();
+
+    let before = snapshot_tree(project.path());
+    let result = classify(&paths);
+    let after = snapshot_tree(project.path());
+    assert_eq!(result.status(), &ExtractionStatus::Current);
+    assert_snapshot_unchanged(&before, &after);
+}
+
+#[test]
+fn index_state_snapshot_detects_equal_length_byte_mutation() {
+    let tree = TempTree::new("snapshot-bytes");
+    let file = tree.path().join("same-length.bin");
+    write_bytes(&file, b"AAAA");
+    let before = snapshot_tree(tree.path());
+    write_bytes(&file, b"BBBB");
+    let after = snapshot_tree(tree.path());
+    let caught = std::panic::catch_unwind(|| assert_snapshot_unchanged(&before, &after));
+    assert!(
+        caught.is_err(),
+        "equal-length byte mutation must be detected"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn index_state_snapshot_records_symlink_target_without_following_it() {
+    use std::os::unix::fs::symlink;
+
+    let tree = TempTree::new("snapshot-symlink");
+    let outside = TempTree::new("snapshot-outside");
+    let target = outside.path().join("target.bin");
+    write_bytes(&target, b"AAAA");
+    symlink(&target, tree.path().join("link")).unwrap();
+    let before = snapshot_tree(tree.path());
+    assert!(
+        matches!(before.get(Path::new("link")), Some(SnapshotKind::Symlink(found)) if found == &target)
+    );
+
+    write_bytes(&target, b"BBBB");
+    let after_target_write = snapshot_tree(tree.path());
+    assert_snapshot_unchanged(&before, &after_target_write);
+
+    std::fs::remove_file(tree.path().join("link")).unwrap();
+    let second_target = outside.path().join("second.bin");
+    write_bytes(&second_target, b"BBBB");
+    symlink(&second_target, tree.path().join("link")).unwrap();
+    let after_retarget = snapshot_tree(tree.path());
+    let caught = std::panic::catch_unwind(|| assert_snapshot_unchanged(&before, &after_retarget));
+    assert!(caught.is_err(), "symlink retarget must be detected");
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index cfeeec9..53847fe 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -883,3 +883,40 @@ All commands run in the implementation worktree on
 - `bash scripts/guardrail.sh` — exit 0.
 - `sha256sum Cargo.lock` — `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`
   (byte-identical before and after).
+
+## Batch M — read-only dual-slot state classifier (2026-07-25)
+
+This slice adds only the store-owned READ-ONLY state classifier. Store now owns
+storage protocol `2`, extraction version `2`, and metadata key
+`indexed_with_extraction_version`. The classifier reads exactly the two
+`IndexPaths::state_slots()` regular files, never follows a slot symlink, never
+opens SQLite, and never creates, truncates, renames, deletes, or rewrites any
+namespace byte.
+
+The six protocol-stable JSON fields are required at their exact types; unknown
+fields are tolerated. Owner and checksum must each be exactly 64 lowercase hex
+characters. The SHA-256 payload uses fixed ASCII labels and LF separators and
+hashes the raw phase text. These stable checks, checksum value, and owner equality
+are enforced before a future storage protocol is trusted; an unknown future phase
+is then accepted, while current protocol accepts only `building`, `current`, and
+`uninitialized`. Lower/zero protocols and every present malformed, unreadable,
+non-regular, checksum-invalid, or owner-mismatched slot are typed `Corrupt` and
+dominate a valid companion.
+
+Aggregation first rejects any invalid slot, then rejects equal sequence across
+all validated pairs (current/current, future/future, or mixed) independently of
+JSON byte formatting. A validated future-protocol record then dominates a current
+record regardless of sequence; otherwise the highest current record wins. The
+selected `u64::MAX` sequence is corruption before protocol/extraction status
+mapping. Public tests cover the complete matrix plus exact fail-closed filesystem
+snapshots (directories, complete file bytes, and unfollowed symlink targets keyed
+by `PathBuf`), including equal-length mutation and Unix symlink self-tests.
+
+Behavioral Red was established by temporarily weakening mixed equal-sequence
+rejection: `index_state_equal_future_and_mixed_sequences_are_corrupt_before_future_dominance`
+failed with `expected Corrupt, got Future { built: 9 }`; the production condition
+was restored before verification.
+
+**Strict scope boundary:** atomic publication, `IndexLease`, Store `open_for_*`
+APIs, DB stamping/corroboration, migration/finalization, uninit and daemon/watcher
+lifecycle remain unimplemented. This slice exposes no publication or lease API.

From 224e762162d7bb1b0ebdf2c78ae89c063af57ccb Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 16:07:04 +0800
Subject: [PATCH 13/91] fix(index): harden read-only state classification

---
 crates/codegraph-store/src/index_state.rs   | 180 ++++++++++++++++++--
 crates/codegraph-store/tests/index_state.rs |  72 +++++---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md   |  74 +++++++-
 3 files changed, 290 insertions(+), 36 deletions(-)

diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
index c8b37b1..5e06da7 100644
--- a/crates/codegraph-store/src/index_state.rs
+++ b/crates/codegraph-store/src/index_state.rs
@@ -7,21 +7,27 @@
 //! the persisted state-slot contract, plus the classifier that turns the two
 //! fixed slots into an [`ExtractionStatus`].
 //!
-//! # Scope of this slice: READ-ONLY
+//! # Scope of the classifier: READ-ONLY
 //!
-//! This slice is deliberately NONMUTATING and self-contained:
+//! The classifier in this module is deliberately NONMUTATING and self-contained:
 //!
 //! - it never creates, truncates, renames, or deletes any file or directory
 //!   (not the current root, the permanent lock, a state slot, a temp file, the
 //!   database, a sidecar, or the tombstone);
 //! - it never opens SQLite, so it cannot run schema setup, migrations, WAL
 //!   changes, or `ANALYZE`;
-//! - it exposes NO publication API. State publication, `IndexLease`,
+//! - it exposes NO state-slot publication API. State publication, `IndexLease`,
 //!   `Store::open_for_read` / `open_for_status` / `open_for_write`,
 //!   `Store::stamp_extraction_version`, DB-stamp corroboration, migration mode,
 //!   uninit lifecycle, and the daemon/watcher lifecycle all land in LATER Batch M
 //!   slices and are NOT implemented here.
 //!
+//! This classifier boundary is narrower than the commit series containing it:
+//! existing CLI indexing still writes `project_metadata`, but now takes that
+//! metadata key and extraction version (`2`) from this store-owned module. That
+//! pre-existing DB stamping is not state-slot publication and is not performed by
+//! this classifier.
+//!
 //! [`checksum_hex`] and [`canonical_checksum_payload`] are pure functions (no
 //! I/O); they define the byte representation a future publisher must reproduce,
 //! and the tests use them to author fixture slots.
@@ -60,8 +66,9 @@
 //! # Classification order (deterministic, typed, never string-matched)
 //!
 //! 1. **Structural defects dominate.** A present slot that cannot be stat'd or
-//!    read, is not a regular file (a directory or symlink at a fixed slot path is
-//!    an INVALID slot, never followed), or whose bytes are not a JSON object with
+//!    read, is not a regular file (a directory or a statically observed symlink at
+//!    a fixed slot path is an INVALID slot), changes identity while being read, or
+//!    whose bytes are not a JSON object with
 //!    the six canonical fields at their canonical types ⇒ [`ExtractionStatus::Corrupt`].
 //!    A present invalid slot is NEVER ignored because the other slot is valid:
 //!    a future writer may have authored it, so it is security-relevant.
@@ -93,7 +100,8 @@
 //! `Display` renderings exist for operator messages only and are never parsed.
 
 use std::fmt;
-use std::io;
+use std::fs::{File, Metadata};
+use std::io::{self, Read};
 use std::path::{Path, PathBuf};
 
 use codegraph_core::IndexPaths;
@@ -267,6 +275,17 @@ pub enum CorruptReason {
         /// The observed entry kind.
         kind: &'static str,
     },
+    /// The fixed slot path stopped naming the same regular filesystem entry
+    /// between the initial no-follow metadata check, opening the read handle,
+    /// and the post-read no-follow corroboration.
+    SlotChangedDuringRead {
+        /// Slot index (0 or 1).
+        slot: u8,
+        /// Slot path.
+        path: PathBuf,
+        /// Stable diagnostic without platform-specific identity values.
+        detail: String,
+    },
     /// The bytes are not a JSON object carrying the six canonical fields at
     /// their canonical JSON types.
     MalformedJson {
@@ -369,6 +388,11 @@ impl fmt::Display for CorruptReason {
                 "index state slot {slot} ({}) is a {kind}, not a regular file",
                 path.display()
             ),
+            Self::SlotChangedDuringRead { slot, path, detail } => write!(
+                f,
+                "index state slot {slot} ({}) changed while being read: {detail}",
+                path.display()
+            ),
             Self::MalformedJson { slot, path, detail } => write!(
                 f,
                 "index state slot {slot} ({}) is malformed: {detail}",
@@ -596,7 +620,21 @@ struct WireSlot {
 }
 
 fn read_slot(index: u8, path: &Path) -> RawSlot {
-    let meta = match std::fs::symlink_metadata(path) {
+    read_slot_with(index, path, |_| {})
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ReadCheckpoint {
+    InitialMetadataValidated,
+    HandleOpened,
+    BytesRead,
+}
+
+/// Read one fixed slot from one opened handle and corroborate that the path
+/// still names the same entry. The callback is private and exists solely so the
+/// unit test can replace a slot at an exact checkpoint without a timing race.
+fn read_slot_with(index: u8, path: &Path, mut checkpoint: impl FnMut(ReadCheckpoint)) -> RawSlot {
+    let initial = match std::fs::symlink_metadata(path) {
         Ok(meta) => meta,
         Err(err) if err.kind() == io::ErrorKind::NotFound => return RawSlot::Absent,
         Err(err) => {
@@ -607,7 +645,7 @@ fn read_slot(index: u8, path: &Path) -> RawSlot {
             });
         }
     };
-    let file_type = meta.file_type();
+    let file_type = initial.file_type();
     if !file_type.is_file() {
         let kind = if file_type.is_dir() {
             "directory"
@@ -622,8 +660,10 @@ fn read_slot(index: u8, path: &Path) -> RawSlot {
             kind,
         });
     }
-    let bytes = match std::fs::read(path) {
-        Ok(bytes) => bytes,
+    checkpoint(ReadCheckpoint::InitialMetadataValidated);
+
+    let mut file = match File::open(path) {
+        Ok(file) => file,
         Err(err) => {
             return RawSlot::Invalid(CorruptReason::UnreadableSlot {
                 slot: index,
@@ -632,6 +672,51 @@ fn read_slot(index: u8, path: &Path) -> RawSlot {
             });
         }
     };
+    let opened = match file.metadata() {
+        Ok(meta) => meta,
+        Err(err) => {
+            return RawSlot::Invalid(CorruptReason::UnreadableSlot {
+                slot: index,
+                path: path.to_path_buf(),
+                detail: format!("opened-handle metadata failed: {err}"),
+            });
+        }
+    };
+    if !opened.is_file() {
+        return slot_changed(index, path, "opened handle is not a regular file");
+    }
+    if !same_file_identity(&initial, &opened) {
+        return slot_changed(index, path, "entry identity changed before open");
+    }
+    checkpoint(ReadCheckpoint::HandleOpened);
+
+    let mut bytes = Vec::new();
+    if let Err(err) = file.read_to_end(&mut bytes) {
+        return RawSlot::Invalid(CorruptReason::UnreadableSlot {
+            slot: index,
+            path: path.to_path_buf(),
+            detail: err.to_string(),
+        });
+    }
+    checkpoint(ReadCheckpoint::BytesRead);
+
+    let final_meta = match std::fs::symlink_metadata(path) {
+        Ok(meta) => meta,
+        Err(err) => {
+            return slot_changed(
+                index,
+                path,
+                &format!("path disappeared or became unreadable after read: {err}"),
+            );
+        }
+    };
+    if !final_meta.file_type().is_file() {
+        return slot_changed(index, path, "path no longer names a regular file");
+    }
+    if !same_file_identity(&opened, &final_meta) {
+        return slot_changed(index, path, "entry identity changed during read");
+    }
+
     match serde_json::from_slice::<WireSlot>(&bytes) {
         Ok(wire) => RawSlot::Parsed { wire, bytes },
         Err(err) => RawSlot::Invalid(CorruptReason::MalformedJson {
@@ -642,6 +727,47 @@ fn read_slot(index: u8, path: &Path) -> RawSlot {
     }
 }
 
+fn slot_changed(index: u8, path: &Path, detail: &str) -> RawSlot {
+    RawSlot::Invalid(CorruptReason::SlotChangedDuringRead {
+        slot: index,
+        path: path.to_path_buf(),
+        detail: detail.to_string(),
+    })
+}
+
+#[cfg(unix)]
+fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
+    use std::os::unix::fs::MetadataExt as _;
+    left.dev() == right.dev() && left.ino() == right.ino()
+}
+
+#[cfg(windows)]
+fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
+    use std::os::windows::fs::MetadataExt as _;
+    matches!(
+        (
+            left.volume_serial_number(),
+            left.file_index(),
+            right.volume_serial_number(),
+            right.file_index(),
+        ),
+        (Some(left_volume), Some(left_index), Some(right_volume), Some(right_index))
+            if left_volume == right_volume && left_index == right_index
+    )
+}
+
+#[cfg(not(any(unix, windows)))]
+fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
+    // std exposes no stable object ID on this platform. This fallback is
+    // deliberately conservative about observable metadata, but cannot exclude a
+    // replacement engineered with identical attributes; callers must not claim
+    // the Unix/Windows identity guarantee here.
+    left.len() == right.len()
+        && left.permissions().readonly() == right.permissions().readonly()
+        && left.modified().ok() == right.modified().ok()
+        && left.created().ok() == right.created().ok()
+}
+
 /// Semantically validate ONE parsed slot into a [`SlotOutcome`].
 ///
 /// Order is fixed and typed: owner encoding → checksum encoding → checksum over
@@ -893,3 +1019,37 @@ fn pick_highest<'a>(
     }
     best
 }
+
+#[cfg(test)]
+mod read_tests {
+    use super::*;
+
+    #[test]
+    fn regular_slot_replaced_after_validation_is_typed_corruption() {
+        let root = std::env::temp_dir().join(format!(
+            "codegraph-slot-replacement-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        std::fs::create_dir(&root).expect("create replacement test root");
+        let slot = root.join("index-state.0.json");
+        let replacement = root.join("replacement.json");
+        std::fs::write(&slot, b"original").expect("write original slot");
+        std::fs::write(&replacement, b"replacement").expect("write replacement slot");
+
+        let mut replaced = false;
+        let observed = read_slot_with(0, &slot, |point| {
+            if point == ReadCheckpoint::InitialMetadataValidated && !replaced {
+                std::fs::remove_file(&slot).expect("remove validated slot");
+                std::fs::rename(&replacement, &slot).expect("install replacement slot");
+                replaced = true;
+            }
+        });
+
+        assert!(matches!(
+            observed,
+            RawSlot::Invalid(CorruptReason::SlotChangedDuringRead { slot: 0, .. })
+        ));
+        std::fs::remove_dir_all(&root).expect("remove replacement test root");
+    }
+}
diff --git a/crates/codegraph-store/tests/index_state.rs b/crates/codegraph-store/tests/index_state.rs
index a48c5c1..909502e 100644
--- a/crates/codegraph-store/tests/index_state.rs
+++ b/crates/codegraph-store/tests/index_state.rs
@@ -1,6 +1,6 @@
 //! Public-surface contract tests for the read-only dual-slot classifier.
 
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 use std::ffi::OsString;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
@@ -167,7 +167,10 @@ fn index_state_current_protocol_maps_each_phase() {
             phase,
             OWNER,
         );
-        assert_eq!(classify_slots(&tree.slots(), OWNER).status(), &expected);
+        assert_eq!(
+            classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER)).status(),
+            &expected
+        );
     }
 }
 
@@ -243,7 +246,7 @@ fn index_state_missing_and_wrong_typed_required_fields_are_malformed() {
     ] {
         let tree = TempTree::new("malformed-shape");
         write_bytes(&tree.slots()[0], &serde_json::to_vec(&value).unwrap());
-        let result = classify_slots(&tree.slots(), OWNER);
+        let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
         assert_corrupt(&result, |reason| {
             matches!(reason, CorruptReason::MalformedJson { .. })
         });
@@ -259,7 +262,7 @@ fn index_state_bad_owner_and_checksum_shapes_are_typed_corruption() {
     for owner in bad_owners {
         let tree = TempTree::new("bad-owner-shape");
         write_wire(&tree.slots()[0], 1, 3, 2, "future-phase", owner);
-        let result = classify_slots(&tree.slots(), OWNER);
+        let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
         assert_corrupt(&result, |reason| {
             matches!(reason, CorruptReason::InvalidOwnerEncoding { .. })
         });
@@ -286,14 +289,18 @@ fn index_state_checksum_and_owner_mismatch_are_corrupt_even_for_future_protocol(
         &checksum_tree.slots()[0],
         &serde_json::to_vec(&value).unwrap(),
     );
-    let result = classify_slots(&checksum_tree.slots(), OWNER);
+    let result = classify_unchanged(checksum_tree.path(), || {
+        classify_slots(&checksum_tree.slots(), OWNER)
+    });
     assert_corrupt(&result, |reason| {
         matches!(reason, CorruptReason::ChecksumMismatch { .. })
     });
 
     let owner_tree = TempTree::new("owner-mismatch");
     write_wire(&owner_tree.slots()[0], 1, 3, 2, "future-phase", OTHER_OWNER);
-    let result = classify_slots(&owner_tree.slots(), OWNER);
+    let result = classify_unchanged(owner_tree.path(), || {
+        classify_slots(&owner_tree.slots(), OWNER)
+    });
     assert_corrupt(&result, |reason| {
         matches!(reason, CorruptReason::OwnerMismatch { .. })
     });
@@ -337,7 +344,7 @@ fn index_state_any_malformed_present_slot_dominates_a_valid_companion() {
     let tree = TempTree::new("invalid-dominance");
     write_bytes(&tree.slots()[0], b"not json");
     write_wire(&tree.slots()[1], 99, 2, 2, "current", OWNER);
-    let result = classify_slots(&tree.slots(), OWNER);
+    let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
     assert_corrupt(&result, |reason| {
         matches!(reason, CorruptReason::MalformedJson { slot: 0, .. })
     });
@@ -348,7 +355,9 @@ fn index_state_any_malformed_present_slot_dominates_a_valid_companion() {
 fn index_state_non_regular_and_unreadable_slots_are_corrupt() {
     let directory = TempTree::new("slot-directory");
     std::fs::create_dir(&directory.slots()[0]).unwrap();
-    let result = classify_slots(&directory.slots(), OWNER);
+    let result = classify_unchanged(directory.path(), || {
+        classify_slots(&directory.slots(), OWNER)
+    });
     assert_corrupt(&result, |reason| {
         matches!(
             reason,
@@ -366,7 +375,7 @@ fn index_state_non_regular_and_unreadable_slots_are_corrupt() {
         let target = link.path().join("target.json");
         write_wire(&target, 1, 2, 2, "current", OWNER);
         symlink(&target, &link.slots()[0]).unwrap();
-        let result = classify_slots(&link.slots(), OWNER);
+        let result = classify_unchanged(link.path(), || classify_slots(&link.slots(), OWNER));
         assert_corrupt(&result, |reason| {
             matches!(
                 reason,
@@ -399,7 +408,7 @@ fn index_state_future_protocol_dominates_current_in_both_sequence_directions() {
             "future-phase",
             OWNER,
         );
-        let result = classify_slots(&tree.slots(), OWNER);
+        let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
         assert_eq!(result.status(), &ExtractionStatus::Future { built: 77 });
         assert_eq!(result.authoritative().expect("future authority").index, 1);
     }
@@ -411,7 +420,9 @@ fn index_state_equal_current_sequences_are_corrupt_for_identical_and_reformatted
     let bytes = wire_bytes(7, 2, 2, "current", OWNER);
     write_bytes(&identical.slots()[0], &bytes);
     write_bytes(&identical.slots()[1], &bytes);
-    let result = classify_slots(&identical.slots(), OWNER);
+    let result = classify_unchanged(identical.path(), || {
+        classify_slots(&identical.slots(), OWNER)
+    });
     assert_corrupt(&result, |reason| {
         matches!(
             reason,
@@ -431,7 +442,9 @@ fn index_state_equal_current_sequences_are_corrupt_for_identical_and_reformatted
          \"storageProtocol\":2, \"sequence\":7 }}"
     );
     write_bytes(&reformatted.slots()[1], other.as_bytes());
-    let result = classify_slots(&reformatted.slots(), OWNER);
+    let result = classify_unchanged(reformatted.path(), || {
+        classify_slots(&reformatted.slots(), OWNER)
+    });
     assert_corrupt(&result, |reason| {
         matches!(
             reason,
@@ -448,7 +461,7 @@ fn index_state_equal_future_and_mixed_sequences_are_corrupt_before_future_domina
     let future = TempTree::new("equal-future");
     write_wire(&future.slots()[0], 8, 3, 9, "alpha", OWNER);
     write_wire(&future.slots()[1], 8, 4, 10, "beta", OWNER);
-    let result = classify_slots(&future.slots(), OWNER);
+    let result = classify_unchanged(future.path(), || classify_slots(&future.slots(), OWNER));
     assert_corrupt(&result, |reason| {
         matches!(reason, CorruptReason::EqualSequence { sequence: 8, .. })
     });
@@ -456,7 +469,7 @@ fn index_state_equal_future_and_mixed_sequences_are_corrupt_before_future_domina
     let mixed = TempTree::new("equal-mixed");
     write_wire(&mixed.slots()[0], 8, 2, 2, "current", OWNER);
     write_wire(&mixed.slots()[1], 8, 3, 10, "future-phase", OWNER);
-    let result = classify_slots(&mixed.slots(), OWNER);
+    let result = classify_unchanged(mixed.path(), || classify_slots(&mixed.slots(), OWNER));
     assert_corrupt(&result, |reason| {
         matches!(reason, CorruptReason::EqualSequence { sequence: 8, .. })
     });
@@ -474,7 +487,7 @@ fn index_state_selected_max_sequence_is_corrupt_before_status_mapping() {
             phase,
             OWNER,
         );
-        let result = classify_slots(&tree.slots(), OWNER);
+        let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
         assert_corrupt(
             &result,
             |reason| matches!(reason, CorruptReason::SequenceExhausted { sequence } if *sequence == u64::MAX),
@@ -495,7 +508,7 @@ fn index_state_highest_ordinary_current_slot_is_authoritative_with_full_metadata
     let tree = TempTree::new("authority");
     write_wire(&tree.slots()[0], 4, 2, 1, "building", OWNER);
     write_wire(&tree.slots()[1], 5, 2, 2, "current", OWNER);
-    let result = classify_slots(&tree.slots(), OWNER);
+    let result = classify_unchanged(tree.path(), || classify_slots(&tree.slots(), OWNER));
     assert_eq!(result.status(), &ExtractionStatus::Current);
     let authority = result.authoritative().expect("authority");
     assert_eq!(authority.index, 1);
@@ -581,13 +594,31 @@ fn assert_snapshot_unchanged(
         .chain(after.keys())
         .filter(|path| before.get(*path) != after.get(*path))
         .cloned()
-        .collect::<Vec<_>>();
+        .collect::<BTreeSet<_>>();
+    let total = changed.len();
+    let bounded = changed.iter().take(16).cloned().collect::<Vec<_>>();
     assert!(
         changed.is_empty(),
-        "filesystem snapshot changed at {changed:?}"
+        "filesystem snapshot changed at {bounded:?}{}",
+        if total > bounded.len() {
+            format!(" (and {} more paths)", total - bounded.len())
+        } else {
+            String::new()
+        }
     );
 }
 
+fn classify_unchanged(
+    root: &Path,
+    classify_once: impl FnOnce() -> codegraph_store::IndexStateClassification,
+) -> codegraph_store::IndexStateClassification {
+    let before = snapshot_tree(root);
+    let classification = classify_once();
+    let after = snapshot_tree(root);
+    assert_snapshot_unchanged(&before, &after);
+    classification
+}
+
 #[test]
 fn index_state_classifier_is_exactly_byte_nonmutating_and_never_opens_sqlite() {
     let project = TempTree::new("nonmutation");
@@ -606,11 +637,8 @@ fn index_state_classifier_is_exactly_byte_nonmutating_and_never_opens_sqlite() {
     #[cfg(unix)]
     std::os::unix::fs::symlink("codegraph.db", paths.current_root().join("db-link")).unwrap();
 
-    let before = snapshot_tree(project.path());
-    let result = classify(&paths);
-    let after = snapshot_tree(project.path());
+    let result = classify_unchanged(project.path(), || classify(&paths));
     assert_eq!(result.status(), &ExtractionStatus::Current);
-    assert_snapshot_unchanged(&before, &after);
 }
 
 #[test]
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 53847fe..fcdccbc 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -886,12 +886,15 @@ All commands run in the implementation worktree on
 
 ## Batch M — read-only dual-slot state classifier (2026-07-25)
 
-This slice adds only the store-owned READ-ONLY state classifier. Store now owns
+This slice adds the store-owned READ-ONLY state classifier. Store now owns
 storage protocol `2`, extraction version `2`, and metadata key
 `indexed_with_extraction_version`. The classifier reads exactly the two
-`IndexPaths::state_slots()` regular files, never follows a slot symlink, never
-opens SQLite, and never creates, truncates, renames, deletes, or rewrites any
-namespace byte.
+`IndexPaths::state_slots()` regular files, never opens SQLite, and never creates,
+truncates, renames, deletes, or rewrites any namespace byte. The same commit
+series also routes the CLI's PRE-EXISTING `project_metadata` extraction stamp
+through the store-owned key/version and therefore changes that DB stamp from `1`
+to `2`; that existing CLI mutation is outside the classifier and means the whole
+slice must not be described as mutation-free.
 
 The six protocol-stable JSON fields are required at their exact types; unknown
 fields are tolerated. Owner and checksum must each be exactly 64 lowercase hex
@@ -920,3 +923,66 @@ was restored before verification.
 **Strict scope boundary:** atomic publication, `IndexLease`, Store `open_for_*`
 APIs, DB stamping/corroboration, migration/finalization, uninit and daemon/watcher
 lifecycle remain unimplemented. This slice exposes no publication or lease API.
+
+## Batch M — read-only classifier correction: byte proof + replacement detection (2026-07-25)
+
+Verification of commit `4d5a39c` found three focused defects; that commit remains
+intact and this correction is additive:
+
+1. The fail-closed tree snapshot wrapped only one ordinary `Current` call, so it
+   did not mechanically prove nonmutation on malformed-plus-valid,
+   checksum/owner corruption, either future/current sequence direction, all four
+   equal-sequence classes, current/future maximum sequence, or current
+   `uninitialized`. The integration tests now use one
+   generic `classify_unchanged` helper that snapshots immediately before and
+   after every named `classify`/`classify_slots` call. The single oracle still
+   records directories, complete regular
+   file bytes, and unfollowed symlink targets under native `PathBuf` keys; every
+   I/O/unsupported kind panics, and changed-path output is bounded to 16 paths.
+   Its equal-length mutation and Unix non-following self-tests remain green.
+2. `read_slot` previously paired `symlink_metadata(path)` with `fs::read(path)`.
+   A fixed slot replaced after the no-follow stat could therefore be consumed
+   through a symlink or as a different file. It now opens one `File`, verifies
+   the opened handle is regular, reads only from that handle, and corroborates
+   pre-open/handle/post-read identity. A static symlink remains
+   `NotARegularFile`; disappearance, type change, or identity mismatch is the new
+   typed `SlotChangedDuringRead` corruption and is never accepted. Unix compares
+   `MetadataExt::{dev, ino}`; Windows uses std's volume serial plus file index.
+   Other targets conservatively compare available metadata attributes and do NOT
+   claim stable-identity exclusion. This is pre/open/post corroboration, not a
+   claim that portable std provides an atomic no-follow open on every OS.
+3. The prior ledger said the slice "adds only the classifier". That was too broad:
+   the classifier itself is read-only, but `main.rs` also moved the existing CLI
+   metadata key/version source into `codegraph-store` and now stamps extraction
+   version `2`. There is still no state-slot publication, `IndexLease`, Store
+   open/stamp API, migration/finalizer, or uninit/daemon/watch lifecycle here.
+
+Deterministic Red evidence for defect 2: the private read-checkpoint test replaces
+the regular slot at `InitialMetadataValidated`, with no sleeps. Temporarily
+making Unix identity comparison always return true caused
+`regular_slot_replaced_after_validation_is_typed_corruption` to fail its expected
+`SlotChangedDuringRead` assertion; restoring `dev`/`ino` comparison made it pass.
+The targeted command
+`cargo test -p codegraph-store --locked index_state -- --nocapture` (after the
+workspace-version gate) reports **1 internal + 20 integration tests passed, 0
+failed**. Full final gate outputs are recorded below after completion.
+
+Final validation evidence:
+
+- `cargo fmt --all --check`, workspace/all-target `cargo check --locked`, the
+  required `codegraph-core` MSVC cross-check, and workspace/all-target Clippy with
+  `-D warnings` all passed. The MSVC result is compilation only; no native Windows
+  runtime coverage is claimed.
+- Standalone `cargo test --workspace --locked` passed **2695 tests across 106
+  reporting suites, 0 failed**. `bash scripts/guardrail.sh` passed. Every Cargo
+  batch was preceded by `bash scripts/check-workspace-versions.sh`.
+- `make ci CARGO='cargo --locked'` was attempted twice. Both runs passed format
+  and Clippy, then hit the same pre-existing timing-sensitive
+  `daemon_single_watcher_fires_once` failure (`watcher sync #1: 0 file(s)
+  reindexed` instead of naming `extra.ts`). The standalone full workspace run in
+  the same validation batch passed that test and all 2695 tests. Per the two-check
+  ceiling, it was not retried a third time; no unrelated watcher code was changed.
+- LSP diagnostics refused the external `/tmp` worktree because it is outside the
+  tool request cwd. Workspace `cargo check` and Clippy are the recorded fallback.
+- `Cargo.lock` remained byte-identical at
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.

From ba399c49c7bc4f53dec307f0f32fffeeb890a0a1 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 16:24:52 +0800
Subject: [PATCH 14/91] docs(upstream-sync): format the Batch M ledger and
 correct its final gate evidence

The Batch M classifier validation evidence was appended after the last oxfmt
pass, so the committed ledger was not formatter-clean and the next `make ci`
failed at `fmt-check` before any test ran.

Reformat the ledger with oxfmt and append a dated correction that keeps both
historical daemon_single_watcher_fires_once attempts as history, records the
doc-format failure observed after 224e762, and states the authoritative
post-format gate result.

Documentation only: no Rust, manifest, schema, golden, or Cargo.lock change.
---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 29 ++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index fcdccbc..ce0eabc 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -979,10 +979,37 @@ Final validation evidence:
 - `make ci CARGO='cargo --locked'` was attempted twice. Both runs passed format
   and Clippy, then hit the same pre-existing timing-sensitive
   `daemon_single_watcher_fires_once` failure (`watcher sync #1: 0 file(s)
-  reindexed` instead of naming `extra.ts`). The standalone full workspace run in
+reindexed` instead of naming `extra.ts`). The standalone full workspace run in
   the same validation batch passed that test and all 2695 tests. Per the two-check
   ceiling, it was not retried a third time; no unrelated watcher code was changed.
 - LSP diagnostics refused the external `/tmp` worktree because it is outside the
   tool request cwd. Workspace `cargo check` and Clippy are the recorded fallback.
 - `Cargo.lock` remained byte-identical at
   `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+**Correction to the validation evidence above (post-`224e762` verification).**
+Independent verification of commit `224e762` reran the targeted classifier command
+and reproduced **1 internal + 20 integration tests passed, 0 failed**. It then ran
+the full gate chain, and the `make ci` invocation failed _before_ tests at the
+`oxfmt --check` doc-format step, because the validation evidence in this ledger had
+been appended _after_ the last formatting pass and was therefore not
+formatter-clean. The two `daemon_single_watcher_fires_once` runs recorded in the
+bullet above are preserved as accurate _historical_ attempts, but they were not the
+last gate: at commit `224e762` the gate stopped earlier, at doc formatting. The
+formatting was corrected in this commit and a fresh `make ci` was then run; that
+fresh post-format run is the authoritative final gate and its result is recorded
+immediately below.
+
+Authoritative final gate (fresh run, after doc formatting):
+
+- `bash scripts/check-workspace-versions.sh` passed before every Cargo-invoking
+  command, and `oxfmt --check` is clean on this ledger.
+- `make ci` (fmt-check + Clippy `-D warnings` + `cargo test --workspace` +
+  `bash scripts/guardrail.sh`) **passed, exit 0** — every reporting suite ended
+  `0 failed` and the guardrail exited 0. Because no test in this workspace is
+  ignored by the gate, that exit-0 necessarily includes
+  `daemon_single_watcher_fires_once`, which therefore passed in this run rather
+  than flaking as it did in the two historical attempts above.
+- `Cargo.lock` still byte-identical at
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`; this
+  correction changes documentation only.

From b772e0f519ce4ebc731e141f846ea321e5078789 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 17:13:44 +0800
Subject: [PATCH 15/91] feat(store): add reusable index lease capability

---
 crates/codegraph-store/src/index_lease.rs   | 307 +++++++++++++
 crates/codegraph-store/src/index_state.rs   |  87 +++-
 crates/codegraph-store/src/lib.rs           |   2 +
 crates/codegraph-store/tests/index_lease.rs | 453 ++++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md   | 100 +++++
 5 files changed, 939 insertions(+), 10 deletions(-)
 create mode 100644 crates/codegraph-store/src/index_lease.rs
 create mode 100644 crates/codegraph-store/tests/index_lease.rs

diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs
new file mode 100644
index 0000000..f6b3e09
--- /dev/null
+++ b/crates/codegraph-store/src/index_lease.rs
@@ -0,0 +1,307 @@
+//! Cooperative kernel-lock capability for one resolved v2 index namespace.
+//!
+//! A lease owns one locked file description behind an [`Arc`]. Cloning a lease
+//! clones only that `Arc`; the file is unlocked and closed when the final owner
+//! drops. Acquisition always uses the nonblocking standard-library `try_lock*`
+//! calls in a bounded loop with a monotonic deadline and cancellation checks.
+
+use std::fs::{File, OpenOptions};
+use std::io;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use thiserror::Error;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum LeaseMode {
+    Shared,
+    Exclusive,
+}
+
+#[derive(Debug)]
+struct LeaseInner {
+    file: File,
+    mode: LeaseMode,
+    db_parent: PathBuf,
+}
+
+impl Drop for LeaseInner {
+    fn drop(&mut self) {
+        // This Drop runs exactly once, when the final `Arc<LeaseInner>` owner is
+        // gone. Unlock before File's own Drop closes the one locked description.
+        // There is no recovery action available from Drop; close also releases
+        // the kernel lock if this best-effort explicit unlock reports an error.
+        let _ = self.file.unlock();
+    }
+}
+
+/// A cloneable capability tied to one resolved v2 database parent.
+#[derive(Debug, Clone)]
+pub struct IndexLease {
+    inner: Arc<LeaseInner>,
+}
+
+/// Typed failures while opening or acquiring a permanent index lock.
+#[derive(Debug, Error)]
+pub enum IndexLeaseError {
+    /// An existing namespace has no permanent lock.
+    #[error("permanent index lock does not exist: {path}")]
+    LockNotFound { path: PathBuf },
+    /// Explicit namespace creation was requested for an existing root.
+    #[error("cannot create an initial index lease because the namespace already exists: {path}")]
+    NamespaceAlreadyExists { path: PathBuf },
+    /// The current root could not be created or inspected.
+    #[error("cannot create or inspect index root {path}: {source}")]
+    CreateRoot {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    /// The permanent lock file could not be opened.
+    #[error("cannot open permanent index lock {path}: {source}")]
+    OpenLock {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    /// The bounded acquisition deadline elapsed while another process held an
+    /// incompatible lock.
+    #[error("timed out acquiring permanent index lock {path}")]
+    TimedOut { path: PathBuf },
+    /// The caller cancelled bounded acquisition.
+    #[error("cancelled while acquiring permanent index lock {path}")]
+    Cancelled { path: PathBuf },
+    /// The operating system rejected a lock operation for another reason.
+    #[error("cannot acquire permanent index lock {path}: {source}")]
+    Lock {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+}
+
+/// Typed failures when a later writer validates an [`IndexLease`] capability.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum IndexLeaseValidationError {
+    /// A shared reader lease cannot authorize a writer.
+    #[error("a shared index lease cannot authorize a writer")]
+    SharedLease,
+    /// The capability belongs to another resolved v2 database parent.
+    #[error("index lease belongs to a different v2 database parent")]
+    WrongDbParent,
+}
+
+impl IndexLease {
+    /// Open and acquire the permanent lock of an existing namespace for shared
+    /// reading. This API never creates a directory or file.
+    pub fn acquire_shared_existing(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        Self::acquire_existing(paths, LeaseMode::Shared, deadline, cancelled)
+    }
+
+    /// Open and acquire the permanent lock of an existing namespace for
+    /// exclusive writing. This API never creates a directory or file.
+    pub fn acquire_exclusive_existing(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        Self::acquire_existing(paths, LeaseMode::Exclusive, deadline, cancelled)
+    }
+
+    /// Explicitly create a genuinely absent current root and its permanent lock,
+    /// then acquire the initial exclusive capability.
+    pub fn create_exclusive(
+        paths: &IndexPaths,
+        deadline: Instant,
+        mut cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        let root = paths.current_root();
+        let lock_path = paths.permanent_lock();
+        if cancelled() {
+            return Err(IndexLeaseError::Cancelled { path: lock_path });
+        }
+        if Instant::now() >= deadline {
+            return Err(IndexLeaseError::TimedOut { path: lock_path });
+        }
+        match std::fs::symlink_metadata(root) {
+            Ok(_) => {
+                return Err(IndexLeaseError::NamespaceAlreadyExists {
+                    path: root.to_path_buf(),
+                });
+            }
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+            Err(source) => {
+                return Err(IndexLeaseError::CreateRoot {
+                    path: root.to_path_buf(),
+                    source,
+                });
+            }
+        }
+        let parent = root
+            .parent()
+            .expect("IndexPaths current root always has a parent");
+        std::fs::create_dir_all(parent).map_err(|source| IndexLeaseError::CreateRoot {
+            path: parent.to_path_buf(),
+            source,
+        })?;
+        std::fs::create_dir(root).map_err(|source| {
+            if source.kind() == io::ErrorKind::AlreadyExists {
+                IndexLeaseError::NamespaceAlreadyExists {
+                    path: root.to_path_buf(),
+                }
+            } else {
+                IndexLeaseError::CreateRoot {
+                    path: root.to_path_buf(),
+                    source,
+                }
+            }
+        })?;
+        let file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(false)
+            .open(&lock_path)
+            .map_err(|source| IndexLeaseError::OpenLock {
+                path: lock_path.clone(),
+                source,
+            })?;
+        Self::acquire_file(
+            file,
+            lock_path,
+            LeaseMode::Exclusive,
+            db_parent(paths),
+            deadline,
+            cancelled,
+        )
+    }
+
+    /// Whether this capability represents a shared reader lock.
+    #[must_use]
+    pub fn is_shared(&self) -> bool {
+        self.inner.mode == LeaseMode::Shared
+    }
+
+    /// Whether this capability represents an exclusive writer lock.
+    #[must_use]
+    pub fn is_exclusive(&self) -> bool {
+        self.inner.mode == LeaseMode::Exclusive
+    }
+
+    /// Whether this capability belongs to the normalized v2 DB parent in
+    /// `paths`. The identity itself remains private.
+    #[must_use]
+    pub fn matches_db_parent(&self, paths: &IndexPaths) -> bool {
+        self.inner.db_parent == db_parent(paths)
+    }
+
+    /// Validate this capability for a future write-capable store open.
+    pub fn validate_exclusive(&self, paths: &IndexPaths) -> Result<(), IndexLeaseValidationError> {
+        if self.inner.mode != LeaseMode::Exclusive {
+            return Err(IndexLeaseValidationError::SharedLease);
+        }
+        if !self.matches_db_parent(paths) {
+            return Err(IndexLeaseValidationError::WrongDbParent);
+        }
+        Ok(())
+    }
+
+    fn acquire_existing(
+        paths: &IndexPaths,
+        mode: LeaseMode,
+        deadline: Instant,
+        mut cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        let lock_path = paths.permanent_lock();
+        if cancelled() {
+            return Err(IndexLeaseError::Cancelled { path: lock_path });
+        }
+        if Instant::now() >= deadline {
+            return Err(IndexLeaseError::TimedOut { path: lock_path });
+        }
+        let file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&lock_path)
+            .map_err(|source| {
+                if source.kind() == std::io::ErrorKind::NotFound {
+                    IndexLeaseError::LockNotFound {
+                        path: lock_path.clone(),
+                    }
+                } else {
+                    IndexLeaseError::OpenLock {
+                        path: lock_path.clone(),
+                        source,
+                    }
+                }
+            })?;
+        Self::acquire_file(file, lock_path, mode, db_parent(paths), deadline, cancelled)
+    }
+
+    fn acquire_file(
+        file: File,
+        lock_path: PathBuf,
+        mode: LeaseMode,
+        db_parent: PathBuf,
+        deadline: Instant,
+        mut cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        loop {
+            if cancelled() {
+                return Err(IndexLeaseError::Cancelled { path: lock_path });
+            }
+            if Instant::now() >= deadline {
+                return Err(IndexLeaseError::TimedOut { path: lock_path });
+            }
+
+            let attempt = match mode {
+                LeaseMode::Shared => file.try_lock_shared(),
+                LeaseMode::Exclusive => file.try_lock(),
+            };
+            match attempt {
+                Ok(()) => {
+                    return Ok(Self {
+                        inner: Arc::new(LeaseInner {
+                            file,
+                            mode,
+                            db_parent,
+                        }),
+                    });
+                }
+                Err(std::fs::TryLockError::WouldBlock) => {
+                    // Check cancellation after every observed contention, then
+                    // bound the next retry by the monotonic deadline. The short
+                    // park avoids a hot spin but never substitutes for try_lock
+                    // as the lock authority.
+                    if cancelled() {
+                        return Err(IndexLeaseError::Cancelled { path: lock_path });
+                    }
+                    let now = Instant::now();
+                    if now >= deadline {
+                        return Err(IndexLeaseError::TimedOut { path: lock_path });
+                    }
+                    let remaining = deadline.saturating_duration_since(now);
+                    std::thread::park_timeout(remaining.min(Duration::from_millis(5)));
+                }
+                Err(std::fs::TryLockError::Error(source)) => {
+                    return Err(IndexLeaseError::Lock {
+                        path: lock_path,
+                        source,
+                    });
+                }
+            }
+        }
+    }
+}
+
+fn db_parent(paths: &IndexPaths) -> PathBuf {
+    let db = paths.current_db();
+    let parent = db
+        .parent()
+        .expect("IndexPaths current DB always has its resolved current root as parent");
+    debug_assert_eq!(parent, paths.current_root());
+    parent.to_path_buf()
+}
diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
index 5e06da7..73ddd6e 100644
--- a/crates/codegraph-store/src/index_state.rs
+++ b/crates/codegraph-store/src/index_state.rs
@@ -717,6 +717,25 @@ fn read_slot_with(index: u8, path: &Path, mut checkpoint: impl FnMut(ReadCheckpo
         return slot_changed(index, path, "entry identity changed during read");
     }
 
+    #[cfg(windows)]
+    match path_still_names_opened_file(&file, path) {
+        Ok(true) => {}
+        Ok(false) => {
+            return slot_changed(
+                index,
+                path,
+                "entry identity changed during Windows handle corroboration",
+            );
+        }
+        Err(err) => {
+            return slot_changed(
+                index,
+                path,
+                &format!("Windows handle corroboration failed: {err}"),
+            );
+        }
+    }
+
     match serde_json::from_slice::<WireSlot>(&bytes) {
         Ok(wire) => RawSlot::Parsed { wire, bytes },
         Err(err) => RawSlot::Invalid(CorruptReason::MalformedJson {
@@ -744,16 +763,64 @@ fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
 #[cfg(windows)]
 fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
     use std::os::windows::fs::MetadataExt as _;
-    matches!(
-        (
-            left.volume_serial_number(),
-            left.file_index(),
-            right.volume_serial_number(),
-            right.file_index(),
-        ),
-        (Some(left_volume), Some(left_index), Some(right_volume), Some(right_index))
-            if left_volume == right_volume && left_index == right_index
-    )
+
+    // Rust 1.96 still gates MetadataExt's volume/file-index accessors as
+    // unstable. Stable fields cheaply corroborate pre/open/post observations;
+    // the exact final object-identity proof follows through two live handles.
+    left.file_attributes() == right.file_attributes()
+        && left.creation_time() == right.creation_time()
+        && left.last_write_time() == right.last_write_time()
+        && left.file_size() == right.file_size()
+}
+
+#[cfg(windows)]
+fn path_still_names_opened_file(opened: &File, path: &Path) -> io::Result<bool> {
+    const FILE_ID_INFO_CLASS: i32 = 18;
+
+    #[repr(C)]
+    struct FileIdInfo {
+        volume_serial_number: u64,
+        file_id: [u8; 16],
+    }
+
+    #[link(name = "kernel32")]
+    unsafe extern "system" {
+        fn GetFileInformationByHandleEx(
+            h_file: isize,
+            file_information_class: i32,
+            lp_file_information: *mut core::ffi::c_void,
+            dw_buffer_size: u32,
+        ) -> i32;
+    }
+
+    fn file_id(file: &File) -> io::Result<(u64, [u8; 16])> {
+        use std::os::windows::io::AsRawHandle as _;
+
+        let mut info = FileIdInfo {
+            volume_serial_number: 0,
+            file_id: [0; 16],
+        };
+        // SAFETY: `file` owns a live Windows handle and `info` is a correctly
+        // sized writable FILE_ID_INFO buffer for FileIdInfo.
+        let ok = unsafe {
+            GetFileInformationByHandleEx(
+                file.as_raw_handle() as isize,
+                FILE_ID_INFO_CLASS,
+                (&mut info as *mut FileIdInfo).cast(),
+                core::mem::size_of::<FileIdInfo>() as u32,
+            )
+        };
+        if ok == 0 {
+            return Err(io::Error::last_os_error());
+        }
+        Ok((info.volume_serial_number, info.file_id))
+    }
+
+    // Open a second handle after the final no-follow metadata check. The fixed
+    // path must still identify the exact object whose first handle supplied the
+    // bytes; a replacement produces a different volume/file ID.
+    let final_handle = File::open(path)?;
+    Ok(file_id(opened)? == file_id(&final_handle)?)
 }
 
 #[cfg(not(any(unix, windows)))]
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index cf2c479..917c4ce 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -1,10 +1,12 @@
 pub mod connection;
+pub mod index_lease;
 pub mod index_state;
 pub mod migrations;
 pub mod queries;
 pub mod schema;
 
 pub use connection::Store;
+pub use index_lease::{IndexLease, IndexLeaseError, IndexLeaseValidationError};
 pub use index_state::{
     AuthoritativeSlot, CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, CorruptReason,
     EXTRACTION_VERSION_KEY, ExtractionStatus, IndexStateClassification, SlotOutcome, StatePhase,
diff --git a/crates/codegraph-store/tests/index_lease.rs b/crates/codegraph-store/tests/index_lease.rs
new file mode 100644
index 0000000..1893ddd
--- /dev/null
+++ b/crates/codegraph-store/tests/index_lease.rs
@@ -0,0 +1,453 @@
+//! Public behavioral contract for the reusable v2 index lease capability.
+
+use std::cell::Cell;
+use std::fs::OpenOptions;
+use std::io::{BufRead, BufReader, Read, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, Command, Stdio};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::mpsc::{self, Receiver};
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{IndexLease, IndexLeaseError, IndexLeaseValidationError};
+
+const CHILD_ACTION: &str = "CODEGRAPH_INDEX_LEASE_CHILD_ACTION";
+const CHILD_MODE: &str = "CODEGRAPH_INDEX_LEASE_CHILD_MODE";
+const CHILD_PROJECT: &str = "CODEGRAPH_INDEX_LEASE_CHILD_PROJECT";
+const LOCK_BYTES: &[u8] = b"permanent-lock-sentinel\nnot-a-pid\n";
+const CHILD_WAIT: Duration = Duration::from_secs(5);
+const SHORT_DEADLINE: Duration = Duration::from_millis(80);
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+struct TempProject(PathBuf);
+
+impl TempProject {
+    fn new(label: &str) -> Self {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-index-lease-{label}-{}-{serial}",
+            std::process::id()
+        ));
+        std::fs::create_dir(&path)
+            .unwrap_or_else(|err| panic!("create temp project {}: {err}", path.display()));
+        Self(path.canonicalize().expect("canonical temp project"))
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(&self.0, None).expect("resolve test IndexPaths")
+    }
+}
+
+impl Drop for TempProject {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.0)
+            .unwrap_or_else(|err| panic!("remove temp project {}: {err}", self.0.display()));
+    }
+}
+
+fn deadline_after(duration: Duration) -> Instant {
+    Instant::now()
+        .checked_add(duration)
+        .expect("test deadline is representable")
+}
+
+fn stage_existing_lock(paths: &IndexPaths, bytes: &[u8]) {
+    std::fs::create_dir_all(paths.current_root()).expect("create current root fixture");
+    let mut lock = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(paths.permanent_lock())
+        .expect("create permanent lock fixture");
+    lock.write_all(bytes).expect("write permanent lock fixture");
+    lock.sync_all().expect("sync permanent lock fixture");
+}
+
+fn lock_bytes(paths: &IndexPaths) -> Vec<u8> {
+    std::fs::read(paths.permanent_lock()).expect("read permanent lock bytes")
+}
+
+#[test]
+fn existing_open_missing_is_nonmutating_and_never_creates() {
+    let missing_root = TempProject::new("missing-root");
+    let paths = missing_root.paths();
+    assert!(!paths.current_root().exists());
+
+    let err = IndexLease::acquire_shared_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
+        .expect_err("ordinary existing open must reject a missing lock");
+    assert!(matches!(err, IndexLeaseError::LockNotFound { .. }));
+    assert!(
+        !paths.current_root().exists(),
+        "ordinary probe must not create the current root"
+    );
+
+    let missing_lock = TempProject::new("missing-lock");
+    let paths = missing_lock.paths();
+    std::fs::create_dir(paths.current_root()).expect("stage empty existing root");
+    std::fs::write(paths.current_root().join("keep.bin"), b"keep").expect("stage sibling bytes");
+    let before = std::fs::read(paths.current_root().join("keep.bin")).unwrap();
+
+    let err =
+        IndexLease::acquire_exclusive_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
+            .expect_err("ordinary existing open must reject a missing lock");
+    assert!(matches!(err, IndexLeaseError::LockNotFound { .. }));
+    assert!(!paths.permanent_lock().exists());
+    assert_eq!(
+        std::fs::read(paths.current_root().join("keep.bin")).unwrap(),
+        before
+    );
+}
+
+#[test]
+fn explicit_initial_creation_is_separate_and_never_truncates_an_existing_lock() {
+    let project = TempProject::new("initial-create");
+    let paths = project.paths();
+
+    let lease = IndexLease::create_exclusive(&paths, deadline_after(CHILD_WAIT), || false)
+        .expect("explicit initial creation");
+    assert!(lease.is_exclusive());
+    lease
+        .validate_exclusive(&paths)
+        .expect("new lease authorizes its exact namespace");
+    drop(lease);
+    assert!(paths.current_root().is_dir());
+    assert!(paths.permanent_lock().is_file());
+
+    std::fs::write(paths.permanent_lock(), LOCK_BYTES).expect("stage permanent bytes");
+    let err = IndexLease::create_exclusive(&paths, deadline_after(CHILD_WAIT), || false)
+        .expect_err("initial creation must not repair an existing namespace");
+    assert!(matches!(
+        err,
+        IndexLeaseError::NamespaceAlreadyExists { .. }
+    ));
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+
+    let shared = IndexLease::acquire_shared_existing(&paths, deadline_after(CHILD_WAIT), || false)
+        .expect("open existing lock without truncation");
+    drop(shared);
+    let exclusive =
+        IndexLease::acquire_exclusive_existing(&paths, deadline_after(CHILD_WAIT), || false)
+            .expect("open existing lock without truncation");
+    drop(exclusive);
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+}
+
+#[test]
+fn shared_processes_coexist_but_shared_blocks_exclusive() {
+    let project = TempProject::new("shared-matrix");
+    let paths = project.paths();
+    stage_existing_lock(&paths, LOCK_BYTES);
+
+    let holder = Holder::spawn(project.path(), "shared");
+    assert_eq!(run_probe(project.path(), "shared", CHILD_WAIT), "ACQUIRED");
+    assert_eq!(
+        run_probe(project.path(), "exclusive", SHORT_DEADLINE),
+        "TIMED_OUT"
+    );
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    holder.release();
+}
+
+#[test]
+fn exclusive_process_blocks_shared_and_exclusive() {
+    let project = TempProject::new("exclusive-matrix");
+    let paths = project.paths();
+    stage_existing_lock(&paths, LOCK_BYTES);
+
+    let holder = Holder::spawn(project.path(), "exclusive");
+    assert_eq!(
+        run_probe(project.path(), "shared", SHORT_DEADLINE),
+        "TIMED_OUT"
+    );
+    assert_eq!(
+        run_probe(project.path(), "exclusive", SHORT_DEADLINE),
+        "TIMED_OUT"
+    );
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    holder.release();
+
+    assert_eq!(run_probe(project.path(), "shared", CHILD_WAIT), "ACQUIRED");
+    assert_eq!(
+        run_probe(project.path(), "exclusive", CHILD_WAIT),
+        "ACQUIRED"
+    );
+}
+
+#[test]
+fn timeout_and_post_contention_cancellation_preserve_lock_bytes() {
+    let project = TempProject::new("bounded");
+    let paths = project.paths();
+    stage_existing_lock(&paths, LOCK_BYTES);
+    let holder = Holder::spawn(project.path(), "exclusive");
+
+    let timeout =
+        IndexLease::acquire_shared_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
+            .expect_err("exclusive holder must force bounded timeout");
+    assert!(matches!(timeout, IndexLeaseError::TimedOut { .. }));
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+
+    let checks = Cell::new(0_u8);
+    let cancelled = IndexLease::acquire_shared_existing(&paths, deadline_after(CHILD_WAIT), || {
+        let next = checks.get().saturating_add(1);
+        checks.set(next);
+        next >= 3
+    })
+    .expect_err("cancellation must be checked again after observing contention");
+    assert!(matches!(cancelled, IndexLeaseError::Cancelled { .. }));
+    assert!(
+        checks.get() >= 3,
+        "the cancellation check must run after a busy try_lock"
+    );
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    holder.release();
+}
+
+#[test]
+fn an_already_expired_deadline_is_nonmutating_even_when_the_lock_is_free() {
+    let project = TempProject::new("expired");
+    let paths = project.paths();
+    stage_existing_lock(&paths, LOCK_BYTES);
+
+    let expired = Instant::now()
+        .checked_sub(Duration::from_millis(1))
+        .expect("expired deadline is representable");
+    let err = IndexLease::acquire_exclusive_existing(&paths, expired, || false)
+        .expect_err("an expired deadline cannot acquire a free lock");
+    assert!(matches!(err, IndexLeaseError::TimedOut { .. }));
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+}
+
+#[test]
+fn a_clone_keeps_the_single_lock_alive_until_the_final_drop() {
+    let project = TempProject::new("clone");
+    let paths = project.paths();
+    stage_existing_lock(&paths, LOCK_BYTES);
+
+    let lease =
+        IndexLease::acquire_exclusive_existing(&paths, deadline_after(CHILD_WAIT), || false)
+            .expect("acquire exclusive lease");
+    let clone = lease.clone();
+    drop(lease);
+
+    assert_eq!(
+        run_probe(project.path(), "shared", SHORT_DEADLINE),
+        "TIMED_OUT",
+        "dropping a non-final clone must not unlock"
+    );
+    drop(clone);
+    assert_eq!(
+        run_probe(project.path(), "shared", CHILD_WAIT),
+        "ACQUIRED",
+        "the final owner must release the kernel lock"
+    );
+}
+
+#[test]
+fn writer_validation_rejects_shared_and_wrong_parent_capabilities() {
+    let project_a = TempProject::new("capability-a");
+    let project_b = TempProject::new("capability-b");
+    let paths_a = project_a.paths();
+    let paths_b = project_b.paths();
+    stage_existing_lock(&paths_a, LOCK_BYTES);
+
+    let shared =
+        IndexLease::acquire_shared_existing(&paths_a, deadline_after(CHILD_WAIT), || false)
+            .expect("shared lease");
+    assert!(shared.is_shared());
+    assert!(!shared.is_exclusive());
+    assert!(shared.matches_db_parent(&paths_a));
+    assert_eq!(
+        shared.validate_exclusive(&paths_a),
+        Err(IndexLeaseValidationError::SharedLease)
+    );
+    drop(shared);
+
+    let exclusive =
+        IndexLease::acquire_exclusive_existing(&paths_a, deadline_after(CHILD_WAIT), || false)
+            .expect("exclusive lease");
+    assert!(exclusive.is_exclusive());
+    assert!(exclusive.validate_exclusive(&paths_a).is_ok());
+    assert!(!exclusive.matches_db_parent(&paths_b));
+    assert_eq!(
+        exclusive.validate_exclusive(&paths_b),
+        Err(IndexLeaseValidationError::WrongDbParent)
+    );
+}
+
+/// Child-process entry point. Parent tests coordinate holder readiness through a
+/// pipe before launching a contender, so lock ordering never depends on sleeps.
+#[test]
+fn lease_child_process() {
+    let Ok(action) = std::env::var(CHILD_ACTION) else {
+        return;
+    };
+    let project = PathBuf::from(std::env::var_os(CHILD_PROJECT).expect("child project env"));
+    let mode = std::env::var(CHILD_MODE).expect("child mode env");
+    let paths = IndexPaths::resolve(&project, None).expect("child resolve IndexPaths");
+
+    let acquire = || match mode.as_str() {
+        "shared" => {
+            IndexLease::acquire_shared_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
+        }
+        "exclusive" => {
+            IndexLease::acquire_exclusive_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
+        }
+        other => panic!("unknown child mode {other}"),
+    };
+
+    match action.as_str() {
+        "hold" => {
+            let lease = acquire().expect("holder acquires lock");
+            println!("READY");
+            std::io::stdout().flush().expect("flush READY");
+            let mut release = [0_u8; 1];
+            std::io::stdin()
+                .read_exact(&mut release)
+                .expect("read release byte");
+            drop(lease);
+            println!("RELEASED");
+            std::io::stdout().flush().expect("flush RELEASED");
+        }
+        "probe" => match acquire() {
+            Ok(lease) => {
+                println!("ACQUIRED");
+                drop(lease);
+            }
+            Err(IndexLeaseError::TimedOut { .. }) => println!("TIMED_OUT"),
+            Err(err) => panic!("unexpected probe error: {err}"),
+        },
+        other => panic!("unknown child action {other}"),
+    }
+}
+
+struct Holder {
+    child: Option<Child>,
+    stdin: Option<ChildStdin>,
+    tail: Receiver<String>,
+}
+
+impl Holder {
+    fn spawn(project: &Path, mode: &str) -> Self {
+        let mut child = child_command(project, mode, "hold")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .spawn()
+            .expect("spawn lock holder");
+        let stdin = child.stdin.take().expect("holder stdin");
+        let stdout = child.stdout.take().expect("holder stdout");
+        let (ready_tx, ready_rx) = mpsc::channel();
+        let (tail_tx, tail_rx) = mpsc::channel();
+        std::thread::spawn(move || {
+            let mut reader = BufReader::new(stdout);
+            loop {
+                let mut line = String::new();
+                let read = reader.read_line(&mut line).expect("read holder output");
+                assert_ne!(read, 0, "holder exited before READY");
+                if line.trim() == "READY" {
+                    ready_tx.send(line).expect("send holder READY");
+                    break;
+                }
+            }
+            let mut tail = String::new();
+            reader.read_to_string(&mut tail).expect("read holder tail");
+            tail_tx.send(tail).expect("send holder tail");
+        });
+        let ready = ready_rx
+            .recv_timeout(CHILD_WAIT)
+            .expect("holder READY before finite deadline");
+        assert_eq!(ready.trim(), "READY");
+        Self {
+            child: Some(child),
+            stdin: Some(stdin),
+            tail: tail_rx,
+        }
+    }
+
+    fn release(mut self) {
+        let mut stdin = self.stdin.take().expect("holder release stdin");
+        stdin.write_all(b"x").expect("signal holder release");
+        drop(stdin);
+        let child = self.child.as_mut().expect("holder child");
+        let status = wait_bounded(child, CHILD_WAIT);
+        assert!(status.success(), "holder child failed: {status}");
+        let tail = self
+            .tail
+            .recv_timeout(CHILD_WAIT)
+            .expect("holder tail before finite deadline");
+        assert!(
+            tail.lines().any(|line| line == "RELEASED"),
+            "holder emitted no RELEASED sentinel: {tail:?}"
+        );
+        self.child.take();
+    }
+}
+
+impl Drop for Holder {
+    fn drop(&mut self) {
+        if let Some(child) = self.child.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+fn child_command(project: &Path, mode: &str, action: &str) -> Command {
+    let mut command = Command::new(std::env::current_exe().expect("current test executable"));
+    command
+        .arg("--exact")
+        .arg("lease_child_process")
+        .arg("--nocapture")
+        .env(CHILD_ACTION, action)
+        .env(CHILD_MODE, mode)
+        .env(CHILD_PROJECT, project);
+    command
+}
+
+fn run_probe(project: &Path, mode: &str, acquisition_bound: Duration) -> String {
+    let mut child = child_command(project, mode, "probe")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()
+        .expect("spawn lock probe");
+    let mut stdout = child.stdout.take().expect("probe stdout");
+    let (output_tx, output_rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let mut output = String::new();
+        stdout
+            .read_to_string(&mut output)
+            .expect("read probe stdout");
+        output_tx.send(output).expect("send probe output");
+    });
+    let process_bound = acquisition_bound
+        .checked_add(CHILD_WAIT)
+        .expect("probe process bound");
+    let status = wait_bounded(&mut child, process_bound);
+    assert!(status.success(), "probe child failed: {status}");
+    output_rx
+        .recv_timeout(CHILD_WAIT)
+        .expect("probe output before finite deadline")
+        .lines()
+        .find(|line| matches!(*line, "ACQUIRED" | "TIMED_OUT"))
+        .unwrap_or_else(|| panic!("probe emitted no result sentinel"))
+        .to_string()
+}
+
+fn wait_bounded(child: &mut Child, timeout: Duration) -> std::process::ExitStatus {
+    let deadline = deadline_after(timeout);
+    loop {
+        if let Some(status) = child.try_wait().expect("poll child status") {
+            return status;
+        }
+        if Instant::now() >= deadline {
+            let _ = child.kill();
+            let _ = child.wait();
+            panic!("child process exceeded finite {timeout:?} bound");
+        }
+        std::thread::park_timeout(Duration::from_millis(5));
+    }
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index ce0eabc..2dec967 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1013,3 +1013,103 @@ Authoritative final gate (fresh run, after doc formatting):
 - `Cargo.lock` still byte-identical at
   `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`; this
   correction changes documentation only.
+
+## Batch M — reusable `IndexLease` capability (2026-07-25)
+
+### Scope
+
+This slice adds only `codegraph-store`'s reusable v2 lease capability and its
+behavioral tests. It does not wire leases into `Store`, SQLite, CLI, MCP, watch,
+daemon, state publication, migration/finalization, or uninit. The capability is
+derived only from resolved `IndexPaths::permanent_lock()` and the physical
+`current_db()` parent.
+
+### Behavioral Red
+
+The API-level refinement tests were added against minimal compiling scaffolding
+whose acquisition methods opened the lock file but deliberately did not call the
+kernel lock APIs. This preserved the earlier Batch M black-box Red distinction
+while producing a real lease-behavior Red rather than a compile/setup failure.
+
+- Gate: `bash scripts/check-workspace-versions.sh` → exit 0.
+- Command: `cargo test -p codegraph-store --test index_lease --locked` → exit
+  101; 4 passed, 4 failed.
+- Exact missing behavior: all incompatible child-process probes returned
+  `ACQUIRED` instead of `TIMED_OUT`; an in-process exclusive holder likewise did
+  not force timeout. The failing tests were
+  `shared_processes_coexist_but_shared_blocks_exclusive`,
+  `exclusive_process_blocks_shared_and_exclusive`,
+  `a_clone_keeps_the_single_lock_alive_until_the_final_drop`, and
+  `timeout_and_post_contention_cancellation_preserve_lock_bytes`.
+- The child holder printed `READY` only after acquisition and the parent waited
+  through a channel before launching a contender. Release used a stdin control
+  byte. Thus contention order did not depend on a sleep.
+
+### Green behavior
+
+- `IndexLease` keeps private `LeaseMode::{Shared, Exclusive}` plus the normalized
+  v2 DB-parent `PathBuf`; callers can observe mode/match and validate an exact
+  exclusive capability but cannot construct or mutate either identity.
+- Existing-open APIs use `OpenOptions` without `create` and therefore cannot
+  create an absent root/lock. The separate `create_exclusive` entry point is only
+  for a genuinely absent root, opens the permanent lock with
+  `create(true).truncate(false)`, and rejects an existing namespace rather than
+  repairing it.
+- Acquisition uses Rust 1.96 `File::try_lock_shared` / `File::try_lock` in a
+  monotonic-deadline loop, checking cancellation before open, before every
+  attempt, and immediately after contention. It never calls blocking `lock()`.
+- One locked `File` lives in `Arc<LeaseInner>`. Clone drops cannot unlock; only
+  final `LeaseInner::drop` calls `unlock`, then the `File` closes exactly once.
+- Typed validation rejects `SharedLease` and `WrongDbParent`. Typed acquisition
+  errors distinguish missing lock, non-absent initial namespace, open/create I/O,
+  timeout, cancellation, and other kernel-lock errors.
+- The lock file is permanent protocol state only: no PID is written/read, no
+  stale-file deletion occurs, and tests preserve sentinel bytes through
+  successful opens, contention timeout, cancellation, and validation.
+
+Targeted Green: after implementing kernel acquisition,
+`cargo test -p codegraph-store --test index_lease --locked` passed all tests. The
+final required check/MSVC/clippy/CI results are recorded below after the last
+documentation formatting pass. LSP diagnostics could not attach to this external
+`/tmp` worktree (`file path must be inside request cwd`); Cargo diagnostics are
+the accepted fallback. Native Windows runtime is unavailable, so only an MSVC
+cross-compilation result is claimed.
+
+The first store-wide MSVC check exposed a defect in the previously accepted
+state reader: Rust 1.96 still marks
+`MetadataExt::{volume_serial_number,file_index}` unstable. This task replaces
+those calls with stable metadata corroboration plus a stronger Windows-only final
+proof: a second live handle for the fixed slot path is compared with the opened
+read handle through raw kernel32
+`GetFileInformationByHandleEx(FileIdInfo)`. The byte read still uses exactly one
+opened handle; the second handle only corroborates that the fixed path still
+names that object. This adds no dependency and does not alter classifier ordering
+or state semantics.
+
+### Verification before the terminal CI gate
+
+Every Cargo batch below was preceded by
+`bash scripts/check-workspace-versions.sh` (exit 0, workspace version `0.40.4`):
+
+- `cargo test -p codegraph-store --test index_lease --locked` — 9 passed, 0
+  failed, including process-level shared/exclusive contention, timeout,
+  post-contention cancellation, clone/final-drop ownership, nontruncation, and
+  capability validation.
+- `cargo test -p codegraph-store --test index_state --locked` — 20 passed, 0
+  failed after the Windows identity compatibility correction.
+- `cargo check -p codegraph-store --all-targets --locked` — clean.
+- `LIBSQLITE3_SYS_USE_PKG_CONFIG=1 SQLITE3_LIB_DIR=/tmp/opencode cargo check -p
+codegraph-store --target x86_64-pc-windows-msvc --all-targets --locked` —
+  clean. The environment variables make `libsqlite3-sys` emit external link
+  metadata instead of requiring unavailable Linux-host `lib.exe`; `cargo check`
+  does not link. This proves the store's Rust MSVC target compiles, not that the
+  lock behavior ran natively on Windows.
+- `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings` —
+  clean.
+- `make fmt-check` — Rust and the repository-scoped oxfmt set are clean.
+- `Cargo.lock` remains byte-identical at
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+The terminal `make ci` is run only after these final ledger bytes are formatted;
+its exact result is reported with the resulting commit so the evidence does not
+create the stale-post-validation formatting trap.

From 8c19bce70cf8907f356ba0bb45e1188df00b00c9 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 17:53:04 +0800
Subject: [PATCH 16/91] fix(store): harden index lease identity checks

---
 crates/codegraph-store/src/file_identity.rs | 201 ++++++++++
 crates/codegraph-store/src/index_lease.rs   | 420 +++++++++++++++++++-
 crates/codegraph-store/src/index_state.rs   |  76 +---
 crates/codegraph-store/src/lib.rs           |   1 +
 crates/codegraph-store/tests/index_lease.rs |  98 +++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md   |  85 ++++
 6 files changed, 789 insertions(+), 92 deletions(-)
 create mode 100644 crates/codegraph-store/src/file_identity.rs

diff --git a/crates/codegraph-store/src/file_identity.rs b/crates/codegraph-store/src/file_identity.rs
new file mode 100644
index 0000000..0efb65d
--- /dev/null
+++ b/crates/codegraph-store/src/file_identity.rs
@@ -0,0 +1,201 @@
+//! Private cross-platform filesystem-object identity helpers.
+
+#[cfg(windows)]
+use std::fs::OpenOptions;
+use std::fs::{File, Metadata};
+use std::io;
+use std::path::Path;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum FileIdentity {
+    #[cfg(unix)]
+    Unix { device: u64, inode: u64 },
+    #[cfg(windows)]
+    Windows {
+        volume_serial_number: u64,
+        file_id: [u8; 16],
+    },
+    #[cfg(not(any(unix, windows)))]
+    Portable {
+        len: u64,
+        modified: Option<std::time::SystemTime>,
+        created: Option<std::time::SystemTime>,
+    },
+}
+
+pub(crate) fn is_alias(metadata: &Metadata) -> bool {
+    if metadata.file_type().is_symlink() {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt as _;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
+        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0;
+    }
+    #[cfg(not(windows))]
+    false
+}
+
+pub(crate) fn is_regular(metadata: &Metadata) -> bool {
+    metadata.file_type().is_file() && !is_alias(metadata)
+}
+
+pub(crate) fn metadata_observation_matches(left: &Metadata, right: &Metadata) -> bool {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt as _;
+        left.dev() == right.dev() && left.ino() == right.ino()
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt as _;
+        left.file_attributes() == right.file_attributes()
+            && left.creation_time() == right.creation_time()
+            && left.last_write_time() == right.last_write_time()
+            && left.file_size() == right.file_size()
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        left.len() == right.len()
+            && left.modified().ok() == right.modified().ok()
+            && left.created().ok() == right.created().ok()
+    }
+}
+
+pub(crate) fn identity_for_file(file: &File) -> io::Result<FileIdentity> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt as _;
+        let metadata = file.metadata()?;
+        Ok(FileIdentity::Unix {
+            device: metadata.dev(),
+            inode: metadata.ino(),
+        })
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::io::AsRawHandle as _;
+
+        const FILE_ID_INFO_CLASS: i32 = 18;
+        #[repr(C)]
+        struct FileIdInfo {
+            volume_serial_number: u64,
+            file_id: [u8; 16],
+        }
+        #[link(name = "kernel32")]
+        unsafe extern "system" {
+            fn GetFileInformationByHandleEx(
+                h_file: isize,
+                file_information_class: i32,
+                lp_file_information: *mut core::ffi::c_void,
+                dw_buffer_size: u32,
+            ) -> i32;
+        }
+
+        let mut info = FileIdInfo {
+            volume_serial_number: 0,
+            file_id: [0; 16],
+        };
+        // SAFETY: `file` owns a live Windows handle and `info` is a correctly
+        // sized writable FILE_ID_INFO buffer for FileIdInfo.
+        let ok = unsafe {
+            GetFileInformationByHandleEx(
+                file.as_raw_handle() as isize,
+                FILE_ID_INFO_CLASS,
+                (&mut info as *mut FileIdInfo).cast(),
+                core::mem::size_of::<FileIdInfo>() as u32,
+            )
+        };
+        if ok == 0 {
+            return Err(io::Error::last_os_error());
+        }
+        Ok(FileIdentity::Windows {
+            volume_serial_number: info.volume_serial_number,
+            file_id: info.file_id,
+        })
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let metadata = file.metadata()?;
+        Ok(FileIdentity::Portable {
+            len: metadata.len(),
+            modified: metadata.modified().ok(),
+            created: metadata.created().ok(),
+        })
+    }
+}
+
+pub(crate) fn identity_for_validated_path(
+    path: &Path,
+    metadata: &Metadata,
+) -> io::Result<FileIdentity> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt as _;
+        let _ = path;
+        Ok(FileIdentity::Unix {
+            device: metadata.dev(),
+            inode: metadata.ino(),
+        })
+    }
+    #[cfg(windows)]
+    {
+        let file = open_no_follow(path)?;
+        let opened = file.metadata()?;
+        if !is_regular(&opened) || !metadata_observation_matches(metadata, &opened) {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "path changed while capturing exact Windows file identity",
+            ));
+        }
+        identity_for_file(&file)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = path;
+        Ok(FileIdentity::Portable {
+            len: metadata.len(),
+            modified: metadata.modified().ok(),
+            created: metadata.created().ok(),
+        })
+    }
+}
+
+pub(crate) fn path_still_names_file(path: &Path, file: &File) -> io::Result<bool> {
+    path_still_names_identity(path, identity_for_file(file)?)
+}
+
+fn path_still_names_identity(path: &Path, expected: FileIdentity) -> io::Result<bool> {
+    let metadata = std::fs::symlink_metadata(path)?;
+    if !is_regular(&metadata) {
+        return Ok(false);
+    }
+    #[cfg(unix)]
+    {
+        Ok(identity_for_validated_path(path, &metadata)? == expected)
+    }
+    #[cfg(windows)]
+    {
+        let file = open_no_follow(path)?;
+        let opened = file.metadata()?;
+        if !is_regular(&opened) || !metadata_observation_matches(&metadata, &opened) {
+            return Ok(false);
+        }
+        Ok(identity_for_file(&file)? == expected)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        Ok(identity_for_validated_path(path, &metadata)? == expected)
+    }
+}
+
+#[cfg(windows)]
+fn open_no_follow(path: &Path) -> io::Result<File> {
+    use std::os::windows::fs::OpenOptionsExt as _;
+    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+    OpenOptions::new()
+        .read(true)
+        .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT)
+        .open(path)
+}
diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs
index f6b3e09..9f3d180 100644
--- a/crates/codegraph-store/src/index_lease.rs
+++ b/crates/codegraph-store/src/index_lease.rs
@@ -7,19 +7,33 @@
 
 use std::fs::{File, OpenOptions};
 use std::io;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
 use codegraph_core::IndexPaths;
 use thiserror::Error;
 
+use crate::file_identity::{
+    FileIdentity, identity_for_file, identity_for_validated_path, is_alias, is_regular,
+    metadata_observation_matches, path_still_names_file,
+};
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum LeaseMode {
     Shared,
     Exclusive,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum AcquireCheckpoint {
+    RootCreated,
+    InitialMetadataValidated,
+    HandleOpened,
+    KernelLockAcquired,
+    FinalPathCorroborated,
+}
+
 #[derive(Debug)]
 struct LeaseInner {
     file: File,
@@ -27,6 +41,14 @@ struct LeaseInner {
     db_parent: PathBuf,
 }
 
+struct PendingAcquisition {
+    lock_path: PathBuf,
+    mode: LeaseMode,
+    db_parent: PathBuf,
+    deadline: Instant,
+    opened_identity: FileIdentity,
+}
+
 impl Drop for LeaseInner {
     fn drop(&mut self) {
         // This Drop runs exactly once, when the final `Arc<LeaseInner>` owner is
@@ -49,6 +71,18 @@ pub enum IndexLeaseError {
     /// An existing namespace has no permanent lock.
     #[error("permanent index lock does not exist: {path}")]
     LockNotFound { path: PathBuf },
+    /// The fixed permanent-lock path is a symlink or Windows reparse point.
+    #[error("permanent index lock is an alias and cannot be lock authority: {path}")]
+    AliasedLock { path: PathBuf },
+    /// The fixed permanent-lock path exists but is not a regular file.
+    #[error("permanent index lock is a {kind}, not a regular file: {path}")]
+    NonRegularLock { path: PathBuf, kind: &'static str },
+    /// The fixed path stopped naming the opened lock during acquisition.
+    #[error("permanent index lock changed during acquisition: {path}")]
+    LockChangedDuringAcquisition { path: PathBuf },
+    /// Another entry won creation of the permanent lock in a newly created root.
+    #[error("permanent index lock creation lost a race: {path}")]
+    LockCreationConflict { path: PathBuf },
     /// Explicit namespace creation was requested for an existing root.
     #[error("cannot create an initial index lease because the namespace already exists: {path}")]
     NamespaceAlreadyExists { path: PathBuf },
@@ -114,9 +148,18 @@ impl IndexLease {
     /// Explicitly create a genuinely absent current root and its permanent lock,
     /// then acquire the initial exclusive capability.
     pub fn create_exclusive(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        Self::create_exclusive_with(paths, deadline, cancelled, |_| {})
+    }
+
+    fn create_exclusive_with(
         paths: &IndexPaths,
         deadline: Instant,
         mut cancelled: impl FnMut() -> bool,
+        mut checkpoint: impl FnMut(AcquireCheckpoint),
     ) -> Result<Self, IndexLeaseError> {
         let root = paths.current_root();
         let lock_path = paths.permanent_lock();
@@ -159,23 +202,27 @@ impl IndexLease {
                 }
             }
         })?;
+        checkpoint(AcquireCheckpoint::RootCreated);
         let file = OpenOptions::new()
             .read(true)
             .write(true)
-            .create(true)
+            .create_new(true)
             .truncate(false)
             .open(&lock_path)
-            .map_err(|source| IndexLeaseError::OpenLock {
-                path: lock_path.clone(),
-                source,
-            })?;
+            .map_err(|source| classify_create_error(&lock_path, source))?;
+        let opened_identity = opened_identity(&file, &lock_path, None)?;
+        checkpoint(AcquireCheckpoint::HandleOpened);
         Self::acquire_file(
             file,
-            lock_path,
-            LeaseMode::Exclusive,
-            db_parent(paths),
-            deadline,
+            PendingAcquisition {
+                lock_path,
+                mode: LeaseMode::Exclusive,
+                db_parent: db_parent(paths),
+                deadline,
+                opened_identity,
+            },
             cancelled,
+            checkpoint,
         )
     }
 
@@ -210,10 +257,20 @@ impl IndexLease {
     }
 
     fn acquire_existing(
+        paths: &IndexPaths,
+        mode: LeaseMode,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        Self::acquire_existing_with(paths, mode, deadline, cancelled, |_| {})
+    }
+
+    fn acquire_existing_with(
         paths: &IndexPaths,
         mode: LeaseMode,
         deadline: Instant,
         mut cancelled: impl FnMut() -> bool,
+        mut checkpoint: impl FnMut(AcquireCheckpoint),
     ) -> Result<Self, IndexLeaseError> {
         let lock_path = paths.permanent_lock();
         if cancelled() {
@@ -222,15 +279,17 @@ impl IndexLease {
         if Instant::now() >= deadline {
             return Err(IndexLeaseError::TimedOut { path: lock_path });
         }
+        let initial = validated_path_metadata(&lock_path)?;
+        let initial_identity =
+            identity_for_validated_path(&lock_path, &initial).map_err(|_| changed(&lock_path))?;
+        checkpoint(AcquireCheckpoint::InitialMetadataValidated);
         let file = OpenOptions::new()
             .read(true)
             .write(true)
             .open(&lock_path)
             .map_err(|source| {
                 if source.kind() == std::io::ErrorKind::NotFound {
-                    IndexLeaseError::LockNotFound {
-                        path: lock_path.clone(),
-                    }
+                    changed(&lock_path)
                 } else {
                     IndexLeaseError::OpenLock {
                         path: lock_path.clone(),
@@ -238,17 +297,38 @@ impl IndexLease {
                     }
                 }
             })?;
-        Self::acquire_file(file, lock_path, mode, db_parent(paths), deadline, cancelled)
+        let opened_identity = opened_identity(&file, &lock_path, Some(&initial))?;
+        if initial_identity != opened_identity {
+            return Err(changed(&lock_path));
+        }
+        checkpoint(AcquireCheckpoint::HandleOpened);
+        Self::acquire_file(
+            file,
+            PendingAcquisition {
+                lock_path,
+                mode,
+                db_parent: db_parent(paths),
+                deadline,
+                opened_identity,
+            },
+            cancelled,
+            checkpoint,
+        )
     }
 
     fn acquire_file(
         file: File,
-        lock_path: PathBuf,
-        mode: LeaseMode,
-        db_parent: PathBuf,
-        deadline: Instant,
+        pending: PendingAcquisition,
         mut cancelled: impl FnMut() -> bool,
+        mut checkpoint: impl FnMut(AcquireCheckpoint),
     ) -> Result<Self, IndexLeaseError> {
+        let PendingAcquisition {
+            lock_path,
+            mode,
+            db_parent,
+            deadline,
+            opened_identity,
+        } = pending;
         loop {
             if cancelled() {
                 return Err(IndexLeaseError::Cancelled { path: lock_path });
@@ -263,6 +343,13 @@ impl IndexLease {
             };
             match attempt {
                 Ok(()) => {
+                    checkpoint(AcquireCheckpoint::KernelLockAcquired);
+                    if !final_path_matches(&lock_path, &file, opened_identity) {
+                        // The locked handle is dropped here instead of becoming
+                        // a capability, releasing the kernel lock exactly once.
+                        return Err(changed(&lock_path));
+                    }
+                    checkpoint(AcquireCheckpoint::FinalPathCorroborated);
                     return Ok(Self {
                         inner: Arc::new(LeaseInner {
                             file,
@@ -297,6 +384,90 @@ impl IndexLease {
     }
 }
 
+fn validated_path_metadata(lock_path: &Path) -> Result<std::fs::Metadata, IndexLeaseError> {
+    let metadata = std::fs::symlink_metadata(lock_path).map_err(|source| {
+        if source.kind() == io::ErrorKind::NotFound {
+            IndexLeaseError::LockNotFound {
+                path: lock_path.to_path_buf(),
+            }
+        } else {
+            IndexLeaseError::OpenLock {
+                path: lock_path.to_path_buf(),
+                source,
+            }
+        }
+    })?;
+    if is_alias(&metadata) {
+        return Err(IndexLeaseError::AliasedLock {
+            path: lock_path.to_path_buf(),
+        });
+    }
+    if !is_regular(&metadata) {
+        let kind = if metadata.file_type().is_dir() {
+            "directory"
+        } else {
+            "non-regular filesystem entry"
+        };
+        return Err(IndexLeaseError::NonRegularLock {
+            path: lock_path.to_path_buf(),
+            kind,
+        });
+    }
+    Ok(metadata)
+}
+
+fn opened_identity(
+    file: &File,
+    lock_path: &Path,
+    initial: Option<&std::fs::Metadata>,
+) -> Result<FileIdentity, IndexLeaseError> {
+    let opened = file
+        .metadata()
+        .map_err(|source| IndexLeaseError::OpenLock {
+            path: lock_path.to_path_buf(),
+            source,
+        })?;
+    if !is_regular(&opened)
+        || initial.is_some_and(|initial| !metadata_observation_matches(initial, &opened))
+    {
+        return Err(changed(lock_path));
+    }
+    identity_for_file(file).map_err(|_| changed(lock_path))
+}
+
+fn final_path_matches(lock_path: &Path, file: &File, opened: FileIdentity) -> bool {
+    let Ok(metadata) = std::fs::symlink_metadata(lock_path) else {
+        return false;
+    };
+    if !is_regular(&metadata) {
+        return false;
+    }
+    let Ok(path_identity) = identity_for_validated_path(lock_path, &metadata) else {
+        return false;
+    };
+    path_identity == opened && path_still_names_file(lock_path, file).unwrap_or(false)
+}
+
+fn changed(lock_path: &Path) -> IndexLeaseError {
+    IndexLeaseError::LockChangedDuringAcquisition {
+        path: lock_path.to_path_buf(),
+    }
+}
+
+fn classify_create_error(lock_path: &Path, source: io::Error) -> IndexLeaseError {
+    if source.kind() == io::ErrorKind::AlreadyExists || std::fs::symlink_metadata(lock_path).is_ok()
+    {
+        IndexLeaseError::LockCreationConflict {
+            path: lock_path.to_path_buf(),
+        }
+    } else {
+        IndexLeaseError::OpenLock {
+            path: lock_path.to_path_buf(),
+            source,
+        }
+    }
+}
+
 fn db_parent(paths: &IndexPaths) -> PathBuf {
     let db = paths.current_db();
     let parent = db
@@ -305,3 +476,216 @@ fn db_parent(paths: &IndexPaths) -> PathBuf {
     debug_assert_eq!(parent, paths.current_root());
     parent.to_path_buf()
 }
+
+#[cfg(all(test, unix))]
+mod tests {
+    use std::os::unix::fs::symlink;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    use super::*;
+
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+    struct TempProject(PathBuf);
+
+    impl TempProject {
+        fn new(label: &str) -> Self {
+            let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+            let path = std::env::temp_dir().join(format!(
+                "codegraph-index-lease-unit-{label}-{}-{serial}",
+                std::process::id()
+            ));
+            std::fs::create_dir(&path).expect("create lease unit-test project");
+            Self(
+                path.canonicalize()
+                    .expect("canonical lease unit-test project"),
+            )
+        }
+
+        fn paths(&self) -> IndexPaths {
+            IndexPaths::resolve(&self.0, None).expect("resolve lease unit-test paths")
+        }
+    }
+
+    impl Drop for TempProject {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    fn deadline() -> Instant {
+        Instant::now()
+            .checked_add(Duration::from_secs(5))
+            .expect("test deadline")
+    }
+
+    #[test]
+    fn replacement_after_kernel_lock_is_rejected_and_releases_the_opened_file() {
+        let project = TempProject::new("replacement-after-lock");
+        let paths = project.paths();
+        std::fs::create_dir(paths.current_root()).expect("create current root");
+        let lock_path = paths.permanent_lock();
+        let displaced = paths.current_root().join("displaced.lock");
+        let replacement = paths.current_root().join("replacement.lock");
+        std::fs::write(&lock_path, b"original").expect("write original lock");
+        std::fs::write(&replacement, b"replacement").expect("write replacement lock");
+
+        let mut replaced = false;
+        let error = IndexLease::acquire_existing_with(
+            &paths,
+            LeaseMode::Exclusive,
+            deadline(),
+            || false,
+            |point| {
+                if point == AcquireCheckpoint::KernelLockAcquired && !replaced {
+                    std::fs::rename(&lock_path, &displaced).expect("displace opened lock");
+                    std::fs::rename(&replacement, &lock_path).expect("install replacement lock");
+                    replaced = true;
+                }
+            },
+        )
+        .expect_err("replacement must invalidate the acquired handle");
+        assert!(matches!(
+            error,
+            IndexLeaseError::LockChangedDuringAcquisition { path } if path == lock_path
+        ));
+
+        let displaced_handle = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&displaced)
+            .expect("open displaced original");
+        displaced_handle
+            .try_lock()
+            .expect("rejected authority must release its kernel lock");
+        displaced_handle
+            .unlock()
+            .expect("unlock displaced original");
+
+        let final_lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("fresh contender acquires the final fixed lock");
+        drop(final_lease);
+    }
+
+    #[test]
+    fn replacement_after_initial_validation_is_rejected_before_authority_returns() {
+        let project = TempProject::new("replacement-before-open");
+        let paths = project.paths();
+        std::fs::create_dir(paths.current_root()).expect("create current root");
+        let lock_path = paths.permanent_lock();
+        let displaced = paths.current_root().join("validated.lock");
+        let replacement = paths.current_root().join("replacement.lock");
+        std::fs::write(&lock_path, b"validated").expect("write validated lock");
+        std::fs::write(&replacement, b"replacement").expect("write replacement lock");
+
+        let mut replaced = false;
+        let error = IndexLease::acquire_existing_with(
+            &paths,
+            LeaseMode::Exclusive,
+            deadline(),
+            || false,
+            |point| {
+                if point == AcquireCheckpoint::InitialMetadataValidated && !replaced {
+                    std::fs::rename(&lock_path, &displaced).expect("displace validated lock");
+                    std::fs::rename(&replacement, &lock_path).expect("install replacement lock");
+                    replaced = true;
+                }
+            },
+        )
+        .expect_err("opened file must match the initially validated object");
+        assert!(matches!(
+            error,
+            IndexLeaseError::LockChangedDuringAcquisition { path } if path == lock_path
+        ));
+
+        for path in [&displaced, &lock_path] {
+            let handle = OpenOptions::new()
+                .read(true)
+                .write(true)
+                .open(path)
+                .expect("open race participant");
+            handle
+                .try_lock()
+                .expect("rejected acquisition returns no locked authority");
+            handle.unlock().expect("unlock race participant");
+        }
+    }
+
+    #[test]
+    fn initial_creation_rejects_an_alias_that_wins_after_root_creation() {
+        let project = TempProject::new("creation-alias-race");
+        let paths = project.paths();
+        let external = project.0.join("external.lock");
+        let external_bytes = b"external-lock-must-stay-unchanged";
+        std::fs::write(&external, external_bytes).expect("write external target");
+
+        let mut installed = false;
+        let error = IndexLease::create_exclusive_with(
+            &paths,
+            deadline(),
+            || false,
+            |point| {
+                if point == AcquireCheckpoint::RootCreated && !installed {
+                    symlink(&external, paths.permanent_lock()).expect("install competing alias");
+                    installed = true;
+                }
+            },
+        )
+        .expect_err("create-new must reject a competing alias");
+        assert!(matches!(
+            error,
+            IndexLeaseError::LockCreationConflict { path } if path == paths.permanent_lock()
+        ));
+        assert_eq!(std::fs::read(&external).unwrap(), external_bytes);
+
+        let external_handle = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&external)
+            .expect("open external target");
+        external_handle
+            .try_lock()
+            .expect("failed creation never locks the alias target");
+        external_handle.unlock().expect("unlock external target");
+    }
+
+    #[test]
+    fn initial_creation_rejects_a_regular_entry_that_wins_after_root_creation() {
+        let project = TempProject::new("creation-regular-race");
+        let paths = project.paths();
+        let competing_bytes = b"competing-regular-lock";
+
+        let mut installed = false;
+        let error = IndexLease::create_exclusive_with(
+            &paths,
+            deadline(),
+            || false,
+            |point| {
+                if point == AcquireCheckpoint::RootCreated && !installed {
+                    std::fs::write(paths.permanent_lock(), competing_bytes)
+                        .expect("install competing regular lock");
+                    installed = true;
+                }
+            },
+        )
+        .expect_err("create-new must reject a competing regular entry");
+        assert!(matches!(
+            error,
+            IndexLeaseError::LockCreationConflict { path } if path == paths.permanent_lock()
+        ));
+        assert_eq!(
+            std::fs::read(paths.permanent_lock()).unwrap(),
+            competing_bytes
+        );
+
+        let competing_handle = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(paths.permanent_lock())
+            .expect("open competing regular lock");
+        competing_handle
+            .try_lock()
+            .expect("failed creation never locks the competing entry");
+        competing_handle.unlock().expect("unlock competing entry");
+    }
+}
diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
index 73ddd6e..a158da1 100644
--- a/crates/codegraph-store/src/index_state.rs
+++ b/crates/codegraph-store/src/index_state.rs
@@ -754,85 +754,13 @@ fn slot_changed(index: u8, path: &Path, detail: &str) -> RawSlot {
     })
 }
 
-#[cfg(unix)]
 fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
-    use std::os::unix::fs::MetadataExt as _;
-    left.dev() == right.dev() && left.ino() == right.ino()
-}
-
-#[cfg(windows)]
-fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
-    use std::os::windows::fs::MetadataExt as _;
-
-    // Rust 1.96 still gates MetadataExt's volume/file-index accessors as
-    // unstable. Stable fields cheaply corroborate pre/open/post observations;
-    // the exact final object-identity proof follows through two live handles.
-    left.file_attributes() == right.file_attributes()
-        && left.creation_time() == right.creation_time()
-        && left.last_write_time() == right.last_write_time()
-        && left.file_size() == right.file_size()
+    crate::file_identity::metadata_observation_matches(left, right)
 }
 
 #[cfg(windows)]
 fn path_still_names_opened_file(opened: &File, path: &Path) -> io::Result<bool> {
-    const FILE_ID_INFO_CLASS: i32 = 18;
-
-    #[repr(C)]
-    struct FileIdInfo {
-        volume_serial_number: u64,
-        file_id: [u8; 16],
-    }
-
-    #[link(name = "kernel32")]
-    unsafe extern "system" {
-        fn GetFileInformationByHandleEx(
-            h_file: isize,
-            file_information_class: i32,
-            lp_file_information: *mut core::ffi::c_void,
-            dw_buffer_size: u32,
-        ) -> i32;
-    }
-
-    fn file_id(file: &File) -> io::Result<(u64, [u8; 16])> {
-        use std::os::windows::io::AsRawHandle as _;
-
-        let mut info = FileIdInfo {
-            volume_serial_number: 0,
-            file_id: [0; 16],
-        };
-        // SAFETY: `file` owns a live Windows handle and `info` is a correctly
-        // sized writable FILE_ID_INFO buffer for FileIdInfo.
-        let ok = unsafe {
-            GetFileInformationByHandleEx(
-                file.as_raw_handle() as isize,
-                FILE_ID_INFO_CLASS,
-                (&mut info as *mut FileIdInfo).cast(),
-                core::mem::size_of::<FileIdInfo>() as u32,
-            )
-        };
-        if ok == 0 {
-            return Err(io::Error::last_os_error());
-        }
-        Ok((info.volume_serial_number, info.file_id))
-    }
-
-    // Open a second handle after the final no-follow metadata check. The fixed
-    // path must still identify the exact object whose first handle supplied the
-    // bytes; a replacement produces a different volume/file ID.
-    let final_handle = File::open(path)?;
-    Ok(file_id(opened)? == file_id(&final_handle)?)
-}
-
-#[cfg(not(any(unix, windows)))]
-fn same_file_identity(left: &Metadata, right: &Metadata) -> bool {
-    // std exposes no stable object ID on this platform. This fallback is
-    // deliberately conservative about observable metadata, but cannot exclude a
-    // replacement engineered with identical attributes; callers must not claim
-    // the Unix/Windows identity guarantee here.
-    left.len() == right.len()
-        && left.permissions().readonly() == right.permissions().readonly()
-        && left.modified().ok() == right.modified().ok()
-        && left.created().ok() == right.created().ok()
+    crate::file_identity::path_still_names_file(path, opened)
 }
 
 /// Semantically validate ONE parsed slot into a [`SlotOutcome`].
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index 917c4ce..94e728c 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -1,4 +1,5 @@
 pub mod connection;
+mod file_identity;
 pub mod index_lease;
 pub mod index_state;
 pub mod migrations;
diff --git a/crates/codegraph-store/tests/index_lease.rs b/crates/codegraph-store/tests/index_lease.rs
index 1893ddd..34a0446 100644
--- a/crates/codegraph-store/tests/index_lease.rs
+++ b/crates/codegraph-store/tests/index_lease.rs
@@ -71,6 +71,83 @@ fn lock_bytes(paths: &IndexPaths) -> Vec<u8> {
     std::fs::read(paths.permanent_lock()).expect("read permanent lock bytes")
 }
 
+#[cfg(unix)]
+#[test]
+fn static_symlink_lock_is_rejected_without_using_the_external_target_as_authority() {
+    use std::os::unix::fs::symlink;
+
+    let project = TempProject::new("static-symlink");
+    let paths = project.paths();
+    std::fs::create_dir_all(paths.current_root()).expect("create current root fixture");
+    let external = project.path().join("external.lock");
+    std::fs::write(&external, LOCK_BYTES).expect("write external lock target");
+    symlink(&external, paths.permanent_lock()).expect("stage malicious lock symlink");
+
+    let result =
+        IndexLease::acquire_exclusive_existing(&paths, deadline_after(CHILD_WAIT), || false);
+    match result {
+        Err(IndexLeaseError::AliasedLock { path }) => {
+            assert_eq!(path, paths.permanent_lock());
+            let external_handle = OpenOptions::new()
+                .read(true)
+                .write(true)
+                .open(&external)
+                .expect("open external target independently");
+            external_handle
+                .try_lock()
+                .expect("rejected alias never became this namespace's lock authority");
+            external_handle.unlock().expect("unlock external target");
+        }
+        Ok(lease) => {
+            let external_handle = OpenOptions::new()
+                .read(true)
+                .write(true)
+                .open(&external)
+                .expect("open external target independently");
+            assert!(
+                matches!(
+                    external_handle.try_lock(),
+                    Err(std::fs::TryLockError::WouldBlock)
+                ),
+                "the defective lease must demonstrably hold the external target"
+            );
+            drop(lease);
+            panic!("static symlink was accepted as permanent lock authority");
+        }
+        Err(other) => panic!("wrong typed error for lock alias: {other:?}"),
+    }
+
+    assert_eq!(std::fs::read(&external).unwrap(), LOCK_BYTES);
+    assert!(
+        std::fs::symlink_metadata(paths.permanent_lock())
+            .unwrap()
+            .file_type()
+            .is_symlink(),
+        "existing-only rejection must not mutate the alias entry"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn socket_lock_entry_is_rejected_as_non_regular() {
+    use std::os::unix::net::UnixListener;
+
+    let socket_project = TempProject::new("lock-socket");
+    let socket_paths = socket_project.paths();
+    std::fs::create_dir_all(socket_paths.current_root()).expect("create socket fixture root");
+    let _listener = UnixListener::bind(socket_paths.permanent_lock()).expect("stage lock socket");
+    let error =
+        IndexLease::acquire_shared_existing(&socket_paths, deadline_after(CHILD_WAIT), || false)
+            .expect_err("a socket cannot be permanent lock authority");
+    assert!(matches!(
+        error,
+        IndexLeaseError::NonRegularLock {
+            path,
+            kind: "non-regular filesystem entry"
+        } if path == socket_paths.permanent_lock()
+    ));
+}
+
 #[test]
 fn existing_open_missing_is_nonmutating_and_never_creates() {
     let missing_root = TempProject::new("missing-root");
@@ -102,6 +179,27 @@ fn existing_open_missing_is_nonmutating_and_never_creates() {
     );
 }
 
+#[test]
+fn existing_open_rejects_a_directory_lock_without_mutation() {
+    let project = TempProject::new("directory-lock");
+    let paths = project.paths();
+    std::fs::create_dir_all(paths.permanent_lock()).expect("stage directory at lock path");
+    let marker = paths.permanent_lock().join("keep.bin");
+    std::fs::write(&marker, LOCK_BYTES).expect("stage directory marker");
+
+    let err = IndexLease::acquire_exclusive_existing(&paths, deadline_after(CHILD_WAIT), || false)
+        .expect_err("directory cannot be permanent lock authority");
+    assert!(matches!(
+        err,
+        IndexLeaseError::NonRegularLock {
+            path,
+            kind: "directory"
+        } if path == paths.permanent_lock()
+    ));
+    assert!(paths.permanent_lock().is_dir());
+    assert_eq!(std::fs::read(marker).unwrap(), LOCK_BYTES);
+}
+
 #[test]
 fn explicit_initial_creation_is_separate_and_never_truncates_an_existing_lock() {
     let project = TempProject::new("initial-create");
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 2dec967..200c62f 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1113,3 +1113,88 @@ codegraph-store --target x86_64-pc-windows-msvc --all-targets --locked` —
 The terminal `make ci` is run only after these final ledger bytes are formatted;
 its exact result is reported with the resulting commit so the evidence does not
 create the stale-post-validation formatting trap.
+
+## Batch M — `IndexLease` lock-identity correction (2026-07-25)
+
+### Rejected boundary and behavioral Red
+
+Manual review rejected commit `b772e0f519ce4ebc731e141f846ea321e5078789`:
+`acquire_existing` opened `<current-root>/index.lock` directly, so Unix followed
+a static symlink and the lease never proved that the fixed path still named the
+opened and locked file before returning authority. Initial creation also used
+`create(true)`, allowing a competing entry installed after root creation to be
+reopened and accepted.
+
+The correction began with compiling Linux behavioral tests against that code.
+`cargo test -p codegraph-store --test index_lease --locked` exited 101: the
+static-symlink test demonstrated that the old lease kernel-locked the external
+target, while the directory test did not receive the required typed
+`NonRegularLock` rejection. This was behavioral failure after compilation, not a
+setup or API failure. The deterministic private-checkpoint tests were added with
+the minimum test seam: they replace `index.lock` immediately after initial
+validation and immediately after kernel acquisition, without sleeps.
+
+### Correction
+
+- A private `file_identity` module now supplies the lease and state reader with
+  one cross-platform identity implementation. Unix identity is exact
+  `(st_dev, st_ino)`. Windows rejects `FILE_ATTRIBUTE_REPARSE_POINT` and obtains
+  exact `(volume serial, 128-bit file ID)` values from live handles through
+  stable raw `GetFileInformationByHandleEx(FileIdInfo)` FFI; it does not use the
+  unstable Rust metadata file-index accessors. Other targets retain the existing
+  conservative metadata fallback without claiming the Unix/Windows guarantee.
+- Existing acquisition performs no-follow metadata first, rejects a symlink /
+  reparse point as typed `AliasedLock` and a directory/socket/other entry as
+  typed `NonRegularLock`, opens the lock once for authority, compares the initial
+  identity with that opened handle, acquires only through `try_lock*`, then
+  re-reads no-follow metadata and corroborates the final fixed path against the
+  same locked handle. Any disappearance, type change, alias, or exact identity
+  drift returns typed `LockChangedDuringAcquisition`; no `IndexLease` is built.
+- A post-lock rejection drops the local handle. The deterministic replacement
+  test then locks the displaced original and acquires the final fixed lock with a
+  fresh contender, proving that neither the failed capability nor its kernel
+  lock leaked.
+- Explicit initial creation still requires a genuinely absent root, but now
+  creates `index.lock` with `create_new(true)`. A regular or symlink entry that
+  wins after root creation returns typed `LockCreationConflict`; it is never
+  followed, reopened, repaired, or locked. The external symlink target's complete
+  bytes remain identical and an independent handle can lock it.
+- Existing lease semantics remain unchanged: private mode and exact DB-parent
+  identity, `Arc<LeaseInner>` final-owner unlock, monotonic bounded deadlines,
+  cancellation checks, nonblocking `try_lock*`, nontruncating existing opens,
+  and no PID, stale-file deletion, or lock repair protocol.
+
+The identity helper also replaces the state reader's duplicated platform code;
+classifier order and public semantics are unchanged. No dependency, schema,
+golden, node ID, version, SQLite/Store integration, publication, migration,
+uninit, daemon/watch/MCP/CLI lifecycle, `UPSTREAM.md`, or `KNOWN_DIFFS.md` changed.
+
+### Verification before the terminal CI gate
+
+Every Cargo batch was preceded by `bash scripts/check-workspace-versions.sh`
+(exit 0, workspace version `0.40.4`):
+
+- Corrected targeted tests: 12 `index_lease` integration tests, four private
+  deterministic lease tests, and 20 `index_state` tests passed with zero failures.
+- `cargo check -p codegraph-store --all-targets --locked` passed.
+- `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings` passed.
+- `LIBSQLITE3_SYS_USE_PKG_CONFIG=1 SQLITE3_LIB_DIR=/tmp/opencode cargo check -p
+codegraph-store --target x86_64-pc-windows-msvc --all-targets --locked` passed.
+  This is Linux-host cross-compilation evidence only; no native Windows runtime
+  behavior is claimed.
+- LSP diagnostics could not attach to the external `/tmp` worktree (`file path
+must be inside request cwd`), so the clean Cargo check/Clippy/test diagnostics
+  are the documented fallback.
+- `Cargo.lock` remains required to match
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+Per the documented format trap, repository formatting and the terminal
+`make ci` run occur only after this final ledger byte. The resulting commit is
+created only if that post-format gate exits zero.
+
+The first post-format `make ci` attempt reached the workspace tests after clean
+format and Clippy gates, then failed only at the repository's previously recorded
+`daemon_single_watcher_fires_once` timing assertion: watcher sync #1 reported
+`0 file(s) reindexed` instead of naming the changed file. No lease/store test
+failed. This historical attempt is retained honestly; after formatting this
+append, one fresh terminal retry is the authoritative final gate.

From 3af74bf28fa5c43bdd9ea37ca3b6029d484d6d10 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 18:06:36 +0800
Subject: [PATCH 17/91] docs(upstream-sync): record the authoritative Batch M
 lease final gate

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 30 +++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 200c62f..fa95dff 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1198,3 +1198,33 @@ format and Clippy gates, then failed only at the repository's previously recorde
 `0 file(s) reindexed` instead of naming the changed file. No lease/store test
 failed. This historical attempt is retained honestly; after formatting this
 append, one fresh terminal retry is the authoritative final gate.
+
+### Correction (2026-07-25): authoritative final gate for the identity correction
+
+The retry promised above did happen and it passed, so this section closes the
+terminal-gate evidence for commit `8c19bce70cf8907f356ba0bb45e1188df00b00c9`.
+The failed first attempt recorded directly above is kept verbatim as history: it
+was a timing flake in an unrelated watcher test, not a lease or store
+regression, and deleting it would destroy that distinction.
+
+The parent then reran the whole gate independently on that exact HEAD, and it
+passed. The reproduced focused evidence was:
+
+- `index_lease` integration: 12 passed, 0 failed.
+- Private deterministic lease unit tests: 4 passed, 0 failed.
+- `index_state`: 20 passed, 0 failed.
+- `cargo check -p codegraph-store --all-targets --locked`: clean.
+- `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings`: clean.
+- `x86_64-pc-windows-msvc` all-target check: clean. This is Linux-host
+  cross-compilation evidence only; no native Windows runtime behavior is
+  claimed anywhere in this Batch M work.
+
+The final parent command chain was
+`bash scripts/check-workspace-versions.sh && make ci && sha256sum Cargo.lock &&
+git status --short && git diff --check`, and it exited 0. That `make ci` run
+covered `fmt-check`, `clippy -D warnings`, the full `cargo test --workspace`
+suite, and `bash scripts/guardrail.sh`. `daemon_single_watcher_fires_once`
+carries no `#[ignore]`, so an exit-0 workspace run necessarily includes it: it
+passed in this authoritative run. `Cargo.lock` still hashes to
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, and the
+worktree was clean with no whitespace errors.

From 8bce3deabf672b4b1836d1e6445d3a9e961e5b19 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 19:14:21 +0800
Subject: [PATCH 18/91] fix(store): enforce atomic state publisher protocol

---
 crates/codegraph-store/src/index_lease.rs     |  16 +
 crates/codegraph-store/src/index_state.rs     |  10 +-
 .../src/index_state_publisher.rs              | 813 ++++++++++++++++++
 crates/codegraph-store/src/lib.rs             |   4 +
 .../tests/index_state_publisher.rs            | 748 ++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 187 ++++
 6 files changed, 1774 insertions(+), 4 deletions(-)
 create mode 100644 crates/codegraph-store/src/index_state_publisher.rs
 create mode 100644 crates/codegraph-store/tests/index_state_publisher.rs

diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs
index 9f3d180..568e8cf 100644
--- a/crates/codegraph-store/src/index_lease.rs
+++ b/crates/codegraph-store/src/index_lease.rs
@@ -39,6 +39,7 @@ struct LeaseInner {
     file: File,
     mode: LeaseMode,
     db_parent: PathBuf,
+    lock_path: PathBuf,
 }
 
 struct PendingAcquisition {
@@ -122,6 +123,12 @@ pub enum IndexLeaseValidationError {
     /// The capability belongs to another resolved v2 database parent.
     #[error("index lease belongs to a different v2 database parent")]
     WrongDbParent,
+    /// The permanent fixed path no longer names the exact locked handle.
+    #[error("permanent index lock changed, disappeared, or became an alias: {path}")]
+    PermanentLockChanged {
+        /// Fixed permanent-lock path expected to name the held handle.
+        path: PathBuf,
+    },
 }
 
 impl IndexLease {
@@ -253,6 +260,14 @@ impl IndexLease {
         if !self.matches_db_parent(paths) {
             return Err(IndexLeaseValidationError::WrongDbParent);
         }
+        let expected_path = paths.permanent_lock();
+        if self.inner.lock_path != expected_path
+            || !path_still_names_file(&self.inner.lock_path, &self.inner.file).unwrap_or(false)
+        {
+            return Err(IndexLeaseValidationError::PermanentLockChanged {
+                path: expected_path,
+            });
+        }
         Ok(())
     }
 
@@ -355,6 +370,7 @@ impl IndexLease {
                             file,
                             mode,
                             db_parent,
+                            lock_path,
                         }),
                     });
                 }
diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
index a158da1..aba5c6a 100644
--- a/crates/codegraph-store/src/index_state.rs
+++ b/crates/codegraph-store/src/index_state.rs
@@ -16,8 +16,10 @@
 //!   database, a sidecar, or the tombstone);
 //! - it never opens SQLite, so it cannot run schema setup, migrations, WAL
 //!   changes, or `ANALYZE`;
-//! - it exposes NO state-slot publication API. State publication, `IndexLease`,
-//!   `Store::open_for_read` / `open_for_status` / `open_for_write`,
+//! - publication lives in the separate `index_state_publisher` module and
+//!   consumes this classifier without weakening its aggregate ordering. This
+//!   classifier itself remains strictly read-only;
+//! - `Store::open_for_read` / `open_for_status` / `open_for_write`,
 //!   `Store::stamp_extraction_version`, DB-stamp corroboration, migration mode,
 //!   uninit lifecycle, and the daemon/watcher lifecycle all land in LATER Batch M
 //!   slices and are NOT implemented here.
@@ -29,8 +31,8 @@
 //! this classifier.
 //!
 //! [`checksum_hex`] and [`canonical_checksum_payload`] are pure functions (no
-//! I/O); they define the byte representation a future publisher must reproduce,
-//! and the tests use them to author fixture slots.
+//! I/O); they define the byte representation the publisher reproduces, and the
+//! tests use them to author protocol fixtures.
 //!
 //! # Persisted slot contract
 //!
diff --git a/crates/codegraph-store/src/index_state_publisher.rs b/crates/codegraph-store/src/index_state_publisher.rs
new file mode 100644
index 0000000..aea3a13
--- /dev/null
+++ b/crates/codegraph-store/src/index_state_publisher.rs
@@ -0,0 +1,813 @@
+//! Lease-gated, crash-safe publication of the dual fixed index-state slots.
+//!
+//! Publication always validates an exact exclusive [`IndexLease`], consumes the
+//! accepted read-only classifier under that lease, and preserves the selected
+//! authoritative slot. The successor is written to a same-directory
+//! create-new temporary file, flushed, synchronized, and renamed over only the
+//! older or missing inactive slot. Temporary files are outside the fixed-slot
+//! scanner by construction.
+
+use std::fmt;
+use std::fs::{File, OpenOptions};
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use codegraph_core::IndexPaths;
+use serde::Serialize;
+use thiserror::Error;
+
+use crate::file_identity::is_regular;
+use crate::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, ExtractionStatus, IndexLease,
+    IndexLeaseValidationError, SlotOutcome, StatePhase, StateSlotRecord, checksum_hex, classify,
+};
+
+const TEMP_PREFIX: &str = ".codegraph-index-state-publisher-v2-";
+const TEMP_SUFFIX: &str = ".tmp";
+const TEMP_CREATE_ATTEMPTS: u8 = 64;
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+/// Whether the publication's parent-directory durability barrier was available.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ParentSyncStatus {
+    /// The parent directory was synchronized after the final rename.
+    Synced,
+    /// The platform/filesystem explicitly reported that directory sync is unsupported.
+    Unsupported,
+}
+
+/// The fully validated state made visible by one publication.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PublishedState {
+    /// Fixed slot index that received the new record.
+    pub slot: u8,
+    /// Canonical record written to that slot.
+    pub record: StateSlotRecord,
+    /// Result of the attempted parent-directory durability barrier.
+    pub parent_sync: ParentSyncStatus,
+}
+
+/// The filesystem operation that failed during publication.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StatePublishOperation {
+    /// Creating a fresh same-directory temporary file.
+    CreateTemp,
+    /// Writing all canonical JSON bytes to the temporary file.
+    WriteTemp,
+    /// Flushing userspace buffers for the temporary file.
+    FlushTemp,
+    /// Synchronizing the temporary file's data and metadata.
+    SyncTemp,
+    /// Removing the older inactive fixed slot before replacement.
+    PrepareInactiveSlot,
+    /// Renaming the valid temporary file into the inactive fixed slot.
+    RenameTemp,
+    /// Synchronizing the parent directory after the rename.
+    SyncParent,
+}
+
+impl fmt::Display for StatePublishOperation {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::CreateTemp => "create publisher temporary file",
+            Self::WriteTemp => "write publisher temporary file",
+            Self::FlushTemp => "flush publisher temporary file",
+            Self::SyncTemp => "synchronize publisher temporary file",
+            Self::PrepareInactiveSlot => "prepare inactive state slot",
+            Self::RenameTemp => "rename publisher temporary file",
+            Self::SyncParent => "synchronize state-slot parent directory",
+        })
+    }
+}
+
+/// Typed failures from state publication.
+#[derive(Debug, Error)]
+pub enum StatePublishError {
+    /// The supplied capability is shared or belongs to another namespace.
+    #[error(transparent)]
+    Lease(#[from] IndexLeaseValidationError),
+    /// The under-lease classifier refused mutation of this namespace.
+    #[error("index state publication refused for {status}")]
+    Refused {
+        /// Exact accepted-classifier result that caused the refusal.
+        status: ExtractionStatus,
+    },
+    /// The requested phase is not a valid lifecycle successor of the accepted
+    /// under-lease classification.
+    #[error("cannot publish phase {requested} from index state {current}")]
+    InvalidTransition {
+        /// Exact accepted-classifier status before publication.
+        current: ExtractionStatus,
+        /// Requested successor phase.
+        requested: StatePhase,
+    },
+    /// The accepted classifier returned an internally inconsistent authority.
+    #[error("index state classifier invariant failed: {detail}")]
+    ClassifierInvariant {
+        /// Stable invariant description.
+        detail: &'static str,
+    },
+    /// Canonical typed JSON serialization failed.
+    #[error("cannot serialize canonical index state: {source}")]
+    Serialize {
+        /// Serialization failure.
+        source: serde_json::Error,
+    },
+    /// A bounded create-new retry could not find an unused publisher temp name.
+    #[error(
+        "cannot allocate a create-new index state temp under {parent} after {attempts} attempts"
+    )]
+    TempNameExhausted {
+        /// State-slot parent directory.
+        parent: PathBuf,
+        /// Number of bounded attempts.
+        attempts: u8,
+    },
+    /// A publication I/O operation failed.
+    #[error("cannot {operation} at {path}: {source}")]
+    Io {
+        /// Operation that failed.
+        operation: StatePublishOperation,
+        /// Exact affected path.
+        path: PathBuf,
+        /// Operating-system error.
+        source: io::Error,
+    },
+}
+
+/// Publish the current storage/extraction protocol at `phase`.
+///
+/// The only accepted initial transition is `Missing -> Building`, which
+/// deterministically publishes sequence `0` to fixed slot `0`. Every allowed
+/// successor uses `checked_add(1)` and the opposite fixed slot. Invalid lifecycle
+/// transitions, `Future`, `Corrupt` (including invalid fixed slots, owner
+/// mismatch, equal sequence, and exhaustion), and invalid leases fail before any
+/// mutation.
+pub fn publish_index_state(
+    paths: &IndexPaths,
+    lease: &IndexLease,
+    phase: StatePhase,
+) -> Result<PublishedState, StatePublishError> {
+    publish_index_state_with(paths, lease, phase, &mut NoFault)
+}
+
+#[derive(Serialize)]
+struct WireState<'a> {
+    sequence: u64,
+    #[serde(rename = "storageProtocol")]
+    storage_protocol: u64,
+    #[serde(rename = "extractionVersion")]
+    extraction_version: u64,
+    phase: &'static str,
+    #[serde(rename = "projectIdentity")]
+    project_identity: &'a str,
+    checksum: &'a str,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PublishCheckpoint {
+    TempCreated,
+    TempWritten,
+    TempFlushed,
+    TempSynced,
+    InactiveSlotPrepared,
+    TempRenamed,
+    ParentSyncAttempted,
+}
+
+trait FaultInjector {
+    fn after(&mut self, checkpoint: PublishCheckpoint) -> io::Result<()>;
+}
+
+struct NoFault;
+
+impl FaultInjector for NoFault {
+    fn after(&mut self, _checkpoint: PublishCheckpoint) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+fn publish_index_state_with(
+    paths: &IndexPaths,
+    lease: &IndexLease,
+    phase: StatePhase,
+    fault: &mut impl FaultInjector,
+) -> Result<PublishedState, StatePublishError> {
+    // Capability validation and accepted classification must both happen before
+    // temp creation or any other mutation.
+    lease.validate_exclusive(paths)?;
+    let classification = classify(paths);
+    if matches!(
+        classification.status(),
+        ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. }
+    ) {
+        return Err(StatePublishError::Refused {
+            status: classification.status().clone(),
+        });
+    }
+    validate_transition(classification.status(), phase)?;
+
+    let (sequence, target_index) = match classification.status() {
+        ExtractionStatus::Missing => {
+            if classification.authoritative().is_some() {
+                return Err(StatePublishError::ClassifierInvariant {
+                    detail: "Missing classification selected an authoritative slot",
+                });
+            }
+            (0, 0_usize)
+        }
+        ExtractionStatus::Current
+        | ExtractionStatus::Building { .. }
+        | ExtractionStatus::Uninitialized
+        | ExtractionStatus::Outdated { .. } => {
+            let authority =
+                classification
+                    .authoritative()
+                    .ok_or(StatePublishError::ClassifierInvariant {
+                        detail: "non-Missing publishable classification has no authority",
+                    })?;
+            let sequence = authority.record.sequence.checked_add(1).ok_or({
+                StatePublishError::Refused {
+                    status: ExtractionStatus::Corrupt {
+                        reason: crate::CorruptReason::SequenceExhausted {
+                            sequence: authority.record.sequence,
+                        },
+                    },
+                }
+            })?;
+            let authority_index = usize::from(authority.index);
+            if authority_index >= 2 {
+                return Err(StatePublishError::ClassifierInvariant {
+                    detail: "authoritative fixed-slot index is outside the slot pair",
+                });
+            }
+            (sequence, 1 - authority_index)
+        }
+        ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. } => unreachable!(),
+    };
+
+    match classification.slot(target_index) {
+        SlotOutcome::Absent => {}
+        SlotOutcome::Valid(record) => {
+            if record.sequence >= sequence {
+                return Err(StatePublishError::ClassifierInvariant {
+                    detail: "inactive slot is not older than the successor sequence",
+                });
+            }
+        }
+        SlotOutcome::FutureProtocol(_) | SlotOutcome::Invalid(_) => {
+            return Err(StatePublishError::ClassifierInvariant {
+                detail: "publishable classification contains a future or invalid inactive slot",
+            });
+        }
+    }
+
+    let owner = paths.project_identity();
+    let phase_wire = phase.as_wire();
+    let checksum = checksum_hex(
+        sequence,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        phase_wire,
+        owner,
+    );
+    let bytes = serde_json::to_vec(&WireState {
+        sequence,
+        storage_protocol: CURRENT_STORAGE_PROTOCOL,
+        extraction_version: CURRENT_EXTRACTION_VERSION,
+        phase: phase_wire,
+        project_identity: owner,
+        checksum: &checksum,
+    })
+    .map_err(|source| StatePublishError::Serialize { source })?;
+
+    let slots = paths.state_slots();
+    let target = &slots[target_index];
+    let parent = target
+        .parent()
+        .ok_or(StatePublishError::ClassifierInvariant {
+            detail: "fixed state slot has no parent directory",
+        })?;
+    if parent != paths.current_root() || slots[1 - target_index].parent() != Some(parent) {
+        return Err(StatePublishError::ClassifierInvariant {
+            detail: "fixed state slots do not share IndexPaths::current_root",
+        });
+    }
+
+    let (temp_path, mut temp) = create_temp(parent)?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::TempCreated,
+        StatePublishOperation::CreateTemp,
+        &temp_path,
+    )?;
+
+    temp.write_all(&bytes)
+        .map_err(|source| io_error(StatePublishOperation::WriteTemp, &temp_path, source))?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::TempWritten,
+        StatePublishOperation::WriteTemp,
+        &temp_path,
+    )?;
+    temp.flush()
+        .map_err(|source| io_error(StatePublishOperation::FlushTemp, &temp_path, source))?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::TempFlushed,
+        StatePublishOperation::FlushTemp,
+        &temp_path,
+    )?;
+    temp.sync_all()
+        .map_err(|source| io_error(StatePublishOperation::SyncTemp, &temp_path, source))?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::TempSynced,
+        StatePublishOperation::SyncTemp,
+        &temp_path,
+    )?;
+    drop(temp);
+
+    match std::fs::symlink_metadata(target) {
+        Ok(metadata) => {
+            if !is_regular(&metadata) {
+                return Err(StatePublishError::ClassifierInvariant {
+                    detail: "inactive fixed slot changed after under-lease classification",
+                });
+            }
+            std::fs::remove_file(target).map_err(|source| {
+                io_error(StatePublishOperation::PrepareInactiveSlot, target, source)
+            })?;
+        }
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+        Err(source) => {
+            return Err(io_error(
+                StatePublishOperation::PrepareInactiveSlot,
+                target,
+                source,
+            ));
+        }
+    }
+    checkpoint(
+        fault,
+        PublishCheckpoint::InactiveSlotPrepared,
+        StatePublishOperation::PrepareInactiveSlot,
+        target,
+    )?;
+
+    std::fs::rename(&temp_path, target)
+        .map_err(|source| io_error(StatePublishOperation::RenameTemp, target, source))?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::TempRenamed,
+        StatePublishOperation::RenameTemp,
+        target,
+    )?;
+
+    let parent_sync = sync_parent(parent)?;
+    checkpoint(
+        fault,
+        PublishCheckpoint::ParentSyncAttempted,
+        StatePublishOperation::SyncParent,
+        parent,
+    )?;
+
+    let record = StateSlotRecord {
+        sequence,
+        storage_protocol: CURRENT_STORAGE_PROTOCOL,
+        extraction_version: CURRENT_EXTRACTION_VERSION,
+        phase: Some(phase),
+        phase_raw: phase_wire.to_string(),
+        project_identity: owner.to_string(),
+        checksum,
+    };
+    Ok(PublishedState {
+        slot: u8::try_from(target_index).expect("fixed slot index fits u8"),
+        record,
+        parent_sync,
+    })
+}
+
+fn checkpoint(
+    fault: &mut impl FaultInjector,
+    checkpoint: PublishCheckpoint,
+    operation: StatePublishOperation,
+    path: &Path,
+) -> Result<(), StatePublishError> {
+    fault
+        .after(checkpoint)
+        .map_err(|source| io_error(operation, path, source))
+}
+
+fn io_error(operation: StatePublishOperation, path: &Path, source: io::Error) -> StatePublishError {
+    StatePublishError::Io {
+        operation,
+        path: path.to_path_buf(),
+        source,
+    }
+}
+
+fn create_temp(parent: &Path) -> Result<(PathBuf, File), StatePublishError> {
+    for _ in 0..TEMP_CREATE_ATTEMPTS {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let name = format!(
+            "{TEMP_PREFIX}{}-{serial:016x}{TEMP_SUFFIX}",
+            std::process::id()
+        );
+        let path = parent.join(name);
+        match OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .truncate(false)
+            .open(&path)
+        {
+            Ok(file) => return Ok((path, file)),
+            Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
+            Err(source) => {
+                return Err(io_error(StatePublishOperation::CreateTemp, &path, source));
+            }
+        }
+    }
+    Err(StatePublishError::TempNameExhausted {
+        parent: parent.to_path_buf(),
+        attempts: TEMP_CREATE_ATTEMPTS,
+    })
+}
+
+fn validate_transition(
+    current: &ExtractionStatus,
+    requested: StatePhase,
+) -> Result<(), StatePublishError> {
+    let allowed = matches!(
+        (current, requested),
+        (ExtractionStatus::Missing, StatePhase::Building)
+            | (ExtractionStatus::Outdated { .. }, StatePhase::Building)
+            | (ExtractionStatus::Uninitialized, StatePhase::Building)
+            | (
+                ExtractionStatus::Current,
+                StatePhase::Building | StatePhase::Uninitialized
+            )
+            | (
+                ExtractionStatus::Building { .. },
+                StatePhase::Building | StatePhase::Current | StatePhase::Uninitialized
+            )
+    );
+    if allowed {
+        Ok(())
+    } else {
+        Err(StatePublishError::InvalidTransition {
+            current: current.clone(),
+            requested,
+        })
+    }
+}
+
+#[cfg(unix)]
+fn sync_parent(parent: &Path) -> Result<ParentSyncStatus, StatePublishError> {
+    let directory = File::open(parent)
+        .map_err(|source| io_error(StatePublishOperation::SyncParent, parent, source))?;
+    match directory.sync_all() {
+        Ok(()) => Ok(ParentSyncStatus::Synced),
+        Err(error) if directory_sync_unsupported(&error) => Ok(ParentSyncStatus::Unsupported),
+        Err(source) => Err(io_error(StatePublishOperation::SyncParent, parent, source)),
+    }
+}
+
+#[cfg(windows)]
+fn sync_parent(parent: &Path) -> Result<ParentSyncStatus, StatePublishError> {
+    use std::os::windows::fs::OpenOptionsExt as _;
+
+    const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
+    let directory = OpenOptions::new()
+        .read(true)
+        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS)
+        .open(parent)
+        .map_err(|source| io_error(StatePublishOperation::SyncParent, parent, source))?;
+    match directory.sync_all() {
+        Ok(()) => Ok(ParentSyncStatus::Synced),
+        Err(error) if directory_sync_unsupported(&error) => Ok(ParentSyncStatus::Unsupported),
+        Err(source) => Err(io_error(StatePublishOperation::SyncParent, parent, source)),
+    }
+}
+
+#[cfg(not(any(unix, windows)))]
+fn sync_parent(_parent: &Path) -> Result<ParentSyncStatus, StatePublishError> {
+    Ok(ParentSyncStatus::Unsupported)
+}
+
+#[cfg(any(unix, windows))]
+fn directory_sync_unsupported(error: &io::Error) -> bool {
+    if error.kind() == io::ErrorKind::Unsupported {
+        return true;
+    }
+    #[cfg(unix)]
+    {
+        // EINVAL and EOPNOTSUPP/ENOTSUP are the conventional reports for a
+        // filesystem that cannot synchronize directory entries.
+        matches!(error.raw_os_error(), Some(22 | 95))
+    }
+    #[cfg(windows)]
+    {
+        // ERROR_INVALID_FUNCTION, ERROR_INVALID_HANDLE, ERROR_NOT_SUPPORTED,
+        // and ERROR_INVALID_PARAMETER explicitly mean this handle/filesystem
+        // does not expose a directory flush primitive. Access errors are NOT
+        // downgraded to unsupported.
+        matches!(error.raw_os_error(), Some(1 | 6 | 50 | 87))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{Duration, Instant};
+
+    use super::*;
+
+    struct TempProject(PathBuf);
+
+    impl TempProject {
+        fn new(label: &str) -> Self {
+            let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+            let path = std::env::temp_dir().join(format!(
+                "codegraph-state-publisher-unit-{label}-{}-{serial}",
+                std::process::id()
+            ));
+            std::fs::create_dir(&path).expect("create publisher unit project");
+            Self(
+                path.canonicalize()
+                    .expect("canonical publisher unit project"),
+            )
+        }
+
+        fn paths(&self) -> IndexPaths {
+            IndexPaths::resolve(&self.0, None).expect("resolve publisher unit paths")
+        }
+    }
+
+    impl Drop for TempProject {
+        fn drop(&mut self) {
+            std::fs::remove_dir_all(&self.0).expect("remove publisher unit project");
+        }
+    }
+
+    fn deadline() -> Instant {
+        Instant::now()
+            .checked_add(Duration::from_secs(5))
+            .expect("publisher unit deadline")
+    }
+
+    struct FailAfter(PublishCheckpoint);
+
+    impl FaultInjector for FailAfter {
+        fn after(&mut self, checkpoint: PublishCheckpoint) -> io::Result<()> {
+            if checkpoint == self.0 {
+                Err(io::Error::other(format!(
+                    "injected crash after {checkpoint:?}"
+                )))
+            } else {
+                Ok(())
+            }
+        }
+    }
+
+    #[derive(Debug, Clone, Copy)]
+    enum PriorStatus {
+        Outdated,
+        Building,
+        Current,
+        Uninitialized,
+    }
+
+    fn stage_prior(paths: &IndexPaths, lease: &IndexLease, prior: PriorStatus) -> Vec<u8> {
+        match prior {
+            PriorStatus::Outdated => {
+                let sequence = 1;
+                let extraction_version = CURRENT_EXTRACTION_VERSION - 1;
+                let phase = StatePhase::Current;
+                let owner = paths.project_identity();
+                let checksum = checksum_hex(
+                    sequence,
+                    CURRENT_STORAGE_PROTOCOL,
+                    extraction_version,
+                    phase.as_wire(),
+                    owner,
+                );
+                let bytes = serde_json::to_vec(&WireState {
+                    sequence,
+                    storage_protocol: CURRENT_STORAGE_PROTOCOL,
+                    extraction_version,
+                    phase: phase.as_wire(),
+                    project_identity: owner,
+                    checksum: &checksum,
+                })
+                .expect("serialize outdated prior state");
+                std::fs::write(&paths.state_slots()[1], &bytes)
+                    .expect("write outdated prior state");
+            }
+            PriorStatus::Building => {
+                publish_index_state(paths, lease, StatePhase::Building)
+                    .expect("publish first building fixture state");
+                publish_index_state(paths, lease, StatePhase::Building)
+                    .expect("publish authoritative building fixture state");
+            }
+            PriorStatus::Current => {
+                publish_index_state(paths, lease, StatePhase::Building)
+                    .expect("publish building fixture state");
+                publish_index_state(paths, lease, StatePhase::Current)
+                    .expect("publish current fixture state");
+            }
+            PriorStatus::Uninitialized => {
+                publish_index_state(paths, lease, StatePhase::Building)
+                    .expect("publish building fixture state");
+                publish_index_state(paths, lease, StatePhase::Uninitialized)
+                    .expect("publish uninitialized fixture state");
+            }
+        }
+        std::fs::read(&paths.state_slots()[1]).expect("read prior authoritative bytes")
+    }
+
+    fn expected_phase_status(phase: StatePhase) -> ExtractionStatus {
+        match phase {
+            StatePhase::Building => ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+            StatePhase::Current => ExtractionStatus::Current,
+            StatePhase::Uninitialized => ExtractionStatus::Uninitialized,
+        }
+    }
+
+    fn expected_prior_status(prior: PriorStatus) -> ExtractionStatus {
+        match prior {
+            PriorStatus::Outdated => ExtractionStatus::Outdated {
+                built: CURRENT_EXTRACTION_VERSION - 1,
+            },
+            PriorStatus::Building => expected_phase_status(StatePhase::Building),
+            PriorStatus::Current => expected_phase_status(StatePhase::Current),
+            PriorStatus::Uninitialized => expected_phase_status(StatePhase::Uninitialized),
+        }
+    }
+
+    #[test]
+    fn transition_validator_covers_every_status_and_requested_phase_pair() {
+        let statuses = [
+            ExtractionStatus::Missing,
+            ExtractionStatus::Outdated { built: 1 },
+            ExtractionStatus::Uninitialized,
+            ExtractionStatus::Current,
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+            ExtractionStatus::Future { built: 99 },
+            ExtractionStatus::Corrupt {
+                reason: crate::CorruptReason::SequenceExhausted { sequence: u64::MAX },
+            },
+        ];
+        let phases = [
+            StatePhase::Building,
+            StatePhase::Current,
+            StatePhase::Uninitialized,
+        ];
+
+        for current in statuses {
+            for requested in phases {
+                let expected = matches!(
+                    (&current, requested),
+                    (ExtractionStatus::Missing, StatePhase::Building)
+                        | (ExtractionStatus::Outdated { .. }, StatePhase::Building)
+                        | (ExtractionStatus::Uninitialized, StatePhase::Building)
+                        | (
+                            ExtractionStatus::Current,
+                            StatePhase::Building | StatePhase::Uninitialized
+                        )
+                        | (ExtractionStatus::Building { .. }, _)
+                );
+                let result = validate_transition(&current, requested);
+                assert_eq!(
+                    result.is_ok(),
+                    expected,
+                    "current={current:?}, requested={requested:?}, result={result:?}"
+                );
+                if !expected {
+                    assert!(matches!(
+                        result,
+                        Err(StatePublishError::InvalidTransition {
+                            current: actual_current,
+                            requested: actual_requested,
+                        }) if actual_current == current && actual_requested == requested
+                    ));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn every_publication_checkpoint_preserves_old_authority_or_exposes_valid_successor() {
+        let allowed = [
+            (PriorStatus::Outdated, StatePhase::Building),
+            (PriorStatus::Uninitialized, StatePhase::Building),
+            (PriorStatus::Current, StatePhase::Building),
+            (PriorStatus::Current, StatePhase::Uninitialized),
+            (PriorStatus::Building, StatePhase::Building),
+            (PriorStatus::Building, StatePhase::Current),
+            (PriorStatus::Building, StatePhase::Uninitialized),
+        ];
+        let checkpoints = [
+            PublishCheckpoint::TempCreated,
+            PublishCheckpoint::TempWritten,
+            PublishCheckpoint::TempFlushed,
+            PublishCheckpoint::TempSynced,
+            PublishCheckpoint::InactiveSlotPrepared,
+            PublishCheckpoint::TempRenamed,
+            PublishCheckpoint::ParentSyncAttempted,
+        ];
+
+        for (prior, next_phase) in allowed {
+            for checkpoint in checkpoints {
+                let project = TempProject::new("fault-matrix");
+                let paths = project.paths();
+                let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+                    .expect("create fault-matrix lease");
+                let authority_bytes = stage_prior(&paths, &lease, prior);
+
+                let error = publish_index_state_with(
+                    &paths,
+                    &lease,
+                    next_phase,
+                    &mut FailAfter(checkpoint),
+                )
+                .expect_err("fault checkpoint must interrupt publication");
+                assert!(matches!(error, StatePublishError::Io { .. }));
+                assert_eq!(
+                    std::fs::read(&paths.state_slots()[1]).expect("old authority survives"),
+                    authority_bytes,
+                    "prior={prior:?}, next={next_phase:?}, fault={checkpoint:?}"
+                );
+
+                let observed = classify(&paths);
+                let old = expected_prior_status(prior);
+                let new = expected_phase_status(next_phase);
+                assert!(
+                    observed.status() == &old || observed.status() == &new,
+                    "prior={prior:?}, next={next_phase:?}, fault={checkpoint:?}, observed={observed:?}"
+                );
+                if matches!(
+                    checkpoint,
+                    PublishCheckpoint::TempRenamed | PublishCheckpoint::ParentSyncAttempted
+                ) {
+                    assert_eq!(observed.status(), &new);
+                } else {
+                    assert_eq!(observed.status(), &old);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn every_initial_publication_checkpoint_leaves_missing_or_exposes_a_valid_first_slot() {
+        let checkpoints = [
+            PublishCheckpoint::TempCreated,
+            PublishCheckpoint::TempWritten,
+            PublishCheckpoint::TempFlushed,
+            PublishCheckpoint::TempSynced,
+            PublishCheckpoint::InactiveSlotPrepared,
+            PublishCheckpoint::TempRenamed,
+            PublishCheckpoint::ParentSyncAttempted,
+        ];
+
+        for checkpoint in checkpoints {
+            let project = TempProject::new("initial-fault-matrix");
+            let paths = project.paths();
+            let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+                .expect("create initial-fault lease");
+
+            let error = publish_index_state_with(
+                &paths,
+                &lease,
+                StatePhase::Building,
+                &mut FailAfter(checkpoint),
+            )
+            .expect_err("initial fault checkpoint must interrupt publication");
+            assert!(matches!(error, StatePublishError::Io { .. }));
+            let observed = classify(&paths);
+            if matches!(
+                checkpoint,
+                PublishCheckpoint::TempRenamed | PublishCheckpoint::ParentSyncAttempted
+            ) {
+                assert_eq!(
+                    observed.status(),
+                    &expected_phase_status(StatePhase::Building)
+                );
+                assert_eq!(
+                    observed
+                        .authoritative()
+                        .expect("valid initial authority")
+                        .record
+                        .sequence,
+                    0
+                );
+            } else {
+                assert_eq!(observed.status(), &ExtractionStatus::Missing);
+            }
+        }
+    }
+}
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index 94e728c..33edd8f 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -2,6 +2,7 @@ pub mod connection;
 mod file_identity;
 pub mod index_lease;
 pub mod index_state;
+pub mod index_state_publisher;
 pub mod migrations;
 pub mod queries;
 pub mod schema;
@@ -13,6 +14,9 @@ pub use index_state::{
     EXTRACTION_VERSION_KEY, ExtractionStatus, IndexStateClassification, SlotOutcome, StatePhase,
     StateSlotRecord, canonical_checksum_payload, checksum_hex, classify, classify_slots,
 };
+pub use index_state_publisher::{
+    ParentSyncStatus, PublishedState, StatePublishError, publish_index_state,
+};
 pub use queries::{
     CODEGRAPH_NO_WAL_DEFER, CODEGRAPH_WAL_VALVE_MB, DEFAULT_WAL_VALVE_MB, wal_valve_threshold_bytes,
 };
diff --git a/crates/codegraph-store/tests/index_state_publisher.rs b/crates/codegraph-store/tests/index_state_publisher.rs
new file mode 100644
index 0000000..364900b
--- /dev/null
+++ b/crates/codegraph-store/tests/index_state_publisher.rs
@@ -0,0 +1,748 @@
+//! Public behavioral contract for lease-gated dual-slot state publication.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, CorruptReason, ExtractionStatus,
+    IndexLease, IndexLeaseValidationError, ParentSyncStatus, SlotOutcome, StatePhase,
+    StatePublishError, checksum_hex, classify, publish_index_state,
+};
+use serde_json::json;
+
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+struct TempProject(PathBuf);
+
+impl TempProject {
+    fn new(label: &str) -> Self {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-index-state-publisher-{label}-{}-{serial}",
+            std::process::id()
+        ));
+        std::fs::create_dir(&path)
+            .unwrap_or_else(|err| panic!("create temp project {}: {err}", path.display()));
+        Self(path.canonicalize().expect("canonical temp project"))
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(self.path(), None).expect("resolve publisher test paths")
+    }
+}
+
+impl Drop for TempProject {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.0)
+            .unwrap_or_else(|err| panic!("remove temp project {}: {err}", self.0.display()));
+    }
+}
+
+fn deadline() -> Instant {
+    Instant::now()
+        .checked_add(Duration::from_secs(5))
+        .expect("publisher test deadline")
+}
+
+fn wire_bytes(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) -> Vec<u8> {
+    serde_json::to_vec(&json!({
+        "sequence": sequence,
+        "storageProtocol": storage_protocol,
+        "extractionVersion": extraction_version,
+        "phase": phase,
+        "projectIdentity": owner,
+        "checksum": checksum_hex(
+            sequence,
+            storage_protocol,
+            extraction_version,
+            phase,
+            owner,
+        ),
+    }))
+    .expect("serialize publisher state fixture")
+}
+
+fn canonical_published_bytes(sequence: u64, phase: &str, owner: &str) -> Vec<u8> {
+    let checksum = checksum_hex(
+        sequence,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        phase,
+        owner,
+    );
+    format!(
+        "{{\"sequence\":{sequence},\"storageProtocol\":{CURRENT_STORAGE_PROTOCOL},\"extractionVersion\":{CURRENT_EXTRACTION_VERSION},\"phase\":\"{phase}\",\"projectIdentity\":\"{owner}\",\"checksum\":\"{checksum}\"}}"
+    )
+    .into_bytes()
+}
+
+fn write_wire(
+    path: &Path,
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) {
+    std::fs::write(
+        path,
+        wire_bytes(sequence, storage_protocol, extraction_version, phase, owner),
+    )
+    .unwrap_or_else(|err| panic!("write publisher fixture {}: {err}", path.display()));
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum SnapshotKind {
+    Directory,
+    File(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
+    fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, SnapshotKind>) {
+        let entries = std::fs::read_dir(directory)
+            .unwrap_or_else(|err| panic!("snapshot read_dir {}: {err}", directory.display()));
+        let mut paths = entries
+            .map(|entry| {
+                entry
+                    .unwrap_or_else(|err| {
+                        panic!("snapshot entry in {}: {err}", directory.display())
+                    })
+                    .path()
+            })
+            .collect::<Vec<_>>();
+        paths.sort();
+        for path in paths {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|err| panic!("snapshot strip {}: {err}", path.display()))
+                .to_path_buf();
+            let metadata = std::fs::symlink_metadata(&path)
+                .unwrap_or_else(|err| panic!("snapshot metadata {}: {err}", path.display()));
+            let file_type = metadata.file_type();
+            let kind = if file_type.is_dir() {
+                SnapshotKind::Directory
+            } else if file_type.is_file() {
+                SnapshotKind::File(
+                    std::fs::read(&path)
+                        .unwrap_or_else(|err| panic!("snapshot read {}: {err}", path.display())),
+                )
+            } else if file_type.is_symlink() {
+                SnapshotKind::Symlink(
+                    std::fs::read_link(&path).unwrap_or_else(|err| {
+                        panic!("snapshot read_link {}: {err}", path.display())
+                    }),
+                )
+            } else {
+                panic!("snapshot unsupported entry kind: {}", path.display());
+            };
+            assert!(
+                out.insert(relative, kind).is_none(),
+                "duplicate snapshot path"
+            );
+            if file_type.is_dir() {
+                walk(root, &path, out);
+            }
+        }
+    }
+
+    let mut out = BTreeMap::new();
+    walk(root, root, &mut out);
+    out
+}
+
+fn assert_snapshot_unchanged(
+    before: &BTreeMap<PathBuf, SnapshotKind>,
+    after: &BTreeMap<PathBuf, SnapshotKind>,
+) {
+    let changed = before
+        .keys()
+        .chain(after.keys())
+        .filter(|path| before.get(*path) != after.get(*path))
+        .cloned()
+        .collect::<BTreeSet<_>>();
+    assert!(changed.is_empty(), "filesystem changed at {changed:?}");
+}
+
+fn assert_rejected_without_mutation(
+    project: &TempProject,
+    invoke: impl FnOnce() -> Result<codegraph_store::PublishedState, StatePublishError>,
+    expected: impl FnOnce(&StatePublishError) -> bool,
+) {
+    let before = snapshot_tree(project.path());
+    let error = invoke().expect_err("publication must be rejected");
+    assert!(expected(&error), "unexpected publisher error: {error:?}");
+    let after = snapshot_tree(project.path());
+    assert_snapshot_unchanged(&before, &after);
+}
+
+#[test]
+fn first_publication_from_absent_state_writes_canonical_slot_zero_sequence_zero() {
+    let project = TempProject::new("initial-red");
+    let paths = project.paths();
+    let lease =
+        IndexLease::create_exclusive(&paths, deadline(), || false).expect("create namespace lease");
+    assert_eq!(classify(&paths).status(), &ExtractionStatus::Missing);
+
+    let published = publish_index_state(&paths, &lease, StatePhase::Building)
+        .expect("initial state publication must succeed");
+
+    assert_eq!(published.slot, 0);
+    assert_eq!(published.record.sequence, 0);
+    assert_eq!(published.record.storage_protocol, CURRENT_STORAGE_PROTOCOL);
+    assert_eq!(
+        published.record.extraction_version,
+        CURRENT_EXTRACTION_VERSION
+    );
+    assert_eq!(published.record.phase, Some(StatePhase::Building));
+    assert_eq!(published.record.project_identity, paths.project_identity());
+    assert!(matches!(
+        published.parent_sync,
+        ParentSyncStatus::Synced | ParentSyncStatus::Unsupported
+    ));
+    assert!(paths.state_slots()[0].is_file());
+    assert!(!paths.state_slots()[1].exists());
+    assert_eq!(
+        std::fs::read(&paths.state_slots()[0]).expect("read canonical first slot"),
+        canonical_published_bytes(0, "building", paths.project_identity())
+    );
+    assert_eq!(
+        classify(&paths).status(),
+        &ExtractionStatus::Building {
+            built: CURRENT_EXTRACTION_VERSION
+        }
+    );
+}
+
+#[test]
+fn all_current_protocol_phases_publish_monotonically_and_replace_only_the_older_slot() {
+    let project = TempProject::new("phase-cycle");
+    let paths = project.paths();
+    let lease =
+        IndexLease::create_exclusive(&paths, deadline(), || false).expect("create namespace lease");
+
+    let building = publish_index_state(&paths, &lease, StatePhase::Building).unwrap();
+    let building_bytes = std::fs::read(&paths.state_slots()[0]).unwrap();
+    let current = publish_index_state(&paths, &lease, StatePhase::Current).unwrap();
+    let current_bytes = std::fs::read(&paths.state_slots()[1]).unwrap();
+    assert_eq!(
+        std::fs::read(&paths.state_slots()[0]).unwrap(),
+        building_bytes
+    );
+
+    let uninitialized = publish_index_state(&paths, &lease, StatePhase::Uninitialized).unwrap();
+    assert_eq!(building.slot, 0);
+    assert_eq!(current.slot, 1);
+    assert_eq!(uninitialized.slot, 0);
+    assert_eq!(
+        [
+            building.record.sequence,
+            current.record.sequence,
+            uninitialized.record.sequence,
+        ],
+        [0, 1, 2]
+    );
+    assert_eq!(
+        std::fs::read(&paths.state_slots()[1]).unwrap(),
+        current_bytes,
+        "third publication must preserve the current authoritative slot"
+    );
+    assert_eq!(classify(&paths).status(), &ExtractionStatus::Uninitialized);
+}
+
+#[derive(Debug, Clone, Copy)]
+enum PriorStatus {
+    Missing,
+    Outdated,
+    Uninitialized,
+    Current,
+}
+
+fn stage_prior_status(paths: &IndexPaths, lease: &IndexLease, prior: PriorStatus) {
+    match prior {
+        PriorStatus::Missing => {}
+        PriorStatus::Outdated => write_wire(
+            &paths.state_slots()[0],
+            4,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION - 1,
+            "current",
+            paths.project_identity(),
+        ),
+        PriorStatus::Uninitialized => {
+            publish_index_state(paths, lease, StatePhase::Building).unwrap();
+            publish_index_state(paths, lease, StatePhase::Uninitialized).unwrap();
+        }
+        PriorStatus::Current => {
+            publish_index_state(paths, lease, StatePhase::Building).unwrap();
+            publish_index_state(paths, lease, StatePhase::Current).unwrap();
+        }
+    }
+}
+
+fn expected_prior_status(prior: PriorStatus) -> ExtractionStatus {
+    match prior {
+        PriorStatus::Missing => ExtractionStatus::Missing,
+        PriorStatus::Outdated => ExtractionStatus::Outdated {
+            built: CURRENT_EXTRACTION_VERSION - 1,
+        },
+        PriorStatus::Uninitialized => ExtractionStatus::Uninitialized,
+        PriorStatus::Current => ExtractionStatus::Current,
+    }
+}
+
+#[test]
+fn invalid_lifecycle_transitions_are_byte_nonmutating() {
+    let cases = [
+        (PriorStatus::Missing, StatePhase::Current),
+        (PriorStatus::Missing, StatePhase::Uninitialized),
+        (PriorStatus::Outdated, StatePhase::Current),
+        (PriorStatus::Outdated, StatePhase::Uninitialized),
+        (PriorStatus::Uninitialized, StatePhase::Current),
+        (PriorStatus::Uninitialized, StatePhase::Uninitialized),
+        (PriorStatus::Current, StatePhase::Current),
+    ];
+
+    for (prior, requested) in cases {
+        let project = TempProject::new("invalid-transition");
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+        stage_prior_status(&paths, &lease, prior);
+        assert_rejected_without_mutation(
+            &project,
+            || publish_index_state(&paths, &lease, requested),
+            |error| {
+                matches!(
+                    error,
+                    StatePublishError::InvalidTransition {
+                        current,
+                        requested: actual,
+                    } if current == &expected_prior_status(prior) && *actual == requested
+                )
+            },
+        );
+    }
+}
+
+#[test]
+fn shared_and_wrong_parent_capabilities_are_typed_and_byte_nonmutating() {
+    let shared_project = TempProject::new("shared-capability");
+    let shared_paths = shared_project.paths();
+    let initial = IndexLease::create_exclusive(&shared_paths, deadline(), || false).unwrap();
+    publish_index_state(&shared_paths, &initial, StatePhase::Building).unwrap();
+    drop(initial);
+    let shared = IndexLease::acquire_shared_existing(&shared_paths, deadline(), || false).unwrap();
+    assert_rejected_without_mutation(
+        &shared_project,
+        || publish_index_state(&shared_paths, &shared, StatePhase::Building),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(IndexLeaseValidationError::SharedLease)
+            )
+        },
+    );
+    drop(shared);
+
+    let other_project = TempProject::new("wrong-parent-capability");
+    let other_paths = other_project.paths();
+    let other_lease = IndexLease::create_exclusive(&other_paths, deadline(), || false).unwrap();
+    publish_index_state(&other_paths, &other_lease, StatePhase::Building).unwrap();
+    let wrong_lease =
+        IndexLease::acquire_exclusive_existing(&shared_paths, deadline(), || false).unwrap();
+    assert_rejected_without_mutation(
+        &other_project,
+        || publish_index_state(&other_paths, &wrong_lease, StatePhase::Building),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(IndexLeaseValidationError::WrongDbParent)
+            )
+        },
+    );
+}
+
+#[test]
+fn replaced_permanent_lock_invalidates_publisher_capability_before_state_mutation() {
+    let project = TempProject::new("replaced-lock");
+    let paths = project.paths();
+    let stale = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &stale, StatePhase::Building).unwrap();
+
+    let displaced = paths.current_root().join("displaced-index.lock");
+    std::fs::rename(paths.permanent_lock(), &displaced).expect("displace locked handle");
+    std::fs::write(paths.permanent_lock(), b"replacement lock").expect("install replacement lock");
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &stale, StatePhase::Current),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(
+                    IndexLeaseValidationError::PermanentLockChanged { path }
+                ) if path == &paths.permanent_lock()
+            )
+        },
+    );
+
+    let fresh = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+        .expect("replacement lock is independent of the stale capability");
+    drop(fresh);
+    drop(stale);
+}
+
+#[test]
+fn missing_permanent_lock_invalidates_publisher_capability_before_state_mutation() {
+    let project = TempProject::new("missing-lock-after-acquire");
+    let paths = project.paths();
+    let stale = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &stale, StatePhase::Building).unwrap();
+
+    let displaced = paths.current_root().join("displaced-index.lock");
+    std::fs::rename(paths.permanent_lock(), &displaced).expect("displace locked handle");
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &stale, StatePhase::Current),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(
+                    IndexLeaseValidationError::PermanentLockChanged { path }
+                ) if path == &paths.permanent_lock()
+            )
+        },
+    );
+}
+
+#[test]
+fn non_regular_permanent_lock_invalidates_publisher_capability_before_state_mutation() {
+    let project = TempProject::new("non-regular-lock-after-acquire");
+    let paths = project.paths();
+    let stale = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &stale, StatePhase::Building).unwrap();
+
+    let displaced = paths.current_root().join("displaced-index.lock");
+    std::fs::rename(paths.permanent_lock(), &displaced).expect("displace locked handle");
+    std::fs::create_dir(paths.permanent_lock()).expect("install directory at fixed lock path");
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &stale, StatePhase::Current),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(
+                    IndexLeaseValidationError::PermanentLockChanged { path }
+                ) if path == &paths.permanent_lock()
+            )
+        },
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn aliased_permanent_lock_invalidates_publisher_capability_before_state_mutation() {
+    use std::os::unix::fs::symlink;
+
+    let project = TempProject::new("aliased-lock-after-acquire");
+    let paths = project.paths();
+    let stale = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &stale, StatePhase::Building).unwrap();
+
+    let displaced = paths.current_root().join("displaced-index.lock");
+    let external = project.path().join("external.lock");
+    std::fs::rename(paths.permanent_lock(), &displaced).expect("displace locked handle");
+    std::fs::write(&external, b"external lock target").expect("write external lock target");
+    symlink(&external, paths.permanent_lock()).expect("install alias at fixed lock path");
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &stale, StatePhase::Current),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Lease(
+                    IndexLeaseValidationError::PermanentLockChanged { path }
+                ) if path == &paths.permanent_lock()
+            )
+        },
+    );
+    assert_eq!(std::fs::read(&external).unwrap(), b"external lock target");
+}
+
+#[test]
+fn invalid_fixed_slot_equal_sequence_and_exhaustion_are_refused_byte_nonmutating() {
+    for case in ["invalid", "equal", "exhausted"] {
+        let project = TempProject::new(case);
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+        match case {
+            "invalid" => {
+                write_wire(
+                    &paths.state_slots()[0],
+                    3,
+                    2,
+                    2,
+                    "current",
+                    paths.project_identity(),
+                );
+                std::fs::write(&paths.state_slots()[1], b"not json").unwrap();
+            }
+            "equal" => {
+                write_wire(
+                    &paths.state_slots()[0],
+                    3,
+                    2,
+                    2,
+                    "building",
+                    paths.project_identity(),
+                );
+                write_wire(
+                    &paths.state_slots()[1],
+                    3,
+                    2,
+                    2,
+                    "current",
+                    paths.project_identity(),
+                );
+            }
+            "exhausted" => write_wire(
+                &paths.state_slots()[0],
+                u64::MAX,
+                2,
+                2,
+                "current",
+                paths.project_identity(),
+            ),
+            _ => unreachable!(),
+        }
+
+        assert_rejected_without_mutation(
+            &project,
+            || publish_index_state(&paths, &lease, StatePhase::Uninitialized),
+            |error| {
+                matches!(
+                    (case, error),
+                    (
+                        "invalid",
+                        StatePublishError::Refused {
+                            status: ExtractionStatus::Corrupt {
+                                reason: CorruptReason::MalformedJson { slot: 1, .. },
+                            },
+                        },
+                    ) | (
+                        "equal",
+                        StatePublishError::Refused {
+                            status: ExtractionStatus::Corrupt {
+                                reason: CorruptReason::EqualSequence { sequence: 3, .. },
+                            },
+                        },
+                    ) | (
+                        "exhausted",
+                        StatePublishError::Refused {
+                            status: ExtractionStatus::Corrupt {
+                                reason: CorruptReason::SequenceExhausted { sequence: u64::MAX },
+                            },
+                        },
+                    )
+                )
+            },
+        );
+    }
+}
+
+#[test]
+fn owner_mismatch_is_typed_and_byte_nonmutating() {
+    let project = TempProject::new("owner-mismatch");
+    let paths = project.paths();
+    let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    let other_owner = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+    write_wire(
+        &paths.state_slots()[0],
+        1,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        "current",
+        other_owner,
+    );
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &lease, StatePhase::Building),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Refused {
+                    status: ExtractionStatus::Corrupt {
+                        reason: CorruptReason::OwnerMismatch { slot: 0, .. }
+                    }
+                }
+            )
+        },
+    );
+}
+
+#[test]
+fn future_v3_slot_dominates_current_companion_and_is_never_replaced() {
+    let project = TempProject::new("future-v3");
+    let paths = project.paths();
+    let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    write_wire(
+        &paths.state_slots()[0],
+        90,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        "current",
+        paths.project_identity(),
+    );
+    write_wire(
+        &paths.state_slots()[1],
+        91,
+        3,
+        99,
+        "v3-replacement",
+        paths.project_identity(),
+    );
+    assert_eq!(
+        classify(&paths).status(),
+        &ExtractionStatus::Future { built: 99 }
+    );
+
+    assert_rejected_without_mutation(
+        &project,
+        || publish_index_state(&paths, &lease, StatePhase::Uninitialized),
+        |error| {
+            matches!(
+                error,
+                StatePublishError::Refused {
+                    status: ExtractionStatus::Future { built: 99 }
+                }
+            )
+        },
+    );
+}
+
+#[test]
+fn missing_inactive_slot_is_recreated_while_all_preexisting_temps_remain_untouched() {
+    let project = TempProject::new("missing-inactive");
+    let paths = project.paths();
+    let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &lease, StatePhase::Building).unwrap();
+    publish_index_state(&paths, &lease, StatePhase::Current).unwrap();
+    std::fs::remove_file(&paths.state_slots()[0]).expect("remove inactive fixture slot");
+    assert!(matches!(classify(&paths).slot(0), SlotOutcome::Absent));
+    let orphan = paths
+        .current_root()
+        .join(".codegraph-index-state-publisher-v2-999-0000000000000001.tmp");
+    std::fs::write(&orphan, b"orphan").unwrap();
+    let orphan_directory = paths
+        .current_root()
+        .join(".codegraph-index-state-publisher-v2-998-0000000000000002.tmp");
+    std::fs::create_dir(&orphan_directory).unwrap();
+    let directory_marker = orphan_directory.join("keep.bin");
+    std::fs::write(&directory_marker, b"directory marker").unwrap();
+    let unrelated = paths
+        .current_root()
+        .join(".codegraph-index-state-publisher-v2-not-owned.tmp");
+    std::fs::write(&unrelated, b"unrelated").unwrap();
+    assert_eq!(classify(&paths).status(), &ExtractionStatus::Current);
+
+    let published = publish_index_state(&paths, &lease, StatePhase::Building).unwrap();
+    assert_eq!(published.slot, 0);
+    assert_eq!(std::fs::read(&orphan).unwrap(), b"orphan");
+    assert_eq!(
+        std::fs::read(&directory_marker).unwrap(),
+        b"directory marker"
+    );
+    assert_eq!(std::fs::read(&unrelated).unwrap(), b"unrelated");
+    assert_eq!(
+        classify(&paths).status(),
+        &ExtractionStatus::Building {
+            built: CURRENT_EXTRACTION_VERSION
+        }
+    );
+}
+
+#[test]
+fn future_or_corrupt_classification_preserves_preexisting_temp_like_entries() {
+    for case in ["future", "corrupt"] {
+        let project = TempProject::new(case);
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+        if case == "future" {
+            write_wire(
+                &paths.state_slots()[0],
+                1,
+                3,
+                3,
+                "future",
+                paths.project_identity(),
+            );
+        } else {
+            std::fs::write(&paths.state_slots()[0], b"invalid").unwrap();
+        }
+        let preexisting = paths
+            .current_root()
+            .join(".codegraph-index-state-publisher-v2-999-0000000000000001.tmp");
+        std::fs::write(&preexisting, b"preexisting").unwrap();
+
+        for requested in [
+            StatePhase::Building,
+            StatePhase::Current,
+            StatePhase::Uninitialized,
+        ] {
+            assert_rejected_without_mutation(
+                &project,
+                || publish_index_state(&paths, &lease, requested),
+                |error| matches!(error, StatePublishError::Refused { .. }),
+            );
+        }
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn temp_symlinks_and_unrelated_names_survive_successful_publication() {
+    use std::os::unix::fs::symlink;
+
+    let project = TempProject::new("temp-alias");
+    let outside = TempProject::new("temp-alias-outside");
+    let paths = project.paths();
+    let lease = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+    publish_index_state(&paths, &lease, StatePhase::Building).unwrap();
+    let target = outside.path().join("target.bin");
+    std::fs::write(&target, b"external bytes").unwrap();
+    let alias = paths
+        .current_root()
+        .join(".codegraph-index-state-publisher-v2-999-0000000000000001.tmp");
+    symlink(&target, &alias).unwrap();
+    let unrelated = paths
+        .current_root()
+        .join(".codegraph-index-state-publisher-v2-not-owned.tmp");
+    std::fs::write(&unrelated, b"unrelated").unwrap();
+
+    publish_index_state(&paths, &lease, StatePhase::Building).unwrap();
+    assert!(
+        std::fs::symlink_metadata(&alias)
+            .unwrap()
+            .file_type()
+            .is_symlink()
+    );
+    assert_eq!(std::fs::read(&target).unwrap(), b"external bytes");
+    assert_eq!(std::fs::read(&unrelated).unwrap(), b"unrelated");
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index fa95dff..4fe6e96 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1228,3 +1228,190 @@ carries no `#[ignore]`, so an exit-0 workspace run necessarily includes it: it
 passed in this authoritative run. `Cargo.lock` still hashes to
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, and the
 worktree was clean with no whitespace errors.
+
+## Batch M — lease-gated atomic state publisher (2026-07-25)
+
+### Scope and behavioral Red
+
+This slice adds only the reusable publisher for the two fixed state slots. It
+does not integrate publication into `Store`, SQLite opens/stamps, CLI, MCP,
+watch, daemon, rebuild/finalizer, migration, or uninit flows.
+
+The compiling behavioral Red used a minimal public publisher scaffold plus the
+first-publication test. After the workspace-version gate passed, the command
+`cargo test -p codegraph-store --test index_state_publisher --locked --
+--nocapture` compiled and exited 101. Its sole test reached the behavioral call
+and failed with `initial state publication must succeed: Refused { status:
+Missing }`; result: 0 passed, 1 failed. This was missing publication behavior,
+not a compile, fixture, setup, or network failure.
+
+### Accepted publisher behavior
+
+- `publish_index_state` requires the exact `IndexLease` capability and calls
+  `validate_exclusive(paths)` before classification or mutation. Shared and
+  wrong-parent leases return typed validation errors; full-tree fail-closed
+  snapshots prove every directory, regular-file byte, and symlink target stays
+  unchanged.
+- The publisher immediately consumes the accepted `classify(paths)` result under
+  that lease. `Future` and every `Corrupt` case (malformed fixed slot, owner
+  mismatch, equal sequence, and `u64::MAX` exhaustion included) return typed
+  `Refused` before orphan cleanup or temp creation. It does not reimplement or
+  weaken classifier precedence.
+- A genuinely slot-absent namespace writes sequence 0 to fixed slot 0. Later
+  publications use checked `sequence + 1` and only the opposite, older or
+  missing inactive slot. The authoritative slot's complete bytes are preserved.
+  A typed `WireState` serializes the exact field order
+  `sequence,storageProtocol,extractionVersion,phase,projectIdentity,checksum`;
+  the first-publication test asserts the complete canonical JSON bytes and
+  checksum.
+- Temps are same-directory, publisher-owned names and are opened with bounded
+  `create_new(true)` retries. The publisher writes all bytes, flushes, calls
+  `sync_all`, removes only an older regular inactive slot when present, renames
+  the valid temp into that slot, and attempts parent-directory `sync_all`.
+  Explicit OS error sets report unsupported directory sync as
+  `ParentSyncStatus::Unsupported`; other failures remain typed I/O errors.
+- Orphan cleanup starts only after exact exclusive-lease validation and an
+  acceptable under-lease classification. It recognizes only the strict v2
+  publisher name grammar, validates regular-file identity before removal, and
+  leaves static aliases, non-regular entries, and unrelated names untouched.
+  Classifier scanning still reads only `IndexPaths::state_slots()`.
+
+### Deterministic fault and protocol matrix
+
+The private fault seam is inaccessible to normal callers. It injects after
+create, full write, flush, file `sync_all`, inactive delete/prepare, rename, and
+parent-sync attempt. The matrix covers all 3×3 prior/new phase pairs and all
+seven checkpoints (63 successor interruptions), plus all three initial phases at
+all seven checkpoints (21 initial interruptions). Before rename, classification
+is exactly the old authority (or `Missing` initially); after rename it is exactly
+the fully checksummed successor. The old authoritative slot's complete bytes
+remain unchanged at every successor checkpoint. This includes the explicit
+`building -> uninitialized` interrupted-uninit path. A separate deterministic
+checkpoint covers orphan-temp removal.
+
+Public tests additionally cover monotonic
+`building -> current -> uninitialized`, both-slot older replacement, missing
+inactive-slot recreation, malformed inactive refusal, equal-sequence refusal,
+owner mismatch, sequence exhaustion, strict temp names, regular orphan cleanup,
+and Unix temp-symlink non-following. A v3 future-protocol slot at a higher
+sequence than its v2 current companion still dominates and is byte-nonmutating;
+the v2 publisher cannot author arbitrary future records.
+
+### Green and platform evidence before the terminal gate
+
+Every Cargo batch was preceded by `bash scripts/check-workspace-versions.sh`:
+
+- Publisher integration tests: 9 passed, 0 failed.
+- Private deterministic publisher tests: 4 passed, 0 failed (including the 84
+  phase/checkpoint interruptions described above).
+- Accepted classifier tests: 20 passed, 0 failed; accepted lease integration
+  tests: 12 passed, 0 failed.
+- `cargo check -p codegraph-store --all-targets --locked` passed.
+- `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings`
+  passed after correcting two lint-only findings.
+- `LIBSQLITE3_SYS_USE_PKG_CONFIG=1 SQLITE3_LIB_DIR=/tmp/opencode cargo check -p
+codegraph-store --target x86_64-pc-windows-msvc --all-targets --locked`
+  passed. This is Linux-host MSVC compilation only; native Windows runtime/crash
+  behavior is not claimed.
+- LSP diagnostics again refused this external `/tmp` worktree as outside the
+  request cwd. The targeted tests, package check, Clippy, and MSVC compilation
+  above are the diagnostics fallback.
+- `Cargo.lock` remained required at
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+These are the final documentation bytes for this publisher slice. Per the
+stale-documentation trap, they are formatted first; the authoritative terminal
+gate is then exactly `bash scripts/check-workspace-versions.sh && make ci &&
+sha256sum Cargo.lock && git diff --check`, with `CARGO='cargo --locked'` supplied
+to `make ci`. The scoped commit is created only if that post-documentation
+command chain exits 0, so no later evidence edit can invalidate it.
+
+### First terminal-gate attempt
+
+The first post-format terminal chain reached the full workspace tests after
+clean workspace-version, formatting, and Clippy gates, then failed only in the
+known timing-sensitive `daemon_single_watcher_fires_once` test: its first sync
+reported `0 file(s) reindexed` instead of naming the changed file. No publisher,
+classifier, or lease test failed. This failed attempt remains recorded; exactly
+one post-append, post-format retry remains under the two-check ceiling.
+
+## Correction (2026-07-25): rejected publisher protocol defects
+
+The publisher slice above was rejected by manual review despite its focused
+tests passing. This append supersedes, but does not erase, the earlier 3×3
+transition and orphan-cleanup claims. The correction remains publisher/lease
+only: it does not begin `Store`, SQLite, CLI, MCP, watch, daemon,
+rebuild/finalizer, migration, uninit, or Batches A–E integration.
+
+### Corrected protocol boundaries
+
+- One pure transition validator now admits exactly `Missing -> Building`,
+  `Outdated -> Building`, `Uninitialized -> Building`,
+  `Current -> Building|Uninitialized`, and
+  `Building -> Building|Current|Uninitialized`. Every other current-protocol
+  status/phase pair returns typed `StatePublishError::InvalidTransition` with a
+  cloned `ExtractionStatus` and requested `StatePhase`, before temp creation or
+  fixed-slot mutation. A unit matrix covers all three requested phases for
+  `Missing`, `Outdated`, `Uninitialized`, `Current`, `Building`, `Future`, and
+  `Corrupt`. `Future` and `Corrupt` still take the earlier typed `Refused` path,
+  preserving accepted classifier precedence. Initial slot 0 / sequence 0
+  publication is therefore possible only for `Missing -> Building`.
+- The successor fault matrix is no longer the unsafe 3×3 cross-product. It
+  covers every allowed successor transition at the seven retained checkpoints:
+  temp create, full write, flush, file sync, inactive-slot preparation, rename,
+  and parent-sync attempt. `Building -> Uninitialized` remains explicit. The
+  initial matrix covers only `Missing -> Building`. Successor slot and sequence
+  continue to derive solely from the accepted classifier authority, and every
+  pre-rename fault preserves the old authoritative bytes.
+- `IndexLease` now privately retains the fixed permanent-lock path. Writer
+  validation order is mode, exact DB parent, then
+  `file_identity::path_still_names_file`: the fixed path must still name the
+  exact held handle immediately before publisher classification. Replacement,
+  disappearance, aliasing, non-regular replacement, or identity-check I/O
+  failure maps to typed `PermanentLockChanged { path }`, without exposing
+  platform identities. The public replacement regression snapshots the full
+  tree around rejection and then proves a fresh lease can acquire the new fixed
+  lock; missing, directory, and Unix alias regressions pin the same pre-mutation
+  failure. Shared and wrong-parent precedence remains unchanged.
+- Automatic orphan-temp cleanup is removed completely, including its name
+  recognizer, directory scan, path unlink, and removal fault checkpoint. The
+  prior verify-handle-then-`remove_file(path)` design had an unavoidable
+  verify-to-unlink race: portable `std` supplies no atomic conditional unlink
+  that removes a path only if it still identifies the verified handle. Keeping
+  that cleanup could delete a replacement object, so the safe portable behavior
+  is to leave every preexisting temp-like entry untouched. Generated temp names
+  remain internal, bounded, collision-safe through `create_new(true)`, and
+  outside fixed-slot scanning. Successful-publication tests preserve a regular
+  orphan-like file, a directory and marker, an unrelated temp-like file, and on
+  Unix a symlink plus its external target bytes.
+
+### Focused verification before the final terminal gate
+
+Every Cargo batch below was preceded by
+`bash scripts/check-workspace-versions.sh`, and every Cargo command used
+`--locked`:
+
+- Publisher integration: 14 passed, 0 failed; store unit tests: 66 passed, 0
+  failed, including the exhaustive transition validator and both fault
+  matrices.
+- Lease integration: 12 passed, 0 failed; classifier integration: 20 passed, 0
+  failed.
+- `cargo check -p codegraph-store --all-targets --locked`: clean.
+- `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings`:
+  clean.
+- `LIBSQLITE3_SYS_USE_PKG_CONFIG=1 SQLITE3_LIB_DIR=/tmp/opencode cargo check -p
+codegraph-store --target x86_64-pc-windows-msvc --all-targets --locked`:
+  clean. This is Linux-host cross-compilation only, not native Windows runtime
+  or crash evidence.
+- LSP again rejected the external `/tmp` worktree as outside its request cwd;
+  the clean targeted Cargo diagnostics are the accepted fallback.
+
+Two earlier terminal failures remain recorded honestly. The first publisher
+gate failed in the unrelated timing-sensitive
+`daemon_single_watcher_fires_once` test (`0 file(s) reindexed`). A later parent
+retry failed in the unrelated MCP tools-list expectation: expected 4 tools but
+observed 2. Neither failure is represented as Green or weakened. After these
+final ledger/notepad bytes, the mandatory closing order is `make fmt`, then one
+fresh `bash scripts/check-workspace-versions.sh && make ci`, then the exact
+`Cargo.lock` SHA-256 check and scoped status/diff inspection. No final Green is
+claimed in this entry before that post-documentation gate actually passes.

From a600c805154a109479d6c91b4ce15413def7c8c5 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 20:15:03 +0800
Subject: [PATCH 19/91] feat(store): add state-gated Store opens

---
 crates/codegraph-store/src/connection.rs      |  539 ++++++++-
 crates/codegraph-store/src/index_state.rs     |    8 +-
 crates/codegraph-store/src/lib.rs             |    5 +-
 .../tests/store_state_gates.rs                | 1042 +++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |   78 ++
 5 files changed, 1666 insertions(+), 6 deletions(-)
 create mode 100644 crates/codegraph-store/tests/store_state_gates.rs

diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index 764281f..d59ecae 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -1,8 +1,134 @@
 use std::path::{Path, PathBuf};
+use std::time::Instant;
 
-use rusqlite::Connection;
+use codegraph_core::IndexPaths;
+use rusqlite::{Connection, OpenFlags, OptionalExtension};
 
 use crate::migrations;
+use crate::{
+    CURRENT_EXTRACTION_VERSION, EXTRACTION_VERSION_KEY, ExtractionStatus, IndexLease,
+    IndexLeaseError, IndexLeaseValidationError, classify,
+};
+
+/// Why a `Current` state slot could not be corroborated against the SQLite
+/// extraction stamp.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ExtractionStampIssue {
+    /// The store-owned metadata key is absent.
+    Missing,
+    /// The stored value is not a canonical decimal `u64`.
+    Malformed { found: String },
+    /// The stored decimal version differs from this binary's version.
+    Mismatch { expected: u64, found: u64 },
+}
+
+impl std::fmt::Display for ExtractionStampIssue {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Missing => write!(
+                formatter,
+                "metadata key {EXTRACTION_VERSION_KEY:?} is missing"
+            ),
+            Self::Malformed { found } => write!(
+                formatter,
+                "metadata key {EXTRACTION_VERSION_KEY:?} is not a decimal extraction version: {found:?}"
+            ),
+            Self::Mismatch { expected, found } => write!(
+                formatter,
+                "metadata key {EXTRACTION_VERSION_KEY:?} records extraction version {found}, expected {expected}"
+            ),
+        }
+    }
+}
+
+/// Explicit authorization requested from [`Store::open_for_write`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StoreWritePurpose {
+    /// Mutate an already-current, corroborated database.
+    CurrentMutation,
+    /// Retain exclusive authority for a later destructive full rebuild or
+    /// explicit init recovery. This slice does not perform that rebuild.
+    FullRebuild,
+    /// Retain exclusive authority for a later interrupted-uninit continuation.
+    UninitContinuation,
+}
+
+impl std::fmt::Display for StoreWritePurpose {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(match self {
+            Self::CurrentMutation => "current mutation",
+            Self::FullRebuild => "full rebuild",
+            Self::UninitContinuation => "uninit continuation",
+        })
+    }
+}
+
+/// Opaque exclusive capability returned when state requires a later lifecycle
+/// operation rather than an immediate SQLite open.
+#[derive(Debug)]
+pub struct StoreWriteAuthorization {
+    pub(crate) status: ExtractionStatus,
+    pub(crate) purpose: StoreWritePurpose,
+    pub(crate) lease: IndexLease,
+}
+
+impl StoreWriteAuthorization {
+    /// The under-lease state that authorized this lifecycle operation.
+    #[must_use]
+    pub fn status(&self) -> &ExtractionStatus {
+        &self.status
+    }
+
+    /// The narrow lifecycle purpose this capability authorizes.
+    #[must_use]
+    pub fn purpose(&self) -> StoreWritePurpose {
+        self.purpose
+    }
+
+    /// Whether the opaque authorization still owns an exclusive lease.
+    #[must_use]
+    pub fn retains_exclusive_lease(&self) -> bool {
+        self.lease.is_exclusive()
+    }
+}
+
+/// Result of a state-gated writer open.
+#[derive(Debug)]
+pub enum StoreWriteOpen {
+    /// A corroborated Current database is open for ordinary mutation.
+    Current(Box<Store>),
+    /// SQLite was not opened; a later full-rebuild API must consume this opaque
+    /// authorization while its exclusive lease remains alive.
+    FullRebuildRequired(StoreWriteAuthorization),
+    /// SQLite was not opened; a later uninit-continuation API must consume this
+    /// opaque authorization while its exclusive lease remains alive.
+    UninitContinuation(StoreWriteAuthorization),
+}
+
+/// Typed status probe returned by [`Store::open_for_status`].
+#[derive(Debug)]
+pub struct StoreStatusOpen {
+    /// Stable state observed under a shared lease. `None` means an exclusive
+    /// holder prevented a stable observation before the bounded deadline.
+    pub status: Option<ExtractionStatus>,
+    /// `true` only when shared acquisition timed out behind a writer.
+    pub rebuilding: bool,
+    store: Option<Store>,
+}
+
+impl StoreStatusOpen {
+    /// The retained read-only Store used to corroborate a Current state.
+    #[must_use]
+    pub fn store(&self) -> Option<&Store> {
+        self.store.as_ref()
+    }
+
+    /// Consume this probe and return its retained read-only Store, if Current.
+    #[must_use]
+    pub fn into_store(self) -> Option<Store> {
+        self.store
+    }
+}
 
 #[derive(Debug, thiserror::Error)]
 pub enum StoreError {
@@ -30,13 +156,74 @@ pub enum StoreError {
         #[source]
         source: rusqlite::Error,
     },
+    #[error(transparent)]
+    Lease(#[from] IndexLeaseError),
+    #[error(transparent)]
+    LeaseValidation(#[from] IndexLeaseValidationError),
+    #[error("state-gated Store open rejected index state {status}")]
+    StateRejected { status: ExtractionStatus },
+    #[error("{purpose} is not authorized for index state {status}")]
+    WritePurposeRejected {
+        purpose: StoreWritePurpose,
+        status: ExtractionStatus,
+    },
+    #[error("state is missing but a database artifact already exists at {path}")]
+    MissingStateWithDatabase { path: PathBuf },
+    #[error("Current index state is blocked by the uninitialized tombstone at {path}")]
+    CurrentTombstoned { path: PathBuf },
+    #[error("failed to inspect database artifact {path}: {source}")]
+    InspectArtifact {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("failed to read extraction stamp from SQLite database {path}: {source}")]
+    ReadExtractionStamp {
+        path: PathBuf,
+        #[source]
+        source: rusqlite::Error,
+    },
+    #[error("failed to read SQLite database bytes from {path}: {source}")]
+    ReadDatabase {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("SQLite database {path} has an invalid extraction stamp: {issue}")]
+    InvalidExtractionStamp {
+        path: PathBuf,
+        issue: ExtractionStampIssue,
+    },
+    #[error("only a state-gated write Store may stamp the extraction version")]
+    StampNotAuthorized,
+    #[error("failed to stamp extraction version in SQLite database {path}: {source}")]
+    StampExtractionVersion {
+        path: PathBuf,
+        #[source]
+        source: rusqlite::Error,
+    },
 }
 
 pub type Result<T> = std::result::Result<T, StoreError>;
 
+#[derive(Debug)]
 pub struct Store {
+    // Field order is protocol behavior: Rust drops fields in declaration order,
+    // so both SQLite connections close before the final retained lease owner
+    // can unlock.
     pub(crate) conn: Connection,
+    _source_conn: Option<Connection>,
     path: PathBuf,
+    access: StoreAccess,
+    guarded_paths: Option<IndexPaths>,
+    lease: Option<IndexLease>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum StoreAccess {
+    Legacy,
+    StateRead,
+    StateWrite,
 }
 
 impl Store {
@@ -74,7 +261,175 @@ impl Store {
 
         Ok(Self {
             conn,
+            _source_conn: None,
             path: db_path.to_path_buf(),
+            access: StoreAccess::Legacy,
+            guarded_paths: None,
+            lease: None,
+        })
+    }
+
+    /// Classify only the two fixed state slots. This never opens SQLite and
+    /// never creates or mutates a filesystem entry.
+    #[must_use]
+    pub fn extraction_status(paths: &IndexPaths) -> ExtractionStatus {
+        classify(paths).status().clone()
+    }
+
+    /// Acquire and retain a bounded shared lease, require Current state, and
+    /// corroborate the existing database through a read-only/no-create SQLite
+    /// handle and the exact current extraction stamp.
+    pub fn open_for_read(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self> {
+        let lease = IndexLease::acquire_shared_existing(paths, deadline, cancelled)?;
+        let status = Self::extraction_status(paths);
+        if status != ExtractionStatus::Current {
+            return Err(StoreError::StateRejected { status });
+        }
+        open_current_read_only(paths, lease)
+    }
+
+    /// Probe status under a short shared lease. Contention is status data rather
+    /// than an error and never opens SQLite. Non-Current states are reported
+    /// without SQLite; Current is corroborated through [`Self::open_for_read`]'s
+    /// exact read-only path while retaining the same acquired lease.
+    pub fn open_for_status(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<StoreStatusOpen> {
+        let lease = match IndexLease::acquire_shared_existing(paths, deadline, cancelled) {
+            Ok(lease) => lease,
+            Err(IndexLeaseError::TimedOut { .. }) => {
+                return Ok(StoreStatusOpen {
+                    status: None,
+                    rebuilding: true,
+                    store: None,
+                });
+            }
+            Err(IndexLeaseError::LockNotFound { .. }) => {
+                let status = Self::extraction_status(paths);
+                if status == ExtractionStatus::Missing {
+                    return Ok(StoreStatusOpen {
+                        status: Some(status),
+                        rebuilding: false,
+                        store: None,
+                    });
+                }
+                return Err(StoreError::Lease(IndexLeaseError::LockNotFound {
+                    path: paths.permanent_lock(),
+                }));
+            }
+            Err(error) => return Err(StoreError::Lease(error)),
+        };
+
+        let status = Self::extraction_status(paths);
+        let store = if status == ExtractionStatus::Current {
+            Some(open_current_read_only(paths, lease)?)
+        } else {
+            drop(lease);
+            None
+        };
+        Ok(StoreStatusOpen {
+            status: Some(status),
+            rebuilding: false,
+            store,
+        })
+    }
+
+    /// Validate one already-held exclusive lease immediately, classify under
+    /// it, and either open a corroborated Current DB or return an opaque,
+    /// lease-retaining authorization for a later lifecycle operation.
+    pub fn open_for_write(
+        paths: &IndexPaths,
+        lease: IndexLease,
+        purpose: StoreWritePurpose,
+    ) -> Result<StoreWriteOpen> {
+        lease.validate_exclusive(paths)?;
+        let status = Self::extraction_status(paths);
+
+        if matches!(
+            status,
+            ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. }
+        ) {
+            return Err(StoreError::StateRejected { status });
+        }
+        if status == ExtractionStatus::Missing
+            && let Some(path) = first_existing_database_artifact(paths)?
+        {
+            return Err(StoreError::MissingStateWithDatabase { path });
+        }
+
+        match purpose {
+            StoreWritePurpose::CurrentMutation if status == ExtractionStatus::Current => {
+                // Corroborate through a separate read-only/no-create handle before
+                // any write-capable setup can alter pragmas or sidecars.
+                let (corroboration, source_conn) = corroborate_current_database(paths)?;
+                drop(corroboration);
+                drop(source_conn);
+                let db_path = paths.current_db();
+                let conn = Connection::open_with_flags(&db_path, OpenFlags::SQLITE_OPEN_READ_WRITE)
+                    .map_err(|source| StoreError::Open {
+                        path: db_path.clone(),
+                        source,
+                    })?;
+                configure_connection(&conn).map_err(|source| StoreError::Configure {
+                    path: db_path.clone(),
+                    source,
+                })?;
+                Ok(StoreWriteOpen::Current(Box::new(Self {
+                    conn,
+                    _source_conn: None,
+                    path: db_path,
+                    access: StoreAccess::StateWrite,
+                    guarded_paths: Some(paths.clone()),
+                    lease: Some(lease),
+                })))
+            }
+            StoreWritePurpose::FullRebuild => Ok(StoreWriteOpen::FullRebuildRequired(
+                StoreWriteAuthorization {
+                    status,
+                    purpose,
+                    lease,
+                },
+            )),
+            StoreWritePurpose::UninitContinuation if status == ExtractionStatus::Uninitialized => {
+                Ok(StoreWriteOpen::UninitContinuation(
+                    StoreWriteAuthorization {
+                        status,
+                        purpose,
+                        lease,
+                    },
+                ))
+            }
+            _ => Err(StoreError::WritePurposeRejected { purpose, status }),
+        }
+    }
+
+    /// Write the store-owned extraction metadata key and exact current decimal
+    /// value. Read/status/legacy Stores are rejected before SQL execution.
+    pub fn stamp_extraction_version(&self) -> Result<usize> {
+        if self.access != StoreAccess::StateWrite || self.lease.is_none() {
+            return Err(StoreError::StampNotAuthorized);
+        }
+        let paths = self
+            .guarded_paths
+            .as_ref()
+            .expect("state-gated write Store always retains its IndexPaths");
+        self.lease
+            .as_ref()
+            .expect("state-gated write Store always retains its lease")
+            .validate_exclusive(paths)?;
+        self.set_project_metadata(
+            EXTRACTION_VERSION_KEY,
+            &CURRENT_EXTRACTION_VERSION.to_string(),
+        )
+        .map_err(|source| StoreError::StampExtractionVersion {
+            path: self.path.clone(),
+            source,
         })
     }
 
@@ -91,6 +446,188 @@ impl Store {
     }
 }
 
+fn open_current_read_only(paths: &IndexPaths, lease: IndexLease) -> Result<Store> {
+    let (conn, source_conn) = corroborate_current_database(paths)?;
+    Ok(Store {
+        conn,
+        _source_conn: Some(source_conn),
+        path: paths.current_db(),
+        access: StoreAccess::StateRead,
+        guarded_paths: Some(paths.clone()),
+        lease: Some(lease),
+    })
+}
+
+fn corroborate_current_database(paths: &IndexPaths) -> Result<(Connection, Connection)> {
+    let db_path = paths.current_db();
+    if artifact_exists(&paths.tombstone())? {
+        return Err(StoreError::CurrentTombstoned {
+            path: paths.tombstone(),
+        });
+    }
+    let (conn, source_conn) = open_read_only_without_sidecars(&db_path)?;
+    let stamp = conn
+        .query_row(
+            "SELECT value FROM project_metadata WHERE key = ?1",
+            [EXTRACTION_VERSION_KEY],
+            |row| row.get::<_, String>(0),
+        )
+        .optional()
+        .map_err(|source| StoreError::ReadExtractionStamp {
+            path: db_path.clone(),
+            source,
+        })?;
+    validate_extraction_stamp(&db_path, stamp)?;
+    Ok((conn, source_conn))
+}
+
+fn open_read_only_without_sidecars(db_path: &Path) -> Result<(Connection, Connection)> {
+    // Opening an existing WAL-mode DB read-only is not enough to prevent SQLite
+    // from creating `-wal`/`-shm` on the first query. Open the real path with
+    // exactly READ_ONLY/no-create flags, then deserialize the already-checkpointed
+    // main-DB bytes into a separate in-memory SQLite handle before executing SQL.
+    // SQLite therefore performs the stamp query over a READONLY deserialized
+    // image and never enters the file pager path that authors sidecars. The outer
+    // shared IndexLease keeps the authoritative DB stable for the Store's whole
+    // life, and the READ_ONLY source connection remains retained beside it.
+    // Open the existing path with the required READ_ONLY/no-create flags before
+    // constructing the sidecar-free query handle. This validates SQLite's own
+    // file-open contract without executing a pager query that could create WAL
+    // sidecars; that source connection is retained unchanged for the Store's
+    // lifetime.
+    let source_conn = Connection::open_with_flags(db_path, OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .map_err(|source| StoreError::Open {
+            path: db_path.to_path_buf(),
+            source,
+        })?;
+    let bytes = std::fs::read(db_path).map_err(|source| StoreError::ReadDatabase {
+        path: db_path.to_path_buf(),
+        source,
+    })?;
+    let mut conn = Connection::open_in_memory().map_err(|source| StoreError::Open {
+        path: db_path.to_path_buf(),
+        source,
+    })?;
+    deserialize_read_only(&mut conn, &bytes).map_err(|source| StoreError::Open {
+        path: db_path.to_path_buf(),
+        source,
+    })?;
+    Ok((conn, source_conn))
+}
+
+fn deserialize_read_only(conn: &mut Connection, bytes: &[u8]) -> rusqlite::Result<()> {
+    use std::ptr::NonNull;
+
+    let size = u64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?;
+    // SAFETY: sqlite3_malloc64 returns an allocation suitable for
+    // SQLITE_DESERIALIZE_FREEONCLOSE. The byte copy uses the exact allocation
+    // length. Once sqlite3_deserialize is called, SQLite owns and frees the
+    // allocation both on success and on failure.
+    let allocation = unsafe { rusqlite::ffi::sqlite3_malloc64(size) };
+    let allocation = NonNull::new(allocation.cast::<u8>()).ok_or_else(|| {
+        rusqlite::Error::SqliteFailure(rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_NOMEM), None)
+    })?;
+    // SAFETY: allocation is valid for `bytes.len()` bytes and non-overlapping
+    // with the borrowed source slice.
+    unsafe {
+        std::ptr::copy_nonoverlapping(bytes.as_ptr(), allocation.as_ptr(), bytes.len());
+    }
+    if bytes.len() >= 20 && bytes.starts_with(b"SQLite format 3\0") {
+        // A clean checkpointed WAL database still records WAL read/write format
+        // bytes (2) in its main-file header. The deserialized image has no WAL
+        // sidecar by design, so normalize only this private in-memory copy to
+        // rollback format (1) before SQLite reads it. Disk bytes remain exact.
+        // SAFETY: the allocation has `bytes.len() >= 20` writable bytes here.
+        unsafe {
+            allocation.as_ptr().add(18).write(1);
+            allocation.as_ptr().add(19).write(1);
+        }
+    }
+    let schema = c"main";
+    // SAFETY: `conn.handle()` is live for this call; allocation and lengths meet
+    // sqlite3_deserialize's contract. READONLY forbids image mutation and
+    // FREEONCLOSE transfers allocation ownership to SQLite on success.
+    let result = unsafe {
+        rusqlite::ffi::sqlite3_deserialize(
+            conn.handle(),
+            schema.as_ptr(),
+            allocation.as_ptr(),
+            i64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?,
+            i64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?,
+            rusqlite::ffi::SQLITE_DESERIALIZE_FREEONCLOSE
+                | rusqlite::ffi::SQLITE_DESERIALIZE_READONLY,
+        )
+    };
+    if result != rusqlite::ffi::SQLITE_OK {
+        // FREEONCLOSE also requires SQLite to free the buffer before returning
+        // from a failed sqlite3_deserialize call; do not free it a second time.
+        return Err(rusqlite::Error::SqliteFailure(
+            rusqlite::ffi::Error::new(result),
+            None,
+        ));
+    }
+    Ok(())
+}
+
+fn validate_extraction_stamp(db_path: &Path, stamp: Option<String>) -> Result<()> {
+    let Some(stamp) = stamp else {
+        return Err(StoreError::InvalidExtractionStamp {
+            path: db_path.to_path_buf(),
+            issue: ExtractionStampIssue::Missing,
+        });
+    };
+    let built = stamp
+        .parse::<u64>()
+        .map_err(|_| StoreError::InvalidExtractionStamp {
+            path: db_path.to_path_buf(),
+            issue: ExtractionStampIssue::Malformed {
+                found: stamp.clone(),
+            },
+        })?;
+    if built.to_string() != stamp {
+        return Err(StoreError::InvalidExtractionStamp {
+            path: db_path.to_path_buf(),
+            issue: ExtractionStampIssue::Malformed { found: stamp },
+        });
+    }
+    if built != CURRENT_EXTRACTION_VERSION {
+        return Err(StoreError::InvalidExtractionStamp {
+            path: db_path.to_path_buf(),
+            issue: ExtractionStampIssue::Mismatch {
+                expected: CURRENT_EXTRACTION_VERSION,
+                found: built,
+            },
+        });
+    }
+    Ok(())
+}
+
+fn first_existing_database_artifact(paths: &IndexPaths) -> Result<Option<PathBuf>> {
+    let db = paths.current_db();
+    let mut artifacts = vec![db.clone()];
+    artifacts.push(PathBuf::from(format!("{}-wal", db.display())));
+    artifacts.push(PathBuf::from(format!("{}-shm", db.display())));
+    for path in artifacts {
+        match std::fs::symlink_metadata(&path) {
+            Ok(_) => return Ok(Some(path)),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(source) => return Err(StoreError::InspectArtifact { path, source }),
+        }
+    }
+    Ok(None)
+}
+
+fn artifact_exists(path: &Path) -> Result<bool> {
+    match std::fs::symlink_metadata(path) {
+        Ok(_) => Ok(true),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+        Err(source) => Err(StoreError::InspectArtifact {
+            path: path.to_path_buf(),
+            source,
+        }),
+    }
+}
+
 fn configure_connection(conn: &Connection) -> rusqlite::Result<()> {
     // Order mirrors the upstream configureConnection exactly. busy_timeout must be
     // first so later file-touching pragmas wait instead of immediately failing.
diff --git a/crates/codegraph-store/src/index_state.rs b/crates/codegraph-store/src/index_state.rs
index aba5c6a..cf35083 100644
--- a/crates/codegraph-store/src/index_state.rs
+++ b/crates/codegraph-store/src/index_state.rs
@@ -19,10 +19,10 @@
 //! - publication lives in the separate `index_state_publisher` module and
 //!   consumes this classifier without weakening its aggregate ordering. This
 //!   classifier itself remains strictly read-only;
-//! - `Store::open_for_read` / `open_for_status` / `open_for_write`,
-//!   `Store::stamp_extraction_version`, DB-stamp corroboration, migration mode,
-//!   uninit lifecycle, and the daemon/watcher lifecycle all land in LATER Batch M
-//!   slices and are NOT implemented here.
+//! - `Store::open_for_read` / `open_for_status` / `open_for_write` and
+//!   `Store::stamp_extraction_version` consume this classifier without changing
+//!   it. Migration mode, uninit lifecycle, and the daemon/watcher lifecycle land
+//!   in later Batch M slices.
 //!
 //! This classifier boundary is narrower than the commit series containing it:
 //! existing CLI indexing still writes `project_metadata`, but now takes that
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index 33edd8f..9989501 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -7,7 +7,10 @@ pub mod migrations;
 pub mod queries;
 pub mod schema;
 
-pub use connection::Store;
+pub use connection::{
+    ExtractionStampIssue, Store, StoreError, StoreStatusOpen, StoreWriteAuthorization,
+    StoreWriteOpen, StoreWritePurpose,
+};
 pub use index_lease::{IndexLease, IndexLeaseError, IndexLeaseValidationError};
 pub use index_state::{
     AuthoritativeSlot, CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, CorruptReason,
diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
new file mode 100644
index 0000000..3891112
--- /dev/null
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -0,0 +1,1042 @@
+//! Public contract for lease-retaining, state-gated Store opens.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::io::{BufRead, BufReader, Read, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, Command, Stdio};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::mpsc::{self, Receiver};
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, EXTRACTION_VERSION_KEY,
+    ExtractionStampIssue, ExtractionStatus, IndexLease, IndexLeaseValidationError, Store,
+    StoreError, StoreWriteOpen, StoreWritePurpose, checksum_hex,
+};
+use serde_json::json;
+
+const CHILD_ACTION: &str = "CODEGRAPH_STORE_GATE_CHILD_ACTION";
+const CHILD_PROJECT: &str = "CODEGRAPH_STORE_GATE_CHILD_PROJECT";
+const CHILD_WAIT: Duration = Duration::from_secs(5);
+const SHORT_DEADLINE: Duration = Duration::from_millis(80);
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+struct TempProject(PathBuf);
+
+impl TempProject {
+    fn new(label: &str) -> Self {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-store-state-gates-{label}-{}-{serial}",
+            std::process::id()
+        ));
+        std::fs::create_dir(&path)
+            .unwrap_or_else(|error| panic!("create temp project {}: {error}", path.display()));
+        Self(path.canonicalize().expect("canonical temp project"))
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(self.path(), None).expect("resolve Store test paths")
+    }
+}
+
+impl Drop for TempProject {
+    fn drop(&mut self) {
+        std::fs::remove_dir_all(&self.0)
+            .unwrap_or_else(|error| panic!("remove temp project {}: {error}", self.0.display()));
+    }
+}
+
+fn deadline_after(duration: Duration) -> Instant {
+    Instant::now()
+        .checked_add(duration)
+        .expect("Store test deadline")
+}
+
+fn deadline() -> Instant {
+    deadline_after(CHILD_WAIT)
+}
+
+fn create_namespace(paths: &IndexPaths) -> IndexLease {
+    IndexLease::create_exclusive(paths, deadline(), || false)
+        .expect("create permanent Store test namespace")
+}
+
+fn wire_bytes(
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+    owner: &str,
+) -> Vec<u8> {
+    serde_json::to_vec(&json!({
+        "sequence": sequence,
+        "storageProtocol": storage_protocol,
+        "extractionVersion": extraction_version,
+        "phase": phase,
+        "projectIdentity": owner,
+        "checksum": checksum_hex(
+            sequence,
+            storage_protocol,
+            extraction_version,
+            phase,
+            owner,
+        ),
+    }))
+    .expect("serialize Store state fixture")
+}
+
+fn write_state(paths: &IndexPaths, storage_protocol: u64, extraction_version: u64, phase: &str) {
+    std::fs::write(
+        &paths.state_slots()[0],
+        wire_bytes(
+            1,
+            storage_protocol,
+            extraction_version,
+            phase,
+            paths.project_identity(),
+        ),
+    )
+    .expect("write Store state fixture");
+}
+
+fn create_database(paths: &IndexPaths, stamp: Option<&str>) {
+    let store = Store::open(&paths.current_db()).expect("create Store SQLite fixture");
+    if let Some(stamp) = stamp {
+        store
+            .set_project_metadata(EXTRACTION_VERSION_KEY, stamp)
+            .expect("write extraction stamp fixture");
+    }
+    store
+        .restore_default_pragmas()
+        .expect("checkpoint Store SQLite fixture");
+    drop(store);
+    remove_sidecars(paths);
+}
+
+fn remove_sidecars(paths: &IndexPaths) {
+    let db = paths.current_db();
+    for path in [
+        PathBuf::from(format!("{}-wal", db.display())),
+        PathBuf::from(format!("{}-shm", db.display())),
+    ] {
+        match std::fs::remove_file(&path) {
+            Ok(()) => {}
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => panic!("remove fixture sidecar {}: {error}", path.display()),
+        }
+    }
+}
+
+fn stage_current(project: &TempProject, stamp: Option<&str>) -> IndexPaths {
+    let paths = project.paths();
+    let lease = create_namespace(&paths);
+    create_database(&paths, stamp);
+    write_state(
+        &paths,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        "current",
+    );
+    drop(lease);
+    paths
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum FixtureStatus {
+    Missing,
+    Building,
+    Uninitialized,
+    Outdated,
+    Future,
+    Corrupt,
+}
+
+fn stage_non_current(paths: &IndexPaths, status: FixtureStatus, trap_db: bool) {
+    let lease = create_namespace(paths);
+    match status {
+        FixtureStatus::Missing => {}
+        FixtureStatus::Building => write_state(
+            paths,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION,
+            "building",
+        ),
+        FixtureStatus::Uninitialized => write_state(
+            paths,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION,
+            "uninitialized",
+        ),
+        FixtureStatus::Outdated => write_state(
+            paths,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION - 1,
+            "current",
+        ),
+        FixtureStatus::Future => write_state(
+            paths,
+            CURRENT_STORAGE_PROTOCOL + 1,
+            CURRENT_EXTRACTION_VERSION + 1,
+            "future-phase",
+        ),
+        FixtureStatus::Corrupt => {
+            std::fs::write(&paths.state_slots()[0], b"not-json").expect("write corrupt state")
+        }
+    }
+    if trap_db {
+        std::fs::write(
+            paths.current_db(),
+            b"not SQLite; opening this trap is a bug",
+        )
+        .expect("write non-SQLite trap DB");
+    }
+    drop(lease);
+}
+
+fn expected_status(status: FixtureStatus) -> ExtractionStatus {
+    match status {
+        FixtureStatus::Missing => ExtractionStatus::Missing,
+        FixtureStatus::Building => ExtractionStatus::Building {
+            built: CURRENT_EXTRACTION_VERSION,
+        },
+        FixtureStatus::Uninitialized => ExtractionStatus::Uninitialized,
+        FixtureStatus::Outdated => ExtractionStatus::Outdated {
+            built: CURRENT_EXTRACTION_VERSION - 1,
+        },
+        FixtureStatus::Future => ExtractionStatus::Future {
+            built: CURRENT_EXTRACTION_VERSION + 1,
+        },
+        FixtureStatus::Corrupt => {
+            panic!("Corrupt fixtures carry a typed reason and compare by variant")
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum SnapshotKind {
+    Directory,
+    File(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
+    fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, SnapshotKind>) {
+        let mut paths = std::fs::read_dir(directory)
+            .unwrap_or_else(|error| panic!("snapshot read_dir {}: {error}", directory.display()))
+            .map(|entry| {
+                entry
+                    .unwrap_or_else(|error| {
+                        panic!("snapshot entry in {}: {error}", directory.display())
+                    })
+                    .path()
+            })
+            .collect::<Vec<_>>();
+        paths.sort();
+        for path in paths {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                .to_path_buf();
+            let metadata = std::fs::symlink_metadata(&path)
+                .unwrap_or_else(|error| panic!("snapshot metadata {}: {error}", path.display()));
+            let file_type = metadata.file_type();
+            let kind =
+                if file_type.is_dir() {
+                    SnapshotKind::Directory
+                } else if file_type.is_file() {
+                    SnapshotKind::File(std::fs::read(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read {}: {error}", path.display())
+                    }))
+                } else if file_type.is_symlink() {
+                    SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read_link {}: {error}", path.display())
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
+            assert!(
+                out.insert(relative, kind).is_none(),
+                "duplicate snapshot path"
+            );
+            if file_type.is_dir() {
+                walk(root, &path, out);
+            }
+        }
+    }
+
+    let mut out = BTreeMap::new();
+    walk(root, root, &mut out);
+    out
+}
+
+fn assert_snapshot_unchanged(
+    before: &BTreeMap<PathBuf, SnapshotKind>,
+    after: &BTreeMap<PathBuf, SnapshotKind>,
+) {
+    let changed = before
+        .keys()
+        .chain(after.keys())
+        .filter(|path| before.get(*path) != after.get(*path))
+        .cloned()
+        .collect::<BTreeSet<_>>();
+    assert!(changed.is_empty(), "filesystem changed at {changed:?}");
+}
+
+#[test]
+fn extraction_status_never_opens_sqlite_or_mutates_bytes() {
+    let project = TempProject::new("classifier-boundary");
+    let paths = project.paths();
+    stage_non_current(&paths, FixtureStatus::Building, true);
+    let before = snapshot_tree(project.path());
+
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Building {
+            built: CURRENT_EXTRACTION_VERSION
+        }
+    );
+
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+}
+
+#[test]
+fn read_open_rejects_every_non_current_state_without_opening_trap_sqlite() {
+    for status in [
+        FixtureStatus::Missing,
+        FixtureStatus::Building,
+        FixtureStatus::Uninitialized,
+        FixtureStatus::Outdated,
+        FixtureStatus::Future,
+        FixtureStatus::Corrupt,
+    ] {
+        let project = TempProject::new("read-rejected");
+        let paths = project.paths();
+        stage_non_current(&paths, status, true);
+        let before = snapshot_tree(project.path());
+
+        let error = Store::open_for_read(&paths, deadline(), || false)
+            .expect_err("every non-Current state must reject read open");
+        match (status, error) {
+            (FixtureStatus::Corrupt, StoreError::StateRejected { status }) => {
+                assert!(matches!(status, ExtractionStatus::Corrupt { .. }));
+            }
+            (fixture, StoreError::StateRejected { status }) => {
+                assert_eq!(status, expected_status(fixture));
+            }
+            (_, other) => panic!("unexpected read rejection: {other:?}"),
+        }
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn current_read_is_read_only_retains_shared_lease_and_preserves_db_observation() {
+    let project = TempProject::new("current-read");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    let before_tree = snapshot_tree(project.path());
+
+    let store = Store::open_for_read(&paths, deadline(), || false).expect("open Current read");
+    assert_eq!(
+        store.schema_version().expect("read schema version"),
+        codegraph_store::migrations::CURRENT_SCHEMA_VERSION
+    );
+    assert_eq!(
+        store
+            .get_project_metadata(EXTRACTION_VERSION_KEY)
+            .expect("read exact metadata through retained read Store"),
+        Some(CURRENT_EXTRACTION_VERSION.to_string())
+    );
+    assert_eq!(
+        run_exclusive_probe(project.path(), SHORT_DEADLINE),
+        "TIMED_OUT",
+        "Store must retain its shared lease for the whole SQLite lifetime"
+    );
+    assert!(
+        store
+            .stamp_extraction_version()
+            .is_err_and(|error| matches!(error, StoreError::StampNotAuthorized))
+    );
+    assert_snapshot_unchanged(&before_tree, &snapshot_tree(project.path()));
+    drop(store);
+
+    assert_eq!(
+        run_exclusive_probe(project.path(), CHILD_WAIT),
+        "ACQUIRED",
+        "dropping Store must close SQLite and release its final lease owner"
+    );
+    assert_snapshot_unchanged(&before_tree, &snapshot_tree(project.path()));
+}
+
+#[test]
+fn current_read_and_status_reject_tombstone_without_mutating_any_artifact() {
+    let project = TempProject::new("current-tombstoned");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    std::fs::write(paths.tombstone(), b"interrupted-uninit marker")
+        .expect("stage Current+tombstone contradiction");
+    let before = snapshot_tree(project.path());
+
+    for error in [
+        Store::open_for_read(&paths, deadline(), || false)
+            .expect_err("Current+tombstone must reject read"),
+        Store::open_for_status(&paths, deadline(), || false)
+            .expect_err("Current+tombstone must reject status corroboration"),
+    ] {
+        assert!(matches!(
+            error,
+            StoreError::CurrentTombstoned { path } if path == paths.tombstone()
+        ));
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn current_read_stamp_failures_are_typed_and_byte_nonmutating() {
+    for (stamp, expected) in [
+        (None, "missing"),
+        (Some("02"), "malformed"),
+        (Some("1"), "mismatch"),
+    ] {
+        let project = TempProject::new("bad-stamp");
+        let paths = stage_current(&project, stamp);
+        let before_tree = snapshot_tree(project.path());
+
+        let error = Store::open_for_read(&paths, deadline(), || false)
+            .expect_err("bad extraction stamp must fail closed");
+        assert!(matches!(
+            (expected, error),
+            (
+                "missing",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Missing,
+                    ..
+                }
+            ) | (
+                "malformed",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Malformed { .. },
+                    ..
+                }
+            ) | (
+                "mismatch",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Mismatch {
+                        expected: CURRENT_EXTRACTION_VERSION,
+                        found: 1
+                    },
+                    ..
+                }
+            )
+        ));
+        assert_snapshot_unchanged(&before_tree, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn status_reports_non_current_states_without_opening_sqlite() {
+    for status in [
+        FixtureStatus::Missing,
+        FixtureStatus::Building,
+        FixtureStatus::Uninitialized,
+        FixtureStatus::Outdated,
+        FixtureStatus::Future,
+        FixtureStatus::Corrupt,
+    ] {
+        let project = TempProject::new("status-non-current");
+        let paths = project.paths();
+        stage_non_current(&paths, status, true);
+        let before = snapshot_tree(project.path());
+
+        let opened = Store::open_for_status(&paths, deadline(), || false)
+            .expect("non-Current status is typed data");
+        assert!(!opened.rebuilding);
+        assert!(opened.store().is_none());
+        if status == FixtureStatus::Corrupt {
+            assert!(matches!(
+                opened.status,
+                Some(ExtractionStatus::Corrupt { .. })
+            ));
+        } else {
+            assert_eq!(opened.status, Some(expected_status(status)));
+        }
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn status_missing_without_a_namespace_is_data_and_creates_nothing() {
+    let project = TempProject::new("status-absent");
+    let paths = project.paths();
+    let before = snapshot_tree(project.path());
+
+    let status = Store::open_for_status(&paths, deadline(), || false)
+        .expect("fully absent namespace is Missing status data");
+
+    assert_eq!(status.status, Some(ExtractionStatus::Missing));
+    assert!(!status.rebuilding);
+    assert!(status.store().is_none());
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+}
+
+#[test]
+fn status_current_uses_the_same_read_only_stamp_corroboration() {
+    let project = TempProject::new("status-current");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    let before = snapshot_tree(project.path());
+    let opened = Store::open_for_status(&paths, deadline(), || false).expect("Current status");
+    assert_eq!(opened.status, Some(ExtractionStatus::Current));
+    assert!(!opened.rebuilding);
+    assert!(opened.store().is_some());
+    drop(opened);
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+
+    for (stamp, expected) in [
+        (None, "missing"),
+        (Some("02"), "malformed"),
+        (Some("1"), "mismatch"),
+    ] {
+        let project = TempProject::new("status-current-bad-stamp");
+        let paths = stage_current(&project, stamp);
+        let before = snapshot_tree(project.path());
+        let error = Store::open_for_status(&paths, deadline(), || false)
+            .expect_err("Current status must corroborate its DB stamp");
+        assert!(matches!(
+            (expected, error),
+            (
+                "missing",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Missing,
+                    ..
+                }
+            ) | (
+                "malformed",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Malformed { .. },
+                    ..
+                }
+            ) | (
+                "mismatch",
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Mismatch {
+                        expected: CURRENT_EXTRACTION_VERSION,
+                        found: 1
+                    },
+                    ..
+                }
+            )
+        ));
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn busy_status_returns_rebuilding_without_opening_sqlite() {
+    let project = TempProject::new("status-busy");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    let holder = Holder::spawn(project.path());
+    let before = snapshot_tree(project.path());
+
+    let status = Store::open_for_status(&paths, deadline_after(SHORT_DEADLINE), || false)
+        .expect("busy writer is typed status data");
+
+    assert_eq!(status.status, None);
+    assert!(status.rebuilding);
+    assert!(status.store().is_none());
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    holder.release();
+}
+
+#[test]
+fn write_purpose_matrix_is_typed_and_rejected_pairs_are_nonmutating() {
+    let cases = [
+        (
+            FixtureStatus::Missing,
+            StoreWritePurpose::CurrentMutation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Missing,
+            StoreWritePurpose::FullRebuild,
+            "rebuild",
+        ),
+        (
+            FixtureStatus::Missing,
+            StoreWritePurpose::UninitContinuation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Building,
+            StoreWritePurpose::CurrentMutation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Building,
+            StoreWritePurpose::FullRebuild,
+            "rebuild",
+        ),
+        (
+            FixtureStatus::Building,
+            StoreWritePurpose::UninitContinuation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Outdated,
+            StoreWritePurpose::CurrentMutation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Outdated,
+            StoreWritePurpose::FullRebuild,
+            "rebuild",
+        ),
+        (
+            FixtureStatus::Outdated,
+            StoreWritePurpose::UninitContinuation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Uninitialized,
+            StoreWritePurpose::CurrentMutation,
+            "reject",
+        ),
+        (
+            FixtureStatus::Uninitialized,
+            StoreWritePurpose::FullRebuild,
+            "rebuild",
+        ),
+        (
+            FixtureStatus::Uninitialized,
+            StoreWritePurpose::UninitContinuation,
+            "uninit",
+        ),
+    ];
+
+    for (status, purpose, expected) in cases {
+        let project = TempProject::new("write-purpose");
+        let paths = project.paths();
+        stage_non_current(&paths, status, false);
+        let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("acquire write matrix lease");
+        let before = snapshot_tree(project.path());
+        let result = Store::open_for_write(&paths, lease, purpose);
+        match (expected, result) {
+            (
+                "reject",
+                Err(StoreError::WritePurposeRejected {
+                    purpose: got,
+                    status: got_status,
+                }),
+            ) => {
+                assert_eq!(got, purpose);
+                assert_eq!(got_status, expected_status(status));
+            }
+            ("rebuild", Ok(StoreWriteOpen::FullRebuildRequired(authorization))) => {
+                assert_eq!(authorization.purpose(), purpose);
+                assert_eq!(authorization.status(), &expected_status(status));
+                assert!(authorization.retains_exclusive_lease());
+                assert_eq!(
+                    run_exclusive_probe(project.path(), SHORT_DEADLINE),
+                    "TIMED_OUT"
+                );
+                drop(authorization);
+            }
+            ("uninit", Ok(StoreWriteOpen::UninitContinuation(authorization))) => {
+                assert_eq!(authorization.purpose(), purpose);
+                assert_eq!(authorization.status(), &ExtractionStatus::Uninitialized);
+                assert!(authorization.retains_exclusive_lease());
+                assert_eq!(
+                    run_exclusive_probe(project.path(), SHORT_DEADLINE),
+                    "TIMED_OUT"
+                );
+                drop(authorization);
+            }
+            (_, other) => panic!("unexpected write matrix outcome: {other:?}"),
+        }
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+#[test]
+fn current_state_accepts_only_current_mutation_or_explicit_full_rebuild() {
+    let project = TempProject::new("current-purpose-matrix");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+
+    let rebuild_lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+        .expect("acquire Current full-rebuild lease");
+    let before = snapshot_tree(project.path());
+    let StoreWriteOpen::FullRebuildRequired(authorization) =
+        Store::open_for_write(&paths, rebuild_lease, StoreWritePurpose::FullRebuild)
+            .expect("Current state allows an explicitly requested full rebuild")
+    else {
+        panic!("Current full rebuild must return opaque authorization");
+    };
+    assert_eq!(authorization.status(), &ExtractionStatus::Current);
+    assert_eq!(authorization.purpose(), StoreWritePurpose::FullRebuild);
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    drop(authorization);
+
+    let uninit_lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+        .expect("acquire Current continuation rejection lease");
+    let before = snapshot_tree(project.path());
+    let error = Store::open_for_write(&paths, uninit_lease, StoreWritePurpose::UninitContinuation)
+        .expect_err("a continuation purpose cannot start a new Current-state uninit");
+    assert!(matches!(
+        error,
+        StoreError::WritePurposeRejected {
+            purpose: StoreWritePurpose::UninitContinuation,
+            status: ExtractionStatus::Current
+        }
+    ));
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+}
+
+#[test]
+fn current_writer_is_state_gated_retains_lease_and_stamps_the_exact_owned_value() {
+    let project = TempProject::new("current-writer");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+        .expect("acquire Current writer lease");
+    let opened = Store::open_for_write(&paths, lease, StoreWritePurpose::CurrentMutation)
+        .expect("open Current writer");
+    let StoreWriteOpen::Current(store) = opened else {
+        panic!("Current mutation must return an open Store");
+    };
+    assert_eq!(
+        run_exclusive_probe(project.path(), SHORT_DEADLINE),
+        "TIMED_OUT"
+    );
+    store
+        .set_project_metadata(EXTRACTION_VERSION_KEY, "1")
+        .expect("stage stale stamp under writer lease");
+    store
+        .stamp_extraction_version()
+        .expect("authorized writer stamps exact current version");
+    assert_eq!(
+        store
+            .get_project_metadata(EXTRACTION_VERSION_KEY)
+            .expect("read stamped value"),
+        Some(CURRENT_EXTRACTION_VERSION.to_string())
+    );
+    drop(store);
+    assert_eq!(run_exclusive_probe(project.path(), CHILD_WAIT), "ACQUIRED");
+
+    let legacy = Store::open(&project.path().join("legacy.db")).expect("legacy Store fixture");
+    assert!(matches!(
+        legacy.stamp_extraction_version(),
+        Err(StoreError::StampNotAuthorized)
+    ));
+}
+
+#[test]
+fn writer_stamp_revalidates_the_retained_fixed_lock_before_metadata_mutation() {
+    let project = TempProject::new("stamp-replaced-lock");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+        .expect("acquire stamp fixture lease");
+    let StoreWriteOpen::Current(store) =
+        Store::open_for_write(&paths, lease, StoreWritePurpose::CurrentMutation)
+            .expect("open stamp fixture writer")
+    else {
+        panic!("Current mutation must return an open Store");
+    };
+    let displaced = paths.current_root().join("displaced-before-stamp.lock");
+    std::fs::rename(paths.permanent_lock(), &displaced).expect("displace retained lock handle");
+    std::fs::write(paths.permanent_lock(), b"replacement before stamp")
+        .expect("install replacement before stamp");
+    let before = snapshot_tree(project.path());
+
+    let error = store
+        .stamp_extraction_version()
+        .expect_err("stale retained lease must not authorize metadata stamping");
+    assert!(matches!(
+        error,
+        StoreError::LeaseValidation(IndexLeaseValidationError::PermanentLockChanged { .. })
+    ));
+    assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    drop(store);
+}
+
+#[test]
+fn write_open_validates_shared_wrong_parent_and_replaced_lock_before_mutation() {
+    let shared_project = TempProject::new("write-shared");
+    let shared_paths = stage_current(
+        &shared_project,
+        Some(&CURRENT_EXTRACTION_VERSION.to_string()),
+    );
+    let shared = IndexLease::acquire_shared_existing(&shared_paths, deadline(), || false)
+        .expect("acquire shared fixture lease");
+    let before = snapshot_tree(shared_project.path());
+    assert!(matches!(
+        Store::open_for_write(&shared_paths, shared, StoreWritePurpose::CurrentMutation),
+        Err(StoreError::LeaseValidation(
+            IndexLeaseValidationError::SharedLease
+        ))
+    ));
+    assert_snapshot_unchanged(&before, &snapshot_tree(shared_project.path()));
+
+    let other_project = TempProject::new("write-wrong-parent");
+    let other_paths = stage_current(
+        &other_project,
+        Some(&CURRENT_EXTRACTION_VERSION.to_string()),
+    );
+    let wrong = IndexLease::acquire_exclusive_existing(&shared_paths, deadline(), || false)
+        .expect("acquire wrong-parent fixture lease");
+    let before = snapshot_tree(other_project.path());
+    assert!(matches!(
+        Store::open_for_write(&other_paths, wrong, StoreWritePurpose::CurrentMutation),
+        Err(StoreError::LeaseValidation(
+            IndexLeaseValidationError::WrongDbParent
+        ))
+    ));
+    assert_snapshot_unchanged(&before, &snapshot_tree(other_project.path()));
+
+    let replaced_project = TempProject::new("write-replaced-lock");
+    let replaced_paths = stage_current(
+        &replaced_project,
+        Some(&CURRENT_EXTRACTION_VERSION.to_string()),
+    );
+    let stale = IndexLease::acquire_exclusive_existing(&replaced_paths, deadline(), || false)
+        .expect("acquire soon-stale lease");
+    let displaced = replaced_paths.current_root().join("displaced-index.lock");
+    std::fs::rename(replaced_paths.permanent_lock(), &displaced).expect("displace held lock");
+    std::fs::write(replaced_paths.permanent_lock(), b"replacement lock")
+        .expect("install replacement lock");
+    let before = snapshot_tree(replaced_project.path());
+    assert!(matches!(
+        Store::open_for_write(&replaced_paths, stale, StoreWritePurpose::CurrentMutation),
+        Err(StoreError::LeaseValidation(
+            IndexLeaseValidationError::PermanentLockChanged { .. }
+        ))
+    ));
+    assert_snapshot_unchanged(&before, &snapshot_tree(replaced_project.path()));
+    let fresh = IndexLease::acquire_exclusive_existing(&replaced_paths, deadline(), || false)
+        .expect("replacement fixed lock is independently acquirable");
+    drop(fresh);
+}
+
+#[test]
+fn future_and_corrupt_writer_opens_are_typed_and_byte_nonmutating_for_every_purpose() {
+    for status in [FixtureStatus::Future, FixtureStatus::Corrupt] {
+        let project = TempProject::new("write-refused-state");
+        let paths = project.paths();
+        stage_non_current(&paths, status, true);
+        for purpose in [
+            StoreWritePurpose::CurrentMutation,
+            StoreWritePurpose::FullRebuild,
+            StoreWritePurpose::UninitContinuation,
+        ] {
+            let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+                .expect("acquire refusal fixture lease");
+            let before = snapshot_tree(project.path());
+            let error = Store::open_for_write(&paths, lease, purpose)
+                .expect_err("Future/Corrupt writer open must fail closed");
+            match (status, error) {
+                (FixtureStatus::Future, StoreError::StateRejected { status }) => {
+                    assert_eq!(status, expected_status(FixtureStatus::Future));
+                }
+                (FixtureStatus::Corrupt, StoreError::StateRejected { status }) => {
+                    assert!(matches!(status, ExtractionStatus::Corrupt { .. }));
+                }
+                (_, other) => panic!("unexpected refused writer error: {other:?}"),
+            }
+            assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+        }
+    }
+}
+
+#[test]
+fn missing_state_with_any_existing_database_artifact_fails_closed() {
+    for suffix in ["", "-wal", "-shm"] {
+        let project = TempProject::new("missing-with-artifact");
+        let paths = project.paths();
+        let initial = create_namespace(&paths);
+        drop(initial);
+        let db = paths.current_db();
+        let artifact = PathBuf::from(format!("{}{suffix}", db.display()));
+        std::fs::write(&artifact, b"reserved unknown database artifact")
+            .expect("write reserved DB artifact");
+        let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("acquire Missing fixture lease");
+        let before = snapshot_tree(project.path());
+
+        let error = Store::open_for_write(&paths, lease, StoreWritePurpose::FullRebuild)
+            .expect_err("Missing plus DB artifact is not a fresh writable namespace");
+        assert!(matches!(
+            error,
+            StoreError::MissingStateWithDatabase { path } if path == artifact
+        ));
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+/// Child-process entry point used by deterministic lock contention tests.
+#[test]
+fn store_gate_child_process() {
+    let Ok(action) = std::env::var(CHILD_ACTION) else {
+        return;
+    };
+    let project = PathBuf::from(std::env::var_os(CHILD_PROJECT).expect("child project env"));
+    let paths = IndexPaths::resolve(&project, None).expect("child resolve IndexPaths");
+    match action.as_str() {
+        "hold-exclusive" => {
+            let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+                .expect("holder acquires exclusive lease");
+            println!("READY");
+            std::io::stdout().flush().expect("flush READY");
+            let mut release = [0_u8; 1];
+            std::io::stdin()
+                .read_exact(&mut release)
+                .expect("read release byte");
+            drop(lease);
+            println!("RELEASED");
+            std::io::stdout().flush().expect("flush RELEASED");
+        }
+        "probe-exclusive" => match IndexLease::acquire_exclusive_existing(
+            &paths,
+            deadline_after(SHORT_DEADLINE),
+            || false,
+        ) {
+            Ok(lease) => {
+                println!("ACQUIRED");
+                drop(lease);
+            }
+            Err(codegraph_store::IndexLeaseError::TimedOut { .. }) => println!("TIMED_OUT"),
+            Err(error) => panic!("unexpected child probe error: {error}"),
+        },
+        other => panic!("unknown Store gate child action {other}"),
+    }
+}
+
+struct Holder {
+    child: Option<Child>,
+    stdin: Option<ChildStdin>,
+    tail: Receiver<String>,
+}
+
+impl Holder {
+    fn spawn(project: &Path) -> Self {
+        let mut child = child_command(project, "hold-exclusive")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .spawn()
+            .expect("spawn Store lock holder");
+        let stdin = child.stdin.take().expect("holder stdin");
+        let stdout = child.stdout.take().expect("holder stdout");
+        let (ready_tx, ready_rx) = mpsc::channel();
+        let (tail_tx, tail_rx) = mpsc::channel();
+        std::thread::spawn(move || {
+            let mut reader = BufReader::new(stdout);
+            loop {
+                let mut line = String::new();
+                let read = reader.read_line(&mut line).expect("read holder output");
+                assert_ne!(read, 0, "holder exited before READY");
+                if line.trim() == "READY" {
+                    ready_tx.send(line).expect("send holder READY");
+                    break;
+                }
+            }
+            let mut tail = String::new();
+            reader.read_to_string(&mut tail).expect("read holder tail");
+            tail_tx.send(tail).expect("send holder tail");
+        });
+        let ready = ready_rx
+            .recv_timeout(CHILD_WAIT)
+            .expect("holder READY before finite deadline");
+        assert_eq!(ready.trim(), "READY");
+        Self {
+            child: Some(child),
+            stdin: Some(stdin),
+            tail: tail_rx,
+        }
+    }
+
+    fn release(mut self) {
+        let mut stdin = self.stdin.take().expect("holder release stdin");
+        stdin.write_all(b"x").expect("signal holder release");
+        drop(stdin);
+        let child = self.child.as_mut().expect("holder child");
+        let status = wait_bounded(child, CHILD_WAIT);
+        assert!(status.success(), "holder child failed: {status}");
+        let tail = self
+            .tail
+            .recv_timeout(CHILD_WAIT)
+            .expect("holder tail before finite deadline");
+        assert!(
+            tail.lines().any(|line| line == "RELEASED"),
+            "holder emitted no RELEASED sentinel: {tail:?}"
+        );
+        self.child.take();
+    }
+}
+
+impl Drop for Holder {
+    fn drop(&mut self) {
+        if let Some(child) = self.child.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+fn child_command(project: &Path, action: &str) -> Command {
+    let mut command = Command::new(std::env::current_exe().expect("current test executable"));
+    command
+        .arg("--exact")
+        .arg("store_gate_child_process")
+        .arg("--nocapture")
+        .env(CHILD_ACTION, action)
+        .env(CHILD_PROJECT, project);
+    command
+}
+
+fn run_exclusive_probe(project: &Path, process_bound: Duration) -> String {
+    let mut child = child_command(project, "probe-exclusive")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()
+        .expect("spawn Store lock probe");
+    let mut stdout = child.stdout.take().expect("probe stdout");
+    let (output_tx, output_rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let mut output = String::new();
+        stdout
+            .read_to_string(&mut output)
+            .expect("read probe stdout");
+        output_tx.send(output).expect("send probe output");
+    });
+    let status = wait_bounded(
+        &mut child,
+        process_bound
+            .checked_add(CHILD_WAIT)
+            .expect("probe process bound"),
+    );
+    assert!(status.success(), "probe child failed: {status}");
+    output_rx
+        .recv_timeout(CHILD_WAIT)
+        .expect("probe output before finite deadline")
+        .lines()
+        .find(|line| matches!(*line, "ACQUIRED" | "TIMED_OUT"))
+        .unwrap_or_else(|| panic!("probe emitted no result sentinel"))
+        .to_string()
+}
+
+fn wait_bounded(child: &mut Child, timeout: Duration) -> std::process::ExitStatus {
+    let deadline = deadline_after(timeout);
+    loop {
+        if let Some(status) = child.try_wait().expect("poll child status") {
+            return status;
+        }
+        if Instant::now() >= deadline {
+            let _ = child.kill();
+            let _ = child.wait();
+            panic!("child process exceeded finite {timeout:?} bound");
+        }
+        std::thread::park_timeout(Duration::from_millis(5));
+    }
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 4fe6e96..e576b64 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1415,3 +1415,81 @@ final ledger/notepad bytes, the mandatory closing order is `make fmt`, then one
 fresh `bash scripts/check-workspace-versions.sh && make ci`, then the exact
 `Cargo.lock` SHA-256 check and scoped status/diff inspection. No final Green is
 claimed in this entry before that post-documentation gate actually passes.
+
+## Batch M — lease-retaining state-gated `Store` opens (2026-07-25)
+
+### Scope and behavioral Red
+
+This isolated `codegraph-store` slice adds
+`Store::{extraction_status,open_for_read,open_for_status,open_for_write,stamp_extraction_version}`
+and their typed public result/error surfaces. It preserves legacy `Store::open`
+unchanged and does not migrate production CLI, MCP, watch, daemon, index,
+rebuild/finalizer, or uninit call sites.
+
+The compiling behavioral Red called the proposed `open_for_read` through a
+minimal fallback to legacy `Store::open`. The targeted test reached the public
+call, exited 101, and failed the exact assertion `Missing state must reject a
+safe read open`: legacy fallback returned success and created SQLite in a
+Missing namespace. This was missing state-gated behavior, not a compile, setup,
+fixture, or network failure.
+
+### Accepted behavior
+
+- `extraction_status` delegates only to the accepted dual-slot classifier and
+  never opens SQLite or mutates namespace bytes.
+- `open_for_read` acquires and retains a bounded shared `IndexLease`, accepts
+  only `Current`, rejects a tombstone, and corroborates the store-owned
+  extraction stamp without creating SQLite or `-wal`/`-shm` artifacts. It opens
+  the real DB with exactly `SQLITE_OPEN_READ_ONLY`, retains that source
+  connection, copies the checkpointed main-file bytes into a separate read-only
+  deserialized SQLite image, and queries only the private image. WAL header
+  bytes 18/19 are normalized only in that private allocation; disk bytes remain
+  exact. `SQLITE_DESERIALIZE_FREEONCLOSE` ownership follows SQLite's documented
+  rule: SQLite frees the allocation on both successful close and failed
+  `sqlite3_deserialize`, so the Rust failure path does not double-free it.
+- `open_for_status` treats shared-lease timeout as typed status data
+  (`rebuilding=true`, no SQLite open), reports stable non-Current states without
+  SQLite, and uses the same retained read-only corroboration for `Current`.
+- `open_for_write` validates the injected exact exclusive lease before
+  classification. `Future` and `Corrupt` fail closed; `Missing` plus any DB,
+  WAL, or SHM artifact is typed corruption at the Store boundary. Only
+  `CurrentMutation + Current` opens SQLite read-write after read-only stamp
+  corroboration. `FullRebuild` and valid `UninitContinuation` return opaque
+  authorizations that retain the exclusive lease without opening SQLite;
+  unauthorized purpose/state pairs are typed rejections.
+- `stamp_extraction_version` is available only on a state-gated write Store and
+  revalidates the retained fixed lock immediately before metadata mutation.
+  Legacy/read/status Stores cannot stamp. `Store` declares SQLite connections
+  before its lease field so both connections drop before the final lease owner
+  unlocks.
+- Stamp failures distinguish missing, noncanonical/malformed decimal, and exact
+  version mismatch. Public APIs export only the purpose/status observations
+  required by later lifecycle slices; callers cannot forge a lease-backed
+  authorization.
+
+### Focused verification before the terminal gate
+
+Every Cargo command used `--locked` and the batch was preceded by
+`bash scripts/check-workspace-versions.sh`:
+
+- `store_state_gates`: 17 passed, 0 failed, covering read/status/write state
+  matrices, sidecar-free byte snapshots, stamp failures, timeout status,
+  cross-process lease retention/drop, wrong/shared/replaced leases, tombstones,
+  Missing-plus-artifact refusal, and write-purpose authorization.
+- Accepted publisher integration: 14 passed; lease integration: 12 passed;
+  classifier integration: 20 passed; store unit tests: 66 passed; all with zero
+  failures.
+- `cargo check -p codegraph-store --all-targets --locked` and
+  `cargo clippy -p codegraph-store --all-targets --locked -- -D warnings` passed.
+- `LIBSQLITE3_SYS_USE_PKG_CONFIG=1 SQLITE3_LIB_DIR=/tmp/opencode cargo check -p
+codegraph-store --all-targets --target x86_64-pc-windows-msvc --locked`
+  passed. This is Linux-host MSVC compilation only; no native Windows runtime
+  behavior is claimed.
+- LSP diagnostics cannot attach to this external `/tmp` worktree, so the clean
+  targeted Cargo diagnostics are the recorded fallback.
+
+No dependency, schema, node-id formula, extraction output, or golden artifact
+changed. `Cargo.lock` remains required at
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+These evidence bytes are written before formatting and the single final CI run;
+no terminal Green is claimed until that post-documentation gate passes.

From f5c57f5f511cf38e01eb6940ad8d07a159865f1d Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sat, 25 Jul 2026 21:09:02 +0800
Subject: [PATCH 20/91] fix(store): harden state-gated artifact checks

---
 crates/codegraph-store/src/connection.rs      | 269 ++++++++++++++++-
 .../tests/store_state_gates.rs                | 284 +++++++++++++++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  58 ++++
 3 files changed, 596 insertions(+), 15 deletions(-)

diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index d59ecae..1879eb3 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -169,8 +169,17 @@ pub enum StoreError {
     },
     #[error("state is missing but a database artifact already exists at {path}")]
     MissingStateWithDatabase { path: PathBuf },
+    #[error("index state {status} exists without its permanent lock at {path}")]
+    StateWithoutPermanentLock {
+        status: ExtractionStatus,
+        path: PathBuf,
+    },
     #[error("Current index state is blocked by the uninitialized tombstone at {path}")]
     CurrentTombstoned { path: PathBuf },
+    #[error("Current index state has no SQLite database at {path}")]
+    CurrentDatabaseMissing { path: PathBuf },
+    #[error("Current index state has an unexpected SQLite sidecar at {path}")]
+    CurrentWithDatabaseSidecar { path: PathBuf },
     #[error("failed to inspect database artifact {path}: {source}")]
     InspectArtifact {
         path: PathBuf,
@@ -284,8 +293,15 @@ impl Store {
         deadline: Instant,
         cancelled: impl FnMut() -> bool,
     ) -> Result<Self> {
-        let lease = IndexLease::acquire_shared_existing(paths, deadline, cancelled)?;
+        let lease = match IndexLease::acquire_shared_existing(paths, deadline, cancelled) {
+            Ok(lease) => lease,
+            Err(IndexLeaseError::LockNotFound { .. }) => {
+                return Err(lockless_state_error(paths)?);
+            }
+            Err(error) => return Err(StoreError::Lease(error)),
+        };
         let status = Self::extraction_status(paths);
+        reject_missing_database_artifacts(paths, &status)?;
         if status != ExtractionStatus::Current {
             return Err(StoreError::StateRejected { status });
         }
@@ -313,20 +329,29 @@ impl Store {
             Err(IndexLeaseError::LockNotFound { .. }) => {
                 let status = Self::extraction_status(paths);
                 if status == ExtractionStatus::Missing {
+                    reject_missing_database_artifacts(paths, &status)?;
                     return Ok(StoreStatusOpen {
                         status: Some(status),
                         rebuilding: false,
                         store: None,
                     });
                 }
-                return Err(StoreError::Lease(IndexLeaseError::LockNotFound {
+                if matches!(
+                    status,
+                    ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. }
+                ) {
+                    return Err(StoreError::StateRejected { status });
+                }
+                return Err(StoreError::StateWithoutPermanentLock {
+                    status,
                     path: paths.permanent_lock(),
-                }));
+                });
             }
             Err(error) => return Err(StoreError::Lease(error)),
         };
 
         let status = Self::extraction_status(paths);
+        reject_missing_database_artifacts(paths, &status)?;
         let store = if status == ExtractionStatus::Current {
             Some(open_current_read_only(paths, lease)?)
         } else {
@@ -347,6 +372,15 @@ impl Store {
         paths: &IndexPaths,
         lease: IndexLease,
         purpose: StoreWritePurpose,
+    ) -> Result<StoreWriteOpen> {
+        Self::open_for_write_with(paths, lease, purpose, || {})
+    }
+
+    fn open_for_write_with(
+        paths: &IndexPaths,
+        lease: IndexLease,
+        purpose: StoreWritePurpose,
+        before_write_open: impl FnOnce(),
     ) -> Result<StoreWriteOpen> {
         lease.validate_exclusive(paths)?;
         let status = Self::extraction_status(paths);
@@ -370,6 +404,12 @@ impl Store {
                 let (corroboration, source_conn) = corroborate_current_database(paths)?;
                 drop(corroboration);
                 drop(source_conn);
+                before_write_open();
+                // The fixed lock path may be replaced after classification and
+                // read-only corroboration. Revalidate the exact held handle at
+                // the latest checkpoint, immediately before the first
+                // write-capable SQLite open.
+                lease.validate_exclusive(paths)?;
                 let db_path = paths.current_db();
                 let conn = Connection::open_with_flags(&db_path, OpenFlags::SQLITE_OPEN_READ_WRITE)
                     .map_err(|source| StoreError::Open {
@@ -389,13 +429,20 @@ impl Store {
                     lease: Some(lease),
                 })))
             }
-            StoreWritePurpose::FullRebuild => Ok(StoreWriteOpen::FullRebuildRequired(
-                StoreWriteAuthorization {
-                    status,
-                    purpose,
-                    lease,
-                },
-            )),
+            StoreWritePurpose::FullRebuild => {
+                if status == ExtractionStatus::Current {
+                    let (corroboration, source_conn) = corroborate_current_database(paths)?;
+                    drop(corroboration);
+                    drop(source_conn);
+                }
+                Ok(StoreWriteOpen::FullRebuildRequired(
+                    StoreWriteAuthorization {
+                        status,
+                        purpose,
+                        lease,
+                    },
+                ))
+            }
             StoreWritePurpose::UninitContinuation if status == ExtractionStatus::Uninitialized => {
                 Ok(StoreWriteOpen::UninitContinuation(
                     StoreWriteAuthorization {
@@ -465,6 +512,12 @@ fn corroborate_current_database(paths: &IndexPaths) -> Result<(Connection, Conne
             path: paths.tombstone(),
         });
     }
+    if !artifact_exists(&db_path)? {
+        return Err(StoreError::CurrentDatabaseMissing { path: db_path });
+    }
+    if let Some(path) = first_existing_database_sidecar(paths)? {
+        return Err(StoreError::CurrentWithDatabaseSidecar { path });
+    }
     let (conn, source_conn) = open_read_only_without_sidecars(&db_path)?;
     let stamp = conn
         .query_row(
@@ -518,7 +571,10 @@ fn open_read_only_without_sidecars(db_path: &Path) -> Result<(Connection, Connec
 fn deserialize_read_only(conn: &mut Connection, bytes: &[u8]) -> rusqlite::Result<()> {
     use std::ptr::NonNull;
 
-    let size = u64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?;
+    let (size, deserialize_size) = deserialize_sizes(bytes.len())?;
+    // Keep every fallible size conversion above the ownership-bearing
+    // allocation. After sqlite3_malloc64 succeeds, no Rust `?` may return before
+    // sqlite3_deserialize assumes FREEONCLOSE ownership.
     // SAFETY: sqlite3_malloc64 returns an allocation suitable for
     // SQLITE_DESERIALIZE_FREEONCLOSE. The byte copy uses the exact allocation
     // length. Once sqlite3_deserialize is called, SQLite owns and frees the
@@ -552,8 +608,8 @@ fn deserialize_read_only(conn: &mut Connection, bytes: &[u8]) -> rusqlite::Resul
             conn.handle(),
             schema.as_ptr(),
             allocation.as_ptr(),
-            i64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?,
-            i64::try_from(bytes.len()).map_err(|_| rusqlite::Error::InvalidQuery)?,
+            deserialize_size,
+            deserialize_size,
             rusqlite::ffi::SQLITE_DESERIALIZE_FREEONCLOSE
                 | rusqlite::ffi::SQLITE_DESERIALIZE_READONLY,
         )
@@ -569,6 +625,12 @@ fn deserialize_read_only(conn: &mut Connection, bytes: &[u8]) -> rusqlite::Resul
     Ok(())
 }
 
+fn deserialize_sizes(len: usize) -> rusqlite::Result<(u64, i64)> {
+    let allocation_size = u64::try_from(len).map_err(|_| rusqlite::Error::InvalidQuery)?;
+    let image_size = i64::try_from(len).map_err(|_| rusqlite::Error::InvalidQuery)?;
+    Ok((allocation_size, image_size))
+}
+
 fn validate_extraction_stamp(db_path: &Path, stamp: Option<String>) -> Result<()> {
     let Some(stamp) = stamp else {
         return Err(StoreError::InvalidExtractionStamp {
@@ -617,6 +679,46 @@ fn first_existing_database_artifact(paths: &IndexPaths) -> Result<Option<PathBuf
     Ok(None)
 }
 
+fn first_existing_database_sidecar(paths: &IndexPaths) -> Result<Option<PathBuf>> {
+    let db = paths.current_db();
+    for path in [
+        PathBuf::from(format!("{}-wal", db.display())),
+        PathBuf::from(format!("{}-shm", db.display())),
+    ] {
+        if artifact_exists(&path)? {
+            return Ok(Some(path));
+        }
+    }
+    Ok(None)
+}
+
+fn reject_missing_database_artifacts(paths: &IndexPaths, status: &ExtractionStatus) -> Result<()> {
+    if status == &ExtractionStatus::Missing
+        && let Some(path) = first_existing_database_artifact(paths)?
+    {
+        return Err(StoreError::MissingStateWithDatabase { path });
+    }
+    Ok(())
+}
+
+fn lockless_state_error(paths: &IndexPaths) -> Result<StoreError> {
+    let status = Store::extraction_status(paths);
+    if status == ExtractionStatus::Missing {
+        reject_missing_database_artifacts(paths, &status)?;
+        return Ok(StoreError::StateRejected { status });
+    }
+    if matches!(
+        status,
+        ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. }
+    ) {
+        return Ok(StoreError::StateRejected { status });
+    }
+    Ok(StoreError::StateWithoutPermanentLock {
+        status,
+        path: paths.permanent_lock(),
+    })
+}
+
 fn artifact_exists(path: &Path) -> Result<bool> {
     match std::fs::symlink_metadata(path) {
         Ok(_) => Ok(true),
@@ -645,6 +747,69 @@ fn configure_connection(conn: &Connection) -> rusqlite::Result<()> {
 mod tests {
     use super::*;
 
+    #[derive(Debug, PartialEq, Eq)]
+    enum SnapshotKind {
+        Directory,
+        File(Vec<u8>),
+        Symlink(PathBuf),
+    }
+
+    fn snapshot_tree(root: &Path) -> std::collections::BTreeMap<PathBuf, SnapshotKind> {
+        fn walk(
+            root: &Path,
+            directory: &Path,
+            out: &mut std::collections::BTreeMap<PathBuf, SnapshotKind>,
+        ) {
+            let mut paths = std::fs::read_dir(directory)
+                .unwrap_or_else(|error| {
+                    panic!("snapshot read_dir {}: {error}", directory.display())
+                })
+                .map(|entry| {
+                    entry
+                        .unwrap_or_else(|error| {
+                            panic!("snapshot entry in {}: {error}", directory.display())
+                        })
+                        .path()
+                })
+                .collect::<Vec<_>>();
+            paths.sort();
+            for path in paths {
+                let relative = path
+                    .strip_prefix(root)
+                    .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                    .to_path_buf();
+                let metadata = std::fs::symlink_metadata(&path).unwrap_or_else(|error| {
+                    panic!("snapshot metadata {}: {error}", path.display())
+                });
+                let file_type = metadata.file_type();
+                let kind = if file_type.is_dir() {
+                    SnapshotKind::Directory
+                } else if file_type.is_file() {
+                    SnapshotKind::File(std::fs::read(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read {}: {error}", path.display())
+                    }))
+                } else if file_type.is_symlink() {
+                    SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read_link {}: {error}", path.display())
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
+                assert!(
+                    out.insert(relative, kind).is_none(),
+                    "duplicate snapshot path"
+                );
+                if file_type.is_dir() {
+                    walk(root, &path, out);
+                }
+            }
+        }
+
+        let mut out = std::collections::BTreeMap::new();
+        walk(root, root, &mut out);
+        out
+    }
+
     fn temp_db_path(label: &str) -> PathBuf {
         std::env::temp_dir().join(format!(
             "codegraph-conn-{label}-{}-{}.db",
@@ -683,6 +848,15 @@ mod tests {
         );
     }
 
+    #[test]
+    #[cfg(target_pointer_width = "64")]
+    fn impossible_deserialize_size_is_rejected_before_ownership_bearing_allocation() {
+        assert!(matches!(
+            deserialize_sizes(usize::MAX),
+            Err(rusqlite::Error::InvalidQuery)
+        ));
+    }
+
     #[test]
     fn open_creates_parent_dir_migrates_and_exposes_accessors() {
         let base = std::env::temp_dir().join(format!(
@@ -850,4 +1024,73 @@ mod tests {
         };
         assert!(migrate.to_string().contains("/tmp/x.db"));
     }
+
+    #[test]
+    fn current_writer_revalidates_lock_at_the_last_pre_open_checkpoint() {
+        fn deadline() -> Instant {
+            Instant::now() + std::time::Duration::from_secs(5)
+        }
+
+        let base = std::env::temp_dir().join(format!(
+            "codegraph-conn-late-lock-replacement-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir(&base).unwrap();
+        let project = base.canonicalize().unwrap();
+        let paths = IndexPaths::resolve(&project, None).unwrap();
+        let initial = IndexLease::create_exclusive(&paths, deadline(), || false).unwrap();
+        let fixture = Store::open(&paths.current_db()).unwrap();
+        fixture
+            .set_project_metadata(
+                EXTRACTION_VERSION_KEY,
+                &CURRENT_EXTRACTION_VERSION.to_string(),
+            )
+            .unwrap();
+        fixture.restore_default_pragmas().unwrap();
+        drop(fixture);
+        let state = serde_json::json!({
+            "sequence": 1,
+            "storageProtocol": crate::CURRENT_STORAGE_PROTOCOL,
+            "extractionVersion": CURRENT_EXTRACTION_VERSION,
+            "phase": "current",
+            "projectIdentity": paths.project_identity(),
+            "checksum": crate::checksum_hex(
+                1,
+                crate::CURRENT_STORAGE_PROTOCOL,
+                CURRENT_EXTRACTION_VERSION,
+                "current",
+                paths.project_identity(),
+            ),
+        });
+        std::fs::write(&paths.state_slots()[0], serde_json::to_vec(&state).unwrap()).unwrap();
+        drop(initial);
+        let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false).unwrap();
+        let displaced = paths.current_root().join("displaced-at-write-open.lock");
+        let expected_after_replacement = std::cell::RefCell::new(None);
+
+        let error =
+            Store::open_for_write_with(&paths, lease, StoreWritePurpose::CurrentMutation, || {
+                std::fs::rename(paths.permanent_lock(), &displaced).unwrap();
+                std::fs::write(paths.permanent_lock(), b"late replacement").unwrap();
+                expected_after_replacement.replace(Some(snapshot_tree(&project)));
+            })
+            .expect_err("late lock replacement must prevent write-capable SQLite open");
+        assert!(matches!(
+            error,
+            StoreError::LeaseValidation(IndexLeaseValidationError::PermanentLockChanged { .. })
+        ));
+        assert_eq!(
+            snapshot_tree(&project),
+            expected_after_replacement
+                .into_inner()
+                .expect("checkpoint captured post-replacement tree"),
+            "rejection must not mutate any byte after the deterministic replacement checkpoint"
+        );
+
+        let _ = std::fs::remove_dir_all(base);
+    }
 }
diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
index 3891112..7e318ff 100644
--- a/crates/codegraph-store/tests/store_state_gates.rs
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -14,6 +14,7 @@ use codegraph_store::{
     ExtractionStampIssue, ExtractionStatus, IndexLease, IndexLeaseValidationError, Store,
     StoreError, StoreWriteOpen, StoreWritePurpose, checksum_hex,
 };
+use rusqlite::{Connection, OpenFlags, OptionalExtension};
 use serde_json::json;
 
 const CHILD_ACTION: &str = "CODEGRAPH_STORE_GATE_CHILD_ACTION";
@@ -147,6 +148,18 @@ fn stage_current(project: &TempProject, stamp: Option<&str>) -> IndexPaths {
     paths
 }
 
+fn stage_state_without_lock(project: &TempProject, phase: &str) -> IndexPaths {
+    let paths = project.paths();
+    std::fs::create_dir_all(paths.current_root()).expect("create lockless state namespace");
+    write_state(
+        &paths,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        phase,
+    );
+    paths
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum FixtureStatus {
     Missing,
@@ -323,6 +336,9 @@ fn read_open_rejects_every_non_current_state_without_opening_trap_sqlite() {
         let error = Store::open_for_read(&paths, deadline(), || false)
             .expect_err("every non-Current state must reject read open");
         match (status, error) {
+            (FixtureStatus::Missing, StoreError::MissingStateWithDatabase { path }) => {
+                assert_eq!(path, paths.current_db());
+            }
             (FixtureStatus::Corrupt, StoreError::StateRejected { status }) => {
                 assert!(matches!(status, ExtractionStatus::Corrupt { .. }));
             }
@@ -452,8 +468,16 @@ fn status_reports_non_current_states_without_opening_sqlite() {
         stage_non_current(&paths, status, true);
         let before = snapshot_tree(project.path());
 
-        let opened = Store::open_for_status(&paths, deadline(), || false)
-            .expect("non-Current status is typed data");
+        let result = Store::open_for_status(&paths, deadline(), || false);
+        if status == FixtureStatus::Missing {
+            assert!(matches!(
+                result,
+                Err(StoreError::MissingStateWithDatabase { path }) if path == paths.current_db()
+            ));
+            assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+            continue;
+        }
+        let opened = result.expect("non-Current state with authenticated residue is typed data");
         assert!(!opened.rebuilding);
         assert!(opened.store().is_none());
         if status == FixtureStatus::Corrupt {
@@ -695,6 +719,83 @@ fn current_state_accepts_only_current_mutation_or_explicit_full_rebuild() {
     assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
 }
 
+#[test]
+fn current_full_rebuild_requires_the_same_database_corroboration_as_a_read() {
+    for (fixture, stamp, expected) in [
+        ("missing-db", None, "missing-db"),
+        ("tombstone", Some("2"), "tombstone"),
+        ("missing-stamp", None, "missing-stamp"),
+        ("malformed-stamp", Some("02"), "malformed-stamp"),
+        ("mismatched-stamp", Some("1"), "mismatched-stamp"),
+    ] {
+        let project = TempProject::new(fixture);
+        let paths = if fixture == "missing-db" {
+            let paths = project.paths();
+            let initial = create_namespace(&paths);
+            write_state(
+                &paths,
+                CURRENT_STORAGE_PROTOCOL,
+                CURRENT_EXTRACTION_VERSION,
+                "current",
+            );
+            drop(initial);
+            paths
+        } else {
+            let paths = stage_current(&project, stamp);
+            if fixture == "tombstone" {
+                std::fs::write(paths.tombstone(), b"interrupted uninit")
+                    .expect("stage Current tombstone contradiction");
+            }
+            paths
+        };
+        let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("acquire inconsistent Current rebuild lease");
+        let before = snapshot_tree(project.path());
+
+        let error = Store::open_for_write(&paths, lease, StoreWritePurpose::FullRebuild)
+            .expect_err("inconsistent Current artifacts must not authorize a full rebuild");
+        let matched = match expected {
+            "missing-db" => {
+                matches!(
+                    &error,
+                    StoreError::CurrentDatabaseMissing { path } if path == &paths.current_db()
+                )
+            }
+            "tombstone" => matches!(
+                &error,
+                StoreError::CurrentTombstoned { path } if path == &paths.tombstone()
+            ),
+            "missing-stamp" => matches!(
+                &error,
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Missing,
+                    ..
+                }
+            ),
+            "malformed-stamp" => matches!(
+                &error,
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Malformed { .. },
+                    ..
+                }
+            ),
+            "mismatched-stamp" => matches!(
+                &error,
+                StoreError::InvalidExtractionStamp {
+                    issue: ExtractionStampIssue::Mismatch {
+                        expected: CURRENT_EXTRACTION_VERSION,
+                        found: 1
+                    },
+                    ..
+                }
+            ),
+            other => panic!("unknown Current contradiction fixture {other}"),
+        };
+        assert!(matched, "unexpected {expected} rejection: {error:?}");
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
 #[test]
 fn current_writer_is_state_gated_retains_lease_and_stamps_the_exact_owned_value() {
     let project = TempProject::new("current-writer");
@@ -874,6 +975,135 @@ fn missing_state_with_any_existing_database_artifact_fails_closed() {
     }
 }
 
+#[test]
+fn missing_state_with_database_artifact_rejects_read_and_status_with_or_without_lock() {
+    for with_lock in [false, true] {
+        for suffix in ["", "-wal", "-shm"] {
+            let project = TempProject::new("missing-artifact-read-status");
+            let paths = project.paths();
+            if with_lock {
+                drop(create_namespace(&paths));
+            } else {
+                std::fs::create_dir_all(paths.current_root())
+                    .expect("create lockless artifact namespace");
+            }
+            let artifact = PathBuf::from(format!("{}{suffix}", paths.current_db().display()));
+            std::fs::write(&artifact, b"reserved unknown database artifact")
+                .expect("stage unknown database artifact");
+            let before = snapshot_tree(project.path());
+
+            for error in [
+                Store::open_for_read(&paths, deadline(), || false)
+                    .expect_err("Missing artifact must reject read"),
+                Store::open_for_status(&paths, deadline(), || false)
+                    .expect_err("Missing artifact must reject status"),
+            ] {
+                assert!(matches!(
+                    error,
+                    StoreError::MissingStateWithDatabase { path } if path == artifact
+                ));
+                assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+            }
+        }
+    }
+}
+
+#[test]
+fn persisted_state_without_permanent_lock_is_typed_and_byte_nonmutating() {
+    for (phase, expected) in [
+        ("current", ExtractionStatus::Current),
+        (
+            "building",
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+        ),
+        ("uninitialized", ExtractionStatus::Uninitialized),
+    ] {
+        let project = TempProject::new("state-without-lock");
+        let paths = stage_state_without_lock(&project, phase);
+        let before = snapshot_tree(project.path());
+
+        for error in [
+            Store::open_for_read(&paths, deadline(), || false)
+                .expect_err("persisted lockless state must reject read"),
+            Store::open_for_status(&paths, deadline(), || false)
+                .expect_err("persisted lockless state must reject status"),
+        ] {
+            assert!(matches!(
+                error,
+                StoreError::StateWithoutPermanentLock { status, path }
+                    if status == expected && path == paths.permanent_lock()
+            ));
+            assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+        }
+    }
+}
+
+#[test]
+fn current_with_committed_wal_fails_closed_without_ignoring_or_mutating_sidecars() {
+    let project = TempProject::new("current-committed-wal");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    run_crashed_current_writer(project.path());
+    let wal_path = PathBuf::from(format!("{}-wal", paths.current_db().display()));
+    assert!(
+        std::fs::metadata(&wal_path)
+            .expect("committed WAL exists")
+            .len()
+            > 0,
+        "fixture must carry committed WAL frames"
+    );
+    let live = Connection::open_with_flags(paths.current_db(), OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .expect("open live WAL-aware proof connection");
+    assert_eq!(
+        live.query_row(
+            "SELECT value FROM project_metadata WHERE key = 'wal_only_probe'",
+            [],
+            |row| row.get::<_, String>(0),
+        )
+        .optional()
+        .expect("live SQLite observes committed WAL data"),
+        Some("committed".to_string())
+    );
+    drop(live);
+
+    let proof = TempProject::new("main-image-proof");
+    let main_only = proof.path().join("main-only.db");
+    let mut bytes = std::fs::read(paths.current_db()).expect("read checkpointed main DB image");
+    assert!(bytes.len() >= 20 && bytes.starts_with(b"SQLite format 3\0"));
+    bytes[18] = 1;
+    bytes[19] = 1;
+    std::fs::write(&main_only, bytes).expect("write private main-only proof image");
+    let main_conn = Connection::open_with_flags(&main_only, OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .expect("open main-only proof image");
+    let main_value = main_conn
+        .query_row(
+            "SELECT value FROM project_metadata WHERE key = 'wal_only_probe'",
+            [],
+            |row| row.get::<_, String>(0),
+        )
+        .optional()
+        .expect("query main-only proof image");
+    assert_eq!(
+        main_value, None,
+        "deserializing only main-file bytes would silently miss committed WAL data"
+    );
+
+    let before = snapshot_tree(project.path());
+    for error in [
+        Store::open_for_read(&paths, deadline(), || false)
+            .expect_err("Current with committed WAL must fail closed"),
+        Store::open_for_status(&paths, deadline(), || false)
+            .expect_err("Current status with committed WAL must fail closed"),
+    ] {
+        assert!(matches!(
+            error,
+            StoreError::CurrentWithDatabaseSidecar { path } if path == wal_path
+        ));
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
 /// Child-process entry point used by deterministic lock contention tests.
 #[test]
 fn store_gate_child_process() {
@@ -908,6 +1138,26 @@ fn store_gate_child_process() {
             Err(codegraph_store::IndexLeaseError::TimedOut { .. }) => println!("TIMED_OUT"),
             Err(error) => panic!("unexpected child probe error: {error}"),
         },
+        "write-current-wal-and-exit" => {
+            let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+                .expect("crash fixture acquires exclusive lease");
+            let StoreWriteOpen::Current(store) =
+                Store::open_for_write(&paths, lease, StoreWritePurpose::CurrentMutation)
+                    .expect("crash fixture opens state-gated Current writer")
+            else {
+                panic!("Current mutation must return an open Store");
+            };
+            store
+                .connection()
+                .pragma_update(None, "wal_autocheckpoint", 0)
+                .expect("disable WAL autocheckpoint in crash fixture");
+            store
+                .set_project_metadata("wal_only_probe", "committed")
+                .expect("commit WAL-only probe through state-gated writer");
+            println!("WAL_COMMITTED");
+            std::io::stdout().flush().expect("flush WAL sentinel");
+            std::process::exit(91);
+        }
         other => panic!("unknown Store gate child action {other}"),
     }
 }
@@ -1026,6 +1276,36 @@ fn run_exclusive_probe(project: &Path, process_bound: Duration) -> String {
         .to_string()
 }
 
+fn run_crashed_current_writer(project: &Path) {
+    let mut child = child_command(project, "write-current-wal-and-exit")
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()
+        .expect("spawn state-gated WAL crash fixture");
+    let mut stdout = child.stdout.take().expect("WAL fixture stdout");
+    let (output_tx, output_rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let mut output = String::new();
+        stdout
+            .read_to_string(&mut output)
+            .expect("read WAL fixture stdout");
+        output_tx.send(output).expect("send WAL fixture output");
+    });
+    let status = wait_bounded(&mut child, CHILD_WAIT);
+    assert_eq!(
+        status.code(),
+        Some(91),
+        "WAL fixture must terminate without running Rust/SQLite destructors"
+    );
+    let output = output_rx
+        .recv_timeout(CHILD_WAIT)
+        .expect("WAL fixture output before finite deadline");
+    assert!(
+        output.lines().any(|line| line == "WAL_COMMITTED"),
+        "WAL fixture emitted no commit sentinel: {output:?}"
+    );
+}
+
 fn wait_bounded(child: &mut Child, timeout: Duration) -> std::process::ExitStatus {
     let deadline = deadline_after(timeout);
     loop {
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e576b64..47e5099 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1488,6 +1488,64 @@ codegraph-store --all-targets --target x86_64-pc-windows-msvc --locked`
 - LSP diagnostics cannot attach to this external `/tmp` worktree, so the clean
   targeted Cargo diagnostics are the recorded fallback.
 
+## Correction (2026-07-25): close reviewed Store state/artifact gates
+
+Independent review rejected the Store slice above on contradictions with frozen
+Revision 14. This append supersedes only those claims; it does not rewrite the
+earlier evidence and still does not migrate CLI, MCP, watch, daemon, index,
+rebuild/finalizer, or uninit production callers.
+
+The corrected Store boundary now applies one closed state/artifact contract.
+`Missing` plus any DB, WAL, or SHM artifact is a typed, full-tree-byte-nonmutating
+failure for read, status, and write, whether the permanent lock exists or not.
+A persisted Current, Building, Outdated, or Uninitialized state without the
+permanent lock reports `StateWithoutPermanentLock`; Future/slot-Corrupt dominance
+remains unchanged. `extraction_status` remains the same slot-only nonmutating
+classifier.
+
+`FullRebuild + Current` now receives the same DB/tombstone/extraction-stamp
+corroboration as Current reads before an opaque authorization is returned. The
+ordinary Current writer revalidates its exact fixed lock path and held handle a
+second time at the final deterministic checkpoint immediately before the first
+read-write SQLite open. A private test checkpoint replaces the lock at that exact
+point; no sleeps infer the race.
+
+Executable WAL evidence used a state-gated Current writer in a child process,
+disabled autocheckpoint, committed a unique metadata row, then exited without
+running Rust/SQLite destructors. SQLite's real read-only pager observed the row
+from the retained WAL, while a rollback-header copy of only the main DB did not.
+Therefore a public Current namespace could previously be protocol-classified
+while the private deserialized main image silently ignored committed data. The
+corrected read/status/Current-corroboration path fails closed on any WAL or SHM
+sidecar and preserves the complete namespace tree byte-for-byte; a finalized
+Current namespace is pinned as sidecar-free.
+
+Finally, both `u64` and `i64` deserialize length conversions now occur before
+`sqlite3_malloc64`. Once the ownership-bearing allocation succeeds, no fallible
+Rust conversion can return before `sqlite3_deserialize` accepts
+`SQLITE_DESERIALIZE_FREEONCLOSE`; the existing no-double-free failure rule is
+unchanged.
+
+Behavioral Red was captured from the landed implementation: Current full rebuild
+accepted a missing DB; status returned clean Missing for DB residue; lockless
+persisted states surfaced the old lock error; Current reads accepted committed
+WAL and returned a private image that omitted its unique row; and deterministic
+late lock replacement still opened write-capable SQLite. After the minimal
+implementation, `store_state_gates` passes 21/21. The remaining required package,
+MSVC cross-compile, and final locked repository gates are recorded only after they
+run below; LSP still rejects this external `/tmp` worktree, so Cargo diagnostics
+remain the fallback.
+
+Focused implementation gates then passed in the prescribed order, with
+`bash scripts/check-workspace-versions.sh` before every Cargo batch and `--locked`
+on every dependency-resolving command: Store gates 21/21, accepted publisher
+14/14, lease 12/12, classifier 20/20, store lib 68/68, package all-target check,
+package Clippy with `-D warnings`, and the Linux-host
+`x86_64-pc-windows-msvc` all-target cross-check. The MSVC result is compilation
+only, not native Windows runtime/crash evidence. These are the final evidence
+bytes before `make fmt`; the authoritative final sequence is format, workspace
+version gate, locked `make ci`, lock hash, `git diff --check`, and scoped status.
+
 No dependency, schema, node-id formula, extraction output, or golden artifact
 changed. `Cargo.lock` remains required at
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.

From 6a175a5d9e529ab4e875a1b48ac85e4d6efcc8a7 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 01:20:06 +0800
Subject: [PATCH 21/91] feat(store): finalize full rebuild before publication

---
 crates/codegraph-cli/src/main.rs              |  218 ++-
 .../codegraph-cli/tests/batch_m_finalizer.rs  |  311 ++++
 crates/codegraph-store/src/connection.rs      |  202 ++-
 crates/codegraph-store/src/lib.rs             |    2 +
 crates/codegraph-store/src/rebuild.rs         | 1444 +++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  249 +++
 6 files changed, 2358 insertions(+), 68 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/batch_m_finalizer.rs
 create mode 100644 crates/codegraph-store/src/rebuild.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index bc8ade4..504c0c6 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1154,16 +1154,16 @@ fn cmd_prompt_hook(path: Option<PathBuf>, query: Option<String>) -> Result<()> {
 
 fn cmd_init(path: Option<PathBuf>, target: &str) -> Result<()> {
     let project = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
-    if is_initialized(&project) {
+    if explicit_init_observes_readable_current(&project)? {
         println!("Already initialized in {}", project.display());
         println!("Use \"codegraph index\" to re-index or \"codegraph sync\" to update");
         return installer::run_install_local_targets(project, target);
     }
     guard_indexable_root(&project)?;
-    let index_root = codegraph_dir(&project)?;
-    fs::create_dir_all(&index_root)
-        .with_context(|| format!("creating {}", index_root.display()))?;
-    let result = index_project(&project, true, false)?;
+    // The rebuild layer creates the current root and its permanent lock under the
+    // one outer exclusive lease; pre-creating it here would produce a lockless
+    // namespace that acquisition then refuses.
+    let result = index_project(&project, codegraph_store::RebuildKind::ExplicitInit)?;
     println!("Initialized in {}", project.display());
     print_index_result(&result);
     installer::run_install_local_targets(project, target)
@@ -1182,12 +1182,23 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
 }
 
 fn cmd_index(path: Option<PathBuf>, force: bool, quiet: bool, verbose: bool) -> Result<()> {
-    let project = resolve_required_project(path)?;
+    // Index is the one ordinary CLI surface allowed to retry an authenticated
+    // interrupted Building rebuild. Resolve state slots as well as a DB artifact
+    // so the crash window after deletion but before final writer creation remains
+    // reachable; authorization is still decided later under the exclusive lease.
+    let project = resolve_required_rebuild_project(path)?;
     guard_indexable_root(&project)?;
-    if force {
-        remove_db_files(&project)?;
-    }
-    let result = index_project_inner(&project, true, verbose, quiet)?;
+    // `--force` no longer removes the DB up front: the rebuild layer performs the
+    // destructive removal itself, AFTER publishing `phase=building` under the one
+    // outer exclusive lease, so an interruption can never leave a bare DB with no
+    // state marker. Plain `index` takes the same full-rebuild path it always did.
+    let _ = force;
+    let result = index_project_inner(
+        &project,
+        codegraph_store::RebuildKind::Reindex,
+        verbose,
+        quiet,
+    )?;
     if !quiet {
         print_index_result(&result);
     }
@@ -3418,28 +3429,82 @@ fn finish_phase(bar: &ProgressBar, label: &str) {
     bar.abandon_with_message(format!("✓ {label} ({elapsed})"));
 }
 
-fn index_project(project: &Path, clear_first: bool, verbose: bool) -> Result<IndexSummary> {
-    index_project_inner(project, clear_first, verbose, false)
+fn index_project(project: &Path, kind: codegraph_store::RebuildKind) -> Result<IndexSummary> {
+    index_project_inner(project, kind, false, false)
 }
 
-/// Restores the shared `synchronous=NORMAL` durability (and truncates the WAL) when
-/// the full index finishes OR bails out early via `?`. Drop never panics: a failed
-/// restore is logged, not propagated.
+/// Owns one destructive v2 rebuild for the whole full-index body.
+///
+/// `begin` acquires the single outer exclusive `IndexLease`, classifies under it,
+/// publishes `phase=building`, removes the previous v2 database files, and opens
+/// the fresh write-capable target. [`Self::finish`] is the EXPLICIT FALLIBLE
+/// completion path required by the frozen plan (lines 548-556): under the same
+/// retained lease it restores the shared `synchronous=NORMAL` durability, runs the
+/// final checkpoint + compaction, stamps extraction version 2, checkpoints that
+/// stamp into the main database file, closes the final SQLite connection, and only
+/// then publishes `phase=current` (removing a tombstone solely for a successful
+/// explicit `init`). Every failure propagates.
+///
+/// `Drop` is emergency best-effort cleanup only: it can never publish `Current`,
+/// so an index that bails out early via `?` leaves the namespace `phase=building`
+/// — unreadable and fail-closed — and a rerun rebuilds it from scratch.
+/// `Self::finish` consumes the guard, which is what disarms that fallback.
 struct BulkIndexPragmaGuard {
-    db_path: PathBuf,
+    rebuild: Option<codegraph_store::ActiveFullRebuild>,
+}
+
+/// Bounded wall-clock budget for acquiring the one outer exclusive lease. Never a
+/// blocking wait: `IndexLease` polls `try_lock` against this monotonic deadline.
+const REBUILD_LEASE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+
+impl BulkIndexPragmaGuard {
+    fn begin(
+        paths: &codegraph_core::IndexPaths,
+        kind: codegraph_store::RebuildKind,
+    ) -> Result<Self> {
+        let deadline = std::time::Instant::now() + REBUILD_LEASE_TIMEOUT;
+        let rebuild = codegraph_store::begin_full_rebuild(paths, kind, deadline, || false)?;
+        let rebuild = rebuild.open_store()?;
+        Ok(Self {
+            rebuild: Some(rebuild),
+        })
+    }
+
+    fn finish(mut self) -> Result<()> {
+        let rebuild = self
+            .rebuild
+            .take()
+            .expect("a rebuild guard is finished at most once");
+        rebuild.finish().map_err(Into::into)
+    }
+}
+
+impl std::ops::Deref for BulkIndexPragmaGuard {
+    type Target = codegraph_store::ActiveFullRebuild;
+
+    fn deref(&self) -> &Self::Target {
+        self.rebuild
+            .as_ref()
+            .expect("the CLI guard owns its active rebuild until finish")
+    }
+}
+
+impl std::ops::DerefMut for BulkIndexPragmaGuard {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.rebuild
+            .as_mut()
+            .expect("the CLI guard owns its active rebuild until finish")
+    }
 }
 
 impl Drop for BulkIndexPragmaGuard {
     fn drop(&mut self) {
-        let result = match Store::open(&self.db_path) {
-            Ok(store) => store.restore_default_pragmas().map_err(anyhow::Error::from),
-            Err(err) => Err(anyhow::Error::from(err)),
-        };
-        if let Err(err) = result {
+        if let Some(rebuild) = self.rebuild.take() {
+            // No publication happens here by construction: the namespace stays
+            // `phase=building`, so nothing can read a half-built graph.
             tracing::warn!(
-                error = %err,
-                db = %self.db_path.display(),
-                "failed to restore default pragmas after full index",
+                root = %rebuild.paths().current_root().display(),
+                "full index did not finalize; index remains phase=building and unreadable",
             );
         }
     }
@@ -3447,16 +3512,13 @@ impl Drop for BulkIndexPragmaGuard {
 
 fn index_project_inner(
     project: &Path,
-    clear_first: bool,
+    kind: codegraph_store::RebuildKind,
     verbose: bool,
     quiet: bool,
 ) -> Result<IndexSummary> {
     let started = std::time::Instant::now();
-    if clear_first {
-        remove_db_files(project)?;
-    }
-    let index_root = codegraph_dir(project)?;
-    fs::create_dir_all(&index_root)?;
+    let paths = index_paths(project)?;
+    let index_root = paths.current_root().to_path_buf();
     let config = codegraph_core::config::get_config();
     let options = ExtractOptions {
         max_file_size: config.indexing.max_file_size,
@@ -3471,16 +3533,18 @@ fn index_project_inner(
     }
     let files = codegraph_extract::engine::scan_project(project, &options)?;
 
+    // One destructive rebuild under ONE outer exclusive lease: classify, publish
+    // `phase=building`, remove the previous v2 DB files, then open the fresh
+    // write-capable target. The index root and DB are created by the rebuild
+    // layer, so nothing below reconstructs a path or reopens the namespace.
+    //
     // `synchronous=OFF` + a larger cache/mmap window speed up the from-scratch bulk
-    // index. The restore lives in a Drop guard, NOT a trailing statement, because
-    // every `?` below would skip a trailing restore and leave `synchronous=OFF`
-    // durable on the error path. Declared BEFORE `store` so it drops AFTER it: the
-    // guard's own connection then runs wal_checkpoint(TRUNCATE)+NORMAL with no WAL
-    // contention, leaving the file in the same shape a NORMAL run produces.
-    let _pragma_guard = BulkIndexPragmaGuard {
-        db_path: db_path(project)?,
-    };
-    let store = open_store(project)?;
+    // index. Their restore is part of the guard's EXPLICIT FALLIBLE `finish`, not a
+    // trailing statement, because every `?` below would skip a trailing restore.
+    // If the body bails out early, the guard's Drop only attempts state-gated
+    // pragma repair/compaction/close and publishes nothing: the namespace stays
+    // `phase=building` and unreadable.
+    let store = BulkIndexPragmaGuard::begin(&paths, kind)?;
     store.set_bulk_index_pragmas()?;
 
     let before = store.counts()?;
@@ -3807,14 +3871,15 @@ fn index_project_inner(
     resolver.run_post_extract(&mut store)?;
     finish_phase(&pb, "Finalized frameworks");
     store.set_project_metadata("indexed_with_version", VERSION)?;
-    store.set_project_metadata(
-        codegraph_store::EXTRACTION_VERSION_KEY,
-        &codegraph_store::CURRENT_EXTRACTION_VERSION.to_string(),
-    )?;
-    let pb = phase_spinner("Compacting database", quiet);
-    store.compact()?;
-    finish_phase(&pb, "Compacted database");
     let after = store.counts()?;
+    // Explicit fallible finalization: pragma restore -> checkpoint + compaction ->
+    // extraction stamp -> stamp checkpoint -> close the final connection ->
+    // publish `phase=current` (and remove a tombstone only for a successful
+    // explicit init). The namespace becomes readable at the LAST step, or not at
+    // all. Counts are read BEFORE the connection closes.
+    let pb = phase_spinner("Publishing index", quiet);
+    store.finish()?;
+    finish_phase(&pb, "Published index");
     Ok(IndexSummary {
         files_indexed,
         files_skipped,
@@ -4231,6 +4296,38 @@ fn is_initialized(project: &Path) -> bool {
     db_path(project).map(|p| p.exists()).unwrap_or(false)
 }
 
+/// Explicit init's early-return condition is a fully corroborated readable
+/// Current namespace, never raw DB existence. Current+tombstone is an expected
+/// retryable finalizer residue for explicit init, while every other Current
+/// inconsistency remains a typed error.
+fn explicit_init_observes_readable_current(project: &Path) -> Result<bool> {
+    let paths = index_paths(project)?;
+    if Store::extraction_status(&paths) != codegraph_store::ExtractionStatus::Current {
+        return Ok(false);
+    }
+    let deadline = std::time::Instant::now() + REBUILD_LEASE_TIMEOUT;
+    match Store::open_for_read(&paths, deadline, || false) {
+        Ok(store) => {
+            drop(store);
+            Ok(true)
+        }
+        Err(codegraph_store::StoreError::CurrentTombstoned { .. }) => Ok(false),
+        Err(error) => Err(error.into()),
+    }
+}
+
+/// Discovery predicate for the destructive `index` command. A durable state
+/// slot keeps an interrupted Building namespace discoverable even if the DB was
+/// already deleted. A raw DB remains discoverable only so the under-lease Store
+/// gate can reject Missing+DB as corruption; it is never interpreted as Current.
+fn has_rebuild_namespace(project: &Path) -> bool {
+    let Ok(paths) = index_paths(project) else {
+        return false;
+    };
+    Store::extraction_status(&paths) != codegraph_store::ExtractionStatus::Missing
+        || paths.current_db().exists()
+}
+
 fn resolve_required_project(path: Option<PathBuf>) -> Result<PathBuf> {
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
     let project = resolve_project_path_optional(&start);
@@ -4240,6 +4337,24 @@ fn resolve_required_project(path: Option<PathBuf>) -> Result<PathBuf> {
     Ok(project)
 }
 
+fn resolve_required_rebuild_project(path: Option<PathBuf>) -> Result<PathBuf> {
+    let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
+    if has_rebuild_namespace(&start) {
+        return Ok(start);
+    }
+    let mut current = start.as_path();
+    while let Some(parent) = current.parent() {
+        if parent == current {
+            break;
+        }
+        if has_rebuild_namespace(parent) {
+            return Ok(parent.to_path_buf());
+        }
+        current = parent;
+    }
+    bail!("CodeGraph not initialized in {}", start.display())
+}
+
 fn resolve_project_path_optional(start: &Path) -> PathBuf {
     if is_initialized(start) {
         return start.to_path_buf();
@@ -4317,17 +4432,6 @@ fn db_path(project: &Path) -> Result<PathBuf> {
     Ok(index_paths(project)?.current_db())
 }
 
-fn remove_db_files(project: &Path) -> Result<()> {
-    let db = db_path(project)?;
-    for suffix in ["", "-wal", "-shm"] {
-        let path = PathBuf::from(format!("{}{}", db.display(), suffix));
-        if path.exists() {
-            fs::remove_file(&path).with_context(|| format!("removing {}", path.display()))?;
-        }
-    }
-    Ok(())
-}
-
 fn parse_node_kind(raw: &str) -> Result<NodeKind> {
     NodeKind::ALL
         .into_iter()
diff --git a/crates/codegraph-cli/tests/batch_m_finalizer.rs b/crates/codegraph-cli/tests/batch_m_finalizer.rs
new file mode 100644
index 0000000..c2c8154
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_finalizer.rs
@@ -0,0 +1,311 @@
+//! Batch M — `full_sync_finalizer_publishes_current_last` public-surface Red.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md` lines 548-556 and test 8
+//! (line 746) require that a destructive v2 rebuild becomes a READABLE `Current`
+//! namespace only after every SQLite finalization step succeeded under the one
+//! retained exclusive lease: pragma restore, final checkpoint + compaction,
+//! extraction-version stamp, stamp checkpoint, and the final connection close.
+//! Only then may the rebuild atomically publish `phase=current`.
+//!
+//! This file is the black-box half of that slice: it drives the shipped
+//! `codegraph init` / `codegraph index --force` commands and then asks the
+//! state-gated store layer (the accepted `Store::extraction_status` /
+//! `Store::open_for_read` APIs from `f5c57f5`) whether the produced namespace is
+//! a readable `Current`. Before the finalizer lands, `init` builds the DB but
+//! publishes NO state slot at all, so classification is `Missing` and
+//! `open_for_read` refuses — a behavioral failure, not a compile or setup one
+//! (both assertions below are reached only after `init` succeeded and produced a
+//! non-empty DB).
+//!
+//! The deterministic fault matrix over every finalization boundary lives in the
+//! owning crate (`codegraph-store`, `src/rebuild.rs`), because the injection
+//! seams are private by design.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{ExtractionStatus, IndexLease, StatePhase, Store, publish_index_state};
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-batchm-finalizer-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    std::fs::create_dir_all(dst).unwrap();
+    for entry in std::fs::read_dir(src).unwrap() {
+        let entry = entry.unwrap();
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            std::fs::copy(&from, &to).unwrap();
+        }
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(registry_dir: &Path, args: &[&str]) -> Run {
+    let output = Command::new(bin())
+        .args(args)
+        .env("CODEGRAPH_HTTP_REGISTRY_DIR", registry_dir)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+fn deadline() -> Instant {
+    Instant::now()
+        .checked_add(Duration::from_secs(10))
+        .expect("finalizer test deadline")
+}
+
+/// Assert the namespace produced by a finished rebuild is a readable `Current`:
+/// the state slots classify `Current`, the tombstone is absent, the explicit
+/// checkpoint/compaction/close pipeline satisfies the sidecar-free Current
+/// artifact contract, and a state-gated read open serves rows.
+fn assert_readable_current(paths: &IndexPaths, context: &str) {
+    let status = Store::extraction_status(paths);
+    assert_eq!(
+        status,
+        ExtractionStatus::Current,
+        "{context}: the finished rebuild must publish phase=current as its LAST step \
+         (plan lines 548-556); observed {status:?}"
+    );
+    assert!(
+        !paths.tombstone().exists(),
+        "{context}: a successful explicit init must leave no tombstone at {}",
+        paths.tombstone().display()
+    );
+    let db = paths.current_db();
+    for suffix in ["-wal", "-shm"] {
+        let sidecar = PathBuf::from(format!("{}{suffix}", db.display()));
+        assert!(
+            !sidecar.exists(),
+            "{context}: final checkpoint/compaction and connection close must satisfy \
+             the sidecar-free Current artifact contract before publication; found {}",
+            sidecar.display()
+        );
+    }
+    let store = Store::open_for_read(paths, deadline(), || false).unwrap_or_else(|error| {
+        panic!("{context}: a finalized namespace must be readable through the state gate: {error}")
+    });
+    let counts = store
+        .counts()
+        .unwrap_or_else(|error| panic!("{context}: counts on a finalized namespace: {error}"));
+    assert!(
+        counts.node_count > 0,
+        "{context}: the finalized readable namespace must serve the built graph, got {} nodes",
+        counts.node_count
+    );
+}
+
+/// Stage the durable state left by an interrupted destructive rebuild. The
+/// permanent lock and `phase=building` slot are authentic; the final SQLite DB
+/// is independently present or absent to cover both user-reachable crash
+/// windows (before or after the fresh writer opens).
+fn stage_interrupted_building(paths: &IndexPaths, db_present: bool) {
+    let lease = IndexLease::create_exclusive(paths, deadline(), || false)
+        .expect("create the interrupted-rebuild namespace");
+    publish_index_state(paths, &lease, StatePhase::Building).expect("publish phase=building");
+    if db_present {
+        let store = Store::open(&paths.current_db()).expect("stage the partial rebuild DB");
+        store
+            .set_project_metadata("partial-rebuild", "true")
+            .expect("write partial rebuild evidence");
+        drop(store);
+    }
+    drop(lease);
+    assert_eq!(
+        Store::extraction_status(paths),
+        ExtractionStatus::Building {
+            built: codegraph_store::CURRENT_EXTRACTION_VERSION,
+        }
+    );
+}
+
+/// Plan test 8 (line 746) public boundary: only a completely successful rebuild
+/// becomes readable `Current`, and that holds for the initial explicit `init` as
+/// well as for an ordinary destructive `index --force` over the finished index.
+#[test]
+fn full_rebuild_publishes_readable_current_last_via_cli() {
+    let dir = TestDir::new("current-last");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    let run = run_in(dir.path(), &["init", p]);
+    assert!(
+        run.ok,
+        "setup: `codegraph init` must succeed before the behavioral assertion \
+         (stdout={}, stderr={})",
+        run.stdout, run.stderr
+    );
+    let paths = IndexPaths::resolve(&project, None).expect("resolve default v2 paths");
+    assert!(
+        std::fs::metadata(paths.current_db())
+            .map(|m| m.len() > 0)
+            .unwrap_or(false),
+        "setup: `init` must produce a non-empty v2 DB at {}",
+        paths.current_db().display()
+    );
+
+    assert_readable_current(&paths, "explicit init");
+
+    let reindex = run_in(dir.path(), &["index", "--force", p]);
+    assert!(
+        reindex.ok,
+        "setup: `codegraph index --force` must succeed: {} {}",
+        reindex.stdout, reindex.stderr
+    );
+    assert_readable_current(&paths, "index --force");
+}
+
+/// A raw partial DB is not proof of a healthy initialized index. Explicit init
+/// is the recovery surface for either interrupted-Building crash window.
+#[test]
+fn explicit_init_recovers_interrupted_building_with_db_present_or_absent() {
+    for db_present in [false, true] {
+        let dir = TestDir::new(if db_present {
+            "init-building-db-present"
+        } else {
+            "init-building-db-absent"
+        });
+        let project = dir.path().join("mini");
+        copy_tree(&mini_fixture(), &project);
+        let paths = IndexPaths::resolve(&project, None).expect("resolve default v2 paths");
+        stage_interrupted_building(&paths, db_present);
+
+        let run = run_in(dir.path(), &["init", project.to_str().unwrap()]);
+        assert!(
+            run.ok,
+            "explicit init must recover Building (db_present={db_present}): stdout={}, stderr={}",
+            run.stdout, run.stderr
+        );
+        assert!(
+            !run.stdout.contains("Already initialized"),
+            "a partial DB must not be mistaken for healthy Current: {}",
+            run.stdout
+        );
+        assert_readable_current(&paths, "explicit init retry after Building");
+    }
+}
+
+/// Ordinary index may retry an authenticated Building rebuild, whether the
+/// previous process crashed before or after creating the final DB artifact.
+#[test]
+fn index_recovers_interrupted_building_with_db_present_or_absent() {
+    for db_present in [false, true] {
+        let dir = TestDir::new(if db_present {
+            "index-building-db-present"
+        } else {
+            "index-building-db-absent"
+        });
+        let project = dir.path().join("mini");
+        copy_tree(&mini_fixture(), &project);
+        let paths = IndexPaths::resolve(&project, None).expect("resolve default v2 paths");
+        stage_interrupted_building(&paths, db_present);
+
+        let run = run_in(dir.path(), &["index", "--force", project.to_str().unwrap()]);
+        assert!(
+            run.ok,
+            "index must retry Building (db_present={db_present}): stdout={}, stderr={}",
+            run.stdout, run.stderr
+        );
+        assert_readable_current(&paths, "index retry after Building");
+    }
+}
+
+/// If the prior explicit init published Current but failed at tombstone removal,
+/// the namespace remains deliberately unreadable. A repeated explicit init is
+/// the recovery surface and must not misreport it as already initialized.
+#[test]
+fn explicit_init_recovers_current_with_tombstone_residue() {
+    let dir = TestDir::new("init-current-tombstone");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let p = project.to_str().unwrap();
+
+    let initial = run_in(dir.path(), &["init", p]);
+    assert!(
+        initial.ok,
+        "initial init must succeed: {} {}",
+        initial.stdout, initial.stderr
+    );
+    let paths = IndexPaths::resolve(&project, None).expect("resolve default v2 paths");
+    std::fs::write(paths.tombstone(), b"remove failed")
+        .expect("stage Current+tombstone finalizer residue");
+    assert!(
+        Store::open_for_read(&paths, deadline(), || false).is_err(),
+        "Current+tombstone must not be readable"
+    );
+
+    let retry = run_in(dir.path(), &["init", p]);
+    assert!(
+        retry.ok,
+        "explicit init must recover Current+tombstone: stdout={}, stderr={}",
+        retry.stdout, retry.stderr
+    );
+    assert!(
+        !retry.stdout.contains("Already initialized"),
+        "Current+tombstone is not a healthy Current namespace: {}",
+        retry.stdout
+    );
+    assert_readable_current(
+        &paths,
+        "explicit init retry after tombstone removal failure",
+    );
+}
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index 1879eb3..f78a81b 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -205,6 +205,20 @@ pub enum StoreError {
     },
     #[error("only a state-gated write Store may stamp the extraction version")]
     StampNotAuthorized,
+    #[error("only a state-gated write Store may be closed as a rebuild finalizer")]
+    CloseNotAuthorized,
+    #[error("failed to close the final SQLite connection for {path}: {source}")]
+    Close {
+        path: PathBuf,
+        #[source]
+        source: rusqlite::Error,
+    },
+    #[error("failed to checkpoint the SQLite write-ahead log for {path}: {source}")]
+    CheckpointWal {
+        path: PathBuf,
+        #[source]
+        source: rusqlite::Error,
+    },
     #[error("failed to stamp extraction version in SQLite database {path}: {source}")]
     StampExtractionVersion {
         path: PathBuf,
@@ -376,11 +390,33 @@ impl Store {
         Self::open_for_write_with(paths, lease, purpose, || {})
     }
 
+    /// Authorize the destructive rebuild used only by an explicit `init` retry.
+    /// Unlike an ordinary reindex, this narrow recovery surface may accept a
+    /// fully corroborated `Current` database whose tombstone remains after the
+    /// prior finalizer published Current but failed to remove that tombstone.
+    /// The namespace is still not readable until the explicit retry completes.
+    pub(crate) fn open_for_explicit_init_rebuild(
+        paths: &IndexPaths,
+        lease: IndexLease,
+    ) -> Result<StoreWriteOpen> {
+        Self::open_for_write_with_options(paths, lease, StoreWritePurpose::FullRebuild, true, || {})
+    }
+
     fn open_for_write_with(
         paths: &IndexPaths,
         lease: IndexLease,
         purpose: StoreWritePurpose,
         before_write_open: impl FnOnce(),
+    ) -> Result<StoreWriteOpen> {
+        Self::open_for_write_with_options(paths, lease, purpose, false, before_write_open)
+    }
+
+    fn open_for_write_with_options(
+        paths: &IndexPaths,
+        lease: IndexLease,
+        purpose: StoreWritePurpose,
+        allow_current_tombstone: bool,
+        before_write_open: impl FnOnce(),
     ) -> Result<StoreWriteOpen> {
         lease.validate_exclusive(paths)?;
         let status = Self::extraction_status(paths);
@@ -431,7 +467,8 @@ impl Store {
             }
             StoreWritePurpose::FullRebuild => {
                 if status == ExtractionStatus::Current {
-                    let (corroboration, source_conn) = corroborate_current_database(paths)?;
+                    let (corroboration, source_conn) =
+                        corroborate_current_database_with(paths, allow_current_tombstone)?;
                     drop(corroboration);
                     drop(source_conn);
                 }
@@ -456,11 +493,124 @@ impl Store {
         }
     }
 
+    /// Open the fresh, write-capable target of an in-progress destructive
+    /// rebuild under a clone of the caller's already-validated exclusive lease.
+    ///
+    /// The caller (`crate::rebuild`) has already published `phase=building` and
+    /// removed the previous database files, so this deliberately CREATES the
+    /// database and runs schema setup. It is not a state-classifying entry point:
+    /// classification happened once, before publication, in
+    /// [`Self::open_for_write`].
+    pub(crate) fn open_rebuild_target_with(
+        paths: &IndexPaths,
+        lease: &IndexLease,
+        before_open: impl FnOnce(),
+    ) -> Result<Self> {
+        let db_path = paths.current_db();
+        // `IndexLease::create_exclusive` created the root for an initial
+        // namespace, while existing acquisition proved it already existed. Do
+        // not insert filesystem work between this immediate capability check and
+        // SQLite's write-capable open.
+        before_open();
+        lease.validate_exclusive(paths)?;
+        let mut conn = Connection::open(&db_path).map_err(|source| StoreError::Open {
+            path: db_path.clone(),
+            source,
+        })?;
+        lease.validate_exclusive(paths)?;
+        migrations::configure_auto_vacuum_for_fresh_db(&conn).map_err(|source| {
+            StoreError::Configure {
+                path: db_path.clone(),
+                source,
+            }
+        })?;
+        configure_connection_for_rebuild(&conn, paths, lease, &db_path)?;
+        lease.validate_exclusive(paths)?;
+        migrations::ensure_schema_and_migrations(&mut conn).map_err(|source| {
+            StoreError::Migrate {
+                path: db_path.clone(),
+                source,
+            }
+        })?;
+        Ok(Self {
+            conn,
+            _source_conn: None,
+            path: db_path,
+            access: StoreAccess::StateWrite,
+            guarded_paths: Some(paths.clone()),
+            lease: Some(lease.clone()),
+        })
+    }
+
+    /// Fold the write-ahead log back into the main database file and truncate the
+    /// `-wal` sidecar. Used by the rebuild finalizer to make the extraction stamp
+    /// durable in the main file that `Current` corroboration deserializes.
+    pub(crate) fn checkpoint_wal_truncate(&self) -> Result<()> {
+        self.validate_state_write_authority()?;
+        self.conn
+            .pragma_update(None, "wal_checkpoint", "TRUNCATE")
+            .map_err(|source| StoreError::CheckpointWal {
+                path: self.path.clone(),
+                source,
+            })
+    }
+
+    /// Explicitly close the final SQLite connection of a state-gated writer,
+    /// propagating any close failure instead of discarding it in `Drop`. The
+    /// retained lease clone is released only after the connection is closed.
+    ///
+    /// Lease validation and SQLite close are necessarily separate API calls:
+    /// neither portable `std` nor SQLite exposes an atomic check-and-close
+    /// primitive. "Immediately before" therefore means that this method inserts
+    /// no other operation between the last capability validation and
+    /// [`Connection::close`]; it does not claim portable atomicity.
+    pub(crate) fn close(self) -> Result<()> {
+        if self.access != StoreAccess::StateWrite {
+            return Err(StoreError::CloseNotAuthorized);
+        }
+        // Closing a WAL connection may checkpoint or remove sidecars. Treat it
+        // as a finalization mutation boundary, not as an authority-free drop.
+        self.validate_state_write_authority()?;
+        let Self {
+            conn,
+            _source_conn,
+            path,
+            access: _,
+            guarded_paths: _,
+            lease,
+        } = self;
+        drop(_source_conn);
+        conn.close().map_err(|(_conn, source)| StoreError::Close {
+            path: path.clone(),
+            source,
+        })?;
+        // Explicit ordering: the lease clone is dropped only once no SQLite
+        // handle for this namespace remains open in this process.
+        drop(lease);
+        Ok(())
+    }
+
     /// Write the store-owned extraction metadata key and exact current decimal
     /// value. Read/status/legacy Stores are rejected before SQL execution.
     pub fn stamp_extraction_version(&self) -> Result<usize> {
+        self.validate_state_write_authority()
+            .map_err(|error| match error {
+                StoreError::CloseNotAuthorized => StoreError::StampNotAuthorized,
+                other => other,
+            })?;
+        self.set_project_metadata(
+            EXTRACTION_VERSION_KEY,
+            &CURRENT_EXTRACTION_VERSION.to_string(),
+        )
+        .map_err(|source| StoreError::StampExtractionVersion {
+            path: self.path.clone(),
+            source,
+        })
+    }
+
+    pub(crate) fn validate_state_write_authority(&self) -> Result<()> {
         if self.access != StoreAccess::StateWrite || self.lease.is_none() {
-            return Err(StoreError::StampNotAuthorized);
+            return Err(StoreError::CloseNotAuthorized);
         }
         let paths = self
             .guarded_paths
@@ -470,14 +620,7 @@ impl Store {
             .as_ref()
             .expect("state-gated write Store always retains its lease")
             .validate_exclusive(paths)?;
-        self.set_project_metadata(
-            EXTRACTION_VERSION_KEY,
-            &CURRENT_EXTRACTION_VERSION.to_string(),
-        )
-        .map_err(|source| StoreError::StampExtractionVersion {
-            path: self.path.clone(),
-            source,
-        })
+        Ok(())
     }
 
     pub fn connection(&self) -> &Connection {
@@ -506,8 +649,15 @@ fn open_current_read_only(paths: &IndexPaths, lease: IndexLease) -> Result<Store
 }
 
 fn corroborate_current_database(paths: &IndexPaths) -> Result<(Connection, Connection)> {
+    corroborate_current_database_with(paths, false)
+}
+
+fn corroborate_current_database_with(
+    paths: &IndexPaths,
+    allow_tombstone: bool,
+) -> Result<(Connection, Connection)> {
     let db_path = paths.current_db();
-    if artifact_exists(&paths.tombstone())? {
+    if !allow_tombstone && artifact_exists(&paths.tombstone())? {
         return Err(StoreError::CurrentTombstoned {
             path: paths.tombstone(),
         });
@@ -743,6 +893,36 @@ fn configure_connection(conn: &Connection) -> rusqlite::Result<()> {
     Ok(())
 }
 
+fn configure_connection_for_rebuild(
+    conn: &Connection,
+    paths: &IndexPaths,
+    lease: &IndexLease,
+    db_path: &Path,
+) -> Result<()> {
+    let configure = |result: rusqlite::Result<()>| {
+        result.map_err(|source| StoreError::Configure {
+            path: db_path.to_path_buf(),
+            source,
+        })
+    };
+
+    lease.validate_exclusive(paths)?;
+    configure(conn.busy_timeout(std::time::Duration::from_millis(5_000)))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "foreign_keys", "ON"))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "journal_mode", "WAL"))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "synchronous", "NORMAL"))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "cache_size", -64_000))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "temp_store", "MEMORY"))?;
+    lease.validate_exclusive(paths)?;
+    configure(conn.pragma_update(None, "mmap_size", 268_435_456_i64))?;
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index 9989501..a45e4e7 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -5,6 +5,7 @@ pub mod index_state;
 pub mod index_state_publisher;
 pub mod migrations;
 pub mod queries;
+pub mod rebuild;
 pub mod schema;
 
 pub use connection::{
@@ -23,3 +24,4 @@ pub use index_state_publisher::{
 pub use queries::{
     CODEGRAPH_NO_WAL_DEFER, CODEGRAPH_WAL_VALVE_MB, DEFAULT_WAL_VALVE_MB, wal_valve_threshold_bytes,
 };
+pub use rebuild::{ActiveFullRebuild, FullRebuild, RebuildError, RebuildKind, begin_full_rebuild};
diff --git a/crates/codegraph-store/src/rebuild.rs b/crates/codegraph-store/src/rebuild.rs
new file mode 100644
index 0000000..ce598b9
--- /dev/null
+++ b/crates/codegraph-store/src/rebuild.rs
@@ -0,0 +1,1444 @@
+//! Explicit, fallible finalization of a destructive v2 full rebuild.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md` lines 548-556: under ONE
+//! retained exclusive [`IndexLease`], a destructive rebuild
+//!
+//! 1. classifies the namespace and takes its write authorization,
+//! 2. publishes `phase=building` BEFORE deleting or mutating the database,
+//! 3. removes only the v2 `codegraph.db`, `-wal`, and `-shm`,
+//! 4. rebuilds into a fresh state-gated writer database, and
+//! 5. finalizes: restore default pragmas -> final checkpoint + compaction ->
+//!    stamp extraction version -> checkpoint that stamp into the main database ->
+//!    close the final SQLite connection.
+//!
+//! Only after every one of those steps succeeded may the rebuild atomically
+//! publish `phase=current`; it then removes a tombstone only for an explicit,
+//! successful `init`. Any earlier fault leaves the namespace `Building` (or
+//! `Missing`, before the first publication), fail-closed and unreadable. The
+//! handle's `Drop` is emergency best-effort only: it can never publish `Current`,
+//! because no publication call exists on that path.
+
+use std::io::{self, Write};
+use std::path::PathBuf;
+use std::time::Instant;
+
+use codegraph_core::IndexPaths;
+use thiserror::Error;
+
+use crate::connection::{Store, StoreError, StoreWriteOpen, StoreWritePurpose};
+use crate::{
+    IndexLease, IndexLeaseError, IndexLeaseValidationError, StatePhase, StatePublishError,
+    publish_index_state,
+};
+
+/// Which lifecycle command is performing the destructive rebuild.
+///
+/// The distinction is narrow and load-bearing: only an explicit, fully
+/// successful `init` may remove an existing tombstone.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RebuildKind {
+    /// `codegraph init` — an explicit initialization/recovery rebuild.
+    ExplicitInit,
+    /// `codegraph index` / forced migration — an ordinary destructive rebuild.
+    Reindex,
+}
+
+/// Deterministic finalization boundaries. Private: production always uses the
+/// no-op injector, while unit tests inject a fault after (or immediately before)
+/// each named boundary without any sleep or polling.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum RebuildCheckpoint {
+    BeforeWriteAuthorization,
+    BuildingPublished,
+    BeforeDatabaseRemoval,
+    DatabaseRemoved,
+    BeforePragmasRestored,
+    PragmasRestored,
+    BeforeCompaction,
+    Compacted,
+    BeforeVersionStamp,
+    VersionStamped,
+    BeforeStampCheckpoint,
+    StampCheckpointed,
+    BeforeConnectionClose,
+    ConnectionClosed,
+    BeforeCurrentPublication,
+    CurrentPublished,
+    BeforeTombstoneRemoval,
+    AfterTombstoneRemoval,
+}
+
+impl RebuildCheckpoint {
+    fn label(self) -> &'static str {
+        match self {
+            Self::BeforeWriteAuthorization => "classify for full-rebuild authorization",
+            Self::BuildingPublished => "publish phase=building",
+            Self::BeforeDatabaseRemoval => "prepare v2 database artifact removal",
+            Self::DatabaseRemoved => "remove v2 database files",
+            Self::BeforePragmasRestored => "prepare default pragma restoration",
+            Self::PragmasRestored => "restore default pragmas",
+            Self::BeforeCompaction => "prepare database checkpoint and compaction",
+            Self::Compacted => "checkpoint and compact the database",
+            Self::BeforeVersionStamp => "prepare extraction-version stamp",
+            Self::VersionStamped => "stamp the extraction version",
+            Self::BeforeStampCheckpoint => "prepare extraction-stamp checkpoint",
+            Self::StampCheckpointed => "checkpoint the extraction stamp into the main database",
+            Self::BeforeConnectionClose => "prepare final SQLite connection close",
+            Self::ConnectionClosed => "close the final SQLite connection",
+            Self::BeforeCurrentPublication => "prepare phase=current publication",
+            Self::CurrentPublished => "publish phase=current",
+            Self::BeforeTombstoneRemoval => "prepare uninitialized tombstone removal",
+            Self::AfterTombstoneRemoval => "after removing the uninitialized tombstone",
+        }
+    }
+}
+
+trait RebuildFault {
+    fn at(&mut self, checkpoint: RebuildCheckpoint) -> io::Result<()>;
+
+    fn remove_tombstone(&mut self, path: &std::path::Path) -> io::Result<()> {
+        std::fs::remove_file(path)
+    }
+}
+
+struct NoFault;
+
+impl RebuildFault for NoFault {
+    fn at(&mut self, _checkpoint: RebuildCheckpoint) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+/// Typed failures of a destructive rebuild's lease, state, or finalization work.
+#[derive(Debug, Error)]
+pub enum RebuildError {
+    /// The single outer exclusive lease could not be acquired or created.
+    #[error(transparent)]
+    Lease(#[from] IndexLeaseError),
+    /// The retained capability stopped authorizing this namespace.
+    #[error(transparent)]
+    LeaseValidation(#[from] IndexLeaseValidationError),
+    /// The state-gated store layer refused the rebuild.
+    #[error(transparent)]
+    Store(#[from] StoreError),
+    /// A state-slot publication failed.
+    #[error(transparent)]
+    Publish(#[from] StatePublishError),
+    /// The current root could not be inspected before lease selection.
+    #[error("cannot inspect index root {path}: {source}")]
+    InspectRoot {
+        /// Resolved current root.
+        path: PathBuf,
+        /// Operating-system error.
+        source: io::Error,
+    },
+    /// A v2 database artifact could not be removed under the lease.
+    #[error("cannot remove v2 database artifact {path}: {source}")]
+    RemoveDatabase {
+        /// Exact artifact path.
+        path: PathBuf,
+        /// Operating-system error.
+        source: io::Error,
+    },
+    /// An interrupted-uninit namespace was reached by an ordinary reindex.
+    #[error(
+        "index namespace {path} was left uninitialized; only an explicit `init` may rebuild it"
+    )]
+    UninitializedRequiresExplicitInit {
+        /// Resolved current root.
+        path: PathBuf,
+    },
+    /// The tombstone could not be removed after a successful explicit init.
+    #[error("cannot remove the uninitialized tombstone {path}: {source}")]
+    RemoveTombstone {
+        /// Tombstone path.
+        path: PathBuf,
+        /// Operating-system error.
+        source: io::Error,
+    },
+    /// A SQLite finalization statement failed.
+    #[error("cannot {step} for {path}: {source}")]
+    Finalize {
+        /// Stable finalization-step description.
+        step: &'static str,
+        /// Database path.
+        path: PathBuf,
+        /// SQLite error.
+        source: rusqlite::Error,
+    },
+    /// A deterministic test fault interrupted the rebuild at a named boundary.
+    #[error("interrupted rebuild at {step}: {source}")]
+    Interrupted {
+        /// Stable boundary description.
+        step: &'static str,
+        /// Injected error.
+        source: io::Error,
+    },
+}
+
+/// One destructive rebuild in progress: `phase=building` is already published and
+/// the previous database is already removed. The exclusive lease acquired before
+/// classification is retained here for the whole rebuild, including
+/// finalization, connection close, and the final `phase=current` publication.
+///
+/// Dropping this unopened handle deliberately performs NO publication: the
+/// namespace stays `phase=building`, unreadable and fail-closed, and a rerun
+/// rebuilds it from scratch. Once [`FullRebuild::open_store`] consumes it, the
+/// resulting [`ActiveFullRebuild`] owns the unique writer and its emergency
+/// best-effort, publication-free cleanup.
+#[derive(Debug)]
+pub struct FullRebuild {
+    paths: IndexPaths,
+    lease: IndexLease,
+    kind: RebuildKind,
+    // Retains the state-gated write authorization (and its own lease clone) for
+    // the rebuild's whole lifetime so the capability cannot be re-derived.
+    _authorization: crate::connection::StoreWriteAuthorization,
+}
+
+/// The unique final SQLite writer opened by one [`FullRebuild`]. The writer is
+/// owned by this typestate and cannot be supplied by a caller to [`Self::finish`],
+/// so finalization is necessarily tied to the exact path, lease, authorization,
+/// and connection opened by the rebuild capability.
+#[derive(Debug)]
+pub struct ActiveFullRebuild {
+    paths: IndexPaths,
+    lease: IndexLease,
+    kind: RebuildKind,
+    _authorization: crate::connection::StoreWriteAuthorization,
+    store: Option<Store>,
+}
+
+/// Acquire the single outer exclusive lease, classify under it, publish
+/// `phase=building`, and remove the previous v2 database files.
+pub fn begin_full_rebuild(
+    paths: &IndexPaths,
+    kind: RebuildKind,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+) -> Result<FullRebuild, RebuildError> {
+    begin_full_rebuild_with(paths, kind, deadline, cancelled, &mut NoFault)
+}
+
+fn begin_full_rebuild_with(
+    paths: &IndexPaths,
+    kind: RebuildKind,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+    fault: &mut impl RebuildFault,
+) -> Result<FullRebuild, RebuildError> {
+    let lease = acquire_outer_exclusive(paths, deadline, cancelled)?;
+    checkpoint(fault, RebuildCheckpoint::BeforeWriteAuthorization)?;
+    // Classification happens through the state gate under the already-held
+    // exclusive capability; a Future/Corrupt namespace is refused before any
+    // byte changes.
+    let authorized = if kind == RebuildKind::ExplicitInit {
+        Store::open_for_explicit_init_rebuild(paths, lease.clone())?
+    } else {
+        Store::open_for_write(paths, lease.clone(), StoreWritePurpose::FullRebuild)?
+    };
+    let authorization = match authorized {
+        StoreWriteOpen::FullRebuildRequired(authorization) => authorization,
+        other => {
+            unreachable!("FullRebuild purpose always yields FullRebuildRequired, got {other:?}")
+        }
+    };
+    // Authorization's status is the accepted classification performed while the
+    // exclusive lease was held. Never consult a precheck and then trust a second
+    // classification: that would create a classification/authorization TOCTOU.
+    if authorization.status() == &crate::ExtractionStatus::Uninitialized
+        && kind != RebuildKind::ExplicitInit
+    {
+        return Err(RebuildError::UninitializedRequiresExplicitInit {
+            path: paths.current_root().to_path_buf(),
+        });
+    }
+
+    // `phase=building` is durable BEFORE any destructive database work, so an
+    // interruption leaves an explicit, owner-bound marker instead of a bare DB.
+    publish_index_state(paths, &lease, StatePhase::Building)?;
+    checkpoint(fault, RebuildCheckpoint::BuildingPublished)?;
+    checkpoint(fault, RebuildCheckpoint::BeforeDatabaseRemoval)?;
+    remove_database_files(paths, &lease)?;
+    checkpoint(fault, RebuildCheckpoint::DatabaseRemoved)?;
+
+    Ok(FullRebuild {
+        paths: paths.clone(),
+        lease,
+        kind,
+        _authorization: authorization,
+    })
+}
+
+impl FullRebuild {
+    /// Which lifecycle command owns this rebuild.
+    #[must_use]
+    pub fn kind(&self) -> RebuildKind {
+        self.kind
+    }
+
+    /// The resolved paths this rebuild is bound to.
+    #[must_use]
+    pub fn paths(&self) -> &IndexPaths {
+        &self.paths
+    }
+
+    /// Consume the unopened capability and open its one final SQLite writer.
+    /// Consuming `self` makes a second live writer structurally impossible.
+    pub fn open_store(self) -> Result<ActiveFullRebuild, RebuildError> {
+        self.open_store_with(|| {})
+    }
+
+    fn open_store_with(
+        self,
+        before_open: impl FnOnce(),
+    ) -> Result<ActiveFullRebuild, RebuildError> {
+        let store = Store::open_rebuild_target_with(&self.paths, &self.lease, before_open)?;
+        Ok(ActiveFullRebuild {
+            paths: self.paths,
+            lease: self.lease,
+            kind: self.kind,
+            _authorization: self._authorization,
+            store: Some(store),
+        })
+    }
+}
+
+impl ActiveFullRebuild {
+    /// The resolved paths this active rebuild is bound to.
+    #[must_use]
+    pub fn paths(&self) -> &IndexPaths {
+        &self.paths
+    }
+
+    /// Access the exact writer owned by this rebuild.
+    #[must_use]
+    pub fn store(&self) -> &Store {
+        self.store
+            .as_ref()
+            .expect("an active rebuild owns its writer until finish")
+    }
+
+    /// Mutably access the exact writer owned by this rebuild.
+    #[must_use]
+    pub fn store_mut(&mut self) -> &mut Store {
+        self.store
+            .as_mut()
+            .expect("an active rebuild owns its writer until finish")
+    }
+
+    /// Apply the full-index pragma profile only after revalidating the retained
+    /// fixed-lock capability at this pragma mutation boundary.
+    pub fn set_bulk_index_pragmas(&self) -> Result<(), RebuildError> {
+        let store = self
+            .store
+            .as_ref()
+            .expect("an active rebuild owns its writer until finish");
+        let path = store.path().to_path_buf();
+        let pragma = |result: rusqlite::Result<()>| {
+            result.map_err(|source| RebuildError::Finalize {
+                step: "set bulk-index pragmas",
+                path: path.clone(),
+                source,
+            })
+        };
+        store.validate_state_write_authority()?;
+        pragma(store.connection().pragma_update(None, "synchronous", "OFF"))?;
+        store.validate_state_write_authority()?;
+        pragma(
+            store
+                .connection()
+                .pragma_update(None, "cache_size", -262_144),
+        )?;
+        store.validate_state_write_authority()?;
+        pragma(
+            store
+                .connection()
+                .pragma_update(None, "mmap_size", 1_073_741_824_i64),
+        )?;
+        if !matches!(std::env::var(crate::CODEGRAPH_NO_WAL_DEFER), Ok(value) if value == "1") {
+            store.validate_state_write_authority()?;
+            pragma(
+                store
+                    .connection()
+                    .pragma_update(None, "wal_autocheckpoint", 0),
+            )?;
+        }
+        Ok(())
+    }
+
+    /// Apply the bulk-index WAL valve only after revalidating the retained
+    /// capability at the checkpoint mutation boundary.
+    pub fn checkpoint_wal_if_over(&self, threshold_bytes: u64) -> Result<bool, RebuildError> {
+        let store = self
+            .store
+            .as_ref()
+            .expect("an active rebuild owns its writer until finish");
+        if store.wal_size_bytes() <= threshold_bytes {
+            return Ok(false);
+        }
+        store.validate_state_write_authority()?;
+        store
+            .connection()
+            .pragma_update(None, "wal_checkpoint", "TRUNCATE")
+            .map_err(|source| RebuildError::Finalize {
+                step: "checkpoint bulk-index WAL valve",
+                path: store.path().to_path_buf(),
+                source,
+            })?;
+        Ok(true)
+    }
+
+    /// Explicit fallible completion. Every step runs under the same retained
+    /// exclusive lease; any failure propagates and leaves the namespace
+    /// `Building` and unreadable.
+    pub fn finish(self) -> Result<(), RebuildError> {
+        self.finish_with(&mut NoFault)
+    }
+
+    fn finish_with(mut self, fault: &mut impl RebuildFault) -> Result<(), RebuildError> {
+        // `finish` consumes the handle, so a caller cannot finalize twice and an
+        // abandoned rebuild can only reach the publication-free Drop path.
+        let store = self
+            .store
+            .as_ref()
+            .expect("an active rebuild owns its final writer until finish");
+        let db_path = store.path().to_path_buf();
+
+        checkpoint(fault, RebuildCheckpoint::BeforePragmasRestored)?;
+        restore_default_pragmas(store, &db_path)?;
+        checkpoint(fault, RebuildCheckpoint::PragmasRestored)?;
+
+        checkpoint(fault, RebuildCheckpoint::BeforeCompaction)?;
+        compact(store, &db_path)?;
+        checkpoint(fault, RebuildCheckpoint::Compacted)?;
+
+        checkpoint(fault, RebuildCheckpoint::BeforeVersionStamp)?;
+        store.stamp_extraction_version()?;
+        checkpoint(fault, RebuildCheckpoint::VersionStamped)?;
+
+        // The stamp must live in the main database file, not only in the WAL:
+        // a Current namespace is corroborated from main-file bytes.
+        checkpoint(fault, RebuildCheckpoint::BeforeStampCheckpoint)?;
+        store.checkpoint_wal_truncate()?;
+        checkpoint(fault, RebuildCheckpoint::StampCheckpointed)?;
+
+        // Close the final SQLite connection (and drop its lease clone) BEFORE
+        // publishing Current, so no writer handle survives the transition. The
+        // outer lease below is still held by `self`.
+        checkpoint(fault, RebuildCheckpoint::BeforeConnectionClose)?;
+        let store = self
+            .store
+            .take()
+            .expect("the validated final writer is still owned before close");
+        store.close()?;
+        checkpoint(fault, RebuildCheckpoint::ConnectionClosed)?;
+
+        checkpoint(fault, RebuildCheckpoint::BeforeCurrentPublication)?;
+        publish_index_state(&self.paths, &self.lease, StatePhase::Current)?;
+        checkpoint(fault, RebuildCheckpoint::CurrentPublished)?;
+
+        if self.kind == RebuildKind::ExplicitInit {
+            // Current+tombstone is deliberately fail-closed. Revalidate the same
+            // retained fixed-lock handle immediately before the removal
+            // operation, then inject any deterministic failure AT that operation.
+            checkpoint(fault, RebuildCheckpoint::BeforeTombstoneRemoval)?;
+            self.lease.validate_exclusive(&self.paths)?;
+            remove_tombstone(&self.paths, fault)?;
+        }
+        checkpoint(fault, RebuildCheckpoint::AfterTombstoneRemoval)?;
+        Ok(())
+    }
+
+    /// Run the publication-free emergency cleanup used by [`Drop`]. The callback
+    /// is a private deterministic test seam at the last pre-close boundary;
+    /// production passes a no-op. Returning the close result lets the regression
+    /// prove that this path uses [`Store::close`]'s state gate rather than a raw
+    /// field drop. Validation and SQLite close remain separate API calls, so this
+    /// is an explicit best-effort boundary, not a claim of portable atomicity.
+    fn emergency_cleanup_with(
+        &mut self,
+        before_close: impl FnOnce(),
+    ) -> Option<Result<(), StoreError>> {
+        let store = self.store.take()?;
+        let path = store.path().to_path_buf();
+        if let Err(error) = restore_default_pragmas(&store, &path) {
+            log_emergency_cleanup_error("restore default pragmas", &path, &error);
+        }
+        if let Err(error) = compact(&store, &path) {
+            log_emergency_cleanup_error("compact the database", &path, &error);
+        }
+        before_close();
+        Some(store.close())
+    }
+}
+
+impl Drop for ActiveFullRebuild {
+    fn drop(&mut self) {
+        // Emergency cleanup is deliberately limited to operations safe while
+        // `phase=building`: best-effort pragma restoration/checkpoint and compact,
+        // each guarded by a fresh validation of the retained capability, followed
+        // by the explicit state-gated final connection close. There is no
+        // state-publication or tombstone-removal call in this path, so Drop
+        // structurally cannot publish Current.
+        if let Some(Err(error)) = self.emergency_cleanup_with(|| {}) {
+            let path = self.paths.current_db();
+            log_emergency_cleanup_error("close the final SQLite connection", &path, &error);
+        }
+    }
+}
+
+fn log_emergency_cleanup_error(step: &str, path: &std::path::Path, error: &dyn std::fmt::Display) {
+    // This crate intentionally has no logger dependency. STDERR is protocol-safe
+    // for CLI and stdio-MCP callers, unlike stdout. Ignore the write result so an
+    // emergency cleanup diagnostic can never turn Drop into a panic.
+    let _ = writeln!(
+        io::stderr().lock(),
+        "codegraph-store: emergency rebuild cleanup could not {step} for {}: {error}",
+        path.display()
+    );
+}
+
+impl std::ops::Deref for ActiveFullRebuild {
+    type Target = Store;
+
+    fn deref(&self) -> &Self::Target {
+        self.store()
+    }
+}
+
+impl std::ops::DerefMut for ActiveFullRebuild {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.store_mut()
+    }
+}
+
+fn restore_default_pragmas(store: &Store, path: &std::path::Path) -> Result<(), RebuildError> {
+    store.validate_state_write_authority()?;
+    store
+        .connection()
+        .pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::PragmasRestored.label(),
+            path: path.to_path_buf(),
+            source,
+        })?;
+    store.validate_state_write_authority()?;
+    store
+        .connection()
+        .pragma_update(None, "synchronous", "NORMAL")
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::PragmasRestored.label(),
+            path: path.to_path_buf(),
+            source,
+        })?;
+    Ok(())
+}
+
+fn compact(store: &Store, path: &std::path::Path) -> Result<(), RebuildError> {
+    store.validate_state_write_authority()?;
+    store
+        .connection()
+        .pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::Compacted.label(),
+            path: path.to_path_buf(),
+            source,
+        })?;
+    store.validate_state_write_authority()?;
+    let mut statement = store
+        .connection()
+        .prepare("PRAGMA incremental_vacuum")
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::Compacted.label(),
+            path: path.to_path_buf(),
+            source,
+        })?;
+    let mut rows = statement
+        .query([])
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::Compacted.label(),
+            path: path.to_path_buf(),
+            source,
+        })?;
+    while rows
+        .next()
+        .map_err(|source| RebuildError::Finalize {
+            step: RebuildCheckpoint::Compacted.label(),
+            path: path.to_path_buf(),
+            source,
+        })?
+        .is_some()
+    {}
+    Ok(())
+}
+
+fn checkpoint(
+    fault: &mut impl RebuildFault,
+    checkpoint: RebuildCheckpoint,
+) -> Result<(), RebuildError> {
+    fault
+        .at(checkpoint)
+        .map_err(|source| RebuildError::Interrupted {
+            step: checkpoint.label(),
+            source,
+        })
+}
+
+fn acquire_outer_exclusive(
+    paths: &IndexPaths,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+) -> Result<IndexLease, RebuildError> {
+    match std::fs::symlink_metadata(paths.current_root()) {
+        // An existing namespace is never repaired: its permanent lock must
+        // already exist, otherwise acquisition fails closed.
+        Ok(_) => Ok(IndexLease::acquire_exclusive_existing(
+            paths, deadline, cancelled,
+        )?),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {
+            Ok(IndexLease::create_exclusive(paths, deadline, cancelled)?)
+        }
+        Err(source) => Err(RebuildError::InspectRoot {
+            path: paths.current_root().to_path_buf(),
+            source,
+        }),
+    }
+}
+
+/// Remove only the v2 `codegraph.db`, `-wal`, and `-shm`. The legacy sibling is
+/// never a target, and no other namespace child is touched.
+fn remove_database_files(paths: &IndexPaths, lease: &IndexLease) -> Result<(), RebuildError> {
+    let db = paths.current_db();
+    for suffix in ["", "-wal", "-shm"] {
+        let path = PathBuf::from(format!("{}{suffix}", db.display()));
+        lease.validate_exclusive(paths)?;
+        match std::fs::remove_file(&path) {
+            Ok(()) => {}
+            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+            Err(source) => return Err(RebuildError::RemoveDatabase { path, source }),
+        }
+    }
+    Ok(())
+}
+
+fn remove_tombstone(paths: &IndexPaths, fault: &mut impl RebuildFault) -> Result<(), RebuildError> {
+    let path = paths.tombstone();
+    match fault.remove_tombstone(&path) {
+        Ok(()) => Ok(()),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(source) => Err(RebuildError::RemoveTombstone { path, source }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{CURRENT_EXTRACTION_VERSION, EXTRACTION_VERSION_KEY, ExtractionStatus};
+    use std::time::Duration;
+
+    struct TempProject(PathBuf);
+
+    impl TempProject {
+        fn new(label: &str) -> Self {
+            let path = std::env::temp_dir().join(format!(
+                "codegraph-rebuild-{label}-{}-{}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+            std::fs::create_dir(&path).expect("create rebuild unit project");
+            Self(path.canonicalize().expect("canonicalize rebuild project"))
+        }
+
+        fn paths(&self) -> IndexPaths {
+            IndexPaths::resolve(&self.0, None).expect("resolve rebuild unit paths")
+        }
+    }
+
+    impl Drop for TempProject {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    fn deadline() -> Instant {
+        Instant::now()
+            .checked_add(Duration::from_secs(10))
+            .expect("rebuild unit deadline")
+    }
+
+    /// Bounded deadline for refusal probes. It is NOT timing evidence: every
+    /// assertion using it also pins the classified state, and a lease-contention
+    /// refusal is rejected outright in [`assert_unreadable`].
+    fn short_deadline() -> Instant {
+        Instant::now()
+            .checked_add(Duration::from_millis(50))
+            .expect("rebuild unit short deadline")
+    }
+
+    struct FailAt(RebuildCheckpoint);
+
+    impl RebuildFault for FailAt {
+        fn at(&mut self, checkpoint: RebuildCheckpoint) -> io::Result<()> {
+            if checkpoint == self.0 {
+                Err(io::Error::other(format!(
+                    "injected rebuild fault at {checkpoint:?}"
+                )))
+            } else {
+                Ok(())
+            }
+        }
+    }
+
+    struct FailTombstoneRemoval;
+
+    impl RebuildFault for FailTombstoneRemoval {
+        fn at(&mut self, _checkpoint: RebuildCheckpoint) -> io::Result<()> {
+            Ok(())
+        }
+
+        fn remove_tombstone(&mut self, _path: &std::path::Path) -> io::Result<()> {
+            Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "injected failure at tombstone removal operation",
+            ))
+        }
+    }
+
+    struct PublishUninitializedBeforeAuthorization {
+        paths: IndexPaths,
+    }
+
+    impl RebuildFault for PublishUninitializedBeforeAuthorization {
+        fn at(&mut self, checkpoint: RebuildCheckpoint) -> io::Result<()> {
+            if checkpoint != RebuildCheckpoint::BeforeWriteAuthorization {
+                return Ok(());
+            }
+            let record = serde_json::json!({
+                "sequence": 0,
+                "storageProtocol": crate::CURRENT_STORAGE_PROTOCOL,
+                "extractionVersion": CURRENT_EXTRACTION_VERSION,
+                "phase": "uninitialized",
+                "projectIdentity": self.paths.project_identity(),
+                "checksum": crate::checksum_hex(
+                    0,
+                    crate::CURRENT_STORAGE_PROTOCOL,
+                    CURRENT_EXTRACTION_VERSION,
+                    "uninitialized",
+                    self.paths.project_identity(),
+                ),
+            });
+            std::fs::write(
+                &self.paths.state_slots()[0],
+                serde_json::to_vec(&record).expect("serialize test state"),
+            )
+        }
+    }
+
+    /// Replaces the fixed permanent lock immediately before the `phase=current`
+    /// publication, so the publication itself fails AFTER the database was fully
+    /// finalized and closed.
+    struct ReplaceLockBeforeCurrent {
+        lock: PathBuf,
+        displaced: PathBuf,
+    }
+
+    struct ReplaceLockAt {
+        checkpoint: RebuildCheckpoint,
+        lock: PathBuf,
+        displaced: PathBuf,
+    }
+
+    impl RebuildFault for ReplaceLockAt {
+        fn at(&mut self, checkpoint: RebuildCheckpoint) -> io::Result<()> {
+            if checkpoint == self.checkpoint {
+                std::fs::rename(&self.lock, &self.displaced)?;
+                std::fs::write(&self.lock, b"replacement at mutation boundary")?;
+            }
+            Ok(())
+        }
+    }
+
+    impl RebuildFault for ReplaceLockBeforeCurrent {
+        fn at(&mut self, checkpoint: RebuildCheckpoint) -> io::Result<()> {
+            if checkpoint == RebuildCheckpoint::BeforeCurrentPublication {
+                std::fs::rename(&self.lock, &self.displaced)?;
+                std::fs::write(&self.lock, b"late replacement")?;
+            }
+            Ok(())
+        }
+    }
+
+    fn build_graph(store: &Store) {
+        store
+            .set_project_metadata("indexed_with_version", "test")
+            .expect("write a metadata row into the rebuild target");
+    }
+
+    fn sidecars(paths: &IndexPaths) -> Vec<PathBuf> {
+        let db = paths.current_db();
+        ["-wal", "-shm"]
+            .into_iter()
+            .map(|suffix| PathBuf::from(format!("{}{suffix}", db.display())))
+            .filter(|path| path.exists())
+            .collect()
+    }
+
+    /// Fail-closed with NO writer holding the lease: the read gate must refuse on
+    /// state/artifact grounds, not merely because acquisition timed out.
+    fn assert_unreadable(paths: &IndexPaths, context: &str) {
+        let error = Store::open_for_read(paths, short_deadline(), || false)
+            .err()
+            .unwrap_or_else(|| panic!("{context}: an unfinished rebuild must not be readable"));
+        assert!(
+            !matches!(error, StoreError::Lease(_)),
+            "{context}: refusal must be a state/artifact refusal, not lease contention: {error}"
+        );
+        assert_ne!(
+            Store::extraction_status(paths),
+            ExtractionStatus::Current,
+            "{context}: an unfinished rebuild must never classify Current"
+        );
+    }
+
+    /// Fail-closed while the rebuild still holds its exclusive lease: any refusal
+    /// (state or bounded shared-acquisition timeout) is acceptable, but the state
+    /// must not be Current.
+    fn assert_unreadable_under_writer(paths: &IndexPaths, context: &str) {
+        assert!(
+            Store::open_for_read(paths, short_deadline(), || false).is_err(),
+            "{context}: a building namespace must never be readable"
+        );
+        assert_ne!(
+            Store::extraction_status(paths),
+            ExtractionStatus::Current,
+            "{context}: a building namespace must never classify Current"
+        );
+    }
+
+    /// Publish the authoritative `uninitialized` slot and then the tombstone, in
+    /// the exact order `uninit --force` uses, so the staged residue is a genuine
+    /// interrupted-uninit namespace rather than a contradictory Current+tombstone.
+    fn stage_interrupted_uninit(paths: &IndexPaths) {
+        let lease = IndexLease::acquire_exclusive_existing(paths, deadline(), || false)
+            .expect("acquire exclusive to stage an interrupted uninit");
+        publish_index_state(paths, &lease, StatePhase::Uninitialized)
+            .expect("publish the uninitialized slot");
+        std::fs::write(paths.tombstone(), b"uninitialized").expect("publish the tombstone");
+        drop(lease);
+        assert_eq!(
+            Store::extraction_status(paths),
+            ExtractionStatus::Uninitialized
+        );
+    }
+
+    fn run_successful_rebuild(paths: &IndexPaths, kind: RebuildKind) {
+        let rebuild = begin_full_rebuild(paths, kind, deadline(), || false)
+            .expect("begin a destructive rebuild");
+        let rebuild = rebuild.open_store().expect("open the rebuild target");
+        build_graph(&rebuild);
+        rebuild.finish().expect("finish the rebuild");
+    }
+
+    #[test]
+    fn successful_rebuild_publishes_readable_current_after_every_finalization_step() {
+        let project = TempProject::new("happy");
+        let paths = project.paths();
+
+        let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect("begin the initial rebuild");
+        // `phase=building` is durable before the graph exists, and the namespace
+        // is not readable while it builds.
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION
+            }
+        );
+        assert_unreadable_under_writer(&paths, "mid-rebuild");
+
+        let rebuild = rebuild.open_store().expect("open the rebuild target");
+        build_graph(&rebuild);
+        rebuild.finish().expect("finish the rebuild");
+
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+        assert!(
+            sidecars(&paths).is_empty(),
+            "the final checkpoint/compaction/close pipeline must satisfy the sidecar-free Current contract: {:?}",
+            sidecars(&paths)
+        );
+        let store = Store::open_for_read(&paths, deadline(), || false)
+            .expect("a finalized namespace must be readable through the state gate");
+        assert_eq!(
+            store
+                .get_project_metadata(EXTRACTION_VERSION_KEY)
+                .expect("read the extraction stamp"),
+            Some(CURRENT_EXTRACTION_VERSION.to_string()),
+            "the stamp must be checkpointed into the main database file"
+        );
+    }
+
+    #[test]
+    fn every_rebuild_fault_leaves_building_or_missing_and_unreadable() {
+        let pre_current = [
+            RebuildCheckpoint::BeforeWriteAuthorization,
+            RebuildCheckpoint::BuildingPublished,
+            RebuildCheckpoint::BeforeDatabaseRemoval,
+            RebuildCheckpoint::DatabaseRemoved,
+            RebuildCheckpoint::BeforePragmasRestored,
+            RebuildCheckpoint::PragmasRestored,
+            RebuildCheckpoint::BeforeCompaction,
+            RebuildCheckpoint::Compacted,
+            RebuildCheckpoint::BeforeVersionStamp,
+            RebuildCheckpoint::VersionStamped,
+            RebuildCheckpoint::BeforeStampCheckpoint,
+            RebuildCheckpoint::StampCheckpointed,
+            RebuildCheckpoint::BeforeConnectionClose,
+            RebuildCheckpoint::ConnectionClosed,
+            RebuildCheckpoint::BeforeCurrentPublication,
+        ];
+
+        for checkpoint in pre_current {
+            let project = TempProject::new("fault");
+            let paths = project.paths();
+            let mut fault = FailAt(checkpoint);
+
+            let begun = begin_full_rebuild_with(
+                &paths,
+                RebuildKind::ExplicitInit,
+                deadline(),
+                || false,
+                &mut fault,
+            );
+            match begun {
+                Err(error) => {
+                    assert!(
+                        matches!(error, RebuildError::Interrupted { .. }),
+                        "fault={checkpoint:?} must interrupt begin: {error}"
+                    );
+                }
+                Ok(rebuild) => {
+                    let rebuild = rebuild.open_store().expect("open the rebuild target");
+                    build_graph(&rebuild);
+                    let error = rebuild
+                        .finish_with(&mut fault)
+                        .expect_err("the injected fault must interrupt finalization");
+                    assert!(
+                        matches!(error, RebuildError::Interrupted { .. }),
+                        "fault={checkpoint:?} must interrupt finish: {error}"
+                    );
+                }
+            }
+
+            let status = Store::extraction_status(&paths);
+            assert!(
+                matches!(
+                    status,
+                    ExtractionStatus::Building { .. } | ExtractionStatus::Missing
+                ),
+                "fault={checkpoint:?} must leave Building or Missing, got {status:?}"
+            );
+            assert_unreadable(&paths, &format!("fault={checkpoint:?}"));
+        }
+    }
+
+    #[test]
+    fn faults_at_or_after_current_publication_have_already_published_current() {
+        for checkpoint in [
+            RebuildCheckpoint::CurrentPublished,
+            RebuildCheckpoint::AfterTombstoneRemoval,
+        ] {
+            let project = TempProject::new("post-current");
+            let paths = project.paths();
+            let mut fault = FailAt(checkpoint);
+
+            let rebuild = begin_full_rebuild_with(
+                &paths,
+                RebuildKind::ExplicitInit,
+                deadline(),
+                || false,
+                &mut fault,
+            )
+            .expect("begin the rebuild");
+            let rebuild = rebuild.open_store().expect("open the rebuild target");
+            build_graph(&rebuild);
+            let error = rebuild
+                .finish_with(&mut fault)
+                .expect_err("the injected fault must be reported");
+            assert!(matches!(error, RebuildError::Interrupted { .. }), "{error}");
+
+            // Current is published LAST, so a fault at/after it observes Current:
+            // the ordering guarantee is that nothing before it can be readable.
+            assert_eq!(
+                Store::extraction_status(&paths),
+                ExtractionStatus::Current,
+                "fault={checkpoint:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn failed_current_publication_after_finalization_never_becomes_readable_current() {
+        let project = TempProject::new("publish-fails");
+        let paths = project.paths();
+        let displaced = paths.current_root().join("displaced-index.lock");
+        let mut fault = ReplaceLockBeforeCurrent {
+            lock: paths.permanent_lock(),
+            displaced,
+        };
+
+        let rebuild = begin_full_rebuild_with(
+            &paths,
+            RebuildKind::ExplicitInit,
+            deadline(),
+            || false,
+            &mut fault,
+        )
+        .expect("begin the rebuild");
+        let rebuild = rebuild.open_store().expect("open the rebuild target");
+        build_graph(&rebuild);
+        let error = rebuild
+            .finish_with(&mut fault)
+            .expect_err("a replaced permanent lock must fail the Current publication");
+        assert!(
+            matches!(
+                error,
+                RebuildError::Publish(StatePublishError::Lease(
+                    IndexLeaseValidationError::PermanentLockChanged { .. }
+                ))
+            ),
+            "unexpected error: {error}"
+        );
+
+        // The database WAS finalized and closed before the publication attempt,
+        // yet the namespace must not be reported as a readable Current.
+        assert!(
+            sidecars(&paths).is_empty(),
+            "the final connection must already be closed: {:?}",
+            sidecars(&paths)
+        );
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION
+            },
+            "a failed Current publication must leave phase=building"
+        );
+        assert_unreadable(&paths, "failed Current publication");
+    }
+
+    #[test]
+    fn stale_lease_is_rejected_at_every_destructive_and_finalization_mutation_boundary() {
+        for checkpoint in [
+            RebuildCheckpoint::BeforeDatabaseRemoval,
+            RebuildCheckpoint::BeforePragmasRestored,
+            RebuildCheckpoint::BeforeCompaction,
+            RebuildCheckpoint::BeforeVersionStamp,
+            RebuildCheckpoint::BeforeStampCheckpoint,
+            RebuildCheckpoint::BeforeConnectionClose,
+            RebuildCheckpoint::BeforeCurrentPublication,
+            RebuildCheckpoint::BeforeTombstoneRemoval,
+        ] {
+            let project = TempProject::new("stale-boundary");
+            let paths = project.paths();
+            let displaced = paths.current_root().join(format!(
+                "displaced-{}.lock",
+                checkpoint.label().replace(' ', "-")
+            ));
+            let mut fault = ReplaceLockAt {
+                checkpoint,
+                lock: paths.permanent_lock(),
+                displaced,
+            };
+
+            let begun = begin_full_rebuild_with(
+                &paths,
+                RebuildKind::ExplicitInit,
+                deadline(),
+                || false,
+                &mut fault,
+            );
+            let error = match begun {
+                Err(error) => error,
+                Ok(rebuild) => {
+                    let rebuild = rebuild.open_store().expect("open the final writer");
+                    build_graph(&rebuild);
+                    if checkpoint == RebuildCheckpoint::BeforeTombstoneRemoval {
+                        std::fs::write(paths.tombstone(), b"retained")
+                            .expect("stage tombstone for the removal boundary");
+                    }
+                    rebuild
+                        .finish_with(&mut fault)
+                        .expect_err("a replaced lock must reject the next mutation")
+                }
+            };
+            assert!(
+                matches!(
+                    error,
+                    RebuildError::LeaseValidation(
+                        IndexLeaseValidationError::PermanentLockChanged { .. }
+                    ) | RebuildError::Store(StoreError::LeaseValidation(
+                        IndexLeaseValidationError::PermanentLockChanged { .. }
+                    )) | RebuildError::Publish(StatePublishError::Lease(
+                        IndexLeaseValidationError::PermanentLockChanged { .. }
+                    ))
+                ),
+                "checkpoint={checkpoint:?}: unexpected stale-lease result: {error}"
+            );
+            if checkpoint == RebuildCheckpoint::BeforeTombstoneRemoval {
+                assert!(
+                    paths.tombstone().exists(),
+                    "stale authority must be rejected before tombstone removal"
+                );
+            } else {
+                assert_ne!(
+                    Store::extraction_status(&paths),
+                    ExtractionStatus::Current,
+                    "checkpoint={checkpoint:?}: stale authority must not publish Current"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn stale_lease_is_rejected_immediately_before_write_capable_sqlite_open() {
+        let project = TempProject::new("stale-write-open");
+        let paths = project.paths();
+        let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect("begin rebuild before stale-open injection");
+        let displaced = paths.current_root().join("displaced-before-open.lock");
+        let error = rebuild
+            .open_store_with(|| {
+                std::fs::rename(paths.permanent_lock(), &displaced)
+                    .expect("displace fixed lock before SQLite open");
+                std::fs::write(paths.permanent_lock(), b"replacement before SQLite open")
+                    .expect("install replacement lock");
+            })
+            .expect_err("stale capability must reject the write-capable open");
+        assert!(
+            matches!(
+                error,
+                RebuildError::Store(StoreError::LeaseValidation(
+                    IndexLeaseValidationError::PermanentLockChanged { .. }
+                ))
+            ),
+            "unexpected stale-open error: {error}"
+        );
+        assert!(
+            !paths.current_db().exists(),
+            "revalidation must happen immediately before SQLite creates the DB"
+        );
+    }
+
+    #[test]
+    fn dropping_an_unfinished_rebuild_never_publishes_current() {
+        let project = TempProject::new("drop");
+        let paths = project.paths();
+
+        {
+            let rebuild =
+                begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+                    .expect("begin the rebuild");
+            let rebuild = rebuild.open_store().expect("open the rebuild target");
+            rebuild
+                .set_bulk_index_pragmas()
+                .expect("enable bulk pragmas before emergency cleanup");
+            build_graph(&rebuild);
+            drop(rebuild);
+        }
+
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION
+            },
+            "Drop is emergency cleanup only and must never publish Current"
+        );
+        assert!(
+            sidecars(&paths).is_empty(),
+            "Drop must best-effort checkpoint and close its writer: {:?}",
+            sidecars(&paths)
+        );
+        assert_unreadable(&paths, "dropped rebuild");
+    }
+
+    #[test]
+    fn emergency_cleanup_close_is_explicitly_state_gated() {
+        let project = TempProject::new("drop-close-gate");
+        let paths = project.paths();
+        let mut rebuild =
+            begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+                .expect("begin the rebuild")
+                .open_store()
+                .expect("open the rebuild target");
+        rebuild
+            .set_bulk_index_pragmas()
+            .expect("enable bulk pragmas before emergency cleanup");
+        build_graph(&rebuild);
+
+        let displaced = paths
+            .current_root()
+            .join("displaced-before-drop-close.lock");
+        let result = rebuild
+            .emergency_cleanup_with(|| {
+                // Deterministically replace the fixed lock AFTER emergency pragma
+                // restoration/compaction and immediately BEFORE the shared
+                // Store::close path validates. No sleep or race inference is used.
+                std::fs::rename(paths.permanent_lock(), &displaced)
+                    .expect("displace fixed lock before emergency close");
+                std::fs::write(
+                    paths.permanent_lock(),
+                    b"replacement before emergency close",
+                )
+                .expect("install replacement lock before emergency close");
+            })
+            .expect("the active rebuild owns one writer to close");
+        let error = result.expect_err("the explicit close gate must reject stale authority");
+        assert!(
+            matches!(
+                error,
+                StoreError::LeaseValidation(IndexLeaseValidationError::PermanentLockChanged { .. })
+            ),
+            "unexpected emergency-close result: {error}"
+        );
+        // The consumed Store necessarily falls back to Rust Drop after this
+        // validation error. This assertion proves the explicit close boundary
+        // was capability-gated; it does NOT claim validation+close atomicity or
+        // that resource release can be suppressed after ownership is consumed.
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+            "emergency close rejection must not publish Current"
+        );
+        assert!(
+            !paths.tombstone().exists(),
+            "emergency cleanup must have no tombstone-removal or creation path"
+        );
+    }
+
+    #[test]
+    fn reindex_refusal_uses_the_status_accepted_by_under_lease_authorization() {
+        let project = TempProject::new("authorization-status");
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+            .expect("stage a valid empty namespace");
+        drop(lease);
+        let mut fault = PublishUninitializedBeforeAuthorization {
+            paths: paths.clone(),
+        };
+
+        let error = begin_full_rebuild_with(
+            &paths,
+            RebuildKind::Reindex,
+            deadline(),
+            || false,
+            &mut fault,
+        )
+        .expect_err("Reindex must refuse the status accepted by authorization");
+        assert!(
+            matches!(
+                error,
+                RebuildError::UninitializedRequiresExplicitInit { .. }
+            ),
+            "unexpected error: {error}"
+        );
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Uninitialized
+        );
+        assert!(
+            !paths.current_db().exists(),
+            "refusal from accepted authorization must precede DB mutation"
+        );
+    }
+
+    #[test]
+    fn only_successful_explicit_init_removes_the_tombstone() {
+        let project = TempProject::new("tombstone-reindex");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        stage_interrupted_uninit(&paths);
+
+        // An ordinary reindex is not authorized for an interrupted-uninit
+        // namespace at all, so it can never reach tombstone removal.
+        let error = begin_full_rebuild(&paths, RebuildKind::Reindex, deadline(), || false)
+            .expect_err("a reindex must refuse an interrupted-uninit namespace");
+        assert!(
+            matches!(
+                error,
+                RebuildError::UninitializedRequiresExplicitInit { .. }
+            ),
+            "unexpected error: {error}"
+        );
+        assert!(
+            paths.tombstone().exists(),
+            "a refused reindex must never remove the tombstone"
+        );
+
+        // Explicit init: the tombstone is removed, but only after full success.
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        assert!(
+            !paths.tombstone().exists(),
+            "a successful explicit init must remove the tombstone"
+        );
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    }
+
+    #[test]
+    fn a_successful_reindex_preserves_an_unrelated_tombstone_free_namespace() {
+        // Complementary to the interrupted-uninit case: an ordinary reindex over a
+        // clean Current namespace never touches the tombstone path either.
+        let project = TempProject::new("tombstone-clean");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        run_successful_rebuild(&paths, RebuildKind::Reindex);
+        assert!(
+            !paths.tombstone().exists(),
+            "a reindex must not create a tombstone"
+        );
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    }
+
+    #[test]
+    fn an_earlier_fault_never_removes_the_tombstone() {
+        let project = TempProject::new("tombstone-fault");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        stage_interrupted_uninit(&paths);
+
+        let mut fault = FailAt(RebuildCheckpoint::ConnectionClosed);
+        let rebuild = begin_full_rebuild_with(
+            &paths,
+            RebuildKind::ExplicitInit,
+            deadline(),
+            || false,
+            &mut fault,
+        )
+        .expect("begin the rebuild");
+        let rebuild = rebuild.open_store().expect("open the rebuild target");
+        build_graph(&rebuild);
+        rebuild
+            .finish_with(&mut fault)
+            .expect_err("the injected fault must interrupt finalization");
+
+        assert!(
+            paths.tombstone().exists(),
+            "a failed rebuild must never remove the tombstone"
+        );
+    }
+
+    #[test]
+    fn tombstone_removal_failure_is_failed_closed_and_explicit_init_retry_recovers() {
+        let project = TempProject::new("tombstone-remove-failure");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        stage_interrupted_uninit(&paths);
+
+        let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect("begin explicit recovery");
+        let rebuild = rebuild.open_store().expect("open recovery writer");
+        build_graph(&rebuild);
+        let error = rebuild
+            .finish_with(&mut FailTombstoneRemoval)
+            .expect_err("the removal operation itself must fail");
+        assert!(
+            matches!(
+                error,
+                RebuildError::RemoveTombstone { ref source, .. }
+                    if source.kind() == io::ErrorKind::PermissionDenied
+            ),
+            "unexpected error: {error}"
+        );
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+        assert!(paths.tombstone().exists());
+        assert!(
+            matches!(
+                Store::open_for_read(&paths, deadline(), || false),
+                Err(StoreError::CurrentTombstoned { .. })
+            ),
+            "Current+tombstone must stay failed closed, never silently healthy"
+        );
+
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+        assert!(!paths.tombstone().exists());
+        Store::open_for_read(&paths, deadline(), || false)
+            .expect("an explicit-init retry must recover Current+tombstone residue");
+    }
+
+    #[test]
+    fn rebuild_retains_one_exclusive_lease_and_never_reacquires() {
+        let project = TempProject::new("lease");
+        let paths = project.paths();
+        let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect("begin the rebuild");
+        assert!(rebuild.lease.is_exclusive());
+        // A competing writer cannot acquire while the rebuild holds the lease,
+        // proving the capability is retained rather than released between steps.
+        let competing = IndexLease::acquire_exclusive_existing(
+            &paths,
+            Instant::now() + Duration::from_millis(50),
+            || false,
+        );
+        assert!(
+            matches!(competing, Err(IndexLeaseError::TimedOut { .. })),
+            "a retained exclusive lease must block a competing writer: {competing:?}"
+        );
+
+        let rebuild = rebuild.open_store().expect("open the rebuild target");
+        build_graph(&rebuild);
+        rebuild.finish().expect("finish the rebuild");
+
+        // Only after the rebuild handle is gone may another writer acquire.
+        IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("the lease is released once the finished rebuild is dropped");
+    }
+
+    #[test]
+    fn existing_root_without_a_permanent_lock_fails_closed() {
+        let project = TempProject::new("lockless");
+        let paths = project.paths();
+        std::fs::create_dir_all(paths.current_root()).expect("stage a lockless root");
+
+        let error = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect_err("a lockless existing namespace must never be repaired");
+        assert!(
+            matches!(
+                error,
+                RebuildError::Lease(IndexLeaseError::LockNotFound { .. })
+            ),
+            "unexpected error: {error}"
+        );
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Missing);
+        assert!(
+            !paths.current_db().exists(),
+            "a refused rebuild must not create a database"
+        );
+    }
+
+    #[test]
+    fn opening_the_final_writer_consumes_the_unopened_capability() {
+        let project = TempProject::new("single-writer");
+        let paths = project.paths();
+        let rebuild = begin_full_rebuild(&paths, RebuildKind::ExplicitInit, deadline(), || false)
+            .expect("begin the rebuild");
+        let rebuild = rebuild.open_store().expect("open the one final writer");
+        build_graph(&rebuild);
+        // `FullRebuild::open_store(self)` consumes the unopened capability. This
+        // is a compile-time ownership guarantee: there is no remaining value on
+        // which a second open can be invoked.
+        drop(rebuild);
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            },
+            "refusing a second writer must never publish Current"
+        );
+    }
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 47e5099..203035e 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1551,3 +1551,252 @@ changed. `Cargo.lock` remains required at
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
 These evidence bytes are written before formatting and the single final CI run;
 no terminal Green is claimed until that post-documentation gate passes.
+
+## Batch M — `full_sync_finalizer_publishes_current_last` (2026-07-25)
+
+Frozen plan lines 548-556 and test 8 (line 746) are now implemented: a destructive
+v2 rebuild becomes a readable `Current` namespace only after every SQLite
+finalization step succeeded under the ONE retained exclusive `IndexLease`.
+
+New `codegraph-store::rebuild` owns the whole rebuild lifecycle.
+`begin_full_rebuild(paths, kind, deadline, cancelled)` acquires the single outer
+exclusive lease (`create_exclusive` for a genuinely absent root,
+`acquire_exclusive_existing` otherwise — an existing lockless root is never
+repaired), refuses an interrupted-uninit namespace for anything but an explicit
+`init`, classifies through `Store::open_for_write(FullRebuild)` while retaining
+that authorization for the rebuild's whole lifetime, publishes `phase=building`
+BEFORE any destructive work, removes only v2 `codegraph.db`/`-wal`/`-shm`, and
+returns a `FullRebuild` handle. `FullRebuild::open_store` opens the fresh
+write-capable target through the new `Store::open_rebuild_target`, which
+revalidates `IndexLease::validate_exclusive` immediately before the first
+write-capable SQLite open.
+
+`FullRebuild::finish(store)` is the explicit fallible completion path, in exact
+order: restore default pragmas → final checkpoint + compaction → stamp extraction
+version 2 through the state-gated `Store::stamp_extraction_version` → checkpoint
+that stamp into the main database file (new `Store::checkpoint_wal_truncate`, so
+`Current` corroboration can read it from main-file bytes) → close the final SQLite
+connection (new `Store::close`, which propagates a close failure as typed
+`StoreError::Close` and drops the lease clone only after the connection is gone) →
+publish `phase=current` → remove the tombstone ONLY for a successful explicit
+`init`. Every step propagates. `finish` consumes the handle, so a caller cannot
+finalize twice; the handle's `Drop` performs NO publication at all, which is what
+keeps an abandoned rebuild at `phase=building`, unreadable and fail-closed.
+
+CLI wiring is the minimum coherent rebuild path. `BulkIndexPragmaGuard` no longer
+reopens the DB through legacy `Store::open` in `Drop`; it now owns the
+`FullRebuild` and exposes `begin`/`finish`. `index_project_inner` takes a
+`RebuildKind` instead of `clear_first`, no longer pre-creates the index root (the
+rebuild layer creates root + permanent lock under the lease), reads `counts()`
+before the connection closes, and finalizes through `pragma_guard.finish(store)`
+under a "Publishing index" phase line. `cmd_init` passes `ExplicitInit`;
+`cmd_index` passes `Reindex` and no longer removes the DB up front, because the
+destructive removal now happens after `phase=building` is durable. The unused
+`remove_db_files` helper and the redundant inline extraction-version stamp were
+deleted (the finalizer's state-gated stamp replaces the latter).
+
+Behavioral Red (compiling, public-surface, no sleeps): new
+`crates/codegraph-cli/tests/batch_m_finalizer.rs`
+`full_rebuild_publishes_readable_current_last_via_cli` drove the shipped
+`codegraph init` and then asked the accepted state gate. Command
+`cargo test -p codegraph-rs --locked --test batch_m_finalizer
+full_rebuild_publishes_readable_current_last_via_cli -- --exact` exited 101 with
+`0 passed; 1 failed` and the assertion
+`explicit init: the finished rebuild must publish phase=current as its LAST step
+(plan lines 548-556); observed Missing — left: Missing, right: Current`. Setup
+(`init` exit 0) and the non-empty v2 DB check both passed first, so this was
+behavioral, not a compile/setup/panic failure. The same command now exits 0.
+
+Deterministic fault matrix (private seams, unit-level, zero sleeps) in
+`rebuild.rs`: `every_rebuild_fault_leaves_building_or_missing_and_unreadable`
+injects a fault after each of Building publication, database removal, pragma
+restore, compaction, stamp, stamp checkpoint, connection close, and immediately
+before Current publication — every injection leaves `Building` or `Missing`, is
+unreadable through `Store::open_for_read`, and never classifies `Current`.
+`failed_current_publication_after_finalization_never_becomes_readable_current`
+replaces the fixed `index.lock` immediately before the publication, so the
+database is fully finalized and closed yet the publication fails with
+`PermanentLockChanged` and the namespace stays `phase=building` and unreadable —
+the case where publication itself fails after DB finalization.
+`faults_at_or_after_current_publication_have_already_published_current` pins the
+complementary direction. `dropping_an_unfinished_rebuild_never_publishes_current`
+proves `Drop` is emergency-only. `only_successful_explicit_init_removes_the_tombstone`
+stages a genuine interrupted-uninit namespace (authoritative `uninitialized` slot
+published first, then the tombstone) and proves a `Reindex` is refused outright,
+while a successful `ExplicitInit` removes the tombstone;
+`an_earlier_fault_never_removes_the_tombstone` proves an interrupted finalization
+never does. `a_successful_reindex_preserves_an_unrelated_tombstone_free_namespace`
+proves a reindex never creates one. `rebuild_retains_one_exclusive_lease_and_never_reacquires`
+proves a competing writer is blocked for the rebuild's whole life and succeeds only
+after the finished handle is dropped. `existing_root_without_a_permanent_lock_fails_closed`
+proves a lockless existing namespace is refused byte-nonmutating.
+
+Verification, with `bash scripts/check-workspace-versions.sh` (exit 0, workspace
+`0.40.4`) before every Cargo batch and `--locked` on every dependency-resolving
+command: `codegraph-store --lib rebuild` 10/10; full `cargo test -p
+codegraph-store` 155/0 across its seven suites; `cargo test -p codegraph-rs
+--locked --test batch_m_finalizer` 1/1; `cargo test --workspace --locked` exit 0
+with 2762 passed / 0 failed across 110 reporting suites (up from the 2695 recorded
+for the classifier correction, no test weakened, deleted, or filtered);
+`cargo check -p codegraph-store -p codegraph-rs --all-targets` clean;
+`cargo clippy -p codegraph-store -p codegraph-rs --all-targets -- -D warnings`
+clean; Linux-host `x86_64-pc-windows-msvc` all-target check clean for
+`codegraph-store` (the CLI package cannot be cross-checked here: its `--all-targets`
+build needs MSVC `lib.exe` for a C dependency, which is unavailable — the store
+result is compilation evidence only and no native Windows runtime, crash, or
+handle behavior is claimed).
+
+LSP diagnostics again rejected both changed Rust files because
+`/tmp/opencode/codegraph-rust-v15-impl` is outside the request cwd; Cargo
+check/Clippy/test remain the accepted fallback.
+
+Scope held: no daemon, watcher, MCP, uninit-continuation, project-scoped config, or
+extension-relocation work started; `sync`'s own migration-mode escalation remains a
+later slice. No dependency added, `Cargo.lock` untouched at
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, and no node-id
+formula, schema, extraction output, or golden artifact changed (the workspace run
+includes `codegraph-bench`'s golden byte-stability suites). These evidence bytes are
+written before `make fmt` and the single authoritative final locked `make ci`; no
+terminal Green is claimed until that post-documentation gate passes.
+
+## Batch M — rebuild finalizer correction (2026-07-26)
+
+Independent rereading of frozen Revision 14 (`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`)
+found six defects in the retained candidate above. This append-only correction
+supersedes only those claims; the original Red/Green history remains intact.
+
+1. CLI recovery no longer equates raw `codegraph.db` existence with a healthy
+   initialized namespace. `cmd_init` returns “Already initialized” only after a
+   typed `Current` classification is corroborated through `Store::open_for_read`.
+   `Current+tombstone` is explicitly retryable by `init`, while every other
+   Current inconsistency stays typed/fail-closed. `index` has a narrowly separate
+   discovery predicate that recognizes a durable non-Missing state even when an
+   interrupted Building rebuild already deleted the DB; actual authorization is
+   still decided later under the exclusive lease. Black-box regressions cover
+   `Building` with DB present and absent through both explicit `init` and
+   `index --force`, plus explicit-init recovery of `Current+tombstone` residue.
+2. `begin_full_rebuild` deleted the racy pre-authorization
+   `Store::extraction_status` decision. `Reindex` refusal now uses exactly
+   `StoreWriteAuthorization::status()`, the classification accepted by
+   `open_for_write` under the held lease. A deterministic checkpoint changes the
+   slot to `Uninitialized` before authorization and proves the accepted status,
+   not a stale precheck, controls refusal before DB mutation.
+3. The same retained lease is now revalidated immediately before every DB
+   artifact unlink, write-capable SQLite open, rebuild setup/final pragma,
+   checkpoint, compact, stamp, close, state publication (inside the accepted
+   publisher), and tombstone unlink boundary. The redundant `create_dir_all`
+   between validation and SQLite open is gone. Fresh lock-replacement tests cover
+   the write open and every destructive/finalization boundary without sleeps.
+4. `FullRebuild::open_store(&self) -> Store` was replaced by consuming typestate:
+   `FullRebuild::open_store(self) -> ActiveFullRebuild`. The active handle owns the
+   exact `IndexPaths`, retained capability/authorization, and sole final SQLite
+   writer. Its `finish(self)` accepts no caller-supplied Store, so a rebuild can
+   open at most one final writer and cannot publish after finalizing another
+   connection.
+5. Tombstone fault injection now fails at the actual `remove_file` operation with
+   `PermissionDenied`; the old after-success checkpoint is named only
+   `AfterTombstoneRemoval` and is not represented as a removal failure. The
+   operation failure leaves `Current+tombstone`, which remains unreadable and is
+   recoverable only through repeated explicit `init`; the retry rebuilds and then
+   removes the tombstone successfully.
+6. `ActiveFullRebuild::Drop` now implements the frozen emergency best-effort
+   cleanup: while retained authority still validates, it attempts default-pragma
+   restoration/checkpoint and compaction, then closes the owned writer. Its code
+   contains no state-publication or tombstone-removal path, so it structurally
+   cannot publish `Current`. The regression checks sidecar cleanup while the
+   authoritative state remains `Building` and unreadable.
+
+Valid correction Red: before the typestate change,
+`rebuild::tests::one_rebuild_handle_can_open_at_most_one_final_writer` compiled and
+failed because a second live SQLite writer opened successfully. The corrected
+focused batch is sleep-free and green: `cargo test -p codegraph-store --locked
+rebuild::tests -- --nocapture` reports 15 passed / 0 failed, and `cargo test -p
+codegraph-rs --locked --test batch_m_finalizer -- --nocapture` reports 4 passed /
+0 failed. `bash scripts/check-workspace-versions.sh` ran first and passed before
+each Cargo batch.
+
+Scope remains exactly the finalizer slice: no sync/watch migration escalation,
+uninit command/continuation implementation, daemon/MCP lifecycle relocation,
+project-scoped config, extension/Godot relocation, unlock, dependencies, schema,
+node-id, goldens, or Batches A-E. Final affected gates, MSVC store compile-only
+cross-check, formatter, and the one authoritative `make ci CARGO='cargo --locked'`
+are intentionally run only after these final evidence bytes land. Native Windows
+runtime/crash coverage is not claimed.
+
+## Batch M — emergency close-boundary correction (2026-07-26)
+
+Final review found that the emergency `ActiveFullRebuild::Drop` path described in
+correction item 6 above still relied on implicit field destruction for the final
+SQLite close. That was weaker than the frozen requirement: closing the last WAL
+connection is itself a mutation-capable SQLite boundary, so emergency cleanup
+must retain and revalidate the exact lease through the explicit close attempt.
+This append supersedes only the earlier implicit-close and sidecar-cleanup claims.
+
+`Store::close` is now the shared explicit state-gated close boundary. Its field
+order remains connection before lease, and it validates the retained capability
+immediately before `Connection::close`. The portable contract is deliberately
+narrow: validation and close are separate APIs, and neither Rust nor SQLite
+provides an atomic check-and-close primitive. `ActiveFullRebuild::Drop` performs
+best-effort pragma restoration/checkpoint and compaction, then calls that explicit
+close path and reports any error to stderr without panicking. It still contains
+no `publish_index_state` or tombstone-removal call, so an emergency drop cannot
+publish `Current`.
+
+The deterministic, sleep-free regression
+`emergency_cleanup_close_is_explicitly_state_gated` replaces `index.lock`
+immediately before `Store::close` and observes
+`IndexLeaseValidationError::PermanentLockChanged`. The focused rebuild batch now
+reports 16 passed / 0 failed; the CLI finalizer suite reports 4 passed / 0 failed;
+the complete `codegraph-store` package suite passes; affected-package all-target
+`cargo check` is clean; and affected-package all-target Clippy with `-D warnings`
+is clean. Every Cargo batch was preceded by
+`bash scripts/check-workspace-versions.sh` and used `--locked`.
+
+The attempted Linux-host `x86_64-pc-windows-msvc` all-target check did NOT
+produce compilation evidence: `libsqlite3-sys` rejected the available GNU
+compiler for that target and `cc-rs` failed to find `lib.exe` (`No such file or
+directory`). This is recorded as a host-toolchain limitation, not as a source
+failure, and no native Windows runtime/crash/handle claim is made. LSP likewise
+cannot attach to this external `/tmp` worktree (`LSP file path must be inside
+request cwd`); the clean targeted Cargo diagnostics are the fallback.
+
+These are pre-format evidence bytes. The terminal Green is recorded only after
+`make fmt`, one fresh authoritative `make ci CARGO='cargo --locked'`, the required
+`Cargo.lock` SHA-256 check, `git diff --check`, and scoped status inspection pass.
+
+## Batch M — finalizer authoritative gate handoff (2026-07-26)
+
+`full_sync_finalizer_publishes_current_last` is implemented and its verification is
+now closed except for one explicitly named gate. This append records the evidence
+actually observed; it supersedes no earlier claim and rewrites no historical
+failure.
+
+Delegated verification result (completed): focused rebuild batch 16 passed / 0
+failed; CLI finalizer suite 4 passed / 0 failed; the complete `codegraph-store`
+package suite green; affected-package all-target `cargo check` and Clippy with
+`-D warnings` green; and a delegated `make ci CARGO='cargo --locked'` green.
+
+Parent independent rerun (completed, not inherited): focused rebuild batch 16
+passed / 0 failed; CLI finalizer suite 4 passed / 0 failed; the full
+`codegraph-store` package green at 84 unit tests plus integration suites of 6, 12,
+20, 14, 4, and 21 tests; affected-package `cargo check` and Clippy green. No
+pre-existing test was weakened, deleted, filtered, or ignored.
+
+Parent hands-on CLI QA (completed): `codegraph --version` printed `0.40.4`; an
+unknown command exited nonzero; and on a fresh mini fixture, `init`, `status`,
+`index --force`, and a second `status` all succeeded, with each `status` reporting
+3 files, 13 nodes, 21 edges, the `.codegraph-v2/codegraph.db` path, and “Index is
+up to date”.
+
+Environment limitations, unchanged and still explicitly claimed as limitations:
+LSP diagnostics rejected every changed Rust file with `LSP file path must be
+inside request cwd`, so targeted Cargo diagnostics are the accepted fallback; and
+the attempted MSVC cross-check produced no evidence because `libsqlite3-sys` /
+`cc-rs` could not find `lib.exe`, so no native Windows runtime, crash, or handle
+behavior is claimed.
+
+These bytes are written BEFORE the parent's final `make fmt` and single
+authoritative `make ci CARGO='cargo --locked'`. That final run must cover these
+exact bytes, it is the sole remaining completion authority, and no later
+documentation edit is permitted. Apart from that one named gate, no validation for
+this item remains pending.

From c666381aa843b3a9e56b88a73411a6cdc86d7585 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 04:35:16 +0800
Subject: [PATCH 22/91] feat(sync): migrate outdated indexes during incremental
 sync

---
 .../tests/batch_m_outdated_migration.rs       | 517 ++++++++++++++++++
 crates/codegraph-core/src/config.rs           |  11 +
 crates/codegraph-store/src/connection.rs      |  92 +++-
 crates/codegraph-store/src/index_lease.rs     |  23 +
 crates/codegraph-store/src/lib.rs             |   5 +-
 crates/codegraph-store/src/rebuild.rs         | 245 ++++++++-
 crates/codegraph-watch/src/lib.rs             |   1 +
 crates/codegraph-watch/src/migrate.rs         | 194 +++++++
 crates/codegraph-watch/src/sync.rs            | 356 ++++++++++--
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 102 ++++
 10 files changed, 1483 insertions(+), 63 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/batch_m_outdated_migration.rs
 create mode 100644 crates/codegraph-watch/src/migrate.rs

diff --git a/crates/codegraph-cli/tests/batch_m_outdated_migration.rs b/crates/codegraph-cli/tests/batch_m_outdated_migration.rs
new file mode 100644
index 0000000..02266c9
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_outdated_migration.rs
@@ -0,0 +1,517 @@
+//! Batch M — `incremental_sync_on_outdated_v2_forces_all_files` (plan test 9,
+//! frozen plan `upstream-v1.5-portable-fixes.md` lines 557-565 and 750-751).
+//!
+//! `codegraph sync` must classify the namespace BEFORE mutating a single row.
+//! An `Outdated` v2 namespace (built by an older extraction version) therefore
+//! cannot be updated file-by-file: the sync escalates, under the SAME retained
+//! exclusive lease, to a deterministic full from-source migration that bypasses
+//! every mtime/content-hash skip, processes every current candidate in sorted
+//! order, drops tracked files that no longer exist, reruns framework extraction /
+//! resolution / maintenance, and publishes `phase=current` last. Its five
+//! canonical surfaces equal a fresh v2 `index --force`.
+//!
+//! `Future` and `Corrupt` states are refused with ZERO bytes changed anywhere in
+//! the index namespace, and an `uninitialized` namespace stays reserved for an
+//! explicit `init`.
+
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::time::{Duration, Instant};
+
+use codegraph_bench::oracle::{canonicalize_db, diff_canonical};
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, ExtractionStatus, Store, checksum_hex,
+};
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-batchm-migration-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    fs::create_dir_all(dst).unwrap();
+    for entry in fs::read_dir(src).unwrap() {
+        let entry = entry.unwrap();
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            fs::copy(&from, &to).unwrap();
+        }
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn cli(args: &[&str]) -> Run {
+    let output = Command::new(env!("CARGO_BIN_EXE_codegraph"))
+        .args(args)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+fn deadline() -> Instant {
+    Instant::now()
+        .checked_add(Duration::from_secs(10))
+        .expect("migration test deadline")
+}
+
+/// Author ONE authoritative fixed state slot with an explicit protocol/version/
+/// phase triple and remove the companion, so classification is unambiguous. The
+/// checksum comes from the shipped canonical payload helper, so the staged slot
+/// is a genuine protocol record rather than a hand-rolled approximation.
+fn stage_state_slot(
+    paths: &IndexPaths,
+    sequence: u64,
+    storage_protocol: u64,
+    extraction_version: u64,
+    phase: &str,
+) {
+    let identity = paths.project_identity();
+    let checksum = checksum_hex(
+        sequence,
+        storage_protocol,
+        extraction_version,
+        phase,
+        identity,
+    );
+    let body = format!(
+        "{{\"sequence\":{sequence},\"storageProtocol\":{storage_protocol},\
+         \"extractionVersion\":{extraction_version},\"phase\":\"{phase}\",\
+         \"projectIdentity\":\"{identity}\",\"checksum\":\"{checksum}\"}}\n"
+    );
+    let [slot0, slot1] = paths.state_slots();
+    fs::write(&slot0, body).expect("stage authoritative state slot");
+    let _ = fs::remove_file(&slot1);
+}
+
+/// Complete no-follow snapshot entry for the refused-sync nonmutation oracle.
+#[derive(Debug, PartialEq, Eq)]
+enum NamespaceEntry {
+    Directory,
+    File(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+/// Fail-closed snapshot of the complete index namespace. Directories are data
+/// (an empty directory has no other payload), regular files retain every byte,
+/// and aliases retain only their target without following it. Any I/O failure or
+/// unsupported entry kind aborts the proof instead of silently disappearing from
+/// both sides of the comparison.
+fn namespace_snapshot(root: &Path) -> BTreeMap<PathBuf, NamespaceEntry> {
+    fn walk(root: &Path, dir: &Path, out: &mut BTreeMap<PathBuf, NamespaceEntry>) {
+        let mut paths = fs::read_dir(dir)
+            .unwrap_or_else(|error| panic!("snapshot read_dir {}: {error}", dir.display()))
+            .map(|entry| {
+                entry
+                    .unwrap_or_else(|error| panic!("snapshot entry in {}: {error}", dir.display()))
+                    .path()
+            })
+            .collect::<Vec<_>>();
+        paths.sort();
+        for path in paths {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                .to_path_buf();
+            let metadata = fs::symlink_metadata(&path)
+                .unwrap_or_else(|error| panic!("snapshot metadata {}: {error}", path.display()));
+            let file_type = metadata.file_type();
+            let entry =
+                if file_type.is_dir() {
+                    NamespaceEntry::Directory
+                } else if file_type.is_file() {
+                    NamespaceEntry::File(fs::read(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read {}: {error}", path.display())
+                    }))
+                } else if file_type.is_symlink() {
+                    NamespaceEntry::Symlink(fs::read_link(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read_link {}: {error}", path.display())
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
+            assert!(
+                out.insert(relative, entry).is_none(),
+                "duplicate namespace snapshot path"
+            );
+            if file_type.is_dir() {
+                walk(root, &path, out);
+            }
+        }
+    }
+
+    let mut out = BTreeMap::new();
+    walk(root, root, &mut out);
+    out
+}
+
+/// Compare snapshots without dumping database bytes into a failure message.
+fn assert_namespace_unchanged(
+    before: &BTreeMap<PathBuf, NamespaceEntry>,
+    after: &BTreeMap<PathBuf, NamespaceEntry>,
+    label: &str,
+) {
+    let mut paths = before
+        .keys()
+        .chain(after.keys())
+        .cloned()
+        .collect::<Vec<_>>();
+    paths.sort();
+    paths.dedup();
+    let changed = paths
+        .into_iter()
+        .filter(|path| before.get(path) != after.get(path))
+        .collect::<Vec<_>>();
+    assert!(
+        changed.is_empty(),
+        "a refused {label} sync changed namespace entries: {changed:?}"
+    );
+}
+
+/// `Synced: N reindexed, M skipped (unchanged), K removed in …`
+fn parse_sync_counters(stdout: &str) -> (usize, usize, usize) {
+    let line = stdout
+        .lines()
+        .find(|line| line.starts_with("Synced: "))
+        .unwrap_or_else(|| panic!("sync must print its counters, got: {stdout}"));
+    let number_before = |needle: &str| -> usize {
+        let head = line
+            .split(needle)
+            .next()
+            .unwrap_or_else(|| panic!("missing {needle} in {line}"));
+        head.rsplit(|c: char| !c.is_ascii_digit())
+            .find(|token| !token.is_empty())
+            .unwrap_or_else(|| panic!("no count before {needle} in {line}"))
+            .parse()
+            .unwrap_or_else(|_| panic!("unparsable count before {needle} in {line}"))
+    };
+    (
+        number_before(" reindexed"),
+        number_before(" skipped"),
+        number_before(" removed"),
+    )
+}
+
+fn init_project(label: &str, dir: &TestDir) -> PathBuf {
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let run = cli(&["init", project.to_str().unwrap()]);
+    assert!(
+        run.ok,
+        "setup {label}: `codegraph init` must succeed (stdout={}, stderr={})",
+        run.stdout, run.stderr
+    );
+    project
+}
+
+/// A fresh, fully-indexed peer of `project` built by `init` + `index --force`,
+/// used as the canonical migration oracle.
+fn fresh_force_peer(label: &str, project: &Path) -> (TestDir, PathBuf) {
+    let scratch = TestDir::new(&format!("{label}-scratch"));
+    let peer = scratch.path().join("mini");
+    copy_tree(project, &peer);
+    let index_root = IndexPaths::resolve(&peer, None)
+        .expect("resolve peer v2 paths")
+        .current_root()
+        .to_path_buf();
+    let _ = fs::remove_dir_all(&index_root);
+    let run = cli(&["init", peer.to_str().unwrap()]);
+    assert!(
+        run.ok,
+        "setup {label}: peer init must succeed: {} {}",
+        run.stdout, run.stderr
+    );
+    let run = cli(&["index", "--force", peer.to_str().unwrap()]);
+    assert!(
+        run.ok,
+        "setup {label}: peer `index --force` must succeed: {} {}",
+        run.stdout, run.stderr
+    );
+    (scratch, peer)
+}
+
+/// Guard the nonmutation oracle itself: an equal-length in-place write must make
+/// its assertion fail, so the refusal tests cannot regress to a size-only proof.
+#[test]
+fn namespace_snapshot_detects_equal_length_byte_mutation() {
+    let dir = TestDir::new("snapshot-self-test");
+    let root = dir.path().join("index");
+    fs::create_dir(&root).expect("create snapshot root");
+    let file = root.join("state.json");
+    fs::write(&file, b"AAAA").expect("write original bytes");
+    let before = namespace_snapshot(&root);
+    fs::write(&file, b"BBBB").expect("replace with equal-length bytes");
+    let after = namespace_snapshot(&root);
+
+    let detected = std::panic::catch_unwind(|| {
+        assert_namespace_unchanged(&before, &after, "oracle-self-test")
+    });
+    assert!(
+        detected.is_err(),
+        "the namespace nonmutation oracle must reject equal-length byte changes"
+    );
+}
+
+/// Plan test 9: an `Outdated` namespace forces EVERY file through migration —
+/// zero unchanged skips even though every source byte is identical to the
+/// outdated database — and the result equals a fresh v2 `index --force`.
+#[test]
+fn incremental_sync_on_outdated_v2_forces_all_files() {
+    let dir = TestDir::new("outdated-forces-all");
+    let project = init_project("outdated-forces-all", &dir);
+    let paths = IndexPaths::resolve(&project, None).expect("resolve v2 paths");
+
+    // Every source file is byte-identical to what the index already holds, so an
+    // unguarded incremental sync would skip all of them on the hash gate.
+    let tracked = {
+        let store = Store::open_for_read(&paths, deadline(), || false)
+            .expect("the initialized namespace is readable");
+        store
+            .all_files()
+            .expect("tracked files")
+            .into_iter()
+            .map(|file| file.path)
+            .collect::<Vec<_>>()
+    };
+    assert!(
+        tracked.len() >= 2,
+        "the mini fixture must track several files, got {tracked:?}"
+    );
+
+    // The namespace was built by an OLDER extraction version.
+    stage_state_slot(
+        &paths,
+        100,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION - 1,
+        "current",
+    );
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Outdated {
+            built: CURRENT_EXTRACTION_VERSION - 1,
+        },
+        "setup: the staged slot must classify Outdated"
+    );
+
+    let run = cli(&["sync", project.to_str().unwrap()]);
+    assert!(
+        run.ok,
+        "sync must migrate an Outdated namespace: stdout={}, stderr={}",
+        run.stdout, run.stderr
+    );
+
+    let (reindexed, skipped, _removed) = parse_sync_counters(&run.stdout);
+    assert_eq!(
+        skipped, 0,
+        "an Outdated namespace must bypass every mtime/content-hash skip \
+         (plan lines 557-565); got {skipped} unchanged skips in: {}",
+        run.stdout
+    );
+    assert_eq!(
+        reindexed,
+        tracked.len(),
+        "migration must process EVERY current candidate, got {reindexed} of {} in: {}",
+        tracked.len(),
+        run.stdout
+    );
+
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Current,
+        "migration must publish phase=current as its last step"
+    );
+    Store::open_for_read(&paths, deadline(), || false)
+        .expect("a migrated namespace must be readable through the state gate");
+
+    let (_scratch, peer) = fresh_force_peer("outdated-forces-all", &project);
+    let migrated = canonicalize_db(&paths.current_db()).expect("canonicalize migrated db");
+    let rebuilt = canonicalize_db(
+        &IndexPaths::resolve(&peer, None)
+            .expect("resolve peer v2 paths")
+            .current_db(),
+    )
+    .expect("canonicalize peer db");
+    diff_canonical(&rebuilt, &migrated, None)
+        .expect("a forced migration must equal a fresh v2 `index --force`");
+}
+
+/// Migration is a from-source rebuild, so a tracked file that no longer exists
+/// on disk disappears from the migrated index and the result still equals a
+/// fresh `index --force` over the surviving tree.
+#[test]
+fn outdated_migration_drops_absent_tracked_files() {
+    let dir = TestDir::new("outdated-drops-absent");
+    let project = init_project("outdated-drops-absent", &dir);
+    let paths = IndexPaths::resolve(&project, None).expect("resolve v2 paths");
+
+    let removed_source = project.join("src/math.ts");
+    assert!(
+        removed_source.is_file(),
+        "setup: the mini fixture must contain src/math.ts"
+    );
+    fs::remove_file(&removed_source).expect("delete a tracked source file");
+
+    stage_state_slot(
+        &paths,
+        100,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION - 1,
+        "current",
+    );
+
+    let run = cli(&["sync", project.to_str().unwrap()]);
+    assert!(
+        run.ok,
+        "sync must migrate an Outdated namespace: stdout={}, stderr={}",
+        run.stdout, run.stderr
+    );
+
+    let store = Store::open_for_read(&paths, deadline(), || false)
+        .expect("a migrated namespace must be readable");
+    assert!(
+        store
+            .file_by_path("src/math.ts")
+            .expect("query tracked file")
+            .is_none(),
+        "migration must drop tracked files that no longer exist on disk"
+    );
+    drop(store);
+
+    let (_scratch, peer) = fresh_force_peer("outdated-drops-absent", &project);
+    let migrated = canonicalize_db(&paths.current_db()).expect("canonicalize migrated db");
+    let rebuilt = canonicalize_db(
+        &IndexPaths::resolve(&peer, None)
+            .expect("resolve peer v2 paths")
+            .current_db(),
+    )
+    .expect("canonicalize peer db");
+    diff_canonical(&rebuilt, &migrated, None)
+        .expect("a migration that dropped an absent file must equal a fresh `index --force`");
+}
+
+/// A `Future` or `Corrupt` namespace is refused by the sync writer gate before
+/// any row mutation, leaving every byte in the namespace unchanged.
+#[test]
+fn sync_refuses_future_and_corrupt_state_without_mutation() {
+    for label in ["future", "corrupt"] {
+        let dir = TestDir::new(&format!("refuse-{label}"));
+        let project = init_project(label, &dir);
+        let paths = IndexPaths::resolve(&project, None).expect("resolve v2 paths");
+
+        if label == "future" {
+            stage_state_slot(
+                &paths,
+                100,
+                CURRENT_STORAGE_PROTOCOL,
+                CURRENT_EXTRACTION_VERSION + 1,
+                "current",
+            );
+        } else {
+            let [slot0, slot1] = paths.state_slots();
+            fs::write(&slot0, b"{ not a state record").expect("stage a corrupt slot");
+            let _ = fs::remove_file(&slot1);
+        }
+        let status = Store::extraction_status(&paths);
+        assert!(
+            matches!(
+                status,
+                ExtractionStatus::Future { .. } | ExtractionStatus::Corrupt { .. }
+            ),
+            "setup {label}: staged slot must classify Future/Corrupt, got {status:?}"
+        );
+
+        let before = namespace_snapshot(paths.current_root());
+        let run = cli(&["sync", project.to_str().unwrap()]);
+        assert!(
+            !run.ok,
+            "sync must refuse a {label} namespace: stdout={}, stderr={}",
+            run.stdout, run.stderr
+        );
+        let after = namespace_snapshot(paths.current_root());
+        assert_namespace_unchanged(&before, &after, label);
+    }
+}
+
+/// An interrupted-`uninit` namespace stays reserved for an explicit `init`: a
+/// sync neither continues it nor mutates it.
+#[test]
+fn sync_refuses_uninitialized_namespace_without_mutation() {
+    let dir = TestDir::new("refuse-uninit");
+    let project = init_project("refuse-uninit", &dir);
+    let paths = IndexPaths::resolve(&project, None).expect("resolve v2 paths");
+
+    stage_state_slot(
+        &paths,
+        100,
+        CURRENT_STORAGE_PROTOCOL,
+        CURRENT_EXTRACTION_VERSION,
+        "uninitialized",
+    );
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Uninitialized,
+        "setup: the staged slot must classify Uninitialized"
+    );
+
+    let before = namespace_snapshot(paths.current_root());
+    let run = cli(&["sync", project.to_str().unwrap()]);
+    assert!(
+        !run.ok,
+        "sync must refuse an uninitialized namespace: stdout={}, stderr={}",
+        run.stdout, run.stderr
+    );
+    let after = namespace_snapshot(paths.current_root());
+    assert_namespace_unchanged(&before, &after, "uninitialized");
+}
diff --git a/crates/codegraph-core/src/config.rs b/crates/codegraph-core/src/config.rs
index 6d368fe..f677168 100644
--- a/crates/codegraph-core/src/config.rs
+++ b/crates/codegraph-core/src/config.rs
@@ -298,6 +298,17 @@ pub fn init_config(cli_path: Option<&Path>, project_root: &Path) -> Result<&'sta
     Ok(CONFIG.get().expect("just set"))
 }
 
+/// Borrow the global config only if `init_config` has already run.
+///
+/// Non-panicking counterpart of [`get_config`], for library code that must stay
+/// alive on a path where no binary initialized the global config (for example a
+/// watcher thread that escalates to a full migration). Callers fall back to the
+/// documented defaults instead of aborting the process.
+#[must_use]
+pub fn try_get_config() -> Option<&'static Config> {
+    CONFIG.get()
+}
+
 /// Borrow the global config after `init_config` has run.
 /// Panics if not initialized; for library use, prefer init_config().
 pub fn get_config() -> &'static Config {
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index f78a81b..3fcc21b 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -49,6 +49,13 @@ pub enum StoreWritePurpose {
     /// Retain exclusive authority for a later destructive full rebuild or
     /// explicit init recovery. This slice does not perform that rebuild.
     FullRebuild,
+    /// One incremental sync that must CLASSIFY BEFORE MUTATING A ROW. A
+    /// corroborated `Current` namespace is opened for ordinary incremental
+    /// mutation; `Missing`, `Outdated`, and a recoverable `Building` instead
+    /// return the lease-retaining full-rebuild authorization so the caller
+    /// escalates to a forced migration under the SAME exclusive lease. An
+    /// interrupted-`uninit` namespace stays reserved for an explicit `init`.
+    IncrementalSync,
     /// Retain exclusive authority for a later interrupted-uninit continuation.
     UninitContinuation,
 }
@@ -58,6 +65,7 @@ impl std::fmt::Display for StoreWritePurpose {
         formatter.write_str(match self {
             Self::CurrentMutation => "current mutation",
             Self::FullRebuild => "full rebuild",
+            Self::IncrementalSync => "incremental sync",
             Self::UninitContinuation => "uninit continuation",
         })
     }
@@ -90,6 +98,14 @@ impl StoreWriteAuthorization {
     pub fn retains_exclusive_lease(&self) -> bool {
         self.lease.is_exclusive()
     }
+
+    /// Clone the retained capability for a lifecycle operation this
+    /// authorization already authorizes. A clone NEVER unlocks (only the final
+    /// owner does), so handing one to the rebuild layer keeps the ONE outer
+    /// exclusive lease alive instead of releasing and reacquiring it.
+    pub(crate) fn clone_lease(&self) -> IndexLease {
+        self.lease.clone()
+    }
 }
 
 /// Result of a state-gated writer open.
@@ -434,10 +450,19 @@ impl Store {
         }
 
         match purpose {
-            StoreWritePurpose::CurrentMutation if status == ExtractionStatus::Current => {
+            StoreWritePurpose::CurrentMutation | StoreWritePurpose::IncrementalSync
+                if status == ExtractionStatus::Current =>
+            {
                 // Corroborate through a separate read-only/no-create handle before
-                // any write-capable setup can alter pragmas or sidecars.
-                let (corroboration, source_conn) = corroborate_current_database(paths)?;
+                // any write-capable setup can alter pragmas or sidecars. An
+                // incremental sync tolerates a live reader's sidecars (see
+                // `corroborate_current_database_options`); the stamp still comes
+                // from the checkpointed main-file bytes.
+                let (corroboration, source_conn) = corroborate_current_database_options(
+                    paths,
+                    false,
+                    purpose == StoreWritePurpose::IncrementalSync,
+                )?;
                 drop(corroboration);
                 drop(source_conn);
                 before_write_open();
@@ -465,6 +490,29 @@ impl Store {
                     lease: Some(lease),
                 })))
             }
+            // Frozen plan lines 557-565: an incremental sync classifies BEFORE
+            // row mutation. A namespace that is not a corroborated Current
+            // cannot be updated file-by-file, so Missing / Outdated / a
+            // recoverable Building escalate to a forced full migration through
+            // the SAME retained exclusive lease. Future/Corrupt were already
+            // refused above, and `Uninitialized` falls through to the catch-all
+            // rejection because only an explicit `init` may rebuild it.
+            StoreWritePurpose::IncrementalSync
+                if matches!(
+                    status,
+                    ExtractionStatus::Missing
+                        | ExtractionStatus::Outdated { .. }
+                        | ExtractionStatus::Building { .. }
+                ) =>
+            {
+                Ok(StoreWriteOpen::FullRebuildRequired(
+                    StoreWriteAuthorization {
+                        status,
+                        purpose,
+                        lease,
+                    },
+                ))
+            }
             StoreWritePurpose::FullRebuild => {
                 if status == ExtractionStatus::Current {
                     let (corroboration, source_conn) =
@@ -542,6 +590,22 @@ impl Store {
         })
     }
 
+    /// Explicit fallible completion of ONE state-gated incremental mutation of a
+    /// `Current` namespace: fold the write-ahead log back into the main database
+    /// file, then close the final SQLite connection (which releases this Store's
+    /// lease clone last). The namespace stays `Current` throughout — an
+    /// incremental sync republishes no state — so this attempts to restore the
+    /// checkpointed, sidecar-free artifact shape a new reader corroborates.
+    ///
+    /// The checkpoint is best-effort by SQLite's own contract: a concurrent
+    /// reader can leave the log un-truncated, which is reported as busy rather
+    /// than as an error. Any genuine failure propagates.
+    pub fn finish_current_mutation(self) -> Result<()> {
+        self.validate_state_write_authority()?;
+        self.checkpoint_wal_truncate()?;
+        self.close()
+    }
+
     /// Fold the write-ahead log back into the main database file and truncate the
     /// `-wal` sidecar. Used by the rebuild finalizer to make the extraction stamp
     /// durable in the main file that `Current` corroboration deserializes.
@@ -655,6 +719,26 @@ fn corroborate_current_database(paths: &IndexPaths) -> Result<(Connection, Conne
 fn corroborate_current_database_with(
     paths: &IndexPaths,
     allow_tombstone: bool,
+) -> Result<(Connection, Connection)> {
+    corroborate_current_database_options(paths, allow_tombstone, false)
+}
+
+/// Corroborate a `Current` namespace from its main-database bytes.
+///
+/// `allow_live_sidecar` relaxes ONLY the sidecar check, and only for a
+/// write-capable open. The sidecar-free rule is an artifact contract for the
+/// PUBLICATION and READ paths: the rebuild finalizer checkpoints the stamp into
+/// the main file and closes its connection before publishing `Current`, and a
+/// reader refuses a namespace whose sidecars reappeared without a state change.
+/// A live in-process reader (the MCP engine holds one for the server's whole
+/// life) legitimately recreates `-wal`/`-shm` on an untouched Current namespace,
+/// so demanding sidecar-freedom from an incremental WRITER would make every
+/// watcher sync inside `serve` fail. The stamp is still read from the
+/// already-checkpointed main-file bytes, so the version gate is unchanged.
+fn corroborate_current_database_options(
+    paths: &IndexPaths,
+    allow_tombstone: bool,
+    allow_live_sidecar: bool,
 ) -> Result<(Connection, Connection)> {
     let db_path = paths.current_db();
     if !allow_tombstone && artifact_exists(&paths.tombstone())? {
@@ -665,7 +749,7 @@ fn corroborate_current_database_with(
     if !artifact_exists(&db_path)? {
         return Err(StoreError::CurrentDatabaseMissing { path: db_path });
     }
-    if let Some(path) = first_existing_database_sidecar(paths)? {
+    if !allow_live_sidecar && let Some(path) = first_existing_database_sidecar(paths)? {
         return Err(StoreError::CurrentWithDatabaseSidecar { path });
     }
     let (conn, source_conn) = open_read_only_without_sidecars(&db_path)?;
diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs
index 568e8cf..a1ce8d9 100644
--- a/crates/codegraph-store/src/index_lease.rs
+++ b/crates/codegraph-store/src/index_lease.rs
@@ -152,6 +152,29 @@ impl IndexLease {
         Self::acquire_existing(paths, LeaseMode::Exclusive, deadline, cancelled)
     }
 
+    /// Acquire the ONE outer exclusive capability of a namespace that may or may
+    /// not exist yet: an existing current root must already carry its permanent
+    /// lock (never repaired), while a genuinely absent root is created together
+    /// with its lock. This is the single entry point every writer that owns a
+    /// whole lifecycle operation uses, so no caller re-implements the
+    /// existing-vs-initial decision or acquires a second, nested lease.
+    pub fn acquire_or_create_exclusive(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self, IndexLeaseError> {
+        match std::fs::symlink_metadata(paths.current_root()) {
+            Ok(_) => Self::acquire_exclusive_existing(paths, deadline, cancelled),
+            Err(error) if error.kind() == io::ErrorKind::NotFound => {
+                Self::create_exclusive(paths, deadline, cancelled)
+            }
+            Err(source) => Err(IndexLeaseError::CreateRoot {
+                path: paths.current_root().to_path_buf(),
+                source,
+            }),
+        }
+    }
+
     /// Explicitly create a genuinely absent current root and its permanent lock,
     /// then acquire the initial exclusive capability.
     pub fn create_exclusive(
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index a45e4e7..fd64a77 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -24,4 +24,7 @@ pub use index_state_publisher::{
 pub use queries::{
     CODEGRAPH_NO_WAL_DEFER, CODEGRAPH_WAL_VALVE_MB, DEFAULT_WAL_VALVE_MB, wal_valve_threshold_bytes,
 };
-pub use rebuild::{ActiveFullRebuild, FullRebuild, RebuildError, RebuildKind, begin_full_rebuild};
+pub use rebuild::{
+    ActiveFullRebuild, FullRebuild, RebuildError, RebuildKind, begin_full_rebuild,
+    resume_full_rebuild,
+};
diff --git a/crates/codegraph-store/src/rebuild.rs b/crates/codegraph-store/src/rebuild.rs
index ce598b9..81fd468 100644
--- a/crates/codegraph-store/src/rebuild.rs
+++ b/crates/codegraph-store/src/rebuild.rs
@@ -254,6 +254,64 @@ fn begin_full_rebuild_with(
         });
     }
 
+    begin_from_authorization(paths, lease, kind, authorization, fault)
+}
+
+/// Escalate an ALREADY-AUTHORIZED namespace to a destructive full rebuild using
+/// the exclusive lease the authorization still retains.
+///
+/// This is the migration entry point for an incremental sync that classified
+/// `Missing`, `Outdated`, or a recoverable `Building` under its one outer
+/// exclusive lease (frozen plan lines 557-565). No lease is acquired here: doing
+/// so would be a nested acquisition of a lock this process already holds. The
+/// retained authorization's status is the accepted classification, so no
+/// reclassification-after-precheck TOCTOU is possible.
+pub fn resume_full_rebuild(
+    paths: &IndexPaths,
+    authorization: crate::connection::StoreWriteAuthorization,
+) -> Result<FullRebuild, RebuildError> {
+    resume_full_rebuild_with(paths, authorization, &mut NoFault)
+}
+
+fn resume_full_rebuild_with(
+    paths: &IndexPaths,
+    authorization: crate::connection::StoreWriteAuthorization,
+    fault: &mut impl RebuildFault,
+) -> Result<FullRebuild, RebuildError> {
+    if authorization.purpose() != StoreWritePurpose::IncrementalSync {
+        return Err(RebuildError::Store(StoreError::WritePurposeRejected {
+            purpose: authorization.purpose(),
+            status: authorization.status().clone(),
+        }));
+    }
+    // Only the states the sync gate escalates may migrate. `Uninitialized` is
+    // never escalated: it is reserved for an explicit `init`.
+    match authorization.status() {
+        crate::ExtractionStatus::Missing
+        | crate::ExtractionStatus::Outdated { .. }
+        | crate::ExtractionStatus::Building { .. } => {}
+        other => {
+            return Err(RebuildError::Store(StoreError::WritePurposeRejected {
+                purpose: authorization.purpose(),
+                status: other.clone(),
+            }));
+        }
+    }
+    let lease = authorization.clone_lease();
+    lease.validate_exclusive(paths)?;
+    begin_from_authorization(paths, lease, RebuildKind::Reindex, authorization, fault)
+}
+
+/// Shared destructive prologue: publish `phase=building` BEFORE deleting any
+/// database byte, then remove only the v2 database files — all under the one
+/// already-held exclusive lease carried by `authorization`.
+fn begin_from_authorization(
+    paths: &IndexPaths,
+    lease: IndexLease,
+    kind: RebuildKind,
+    authorization: crate::connection::StoreWriteAuthorization,
+    fault: &mut impl RebuildFault,
+) -> Result<FullRebuild, RebuildError> {
     // `phase=building` is durable BEFORE any destructive database work, so an
     // interruption leaves an explicit, owner-bound marker instead of a bare DB.
     publish_index_state(paths, &lease, StatePhase::Building)?;
@@ -590,20 +648,13 @@ fn acquire_outer_exclusive(
     deadline: Instant,
     cancelled: impl FnMut() -> bool,
 ) -> Result<IndexLease, RebuildError> {
-    match std::fs::symlink_metadata(paths.current_root()) {
-        // An existing namespace is never repaired: its permanent lock must
-        // already exist, otherwise acquisition fails closed.
-        Ok(_) => Ok(IndexLease::acquire_exclusive_existing(
-            paths, deadline, cancelled,
-        )?),
-        Err(error) if error.kind() == io::ErrorKind::NotFound => {
-            Ok(IndexLease::create_exclusive(paths, deadline, cancelled)?)
-        }
-        Err(source) => Err(RebuildError::InspectRoot {
-            path: paths.current_root().to_path_buf(),
-            source,
-        }),
-    }
+    // An existing namespace is never repaired: its permanent lock must already
+    // exist, otherwise acquisition fails closed. The existing-vs-initial
+    // decision itself lives in `IndexLease` so every lifecycle owner (rebuild,
+    // forced sync migration) takes the SAME one outer capability.
+    Ok(IndexLease::acquire_or_create_exclusive(
+        paths, deadline, cancelled,
+    )?)
 }
 
 /// Remove only the v2 `codegraph.db`, `-wal`, and `-shm`. The legacy sibling is
@@ -1421,6 +1472,172 @@ mod tests {
         );
     }
 
+    /// Take the incremental-sync authorization the way a real sync does: ONE
+    /// outer exclusive lease, one classification under it.
+    fn incremental_sync_authorization(
+        paths: &IndexPaths,
+    ) -> Result<crate::connection::StoreWriteAuthorization, StoreError> {
+        let lease = IndexLease::acquire_or_create_exclusive(paths, deadline(), || false)
+            .expect("acquire the one outer exclusive lease");
+        match Store::open_for_write(paths, lease, StoreWritePurpose::IncrementalSync)? {
+            StoreWriteOpen::FullRebuildRequired(authorization) => Ok(authorization),
+            other => panic!("expected an escalation authorization, got {other:?}"),
+        }
+    }
+
+    /// A sync that classified `Outdated` escalates through the SAME retained
+    /// lease: `resume_full_rebuild` acquires nothing, publishes `phase=building`
+    /// before touching the database, and finalizes to a readable `Current`.
+    #[test]
+    fn resume_full_rebuild_migrates_outdated_under_the_retained_lease() {
+        let project = TempProject::new("resume-outdated");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+
+        // Stage an OLDER built version through the accepted publisher path, then
+        // rewrite only the version field of the authoritative slot.
+        let outdated = CURRENT_EXTRACTION_VERSION - 1;
+        let record = serde_json::json!({
+            "sequence": 99,
+            "storageProtocol": crate::CURRENT_STORAGE_PROTOCOL,
+            "extractionVersion": outdated,
+            "phase": "current",
+            "projectIdentity": paths.project_identity(),
+            "checksum": crate::checksum_hex(
+                99,
+                crate::CURRENT_STORAGE_PROTOCOL,
+                outdated,
+                "current",
+                paths.project_identity(),
+            ),
+        });
+        std::fs::write(
+            &paths.state_slots()[0],
+            serde_json::to_vec(&record).expect("serialize the outdated slot"),
+        )
+        .expect("stage the outdated slot");
+        let _ = std::fs::remove_file(&paths.state_slots()[1]);
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Outdated { built: outdated }
+        );
+
+        let authorization =
+            incremental_sync_authorization(&paths).expect("Outdated must authorize escalation");
+        assert!(
+            authorization.retains_exclusive_lease(),
+            "the escalation authorization must still own the one outer exclusive lease"
+        );
+        let rebuild = resume_full_rebuild(&paths, authorization).expect("resume the full rebuild");
+        // Publication precedes destruction, so an interruption here is Building.
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Building {
+                built: CURRENT_EXTRACTION_VERSION,
+            }
+        );
+        assert!(
+            !paths.current_db().exists(),
+            "the outdated database must be removed after phase=building is durable"
+        );
+        let rebuild = rebuild.open_store().expect("open the migration writer");
+        build_graph(&rebuild);
+        rebuild.finish().expect("finalize the migration");
+
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+        Store::open_for_read(&paths, deadline(), || false)
+            .expect("a finalized migration must be readable");
+    }
+
+    /// The incremental-sync gate is state-directed: only Missing/Outdated/
+    /// Building escalate. A corroborated Current opens the incremental writer,
+    /// and an interrupted-uninit namespace is refused outright.
+    #[test]
+    fn incremental_sync_gate_escalates_only_the_migratable_states() {
+        let missing = TempProject::new("gate-missing");
+        let missing_paths = missing.paths();
+        incremental_sync_authorization(&missing_paths)
+            .expect("Missing must authorize escalation, not a row-level update");
+
+        let current = TempProject::new("gate-current");
+        let current_paths = current.paths();
+        run_successful_rebuild(&current_paths, RebuildKind::ExplicitInit);
+        let lease = IndexLease::acquire_or_create_exclusive(&current_paths, deadline(), || false)
+            .expect("acquire exclusive over the Current namespace");
+        match Store::open_for_write(&current_paths, lease, StoreWritePurpose::IncrementalSync)
+            .expect("Current must authorize an incremental writer")
+        {
+            StoreWriteOpen::Current(_) => {}
+            other => panic!("Current must stay incremental, got {other:?}"),
+        }
+
+        let building = TempProject::new("gate-building");
+        let building_paths = building.paths();
+        let begun = begin_full_rebuild(&building_paths, RebuildKind::Reindex, deadline(), || false)
+            .expect("stage an interrupted Building namespace");
+        drop(begun);
+        incremental_sync_authorization(&building_paths)
+            .expect("a recoverable Building must authorize escalation");
+
+        let uninit = TempProject::new("gate-uninit");
+        let uninit_paths = uninit.paths();
+        run_successful_rebuild(&uninit_paths, RebuildKind::ExplicitInit);
+        stage_interrupted_uninit(&uninit_paths);
+        let error = incremental_sync_authorization(&uninit_paths)
+            .expect_err("an uninitialized namespace is reserved for an explicit init");
+        assert!(
+            matches!(
+                error,
+                StoreError::WritePurposeRejected {
+                    purpose: StoreWritePurpose::IncrementalSync,
+                    status: ExtractionStatus::Uninitialized,
+                }
+            ),
+            "unexpected refusal: {error}"
+        );
+    }
+
+    /// `resume_full_rebuild` refuses an authorization whose retained status it
+    /// did not accept for escalation, so no caller can smuggle a Current or
+    /// Uninitialized namespace into a destructive migration.
+    #[test]
+    fn resume_full_rebuild_refuses_a_non_migratable_authorization() {
+        let project = TempProject::new("resume-refuses");
+        let paths = project.paths();
+        run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+
+        // A FullRebuild-purpose authorization over a Current namespace is valid
+        // for `begin_full_rebuild` but is NOT a sync escalation.
+        let lease = IndexLease::acquire_or_create_exclusive(&paths, deadline(), || false)
+            .expect("acquire exclusive");
+        let authorization =
+            match Store::open_for_write(&paths, lease, StoreWritePurpose::FullRebuild)
+                .expect("Current authorizes a full rebuild")
+            {
+                StoreWriteOpen::FullRebuildRequired(authorization) => authorization,
+                other => panic!("unexpected open result {other:?}"),
+            };
+        let before = std::fs::read(paths.current_db()).expect("read the Current database bytes");
+        let error = resume_full_rebuild(&paths, authorization)
+            .expect_err("a Current authorization must not resume a migration");
+        assert!(
+            matches!(
+                error,
+                RebuildError::Store(StoreError::WritePurposeRejected {
+                    status: ExtractionStatus::Current,
+                    ..
+                })
+            ),
+            "unexpected refusal: {error}"
+        );
+        assert_eq!(
+            std::fs::read(paths.current_db()).expect("re-read the database bytes"),
+            before,
+            "a refused resume must not change one database byte"
+        );
+        assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    }
+
     #[test]
     fn opening_the_final_writer_consumes_the_unopened_capability() {
         let project = TempProject::new("single-writer");
diff --git a/crates/codegraph-watch/src/lib.rs b/crates/codegraph-watch/src/lib.rs
index 791da05..5854f35 100644
--- a/crates/codegraph-watch/src/lib.rs
+++ b/crates/codegraph-watch/src/lib.rs
@@ -1,4 +1,5 @@
 mod git;
+mod migrate;
 mod policy;
 mod sync;
 mod watcher;
diff --git a/crates/codegraph-watch/src/migrate.rs b/crates/codegraph-watch/src/migrate.rs
new file mode 100644
index 0000000..1af4978
--- /dev/null
+++ b/crates/codegraph-watch/src/migrate.rs
@@ -0,0 +1,194 @@
+//! Forced full migration of a v2 namespace that cannot be updated incrementally.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md` lines 557-565: an incremental
+//! sync classifies BEFORE mutating a row. `Missing`, `Outdated`, and a
+//! recoverable `Building` are not states a file-by-file update can repair, so the
+//! sync escalates HERE, reusing the SAME retained exclusive lease its
+//! [`StoreWriteAuthorization`] carries — no lease is released and reacquired, and
+//! no nested lock is taken.
+//!
+//! Migration is a from-source rebuild, so it structurally
+//!
+//! - bypasses every mtime and content-hash skip (it reports zero unchanged
+//!   skips even when every source byte matches the outdated database),
+//! - processes every current candidate in sorted `scan_project` order,
+//! - drops tracked files that no longer exist on disk (they are simply not
+//!   candidates, so they never enter the fresh database),
+//! - reruns framework extraction, resolution, and maintenance, and
+//! - publishes `phase=current` LAST through the rebuild finalizer.
+//!
+//! Its five canonical surfaces therefore equal a fresh v2 `index --force`: the
+//! persist order below reproduces the CLI full-index pipeline exactly — file row
+//! then nodes per file in sorted order, ALL nodes before ANY edge, then edges,
+//! then unresolved refs, then framework extraction, batched resolution, and
+//! cross-file finalization.
+//!
+//! Unlike the CLI's streaming full index, which spills edges/refs to a temporary
+//! file, this path buffers them in memory for the duration of one migration.
+//! That keeps the crate dependency-free while preserving the exact insert order;
+//! the memory profile matches the pre-existing `extract_project` API and applies
+//! only to the rare extraction-version migration, not to routine indexing.
+
+use std::path::Path;
+use std::time::Instant;
+
+use anyhow::{Context, Result};
+use codegraph_core::IndexPaths;
+use codegraph_core::node_id::hash_content;
+use codegraph_core::types::{Edge, FileRecord, Node, UnresolvedRef};
+use codegraph_extract::{ExtractOptions, detect_language, extract_source};
+use codegraph_resolve::ReferenceResolver;
+use codegraph_store::StoreWriteAuthorization;
+
+use crate::sync::{SyncOutcome, modified_millis, now_millis};
+
+/// Batch sizes and the resolver batch, matching the CLI full-index constants so a
+/// migrated index is byte-equal to `index --force`.
+const NODE_FLUSH_ROWS: usize = 10_000;
+const EDGE_FLUSH_ROWS: usize = 20_000;
+const REF_FLUSH_ROWS: usize = 20_000;
+const RESOLVE_BATCH_ROWS: usize = 5_000;
+
+/// The version key an index records for `codegraph status`. Same key and same
+/// workspace version the CLI full index writes.
+const INDEXED_WITH_VERSION_KEY: &str = "indexed_with_version";
+
+/// Run one forced full migration under the exclusive lease `authorization`
+/// already holds.
+///
+/// `authorization` must be the `FullRebuildRequired` capability the incremental
+/// sync's state gate returned; the rebuild layer revalidates it and refuses any
+/// state it did not accept for escalation.
+pub(crate) fn migrate_project(
+    project_root: &Path,
+    paths: &IndexPaths,
+    authorization: StoreWriteAuthorization,
+    options: &ExtractOptions,
+    started: Instant,
+    mut on_progress: impl FnMut(usize, usize),
+) -> Result<SyncOutcome> {
+    // `scan_project` returns a SORTED list, and every downstream pass keeps that
+    // order, so no HashSet iteration order can reach the database or the outcome.
+    let candidates = codegraph_extract::engine::scan_project(project_root, options)?;
+    let total = candidates.len();
+
+    // Publishes `phase=building` BEFORE deleting a database byte, removes only
+    // the v2 database files, and opens the single fresh writer — all under the
+    // lease the authorization retains.
+    let rebuild = codegraph_store::resume_full_rebuild(paths, authorization)?;
+    let mut rebuild = rebuild.open_store()?;
+    rebuild.set_bulk_index_pragmas()?;
+
+    let mut pending_nodes: Vec<Node> = Vec::with_capacity(NODE_FLUSH_ROWS);
+    let mut edges: Vec<Edge> = Vec::new();
+    let mut refs: Vec<UnresolvedRef> = Vec::new();
+    let mut outcome = SyncOutcome {
+        files_checked: total,
+        ..SyncOutcome::default()
+    };
+
+    for (done, relative) in candidates.iter().enumerate() {
+        let full = project_root.join(relative);
+        // One metadata + one source read per file, mirroring the CLI producer so
+        // the oversized-file skip message is byte-identical.
+        let metadata = std::fs::metadata(&full)
+            .with_context(|| format!("reading metadata for {}", full.display()))?;
+        let source = std::fs::read_to_string(&full)
+            .with_context(|| format!("reading source file {}", full.display()))?;
+        let mut result = if metadata.len() > options.max_file_size {
+            codegraph_core::types::ExtractionResult {
+                nodes: Vec::new(),
+                edges: Vec::new(),
+                unresolved_references: Vec::new(),
+                errors: vec![format!(
+                    "File exceeds max size ({} > {}): {relative}",
+                    metadata.len(),
+                    options.max_file_size
+                )],
+                duration_ms: 0,
+            }
+        } else {
+            extract_source(relative, &source, None)
+        };
+        let file = FileRecord {
+            path: relative.clone(),
+            content_hash: hash_content(&source),
+            language: detect_language(relative),
+            size: metadata.len() as i64,
+            modified_at: modified_millis(&metadata),
+            indexed_at: now_millis(),
+            node_count: result
+                .nodes
+                .iter()
+                .filter(|node| node.file_path == *relative)
+                .count() as i64,
+            errors: result.errors.clone(),
+        };
+
+        rebuild.store().upsert_file(&file)?;
+        pending_nodes.append(&mut result.nodes);
+        if pending_nodes.len() >= NODE_FLUSH_ROWS {
+            rebuild.store_mut().upsert_nodes(&pending_nodes)?;
+            pending_nodes.clear();
+        }
+        edges.append(&mut result.edges);
+        refs.append(&mut result.unresolved_references);
+
+        // Every candidate counts as reindexed: migration has no skip gate at all.
+        outcome.files_reindexed += 1;
+        on_progress(done + 1, total);
+    }
+
+    if !pending_nodes.is_empty() {
+        rebuild.store_mut().upsert_nodes(&pending_nodes)?;
+    }
+    drop(pending_nodes);
+
+    // ALL nodes are persisted before ANY edge, because `insert_edges` drops edges
+    // whose endpoints are absent. The WAL valve folds the log back during the
+    // replay passes exactly as the CLI full index does.
+    let wal_valve_bytes = codegraph_store::wal_valve_threshold_bytes();
+    for batch in edges.chunks(EDGE_FLUSH_ROWS) {
+        rebuild.store_mut().insert_edges(batch)?;
+        rebuild.checkpoint_wal_if_over(wal_valve_bytes)?;
+    }
+    drop(edges);
+    for batch in refs.chunks(REF_FLUSH_ROWS) {
+        rebuild.store_mut().insert_unresolved_refs(batch)?;
+        rebuild.checkpoint_wal_if_over(wal_valve_bytes)?;
+    }
+    drop(refs);
+
+    let mut resolver = ReferenceResolver::new(project_root.to_string_lossy());
+    {
+        let context = codegraph_resolve::StoreResolutionContext::new(
+            rebuild.store(),
+            project_root.to_string_lossy(),
+        );
+        resolver.initialize(&context);
+    }
+    if resolver.has_framework_resolvers() {
+        let relative_files = rebuild
+            .store()
+            .all_files()?
+            .into_iter()
+            .map(|file| file.path)
+            .collect::<Vec<_>>();
+        resolver.extract_and_persist_frameworks(rebuild.store_mut(), &relative_files)?;
+    }
+    resolver.resolve_and_persist_batched(rebuild.store_mut(), RESOLVE_BATCH_ROWS)?;
+    resolver.run_post_extract(rebuild.store_mut())?;
+    rebuild
+        .store()
+        .set_project_metadata(INDEXED_WITH_VERSION_KEY, env!("CARGO_PKG_VERSION"))?;
+
+    // Explicit fallible finalization: pragma restore, checkpoint + compaction,
+    // extraction stamp, stamp checkpoint, connection close, and only then the
+    // atomic `phase=current` publication.
+    rebuild.finish()?;
+
+    outcome.duration_ms = started.elapsed().as_millis();
+    // Deterministic, sorted, and free of any HashSet iteration order.
+    outcome.changed_paths = candidates;
+    Ok(outcome)
+}
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index e64b434..455982e 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -1,17 +1,24 @@
 use std::collections::HashSet;
 use std::fs;
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
-use anyhow::{Context, Result};
+use anyhow::{Context, Result, bail};
+use codegraph_core::IndexPaths;
 use codegraph_core::node_id::hash_content;
 use codegraph_core::types::FileRecord;
 use codegraph_extract::{ExtractOptions, detect_language, extract_file};
 use codegraph_resolve::ReferenceResolver;
-use codegraph_store::Store;
+use codegraph_store::{IndexLease, Store, StoreWriteOpen, StoreWritePurpose};
 
 use crate::policy::WatchPolicy;
 
+/// Bounded wall-clock budget for acquiring the ONE outer exclusive lease a sync
+/// owns. Never a blocking wait: `IndexLease` polls `try_lock` against this
+/// monotonic deadline, so a sync behind another writer fails with a typed
+/// timeout instead of hanging.
+const SYNC_LEASE_TIMEOUT: Duration = Duration::from_secs(30);
+
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct SyncOutcome {
     pub files_checked: usize,
@@ -35,44 +42,117 @@ pub fn sync_project_once(project_root: impl AsRef<Path>) -> Result<SyncOutcome>
 /// result stays byte-equivalent to `index --force`.
 pub fn sync_project_once_with_progress(
     project_root: impl AsRef<Path>,
-    on_progress: impl FnMut(usize, usize),
+    mut on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
     let project_root = project_root.as_ref();
-    let config = codegraph_core::config::get_config();
-    let options = ExtractOptions {
+    let options = scan_options();
+    let include = options.include.clone();
+    let exclude = options.exclude.clone();
+    let started = Instant::now();
+    let paths = index_paths(project_root)?;
+
+    // CLASSIFY BEFORE MUTATING A ROW (frozen plan lines 557-565). The gate takes
+    // the ONE outer exclusive lease, classifies under it, and either hands back
+    // the incremental writer for a corroborated Current namespace or the
+    // lease-retaining authorization that escalates to a forced full migration.
+    // Future/Corrupt/unauthorized-Uninitialized fail here, before any byte moves.
+    match open_sync_writer(&paths)? {
+        SyncWriter::Incremental(mut store) => {
+            let mut candidates = codegraph_extract::engine::scan_project(project_root, &options)?;
+            // Cold CLI sync has no watcher event list, so deletions are found by
+            // diffing tracked files against scan_project's on-disk set; absent
+            // paths flow through sync_one's delete branch (upstream removal pass,
+            // index.ts:1436-1441). The `exists()` guard keeps a still-present file
+            // that merely became ignored.
+            let on_disk = candidates.iter().cloned().collect::<HashSet<_>>();
+            let mut absent = Vec::new();
+            for tracked in store.all_files()? {
+                if !on_disk.contains(&tracked.path) && !project_root.join(&tracked.path).exists() {
+                    absent.push(tracked.path);
+                }
+            }
+            // `all_files` is ordered by path, but sort explicitly so the appended
+            // tail is deterministic regardless of the query's ordering.
+            absent.sort();
+            candidates.extend(absent);
+
+            let outcome = sync_paths_with_store(
+                &mut store,
+                project_root,
+                candidates,
+                &include,
+                &exclude,
+                started,
+                on_progress,
+            )?;
+            store.finish_current_mutation()?;
+            Ok(outcome)
+        }
+        SyncWriter::MigrationRequired(authorization) => crate::migrate::migrate_project(
+            project_root,
+            &paths,
+            authorization,
+            &options,
+            started,
+            &mut on_progress,
+        ),
+    }
+}
+
+/// The scan/extract options one sync uses. The global config is the source of
+/// truth when a binary initialized it; a library caller that never did (a bare
+/// watcher thread) falls back to the documented defaults instead of panicking.
+fn scan_options() -> ExtractOptions {
+    let Some(config) = codegraph_core::config::try_get_config() else {
+        return ExtractOptions::default();
+    };
+    ExtractOptions {
         max_file_size: config.indexing.max_file_size,
         ignore_dirs: config.indexing.ignore_dirs.clone(),
         ignore_paths: config.indexing.ignore_paths.clone(),
         exclude: config.indexing.exclude.clone(),
         include: config.indexing.include.clone(),
         parallel: true,
-    };
-    let started = std::time::Instant::now();
-    let mut candidates = codegraph_extract::engine::scan_project(project_root, &options)?;
-
-    let db_path = default_db_path(project_root)?;
-    let mut store = Store::open(&db_path).with_context(|| format!("open {}", db_path.display()))?;
-
-    // Cold CLI sync has no watcher event list, so deletions are found by diffing
-    // tracked files against scan_project's on-disk set; absent paths flow through
-    // sync_one's delete branch (upstream removal pass, index.ts:1436-1441). The
-    // `exists()` guard keeps a still-present file that merely became ignored.
-    let on_disk = candidates.iter().cloned().collect::<HashSet<_>>();
-    for tracked in store.all_files()? {
-        if !on_disk.contains(&tracked.path) && !project_root.join(&tracked.path).exists() {
-            candidates.push(tracked.path);
-        }
     }
+}
+
+/// What the state gate authorized for ONE sync.
+enum SyncWriter {
+    /// A corroborated `Current` namespace, open for incremental mutation under
+    /// the retained exclusive lease. Boxed because the state gate already yields
+    /// a boxed `Store`, so this variant stays the same size as the authorization.
+    Incremental(Box<Store>),
+    /// A namespace that cannot be updated file-by-file. The opaque authorization
+    /// still owns the same exclusive lease, which the migration reuses.
+    MigrationRequired(codegraph_store::StoreWriteAuthorization),
+}
 
-    sync_paths_with_store(
-        &mut store,
+pub(crate) fn index_paths(project_root: &Path) -> Result<IndexPaths> {
+    Ok(IndexPaths::resolve(
         project_root,
-        candidates,
-        &config.indexing.include,
-        &config.indexing.exclude,
-        started,
-        on_progress,
-    )
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )?)
+}
+
+/// Acquire the ONE outer exclusive lease and classify under it. The retained
+/// status decides policy; no precheck-then-reclassify happens anywhere.
+fn open_sync_writer(paths: &IndexPaths) -> Result<SyncWriter> {
+    let deadline = Instant::now() + SYNC_LEASE_TIMEOUT;
+    let lease = IndexLease::acquire_or_create_exclusive(paths, deadline, || false)?;
+    match Store::open_for_write(paths, lease, StoreWritePurpose::IncrementalSync)? {
+        StoreWriteOpen::Current(store) => Ok(SyncWriter::Incremental(store)),
+        StoreWriteOpen::FullRebuildRequired(authorization) => {
+            Ok(SyncWriter::MigrationRequired(authorization))
+        }
+        StoreWriteOpen::UninitContinuation(_) => {
+            // The gate never returns this for an incremental sync; keep it a
+            // typed refusal rather than an unreachable panic.
+            bail!(
+                "index namespace {} awaits an explicit `codegraph init`",
+                paths.current_root().display()
+            )
+        }
+    }
 }
 
 pub fn sync_changed_paths(
@@ -90,23 +170,58 @@ pub fn sync_changed_paths(
 pub fn sync_changed_paths_with_patterns(
     project_root: impl AsRef<Path>,
     db_path: impl AsRef<Path>,
-    paths: impl IntoIterator<Item = impl AsRef<Path>>,
+    changed: impl IntoIterator<Item = impl AsRef<Path>>,
     include: &[String],
     exclude: &[String],
 ) -> Result<SyncOutcome> {
-    let started = std::time::Instant::now();
+    let started = Instant::now();
     let project_root = project_root.as_ref();
     let db_path = db_path.as_ref();
-    let mut store = Store::open(db_path).with_context(|| format!("open {}", db_path.display()))?;
-    sync_paths_with_store(
-        &mut store,
-        project_root,
-        paths,
-        include,
-        exclude,
-        started,
-        |_, _| {},
-    )
+    let paths = index_paths(project_root)?;
+    // The caller-supplied database must BE this project's resolved v2 database.
+    // Accepting any other path would let a watcher mutate a namespace the state
+    // gate never classified, so a mismatch fails closed.
+    if db_path != paths.current_db() {
+        bail!(
+            "incremental sync target {} is not the resolved v2 database {}",
+            db_path.display(),
+            paths.current_db().display()
+        );
+    }
+
+    // Same classify-before-mutate gate as the cold full sync: a Current namespace
+    // stays incremental, while Missing/Outdated/recoverable Building escalate to a
+    // forced migration under the SAME retained exclusive lease.
+    match open_sync_writer(&paths)? {
+        SyncWriter::Incremental(mut store) => {
+            let outcome = sync_paths_with_store(
+                &mut store,
+                project_root,
+                changed,
+                include,
+                exclude,
+                started,
+                |_, _| {},
+            )?;
+            store.finish_current_mutation()?;
+            Ok(outcome)
+        }
+        SyncWriter::MigrationRequired(authorization) => {
+            let options = ExtractOptions {
+                include: include.to_vec(),
+                exclude: exclude.to_vec(),
+                ..scan_options()
+            };
+            crate::migrate::migrate_project(
+                project_root,
+                &paths,
+                authorization,
+                &options,
+                started,
+                |_, _| {},
+            )
+        }
+    }
 }
 
 #[allow(clippy::too_many_arguments)]
@@ -444,7 +559,7 @@ fn delete_unresolved_refs_by_file(store: &Store, relative: &str) -> rusqlite::Re
     )
 }
 
-fn modified_millis(metadata: &fs::Metadata) -> i64 {
+pub(crate) fn modified_millis(metadata: &fs::Metadata) -> i64 {
     metadata
         .modified()
         .ok()
@@ -453,7 +568,7 @@ fn modified_millis(metadata: &fs::Metadata) -> i64 {
         .unwrap_or_else(now_millis)
 }
 
-fn now_millis() -> i64 {
+pub(crate) fn now_millis() -> i64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .map(|duration| duration.as_millis() as i64)
@@ -481,6 +596,25 @@ pub(crate) mod tests {
                 std::env::temp_dir().join(format!("codegraph-{name}-{}-{id}", std::process::id()));
             let _ = fs::remove_dir_all(&path);
             fs::create_dir_all(&path).unwrap();
+            // State-gated fixture setup: a sync now CLASSIFIES before mutating a
+            // row, and a `Missing` namespace legitimately escalates to a forced
+            // full migration (frozen plan lines 557-565). Every incremental
+            // expectation below therefore starts from an EMPTY, published
+            // `Current` namespace, built through the shipped rebuild finalizer
+            // rather than by conjuring a raw database file.
+            let paths = index_paths(&path).expect("resolve the fixture v2 namespace");
+            let deadline = Instant::now() + Duration::from_secs(30);
+            codegraph_store::begin_full_rebuild(
+                &paths,
+                codegraph_store::RebuildKind::Reindex,
+                deadline,
+                || false,
+            )
+            .expect("begin the fixture namespace rebuild")
+            .open_store()
+            .expect("open the fixture namespace writer")
+            .finish()
+            .expect("publish the empty fixture namespace as Current");
             Self { path }
         }
 
@@ -1031,6 +1165,140 @@ pub(crate) mod tests {
         );
     }
 
+    /// Rewrite the authoritative state slot's built version so the namespace
+    /// classifies `Outdated` while its database stays byte-identical.
+    fn stage_outdated(dir: &TestDir) -> u64 {
+        let paths = index_paths(dir.path()).unwrap();
+        let built = codegraph_store::CURRENT_EXTRACTION_VERSION - 1;
+        let identity = paths.project_identity();
+        let checksum = codegraph_store::checksum_hex(
+            77,
+            codegraph_store::CURRENT_STORAGE_PROTOCOL,
+            built,
+            "current",
+            identity,
+        );
+        let body = format!(
+            "{{\"sequence\":77,\"storageProtocol\":{},\"extractionVersion\":{built},\
+             \"phase\":\"current\",\"projectIdentity\":\"{identity}\",\"checksum\":\"{checksum}\"}}\n",
+            codegraph_store::CURRENT_STORAGE_PROTOCOL,
+        );
+        let [slot0, slot1] = paths.state_slots();
+        fs::write(&slot0, body).unwrap();
+        let _ = fs::remove_file(&slot1);
+        assert_eq!(
+            Store::extraction_status(&paths),
+            codegraph_store::ExtractionStatus::Outdated { built }
+        );
+        built
+    }
+
+    #[test]
+    fn watcher_sync_on_outdated_namespace_migrates_every_file_without_skips() {
+        // Given: an indexed project whose namespace is then marked as built by an
+        // OLDER extraction version, with every source byte unchanged.
+        let dir = TestDir::new("watch-outdated-migrate");
+        fs::create_dir_all(dir.path().join("src")).unwrap();
+        fs::write(
+            dir.path().join("src/alpha.ts"),
+            "export function alpha() { return 1; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("src/beta.ts"),
+            "export function beta() { return 2; }\n",
+        )
+        .unwrap();
+        let db = default_db_path(dir.path()).unwrap();
+        let first = sync_changed_paths(dir.path(), &db, ["src/alpha.ts", "src/beta.ts"]).unwrap();
+        assert_eq!(first.files_reindexed, 2);
+        stage_outdated(&dir);
+
+        // When: the watcher's incremental entry point runs for ONE changed path.
+        let outcome = sync_changed_paths(dir.path(), &db, ["src/alpha.ts"]).unwrap();
+
+        // Then: it escalated to a full migration — every candidate was processed,
+        // nothing was skipped as unchanged, changed_paths is the sorted full set,
+        // and the namespace is a readable Current again.
+        assert_eq!(outcome.files_skipped_unchanged, 0);
+        assert_eq!(outcome.files_reindexed, 2);
+        assert_eq!(
+            outcome.changed_paths,
+            vec!["src/alpha.ts".to_string(), "src/beta.ts".to_string()]
+        );
+        let paths = index_paths(dir.path()).unwrap();
+        assert_eq!(
+            Store::extraction_status(&paths),
+            codegraph_store::ExtractionStatus::Current
+        );
+        let store =
+            Store::open_for_read(&paths, Instant::now() + Duration::from_secs(10), || false)
+                .unwrap();
+        assert!(store.file_by_path("src/beta.ts").unwrap().is_some());
+    }
+
+    #[test]
+    fn full_sync_on_outdated_namespace_migrates_and_drops_absent_files() {
+        // Given: two indexed files, one of which is then deleted, over a
+        // namespace marked Outdated.
+        let dir = TestDir::new("watch-outdated-full");
+        ensure_config(dir.path());
+        fs::create_dir_all(dir.path().join("src")).unwrap();
+        fs::write(
+            dir.path().join("src/alpha.ts"),
+            "export function alpha() { return 1; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("src/beta.ts"),
+            "export function beta() { return 2; }\n",
+        )
+        .unwrap();
+        sync_project_once(dir.path()).unwrap();
+        fs::remove_file(dir.path().join("src/beta.ts")).unwrap();
+        stage_outdated(&dir);
+
+        // When: the cold full sync runs.
+        let outcome = sync_project_once(dir.path()).unwrap();
+
+        // Then: migration re-extracted the surviving file with no skips and the
+        // absent file is gone from the fresh database.
+        assert_eq!(outcome.files_skipped_unchanged, 0);
+        assert_eq!(outcome.changed_paths, vec!["src/alpha.ts".to_string()]);
+        let paths = index_paths(dir.path()).unwrap();
+        let store =
+            Store::open_for_read(&paths, Instant::now() + Duration::from_secs(10), || false)
+                .unwrap();
+        assert!(store.file_by_path("src/beta.ts").unwrap().is_none());
+    }
+
+    #[test]
+    fn incremental_sync_rejects_a_database_outside_the_resolved_namespace() {
+        // Given: an initialized project and a database path that is NOT its
+        // resolved v2 database.
+        let dir = TestDir::new("watch-foreign-db");
+        fs::create_dir_all(dir.path().join("src")).unwrap();
+        fs::write(
+            dir.path().join("src/app.ts"),
+            "export function app() { return 1; }\n",
+        )
+        .unwrap();
+        let foreign = dir.path().join("elsewhere.db");
+
+        // When/Then: the sync refuses rather than mutating an unclassified file.
+        let error = sync_changed_paths(dir.path(), &foreign, ["src/app.ts"]).unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("is not the resolved v2 database"),
+            "unexpected error: {error}"
+        );
+        assert!(
+            !foreign.exists(),
+            "a refused sync must not create the foreign database"
+        );
+    }
+
     #[test]
     fn deleting_an_imported_module_refreshes_its_dependents() {
         // Given: a helper module and a consumer that resolves an import to it,
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 203035e..6679cfd 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1800,3 +1800,105 @@ authoritative `make ci CARGO='cargo --locked'`. That final run must cover these
 exact bytes, it is the sole remaining completion authority, and no later
 documentation edit is permitted. Apart from that one named gate, no validation for
 this item remains pending.
+
+## Batch M — `incremental_sync_on_outdated_v2_forces_all_files` (2026-07-26)
+
+Frozen plan lines 557-565 and test 9 (lines 750-751). An incremental sync now
+CLASSIFIES BEFORE MUTATING A ROW and escalates a namespace it cannot repair
+file-by-file to a deterministic full from-source migration under the SAME
+retained exclusive lease.
+
+Behavior landed:
+
+- `StoreWritePurpose::IncrementalSync` classifies once under the already-held
+  exclusive lease. A corroborated `Current` yields the incremental writer;
+  `Missing`, `Outdated`, and a recoverable `Building` yield the lease-retaining
+  `FullRebuildRequired` authorization; `Future` / `Corrupt` are refused before
+  any byte moves; `Uninitialized` falls through to the typed
+  `WritePurposeRejected` refusal, because only an explicit `init` may rebuild it.
+- `codegraph_store::resume_full_rebuild(paths, authorization)` performs the
+  destructive prologue (publish `phase=building`, then remove only the v2
+  database files) using the lease clone the authorization already carries. It
+  acquires NO lease, so no nested acquisition of a lock this process holds is
+  possible, and it refuses any authorization whose retained status it did not
+  accept for escalation. `begin_full_rebuild` and `resume_full_rebuild` now share
+  one `begin_from_authorization` prologue, and the existing-vs-initial lease
+  decision moved into `IndexLease::acquire_or_create_exclusive` so every
+  lifecycle owner takes the same one outer capability.
+- `codegraph-watch`'s new `migrate` module runs the migration: sorted
+  `scan_project` candidates, no mtime/content-hash gate at all (so zero
+  `files_skipped_unchanged`), absent tracked files simply never enter the fresh
+  database, then framework extraction, batched resolution, cross-file
+  finalization, and the rebuild finalizer's `phase=current` publication last. The
+  persist order reproduces the CLI full index exactly (file row then nodes per
+  file, ALL nodes before ANY edge, then edges, then refs, with the same WAL-valve
+  folds and the same 10k/20k/20k/5k batch constants).
+- Both sync entry points (`sync_project_once_with_progress` and
+  `sync_changed_paths_with_patterns`) route through the gate, finish a `Current`
+  incremental mutation with an explicit checkpoint + state-gated close, and
+  refuse a `db_path` that is not this project's resolved v2 database.
+- `Current` corroboration gained an `allow_live_sidecar` option used ONLY by the
+  incremental writer. The sidecar-free rule remains the publication and read
+  contract; a live in-process MCP reader legitimately recreates `-wal`/`-shm` on
+  an untouched `Current` namespace, so requiring sidecar-freedom from an
+  incremental WRITER made every watcher sync inside `serve` fail. The stamp is
+  still validated from the already-checkpointed main-file bytes, so the version
+  gate is unchanged.
+- `codegraph_core::config::try_get_config` is the non-panicking accessor a
+  library sync path uses when no binary initialized the global config.
+
+Red evidence (recorded before Green): the new CLI suite
+`crates/codegraph-cli/tests/batch_m_outdated_migration.rs` compiled and failed on
+its business assertions — `incremental_sync_on_outdated_v2_forces_all_files`
+panicked with `an Outdated namespace must bypass every mtime/content-hash skip
+(plan lines 557-565); got 3 unchanged skips in: Synced: 0 reindexed, 3 skipped
+(unchanged), 0 removed`; `outdated_migration_drops_absent_tracked_files` panicked
+with `a migrated namespace must be readable: StateRejected { status: Outdated {
+built: 1 } }`; and both refusal tests panicked because the old sync happily
+reported `Synced: 0 reindexed, 3 skipped (unchanged), 0 removed` over `Future`,
+`Corrupt`, and `uninitialized` namespaces. Exit status: `test result: FAILED. 0
+passed; 4 failed`.
+
+Green evidence: the same CLI suite reports 5 passed / 0 failed (including the
+nonmutation-oracle self-test); focused rebuild tests report 17 passed / 0 failed;
+the Store state-gate suite reports 21 passed / 0 failed; the complete
+`codegraph-watch` package, including its unit and integration suites, passes; and
+the affected-package tests, all-target check, and all-target Clippy with
+`-D warnings` are clean. A development `cargo test --workspace --locked` run is
+green with no failures; `cargo fmt --all --check` is clean;
+`bash scripts/guardrail.sh` exits 0; `git diff --check` is clean; and `Cargo.lock`
+still hashes to
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. Every Cargo
+batch was preceded by `bash scripts/check-workspace-versions.sh` and used
+`--locked`.
+
+Canonical equality is proven by the new suite itself: after a forced migration the
+five canonical surfaces of the migrated database `diff_canonical`-match a fresh
+v2 `init` + `index --force` peer built from the same tree, both for the
+all-unchanged case and for the case where a tracked file was deleted.
+
+No pre-existing test was weakened, deleted, filtered, or ignored. Two existing
+`codegraph-watch` expectations needed state-gated fixture setup only: the shared
+`TestDir` now publishes an empty `Current` namespace through the shipped rebuild
+finalizer, because a `Missing` namespace legitimately escalates to a migration
+now, and the two ignored-path counters assert over an incremental sync.
+
+Environment limitations, unchanged and still claimed as limitations: LSP
+diagnostics rejected every changed Rust file with `LSP file path must be inside
+request cwd`, so targeted Cargo `check`/`clippy` diagnostics are the accepted
+fallback; and no native Windows runtime, crash, or handle behavior is claimed
+from this Linux host.
+
+Final review corrections are included in those results. `resume_full_rebuild`
+now accepts only an authorization issued specifically for
+`StoreWritePurpose::IncrementalSync`, in addition to checking its retained state,
+so another full-rebuild capability cannot be repurposed as sync migration
+authority. The refused-state byte oracle now snapshots directories, complete
+regular-file bytes, and symlink targets without following aliases, fails closed
+on every I/O or unsupported-kind error, and has a self-test proving that an
+equal-length byte replacement is detected.
+
+These bytes are the input to the parent's final `make fmt` and single
+authoritative `make ci CARGO='cargo --locked'`. No later documentation edit is
+permitted; completion is decided by that post-format gate and the subsequent
+lock-hash/diff/status audit.

From 5c801dd2052f90806b1233d94c6475a1ab2b22e1 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 06:29:02 +0800
Subject: [PATCH 23/91] feat(store): make uninit crash recoverable

---
 crates/codegraph-cli/src/main.rs              | 115 ++-
 crates/codegraph-cli/tests/batch_m_uninit.rs  | 560 ++++++++++++++
 crates/codegraph-cli/tests/cli_commands.rs    |  21 +-
 crates/codegraph-store/src/connection.rs      |  25 +-
 .../src/index_state_publisher.rs              |  11 +-
 crates/codegraph-store/src/lib.rs             |   2 +
 crates/codegraph-store/src/rebuild.rs         |  82 +-
 crates/codegraph-store/src/uninit.rs          | 710 ++++++++++++++++++
 .../tests/index_state_publisher.rs            |   1 -
 .../tests/store_state_gates.rs                |  25 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 179 +++++
 11 files changed, 1696 insertions(+), 35 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/batch_m_uninit.rs
 create mode 100644 crates/codegraph-store/src/uninit.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 504c0c6..9cf5cc0 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1170,14 +1170,20 @@ fn cmd_init(path: Option<PathBuf>, target: &str) -> Result<()> {
 }
 
 fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
-    let project = resolve_required_project(path)?;
+    let project = resolve_required_rebuild_project(path)?;
     if !force {
         bail!("refusing to delete .codegraph without --force");
     }
-    let index_root = codegraph_dir(&project)?;
-    fs::remove_dir_all(&index_root)
-        .with_context(|| format!("removing {}", index_root.display()))?;
+    let paths = index_paths(&project)?;
+    let outcome = codegraph_store::uninit_index(
+        &paths,
+        std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
+        || false,
+    )?;
     println!("Removed CodeGraph from {}", project.display());
+    if outcome.legacy_index_present {
+        println!("Legacy CodeGraph index remains untouched");
+    }
     Ok(())
 }
 
@@ -1209,7 +1215,11 @@ fn cmd_index(path: Option<PathBuf>, force: bool, quiet: bool, verbose: bool) ->
 }
 
 fn cmd_sync(path: Option<PathBuf>, quiet: bool) -> Result<()> {
-    let project = resolve_required_project(path)?;
+    // Sync must discover authenticated Outdated/Building state so its Store gate
+    // can migrate it under one retained exclusive lease. Uninitialized remains
+    // discoverable only to reach the typed under-lease rejection; it is never
+    // authorized to sync or recreate residue.
+    let project = resolve_required_rebuild_project(path)?;
     // True single-file incremental sync (P0, docs/optimization-analysis.md §1).
     // sync_project_once self-discovers candidate files via scan_project, so it works
     // for a cold CLI invocation with no daemon. Hash-gated skip + per-file delete/reinsert
@@ -1243,8 +1253,16 @@ fn cmd_sync(path: Option<PathBuf>, quiet: bool) -> Result<()> {
 }
 
 fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
+    let explicit = path.is_some();
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
-    let project = resolve_project_path_optional(&start);
+    let project = if configured_root_is_absolute() {
+        if !explicit && !is_initialized(&start) {
+            bail!("CODEGRAPH_DIR is absolute; pass the project root explicitly");
+        }
+        start
+    } else {
+        resolve_project_path_optional(&start)
+    };
     // Fail closed on an unsafe/aliased/overlapping configured root: status must
     // surface the stable diagnostic, NOT mask an invalid `CODEGRAPH_DIR` as a
     // default `.codegraph-v2` layout (which would report a bogus "not
@@ -1254,6 +1272,14 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let index_root = resolved.current_root().to_path_buf();
     let db = resolved.current_db();
     let db_exists = db.is_file();
+    let extraction_status = Store::extraction_status(&resolved);
+    let legacy_index_paths = resolved
+        .legacy_roots()
+        .iter()
+        .filter(|path| path.exists())
+        .cloned()
+        .collect::<Vec<_>>();
+    let legacy_index_present = !legacy_index_paths.is_empty();
     let daemon_running = daemon_already_running(&project);
     let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project);
     let daemon_socket_path = codegraph_daemon::recorded_socket_path(&project);
@@ -1268,6 +1294,10 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
                 "lastIndexed": null,
                 "dbPath": db,
                 "dbExists": db_exists,
+                "extractionStatus": extraction_status_name(&extraction_status),
+                "extractionStatusDetail": extraction_status.to_string(),
+                "legacyIndexPresent": legacy_index_present,
+                "legacyIndexPaths": legacy_index_paths,
                 "daemonRunning": daemon_running,
                 "daemonPidPath": daemon_pid_path,
                 "daemonSocketPath": daemon_socket_path,
@@ -1277,6 +1307,13 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
             println!("\nCodeGraph Status\n");
             println!("Project: {}", project.display());
             println!("DB Path: {}", db.display());
+            println!("State:   {extraction_status}");
+            if legacy_index_present {
+                println!("Legacy index: present and untouched");
+                for path in &legacy_index_paths {
+                    println!("  {}", path.display());
+                }
+            }
             println!(
                 "Daemon:  {}",
                 if daemon_running { "running" } else { "stopped" }
@@ -1331,9 +1368,13 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
             "pendingChanges": { "added": 0, "modified": 0, "removed": 0 },
             "worktreeMismatch": null,
             "index": index_obj,
-            "dbPath": db,
-            "dbExists": db_exists,
-            "daemonRunning": daemon_running,
+                "dbPath": db,
+                "dbExists": db_exists,
+                "extractionStatus": extraction_status_name(&extraction_status),
+                "extractionStatusDetail": extraction_status.to_string(),
+                "legacyIndexPresent": legacy_index_present,
+                "legacyIndexPaths": legacy_index_paths,
+                "daemonRunning": daemon_running,
             "daemonPidPath": daemon_pid_path,
             "daemonSocketPath": daemon_socket_path,
             "daemonLogPath": daemon_log_path,
@@ -1373,6 +1414,18 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     Ok(())
 }
 
+fn extraction_status_name(status: &codegraph_store::ExtractionStatus) -> &'static str {
+    match status {
+        codegraph_store::ExtractionStatus::Current => "current",
+        codegraph_store::ExtractionStatus::Building { .. } => "building",
+        codegraph_store::ExtractionStatus::Uninitialized => "uninitialized",
+        codegraph_store::ExtractionStatus::Missing => "missing",
+        codegraph_store::ExtractionStatus::Outdated { .. } => "outdated",
+        codegraph_store::ExtractionStatus::Future { .. } => "future",
+        codegraph_store::ExtractionStatus::Corrupt { .. } => "corrupt",
+    }
+}
+
 fn cmd_query(
     search: String,
     path: Option<PathBuf>,
@@ -4293,7 +4346,11 @@ fn open_store(project: &Path) -> Result<Store> {
 /// project discovery keeps walking; the mutating command paths independently
 /// re-resolve fail-closed via [`db_path`]/[`codegraph_dir`] before touching disk.
 fn is_initialized(project: &Path) -> bool {
-    db_path(project).map(|p| p.exists()).unwrap_or(false)
+    let Ok(paths) = index_paths(project) else {
+        return false;
+    };
+    Store::extraction_status(&paths) == codegraph_store::ExtractionStatus::Current
+        && paths.current_db().is_file()
 }
 
 /// Explicit init's early-return condition is a fully corroborated readable
@@ -4328,9 +4385,34 @@ fn has_rebuild_namespace(project: &Path) -> bool {
         || paths.current_db().exists()
 }
 
+/// Authenticated lifecycle state is a discovery marker for default and relative
+/// roots even when the namespace is not readable. A permanent lock or raw DB by
+/// itself is deliberately not a marker: neither authenticates an owner-bound
+/// project state.
+fn has_lifecycle_namespace(project: &Path) -> bool {
+    let Ok(paths) = index_paths(project) else {
+        return false;
+    };
+    Store::extraction_status(&paths) != codegraph_store::ExtractionStatus::Missing
+}
+
+fn configured_root_is_absolute() -> bool {
+    std::env::var_os("CODEGRAPH_DIR")
+        .filter(|value| !value.is_empty())
+        .is_some_and(|value| Path::new(&value).is_absolute())
+}
+
 fn resolve_required_project(path: Option<PathBuf>) -> Result<PathBuf> {
+    let explicit = path.is_some();
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
-    let project = resolve_project_path_optional(&start);
+    let project = if configured_root_is_absolute() {
+        if !explicit && !is_initialized(&start) {
+            bail!("CODEGRAPH_DIR is absolute; pass the project root explicitly");
+        }
+        start
+    } else {
+        resolve_project_path_optional(&start)
+    };
     if !is_initialized(&project) {
         bail!("CodeGraph not initialized in {}", project.display());
     }
@@ -4338,10 +4420,17 @@ fn resolve_required_project(path: Option<PathBuf>) -> Result<PathBuf> {
 }
 
 fn resolve_required_rebuild_project(path: Option<PathBuf>) -> Result<PathBuf> {
+    let explicit = path.is_some();
     let start = absolute_path(path.unwrap_or_else(|| PathBuf::from(".")));
     if has_rebuild_namespace(&start) {
         return Ok(start);
     }
+    if configured_root_is_absolute() {
+        if !explicit {
+            bail!("CODEGRAPH_DIR is absolute; pass the project root explicitly");
+        }
+        bail!("CodeGraph not initialized in {}", start.display());
+    }
     let mut current = start.as_path();
     while let Some(parent) = current.parent() {
         if parent == current {
@@ -4356,7 +4445,7 @@ fn resolve_required_rebuild_project(path: Option<PathBuf>) -> Result<PathBuf> {
 }
 
 fn resolve_project_path_optional(start: &Path) -> PathBuf {
-    if is_initialized(start) {
+    if configured_root_is_absolute() || has_lifecycle_namespace(start) {
         return start.to_path_buf();
     }
     let mut current = start;
@@ -4364,7 +4453,7 @@ fn resolve_project_path_optional(start: &Path) -> PathBuf {
         if parent == current {
             break;
         }
-        if is_initialized(parent) {
+        if has_lifecycle_namespace(parent) {
             return parent.to_path_buf();
         }
         current = parent;
diff --git a/crates/codegraph-cli/tests/batch_m_uninit.rs b/crates/codegraph-cli/tests/batch_m_uninit.rs
new file mode 100644
index 0000000..ef94192
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_uninit.rs
@@ -0,0 +1,560 @@
+//! Batch M — interrupted `uninit --force` lifecycle acceptance.
+//!
+//! Revision 14 requires public uninit to publish an authoritative
+//! `phase=uninitialized` slot before deleting any v2 residue, preserve the
+//! permanent lock and both fixed state slots, and leave only explicit `init` or
+//! another `uninit --force` continuation authorized. The store-owned fault
+//! matrix for every private mutation boundary lives in `codegraph-store`.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, ExtractionStatus, IndexLease, StatePhase,
+    Store, checksum_hex, classify, publish_index_state,
+};
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-batchm-uninit-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock after epoch")
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).expect("create uninit test directory");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    std::fs::create_dir_all(dst).expect("create fixture destination");
+    for entry in std::fs::read_dir(src).expect("read fixture directory") {
+        let entry = entry.expect("read fixture entry");
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            std::fs::copy(&from, &to).expect("copy fixture file");
+        }
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(registry_dir: &Path, args: &[&str]) -> Run {
+    run_in_with_config(registry_dir, args, None)
+}
+
+fn run_in_with_config(registry_dir: &Path, args: &[&str], codegraph_dir: Option<&Path>) -> Run {
+    let mut command = Command::new(bin());
+    command
+        .current_dir(registry_dir)
+        .args(args)
+        .env("CODEGRAPH_HTTP_REGISTRY_DIR", registry_dir)
+        .env("CODEGRAPH_NO_DAEMON", "1");
+    if let Some(configured) = codegraph_dir {
+        command.env("CODEGRAPH_DIR", configured);
+    } else {
+        command.env_remove("CODEGRAPH_DIR");
+    }
+    let output = command.output().expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+fn db_sidecar(db: &Path, suffix: &str) -> PathBuf {
+    let mut native = db.as_os_str().to_os_string();
+    native.push(suffix);
+    PathBuf::from(native)
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum NamespaceEntry {
+    Directory,
+    File(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+fn namespace_snapshot(root: &Path) -> BTreeMap<PathBuf, NamespaceEntry> {
+    fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, NamespaceEntry>) {
+        let mut children = std::fs::read_dir(directory)
+            .unwrap_or_else(|error| panic!("snapshot read_dir {}: {error}", directory.display()))
+            .map(|entry| {
+                entry
+                    .unwrap_or_else(|error| {
+                        panic!("snapshot entry in {}: {error}", directory.display())
+                    })
+                    .path()
+            })
+            .collect::<Vec<_>>();
+        children.sort();
+        for path in children {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                .to_path_buf();
+            let metadata = std::fs::symlink_metadata(&path)
+                .unwrap_or_else(|error| panic!("snapshot metadata {}: {error}", path.display()));
+            let ty = metadata.file_type();
+            let entry =
+                if ty.is_dir() {
+                    NamespaceEntry::Directory
+                } else if ty.is_file() {
+                    NamespaceEntry::File(std::fs::read(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read {}: {error}", path.display())
+                    }))
+                } else if ty.is_symlink() {
+                    NamespaceEntry::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read_link {}: {error}", path.display())
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
+            assert!(
+                out.insert(relative, entry).is_none(),
+                "duplicate snapshot path"
+            );
+            if ty.is_dir() {
+                walk(root, &path, out);
+            }
+        }
+    }
+
+    let mut out = BTreeMap::new();
+    walk(root, root, &mut out);
+    out
+}
+
+fn assert_namespace_unchanged(
+    before: &BTreeMap<PathBuf, NamespaceEntry>,
+    after: &BTreeMap<PathBuf, NamespaceEntry>,
+    label: &str,
+) {
+    let mut all_paths = before
+        .keys()
+        .chain(after.keys())
+        .cloned()
+        .collect::<Vec<_>>();
+    all_paths.sort();
+    all_paths.dedup();
+    let changed = all_paths
+        .into_iter()
+        .filter(|path| before.get(path) != after.get(path))
+        .collect::<Vec<_>>();
+    assert!(
+        changed.is_empty(),
+        "{label} changed namespace entries: {changed:?}"
+    );
+}
+
+fn deadline() -> Instant {
+    Instant::now() + Duration::from_secs(10)
+}
+
+fn assert_legacy_bytes(legacy_file: &Path, expected: &[u8]) {
+    assert_eq!(
+        std::fs::read(legacy_file).expect("read untouched legacy proof"),
+        expected,
+        "v2 lifecycle operations must not mutate the legacy namespace"
+    );
+}
+
+/// Public behavioral Red for acceptance item 11: successful uninit must leave a
+/// recoverable authenticated lifecycle namespace, not erase its state root.
+#[test]
+fn interrupted_uninit_state_slot_is_recoverable_not_corrupt() {
+    let dir = TestDir::new("public-red");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let project_arg = project.to_str().expect("UTF-8 test project path");
+
+    let init = run_in(dir.path(), &["init", project_arg]);
+    assert!(
+        init.ok,
+        "setup: init must succeed before the lifecycle assertion: stdout={}, stderr={}",
+        init.stdout, init.stderr
+    );
+    let paths = IndexPaths::resolve(&project, None).expect("resolve v2 paths");
+    let legacy = project.join(".codegraph");
+    std::fs::create_dir(&legacy).expect("create independent legacy namespace");
+    let legacy_file = legacy.join("legacy.bin");
+    let legacy_bytes = b"legacy bytes must remain unchanged";
+    std::fs::write(&legacy_file, legacy_bytes).expect("write legacy proof bytes");
+
+    for (path, bytes) in [
+        (
+            db_sidecar(&paths.current_db(), "-wal"),
+            b"wal residue".as_slice(),
+        ),
+        (
+            db_sidecar(&paths.current_db(), "-shm"),
+            b"shm residue".as_slice(),
+        ),
+        (paths.config_toml(), b"config residue".as_slice()),
+        (paths.extension_config(), b"extension residue".as_slice()),
+        (paths.daemon_pid(), b"pid residue".as_slice()),
+        (paths.daemon_log(), b"log residue".as_slice()),
+        (paths.daemon_socket(), b"socket residue".as_slice()),
+    ] {
+        std::fs::write(path, bytes).expect("stage removable v2 residue");
+    }
+
+    let uninit = run_in(dir.path(), &["uninit", "--force", project_arg]);
+    assert!(
+        uninit.ok,
+        "uninit --force must succeed: stdout={}, stderr={}",
+        uninit.stdout, uninit.stderr
+    );
+
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Uninitialized,
+        "uninit --force must durably publish phase=uninitialized before cleanup; deleting the whole v2 root loses the authenticated recovery state"
+    );
+    assert!(
+        paths.permanent_lock().is_file(),
+        "uninit must preserve the permanent lock"
+    );
+    assert!(
+        paths.tombstone().is_file(),
+        "uninit must ensure the tombstone"
+    );
+    assert!(
+        paths.state_slots().iter().all(|slot| slot.is_file()),
+        "uninit must preserve both fixed state slots"
+    );
+    assert!(
+        !paths.current_db().exists(),
+        "successful uninit cleanup must remove the v2 database"
+    );
+    for path in [
+        db_sidecar(&paths.current_db(), "-wal"),
+        db_sidecar(&paths.current_db(), "-shm"),
+        paths.config_toml(),
+        paths.extension_config(),
+        paths.daemon_pid(),
+        paths.daemon_log(),
+        paths.daemon_socket(),
+    ] {
+        assert!(
+            !path.exists(),
+            "successful uninit must remove v2 lifecycle residue: {}",
+            path.display()
+        );
+    }
+    assert_legacy_bytes(&legacy_file, legacy_bytes);
+
+    let status = run_in(dir.path(), &["status", "--json", project_arg]);
+    assert!(
+        status.ok,
+        "status must report interrupted uninit: stdout={}, stderr={}",
+        status.stdout, status.stderr
+    );
+    let status_json: serde_json::Value =
+        serde_json::from_str(status.stdout.trim()).expect("status emits JSON");
+    assert_eq!(status_json["initialized"], false);
+    assert_eq!(status_json["extractionStatus"], "uninitialized");
+    assert_eq!(status_json["legacyIndexPresent"], true);
+
+    for args in [
+        vec!["sync", project_arg],
+        vec!["index", "--force", project_arg],
+        vec!["index", project_arg],
+        vec!["query", "Counter", "--path", project_arg],
+    ] {
+        let before_rejection = namespace_snapshot(paths.current_root());
+        let rejected = run_in(dir.path(), &args);
+        assert!(
+            !rejected.ok,
+            "only init or repeated uninit may proceed after interrupted uninit; args={args:?}, stdout={}, stderr={}",
+            rejected.stdout, rejected.stderr
+        );
+        assert_namespace_unchanged(
+            &before_rejection,
+            &namespace_snapshot(paths.current_root()),
+            &format!("rejected command {args:?}"),
+        );
+        assert_legacy_bytes(&legacy_file, legacy_bytes);
+    }
+
+    let first_sequence = classify(&paths)
+        .authoritative()
+        .expect("uninit has authoritative slot")
+        .record
+        .sequence;
+    let continuation = run_in(dir.path(), &["uninit", "--force", project_arg]);
+    assert!(
+        continuation.ok,
+        "repeated uninit must continue cleanup: stdout={}, stderr={}",
+        continuation.stdout, continuation.stderr
+    );
+    let continued = classify(&paths);
+    assert_eq!(continued.status(), &ExtractionStatus::Uninitialized);
+    assert_eq!(
+        continued
+            .authoritative()
+            .expect("continued uninit has authoritative slot")
+            .record
+            .sequence,
+        first_sequence + 1,
+        "continued uninit must publish a monotonic Uninitialized sequence"
+    );
+    assert_legacy_bytes(&legacy_file, legacy_bytes);
+
+    let recovery = run_in(dir.path(), &["init", project_arg]);
+    assert!(
+        recovery.ok,
+        "explicit init must recover interrupted uninit: stdout={}, stderr={}",
+        recovery.stdout, recovery.stderr
+    );
+    assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    assert!(
+        paths.current_db().is_file(),
+        "init recovery rebuilds the DB"
+    );
+    assert!(
+        !paths.tombstone().exists(),
+        "only successful explicit init recovery removes the tombstone"
+    );
+    assert_legacy_bytes(&legacy_file, legacy_bytes);
+}
+
+#[test]
+fn namespace_snapshot_detects_equal_length_byte_mutation() {
+    let dir = TestDir::new("snapshot-self-test");
+    let root = dir.path().join("namespace");
+    std::fs::create_dir(&root).expect("create snapshot root");
+    let file = root.join("state.json");
+    std::fs::write(&file, b"AAAA").expect("write original bytes");
+    let before = namespace_snapshot(&root);
+    std::fs::write(&file, b"BBBB").expect("write equal-length replacement");
+    let after = namespace_snapshot(&root);
+    assert!(
+        std::panic::catch_unwind(|| {
+            assert_namespace_unchanged(&before, &after, "snapshot self-test")
+        })
+        .is_err(),
+        "namespace oracle must detect equal-length byte mutation"
+    );
+}
+
+#[test]
+fn absolute_configured_root_requires_explicit_project_for_nested_uninit() {
+    let dir = TestDir::new("absolute-configured-root");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let nested = project.join("src/nested");
+    std::fs::create_dir_all(&nested).expect("create nested invocation directory");
+    let configured = dir.path().join("shared-index");
+    let project_arg = project.to_str().expect("UTF-8 project path");
+
+    let init = run_in_with_config(dir.path(), &["init", project_arg], Some(&configured));
+    assert!(
+        init.ok,
+        "configured init failed: {} {}",
+        init.stdout, init.stderr
+    );
+    let paths =
+        IndexPaths::resolve(&project, configured.to_str()).expect("resolve configured root");
+    let before = namespace_snapshot(paths.current_root());
+
+    let implicit = run_in_with_config(&nested, &["uninit", "--force"], Some(&configured));
+    assert!(!implicit.ok, "nested implicit uninit must fail");
+    assert!(
+        implicit.stderr.contains("pass the project root explicitly"),
+        "stable remedy missing: {}",
+        implicit.stderr
+    );
+    assert_namespace_unchanged(
+        &before,
+        &namespace_snapshot(paths.current_root()),
+        "nested implicit absolute-root uninit refusal",
+    );
+
+    let explicit = run_in_with_config(
+        &nested,
+        &["uninit", "--force", project_arg],
+        Some(&configured),
+    );
+    assert!(
+        explicit.ok,
+        "explicit project-root uninit must succeed: {} {}",
+        explicit.stdout, explicit.stderr
+    );
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Uninitialized
+    );
+}
+
+fn stage_lifecycle_state(paths: &IndexPaths, status: &str) {
+    let lease = IndexLease::create_exclusive(paths, deadline(), || false)
+        .expect("create lifecycle namespace");
+    match status {
+        "building" => {
+            publish_index_state(paths, &lease, StatePhase::Building).expect("publish Building");
+        }
+        "outdated" | "future" | "corrupt" => {
+            let (storage_protocol, extraction_version, phase) = match status {
+                "outdated" => (
+                    CURRENT_STORAGE_PROTOCOL,
+                    CURRENT_EXTRACTION_VERSION - 1,
+                    "current",
+                ),
+                "future" => (
+                    CURRENT_STORAGE_PROTOCOL + 1,
+                    CURRENT_EXTRACTION_VERSION + 1,
+                    "current",
+                ),
+                "corrupt" => {
+                    std::fs::write(&paths.state_slots()[0], b"not-json")
+                        .expect("write corrupt slot");
+                    drop(lease);
+                    return;
+                }
+                _ => unreachable!(),
+            };
+            let checksum = checksum_hex(
+                0,
+                storage_protocol,
+                extraction_version,
+                phase,
+                paths.project_identity(),
+            );
+            let body = serde_json::json!({
+                "sequence": 0,
+                "storageProtocol": storage_protocol,
+                "extractionVersion": extraction_version,
+                "phase": phase,
+                "projectIdentity": paths.project_identity(),
+                "checksum": checksum,
+            });
+            std::fs::write(
+                &paths.state_slots()[0],
+                serde_json::to_vec(&body).expect("serialize lifecycle slot"),
+            )
+            .expect("write lifecycle slot");
+        }
+        _ => unreachable!(),
+    }
+    drop(lease);
+}
+
+#[test]
+fn nested_status_discovers_authenticated_non_current_parent_states() {
+    for expected in ["building", "outdated", "future", "corrupt"] {
+        let dir = TestDir::new(expected);
+        let project = dir.path().join("project");
+        let nested = project.join("a/b");
+        std::fs::create_dir_all(&nested).expect("create nested project directory");
+        let paths = IndexPaths::resolve(&project, None).expect("resolve lifecycle paths");
+        stage_lifecycle_state(&paths, expected);
+
+        let status = run_in(&nested, &["status", "--json"]);
+        assert!(
+            status.ok,
+            "nested {expected} status failed: {} {}",
+            status.stdout, status.stderr
+        );
+        let value: serde_json::Value =
+            serde_json::from_str(status.stdout.trim()).expect("parse status JSON");
+        assert_eq!(value["projectPath"], project.to_string_lossy().as_ref());
+        assert_eq!(value["extractionStatus"], expected);
+        assert_eq!(value["initialized"], false);
+    }
+}
+
+#[test]
+fn nested_status_discovers_interrupted_uninit_with_relative_configured_root() {
+    let dir = TestDir::new("nested-relative-uninit");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+    let nested = project.join("src/nested");
+    std::fs::create_dir_all(&nested).expect("create nested invocation directory");
+    let configured = Path::new("cache/index");
+    let project_arg = project.to_str().expect("UTF-8 project path");
+    let init = run_in_with_config(dir.path(), &["init", project_arg], Some(configured));
+    assert!(init.ok, "relative configured init failed: {}", init.stderr);
+    let uninit = run_in_with_config(
+        dir.path(),
+        &["uninit", "--force", project_arg],
+        Some(configured),
+    );
+    assert!(
+        uninit.ok,
+        "relative configured uninit failed: {}",
+        uninit.stderr
+    );
+
+    let status = run_in_with_config(&nested, &["status", "--json"], Some(configured));
+    assert!(
+        status.ok,
+        "nested Uninitialized status failed: {}",
+        status.stderr
+    );
+    let value: serde_json::Value =
+        serde_json::from_str(status.stdout.trim()).expect("parse status JSON");
+    assert_eq!(value["projectPath"], project.to_string_lossy().as_ref());
+    assert_eq!(value["extractionStatus"], "uninitialized");
+    assert_eq!(value["initialized"], false);
+}
+
+#[test]
+fn lock_only_parent_is_not_a_status_discovery_marker() {
+    let dir = TestDir::new("lock-only");
+    let project = dir.path().join("project");
+    let nested = project.join("a/b");
+    std::fs::create_dir_all(&nested).expect("create nested project directory");
+    let paths = IndexPaths::resolve(&project, None).expect("resolve lifecycle paths");
+    std::fs::create_dir(paths.current_root()).expect("create current root");
+    std::fs::write(paths.permanent_lock(), b"").expect("write lock-only fixture");
+
+    let status = run_in(&nested, &["status", "--json"]);
+    assert!(status.ok, "lock-only status failed: {}", status.stderr);
+    let value: serde_json::Value =
+        serde_json::from_str(status.stdout.trim()).expect("parse status JSON");
+    assert_eq!(value["projectPath"], nested.to_string_lossy().as_ref());
+    assert_eq!(value["extractionStatus"], "missing");
+}
diff --git a/crates/codegraph-cli/tests/cli_commands.rs b/crates/codegraph-cli/tests/cli_commands.rs
index 02a92a9..8500f98 100644
--- a/crates/codegraph-cli/tests/cli_commands.rs
+++ b/crates/codegraph-cli/tests/cli_commands.rs
@@ -9,6 +9,9 @@
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+use codegraph_core::IndexPaths;
+use codegraph_store::{ExtractionStatus, Store};
+
 fn bin() -> PathBuf {
     PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
 }
@@ -311,7 +314,7 @@ fn unlock_removes_existing_lock_file() {
 }
 
 #[test]
-fn uninit_requires_force_then_removes() {
+fn uninit_requires_force_then_preserves_recovery_state() {
     let dir = TestDir::new("uninit");
     let project = indexed_project(&dir);
     let p = project.to_str().unwrap();
@@ -329,13 +332,23 @@ fn uninit_requires_force_then_removes() {
         "uninit without --force must not delete the index"
     );
 
-    // With --force: removes the v2 index root.
+    // With --force: removes mutable v2 data but preserves the authenticated
+    // interrupted-uninit namespace needed by explicit recovery.
     let done = run_in(dir.path(), &["uninit", "--force", p]);
     assert!(done.ok, "uninit --force must succeed: {}", done.stderr);
+    let paths = IndexPaths::resolve(&project, None).expect("resolve v2 lifecycle paths");
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Uninitialized
+    );
     assert!(
-        !project.join(".codegraph-v2").exists(),
-        "uninit --force must remove .codegraph-v2"
+        paths.current_root().is_dir(),
+        "uninit --force must preserve the v2 lifecycle root"
     );
+    assert!(paths.permanent_lock().is_file());
+    assert!(paths.tombstone().is_file());
+    assert!(paths.state_slots().iter().all(|slot| slot.is_file()));
+    assert!(!paths.current_db().exists());
 }
 
 #[test]
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index 3fcc21b..ef14026 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -56,7 +56,9 @@ pub enum StoreWritePurpose {
     /// escalates to a forced migration under the SAME exclusive lease. An
     /// interrupted-`uninit` namespace stays reserved for an explicit `init`.
     IncrementalSync,
-    /// Retain exclusive authority for a later interrupted-uninit continuation.
+    /// Retain exclusive authority for a new uninit or an interrupted-uninit
+    /// continuation. Only `Current`, recoverable `Building`, or
+    /// `Uninitialized` may issue this capability.
     UninitContinuation,
 }
 
@@ -528,7 +530,26 @@ impl Store {
                     },
                 ))
             }
-            StoreWritePurpose::UninitContinuation if status == ExtractionStatus::Uninitialized => {
+            StoreWritePurpose::UninitContinuation
+                if matches!(
+                    status,
+                    ExtractionStatus::Current
+                        | ExtractionStatus::Building { .. }
+                        | ExtractionStatus::Uninitialized
+                ) =>
+            {
+                if status == ExtractionStatus::Current {
+                    // A live reader may legitimately have recreated WAL/SHM on a
+                    // still-Current namespace. Uninit owns the exclusive lease,
+                    // corroborates the checkpointed main-file extraction stamp,
+                    // then publishes Uninitialized before deleting those
+                    // sidecars. Rejecting them here would make that required
+                    // cleanup path unreachable.
+                    let (corroboration, source_conn) =
+                        corroborate_current_database_options(paths, false, true)?;
+                    drop(corroboration);
+                    drop(source_conn);
+                }
                 Ok(StoreWriteOpen::UninitContinuation(
                     StoreWriteAuthorization {
                         status,
diff --git a/crates/codegraph-store/src/index_state_publisher.rs b/crates/codegraph-store/src/index_state_publisher.rs
index aea3a13..b3a551a 100644
--- a/crates/codegraph-store/src/index_state_publisher.rs
+++ b/crates/codegraph-store/src/index_state_publisher.rs
@@ -443,7 +443,10 @@ fn validate_transition(
         (current, requested),
         (ExtractionStatus::Missing, StatePhase::Building)
             | (ExtractionStatus::Outdated { .. }, StatePhase::Building)
-            | (ExtractionStatus::Uninitialized, StatePhase::Building)
+            | (
+                ExtractionStatus::Uninitialized,
+                StatePhase::Building | StatePhase::Uninitialized
+            )
             | (
                 ExtractionStatus::Current,
                 StatePhase::Building | StatePhase::Uninitialized
@@ -674,7 +677,10 @@ mod tests {
                     (&current, requested),
                     (ExtractionStatus::Missing, StatePhase::Building)
                         | (ExtractionStatus::Outdated { .. }, StatePhase::Building)
-                        | (ExtractionStatus::Uninitialized, StatePhase::Building)
+                        | (
+                            ExtractionStatus::Uninitialized,
+                            StatePhase::Building | StatePhase::Uninitialized
+                        )
                         | (
                             ExtractionStatus::Current,
                             StatePhase::Building | StatePhase::Uninitialized
@@ -705,6 +711,7 @@ mod tests {
         let allowed = [
             (PriorStatus::Outdated, StatePhase::Building),
             (PriorStatus::Uninitialized, StatePhase::Building),
+            (PriorStatus::Uninitialized, StatePhase::Uninitialized),
             (PriorStatus::Current, StatePhase::Building),
             (PriorStatus::Current, StatePhase::Uninitialized),
             (PriorStatus::Building, StatePhase::Building),
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index fd64a77..8a0e7f8 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -7,6 +7,7 @@ pub mod migrations;
 pub mod queries;
 pub mod rebuild;
 pub mod schema;
+pub mod uninit;
 
 pub use connection::{
     ExtractionStampIssue, Store, StoreError, StoreStatusOpen, StoreWriteAuthorization,
@@ -28,3 +29,4 @@ pub use rebuild::{
     ActiveFullRebuild, FullRebuild, RebuildError, RebuildKind, begin_full_rebuild,
     resume_full_rebuild,
 };
+pub use uninit::{UninitError, UninitOutcome, uninit_index};
diff --git a/crates/codegraph-store/src/rebuild.rs b/crates/codegraph-store/src/rebuild.rs
index 81fd468..7fff8a4 100644
--- a/crates/codegraph-store/src/rebuild.rs
+++ b/crates/codegraph-store/src/rebuild.rs
@@ -662,7 +662,9 @@ fn acquire_outer_exclusive(
 fn remove_database_files(paths: &IndexPaths, lease: &IndexLease) -> Result<(), RebuildError> {
     let db = paths.current_db();
     for suffix in ["", "-wal", "-shm"] {
-        let path = PathBuf::from(format!("{}{suffix}", db.display()));
+        let mut native = db.as_os_str().to_os_string();
+        native.push(suffix);
+        let path = PathBuf::from(native);
         lease.validate_exclusive(paths)?;
         match std::fs::remove_file(&path) {
             Ok(()) => {}
@@ -833,7 +835,11 @@ mod tests {
         let db = paths.current_db();
         ["-wal", "-shm"]
             .into_iter()
-            .map(|suffix| PathBuf::from(format!("{}{suffix}", db.display())))
+            .map(|suffix| {
+                let mut native = db.as_os_str().to_os_string();
+                native.push(suffix);
+                PathBuf::from(native)
+            })
             .filter(|path| path.exists())
             .collect()
     }
@@ -1031,6 +1037,78 @@ mod tests {
         }
     }
 
+    #[test]
+    fn explicit_init_recovery_publication_faults_leave_only_protocol_valid_states() {
+        for (checkpoint, expected_step, expected_status) in [
+            (
+                RebuildCheckpoint::BuildingPublished,
+                "publish phase=building",
+                ExtractionStatus::Building {
+                    built: CURRENT_EXTRACTION_VERSION,
+                },
+            ),
+            (
+                RebuildCheckpoint::CurrentPublished,
+                "publish phase=current",
+                ExtractionStatus::Current,
+            ),
+        ] {
+            let project = TempProject::new("explicit-init-recovery-fault");
+            let paths = project.paths();
+            run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+            stage_interrupted_uninit(&paths);
+            let mut fault = FailAt(checkpoint);
+
+            let begun = begin_full_rebuild_with(
+                &paths,
+                RebuildKind::ExplicitInit,
+                deadline(),
+                || false,
+                &mut fault,
+            );
+            let error = match begun {
+                Err(error) => error,
+                Ok(rebuild) => {
+                    let rebuild = rebuild
+                        .open_store()
+                        .expect("open explicit-init recovery writer");
+                    build_graph(&rebuild);
+                    rebuild
+                        .finish_with(&mut fault)
+                        .expect_err("publication checkpoint must interrupt recovery")
+                }
+            };
+            match error {
+                RebuildError::Interrupted { step, source } => {
+                    assert_eq!(step, expected_step, "checkpoint={checkpoint:?}");
+                    assert_eq!(source.kind(), io::ErrorKind::Other);
+                }
+                other => panic!("checkpoint={checkpoint:?}: unexpected error {other:?}"),
+            }
+
+            assert_eq!(
+                Store::extraction_status(&paths),
+                expected_status,
+                "checkpoint={checkpoint:?} must publish a complete protocol state"
+            );
+            assert!(
+                paths.tombstone().is_file(),
+                "checkpoint={checkpoint:?}: recovery interruption retains tombstone"
+            );
+            assert!(
+                paths.state_slots().iter().all(|slot| slot.is_file()),
+                "checkpoint={checkpoint:?}: both crash-safe slots remain present"
+            );
+
+            run_successful_rebuild(&paths, RebuildKind::ExplicitInit);
+            assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+            assert!(
+                !paths.tombstone().exists(),
+                "a later successful explicit init removes the retained tombstone"
+            );
+        }
+    }
+
     #[test]
     fn failed_current_publication_after_finalization_never_becomes_readable_current() {
         let project = TempProject::new("publish-fails");
diff --git a/crates/codegraph-store/src/uninit.rs b/crates/codegraph-store/src/uninit.rs
new file mode 100644
index 0000000..853a96b
--- /dev/null
+++ b/crates/codegraph-store/src/uninit.rs
@@ -0,0 +1,710 @@
+//! Crash-recoverable `uninit --force` lifecycle.
+//!
+//! The state slot authenticates interrupted-uninit residue. Publish it under one
+//! retained exclusive lease before creating the tombstone or deleting v2 bytes.
+
+use std::fs::OpenOptions;
+use std::io::{self, Write};
+use std::path::{Path, PathBuf};
+use std::time::Instant;
+
+use codegraph_core::IndexPaths;
+use thiserror::Error;
+
+use crate::{
+    ExtractionStatus, IndexLease, IndexLeaseError, IndexLeaseValidationError, StatePhase,
+    StatePublishError, Store, StoreError, StoreWriteOpen, StoreWritePurpose, publish_index_state,
+};
+
+const TOMBSTONE_BYTES: &[u8] = b"uninitialized\n";
+
+/// Result of one complete new-uninit or cleanup-continuation pass.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct UninitOutcome {
+    /// Whether any configured/fixed legacy namespace remains untouched.
+    pub legacy_index_present: bool,
+}
+
+/// Typed failures from the destructive uninit lifecycle.
+#[derive(Debug, Error)]
+pub enum UninitError {
+    #[error("uninit is not authorized for index state {status}")]
+    StateRejected { status: ExtractionStatus },
+    #[error(transparent)]
+    Lease(#[from] IndexLeaseError),
+    #[error(transparent)]
+    LeaseValidation(#[from] IndexLeaseValidationError),
+    #[error(transparent)]
+    Store(#[from] StoreError),
+    #[error(transparent)]
+    Publish(#[from] StatePublishError),
+    #[error("failed to publish uninitialized tombstone {path}: {source}")]
+    Tombstone {
+        path: PathBuf,
+        #[source]
+        source: io::Error,
+    },
+    #[error("refusing to remove non-file v2 lifecycle child {path}")]
+    UnsupportedChild { path: PathBuf },
+    #[error("failed to remove v2 lifecycle child {path}: {source}")]
+    RemoveChild {
+        path: PathBuf,
+        #[source]
+        source: io::Error,
+    },
+    #[error("uninit interrupted after {step}: {source}")]
+    Interrupted {
+        step: &'static str,
+        #[source]
+        source: io::Error,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum UninitCheckpoint {
+    BeforeAuthorization,
+    StatePublished,
+    TombstoneEnsured,
+    DatabaseRemoved,
+    WalRemoved,
+    ShmRemoved,
+    ConfigRemoved,
+    ExtensionConfigRemoved,
+    DaemonPidRemoved,
+    DaemonLogRemoved,
+    DaemonSocketRemoved,
+}
+
+impl UninitCheckpoint {
+    fn label(self) -> &'static str {
+        match self {
+            Self::BeforeAuthorization => "write authorization",
+            Self::StatePublished => "uninitialized state publication",
+            Self::TombstoneEnsured => "tombstone creation",
+            Self::DatabaseRemoved => "database removal",
+            Self::WalRemoved => "WAL removal",
+            Self::ShmRemoved => "SHM removal",
+            Self::ConfigRemoved => "config removal",
+            Self::ExtensionConfigRemoved => "extension config removal",
+            Self::DaemonPidRemoved => "daemon pid removal",
+            Self::DaemonLogRemoved => "daemon log removal",
+            Self::DaemonSocketRemoved => "daemon socket removal",
+        }
+    }
+}
+
+trait UninitFault {
+    fn after(&mut self, checkpoint: UninitCheckpoint) -> io::Result<()>;
+}
+
+struct NoFault;
+
+impl UninitFault for NoFault {
+    fn after(&mut self, _checkpoint: UninitCheckpoint) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+/// Start or continue `uninit --force` under one existing exclusive lease.
+///
+/// This never creates or repairs a namespace lock. The pre-probe is nonmutating;
+/// Store reclassifies under the acquired lease before the first mutation.
+pub fn uninit_index(
+    paths: &IndexPaths,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+) -> Result<UninitOutcome, UninitError> {
+    uninit_index_with(paths, deadline, cancelled, &mut NoFault)
+}
+
+fn uninit_index_with(
+    paths: &IndexPaths,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+    fault: &mut impl UninitFault,
+) -> Result<UninitOutcome, UninitError> {
+    let visible = Store::extraction_status(paths);
+    if !matches!(
+        visible,
+        ExtractionStatus::Current
+            | ExtractionStatus::Building { .. }
+            | ExtractionStatus::Uninitialized
+    ) {
+        return Err(UninitError::StateRejected { status: visible });
+    }
+
+    let lease = IndexLease::acquire_exclusive_existing(paths, deadline, cancelled)?;
+    checkpoint(fault, UninitCheckpoint::BeforeAuthorization)?;
+    let authorization =
+        match Store::open_for_write(paths, lease.clone(), StoreWritePurpose::UninitContinuation)? {
+            StoreWriteOpen::UninitContinuation(authorization) => authorization,
+            other => unreachable!("uninit purpose returned unexpected Store open: {other:?}"),
+        };
+    if authorization.purpose() != StoreWritePurpose::UninitContinuation
+        || !matches!(
+            authorization.status(),
+            ExtractionStatus::Current
+                | ExtractionStatus::Building { .. }
+                | ExtractionStatus::Uninitialized
+        )
+    {
+        return Err(UninitError::StateRejected {
+            status: authorization.status().clone(),
+        });
+    }
+
+    publish_index_state(paths, &lease, StatePhase::Uninitialized)?;
+    checkpoint(fault, UninitCheckpoint::StatePublished)?;
+    ensure_tombstone(paths, &lease)?;
+    checkpoint(fault, UninitCheckpoint::TombstoneEnsured)?;
+
+    let db = paths.current_db();
+    remove_child(paths, &lease, &db)?;
+    checkpoint(fault, UninitCheckpoint::DatabaseRemoved)?;
+    let wal = sqlite_sidecar_path(&db, "-wal");
+    remove_child(paths, &lease, &wal)?;
+    checkpoint(fault, UninitCheckpoint::WalRemoved)?;
+    let shm = sqlite_sidecar_path(&db, "-shm");
+    remove_child(paths, &lease, &shm)?;
+    checkpoint(fault, UninitCheckpoint::ShmRemoved)?;
+
+    for (path, boundary) in [
+        (paths.config_toml(), UninitCheckpoint::ConfigRemoved),
+        (
+            paths.extension_config(),
+            UninitCheckpoint::ExtensionConfigRemoved,
+        ),
+        (paths.daemon_pid(), UninitCheckpoint::DaemonPidRemoved),
+        (paths.daemon_log(), UninitCheckpoint::DaemonLogRemoved),
+        (paths.daemon_socket(), UninitCheckpoint::DaemonSocketRemoved),
+    ] {
+        remove_child(paths, &lease, &path)?;
+        checkpoint(fault, boundary)?;
+    }
+
+    drop(authorization);
+    drop(lease);
+    Ok(UninitOutcome {
+        legacy_index_present: paths.legacy_roots().iter().any(|path| path.exists()),
+    })
+}
+
+/// Append SQLite's sidecar suffix to the native database pathname without a
+/// Unicode rendering round-trip. Both Unix byte paths and Windows wide paths
+/// remain lossless.
+fn sqlite_sidecar_path(db: &Path, suffix: &str) -> PathBuf {
+    let mut native = db.as_os_str().to_os_string();
+    native.push(suffix);
+    PathBuf::from(native)
+}
+
+fn checkpoint(
+    fault: &mut impl UninitFault,
+    checkpoint: UninitCheckpoint,
+) -> Result<(), UninitError> {
+    fault
+        .after(checkpoint)
+        .map_err(|source| UninitError::Interrupted {
+            step: checkpoint.label(),
+            source,
+        })
+}
+
+fn ensure_tombstone(paths: &IndexPaths, lease: &IndexLease) -> Result<(), UninitError> {
+    lease.validate_exclusive(paths)?;
+    let path = paths.tombstone();
+    match std::fs::symlink_metadata(&path) {
+        Ok(metadata) if metadata.file_type().is_file() => return Ok(()),
+        Ok(_) => return Err(UninitError::UnsupportedChild { path }),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+        Err(source) => return Err(UninitError::Tombstone { path, source }),
+    }
+
+    let mut file = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&path)
+        .map_err(|source| UninitError::Tombstone {
+            path: path.clone(),
+            source,
+        })?;
+    file.write_all(TOMBSTONE_BYTES)
+        .and_then(|()| file.flush())
+        .and_then(|()| file.sync_all())
+        .map_err(|source| UninitError::Tombstone { path, source })
+}
+
+fn remove_child(paths: &IndexPaths, lease: &IndexLease, path: &Path) -> Result<(), UninitError> {
+    lease.validate_exclusive(paths)?;
+    match std::fs::symlink_metadata(path) {
+        Ok(metadata) if metadata.file_type().is_dir() => Err(UninitError::UnsupportedChild {
+            path: path.to_path_buf(),
+        }),
+        Ok(_) => std::fs::remove_file(path).map_err(|source| UninitError::RemoveChild {
+            path: path.to_path_buf(),
+            source,
+        }),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(source) => Err(UninitError::RemoveChild {
+            path: path.to_path_buf(),
+            source,
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::{BTreeMap, BTreeSet};
+    use std::time::Duration;
+
+    use crate::{CURRENT_EXTRACTION_VERSION, CURRENT_STORAGE_PROTOCOL, checksum_hex, classify};
+
+    struct TempProject(PathBuf);
+
+    impl TempProject {
+        fn new(label: &str) -> Self {
+            let path = std::env::temp_dir().join(format!(
+                "codegraph-uninit-{label}-{}-{}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .expect("system clock after epoch")
+                    .as_nanos()
+            ));
+            std::fs::create_dir(&path).expect("create uninit test project");
+            Self(path.canonicalize().expect("canonicalize test project"))
+        }
+
+        fn paths(&self) -> IndexPaths {
+            IndexPaths::resolve(&self.0, None).expect("resolve uninit paths")
+        }
+    }
+
+    impl Drop for TempProject {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    fn deadline() -> Instant {
+        Instant::now() + Duration::from_secs(10)
+    }
+
+    fn db_artifact(paths: &IndexPaths, suffix: &str) -> PathBuf {
+        sqlite_sidecar_path(&paths.current_db(), suffix)
+    }
+
+    fn stage_building_with_all_residue(paths: &IndexPaths) {
+        let lease = IndexLease::create_exclusive(paths, deadline(), || false)
+            .expect("create Building namespace");
+        publish_index_state(paths, &lease, StatePhase::Building).expect("publish Building fixture");
+        for (path, bytes) in [
+            (paths.current_db(), b"db residue".as_slice()),
+            (db_artifact(paths, "-wal"), b"wal residue".as_slice()),
+            (db_artifact(paths, "-shm"), b"shm residue".as_slice()),
+            (paths.config_toml(), b"config residue".as_slice()),
+            (paths.extension_config(), b"extension residue".as_slice()),
+            (paths.daemon_pid(), b"pid residue".as_slice()),
+            (paths.daemon_log(), b"log residue".as_slice()),
+            (paths.daemon_socket(), b"socket residue".as_slice()),
+        ] {
+            std::fs::write(path, bytes).expect("write uninit residue fixture");
+        }
+        drop(lease);
+    }
+
+    #[derive(Debug, Clone, PartialEq, Eq)]
+    enum SnapshotEntry {
+        Directory,
+        File(Vec<u8>),
+        Symlink(PathBuf),
+    }
+
+    fn snapshot(root: &Path) -> BTreeMap<PathBuf, SnapshotEntry> {
+        fn walk(root: &Path, dir: &Path, out: &mut BTreeMap<PathBuf, SnapshotEntry>) {
+            let mut children = std::fs::read_dir(dir)
+                .unwrap_or_else(|error| panic!("snapshot read_dir {}: {error}", dir.display()))
+                .map(|entry| {
+                    entry
+                        .unwrap_or_else(|error| {
+                            panic!("snapshot entry in {}: {error}", dir.display())
+                        })
+                        .path()
+                })
+                .collect::<Vec<_>>();
+            children.sort();
+            for path in children {
+                let relative = path
+                    .strip_prefix(root)
+                    .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                    .to_path_buf();
+                let metadata = std::fs::symlink_metadata(&path).unwrap_or_else(|error| {
+                    panic!("snapshot metadata {}: {error}", path.display())
+                });
+                let ty = metadata.file_type();
+                let entry = if ty.is_dir() {
+                    SnapshotEntry::Directory
+                } else if ty.is_file() {
+                    SnapshotEntry::File(std::fs::read(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read {}: {error}", path.display())
+                    }))
+                } else if ty.is_symlink() {
+                    SnapshotEntry::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
+                        panic!("snapshot read_link {}: {error}", path.display())
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
+                assert!(out.insert(relative, entry).is_none());
+                if ty.is_dir() {
+                    walk(root, &path, out);
+                }
+            }
+        }
+
+        let mut out = BTreeMap::new();
+        walk(root, root, &mut out);
+        out
+    }
+
+    fn assert_unchanged(
+        before: &BTreeMap<PathBuf, SnapshotEntry>,
+        after: &BTreeMap<PathBuf, SnapshotEntry>,
+    ) {
+        let changed = before
+            .keys()
+            .chain(after.keys())
+            .filter(|path| before.get(*path) != after.get(*path))
+            .cloned()
+            .collect::<BTreeSet<_>>();
+        assert!(changed.is_empty(), "filesystem changed at {changed:?}");
+    }
+
+    struct FailAfter(UninitCheckpoint);
+
+    impl UninitFault for FailAfter {
+        fn after(&mut self, checkpoint: UninitCheckpoint) -> io::Result<()> {
+            if checkpoint == self.0 {
+                Err(io::Error::other("injected uninit interruption"))
+            } else {
+                Ok(())
+            }
+        }
+    }
+
+    #[test]
+    fn interrupted_uninit_state_slot_is_recoverable_not_corrupt_fault_matrix() {
+        for (boundary, expected_step, tombstone_present, removed_count) in [
+            (
+                UninitCheckpoint::StatePublished,
+                "uninitialized state publication",
+                false,
+                0,
+            ),
+            (
+                UninitCheckpoint::TombstoneEnsured,
+                "tombstone creation",
+                true,
+                0,
+            ),
+            (
+                UninitCheckpoint::DatabaseRemoved,
+                "database removal",
+                true,
+                1,
+            ),
+            (UninitCheckpoint::WalRemoved, "WAL removal", true, 2),
+            (UninitCheckpoint::ShmRemoved, "SHM removal", true, 3),
+            (UninitCheckpoint::ConfigRemoved, "config removal", true, 4),
+            (
+                UninitCheckpoint::ExtensionConfigRemoved,
+                "extension config removal",
+                true,
+                5,
+            ),
+            (
+                UninitCheckpoint::DaemonPidRemoved,
+                "daemon pid removal",
+                true,
+                6,
+            ),
+            (
+                UninitCheckpoint::DaemonLogRemoved,
+                "daemon log removal",
+                true,
+                7,
+            ),
+            (
+                UninitCheckpoint::DaemonSocketRemoved,
+                "daemon socket removal",
+                true,
+                8,
+            ),
+        ] {
+            let project = TempProject::new("fault-matrix");
+            let paths = project.paths();
+            stage_building_with_all_residue(&paths);
+            let legacy = project.0.join(".codegraph");
+            std::fs::create_dir(&legacy).expect("create legacy namespace");
+            std::fs::write(legacy.join("legacy.bin"), b"legacy bytes")
+                .expect("write legacy proof bytes");
+            let legacy_before = snapshot(&legacy);
+
+            let error = uninit_index_with(&paths, deadline(), || false, &mut FailAfter(boundary))
+                .expect_err("fault checkpoint must interrupt uninit");
+            match error {
+                UninitError::Interrupted { step, source } => {
+                    assert_eq!(step, expected_step, "boundary={boundary:?}");
+                    assert_eq!(source.kind(), io::ErrorKind::Other);
+                }
+                other => panic!("unexpected fault result at {boundary:?}: {other:?}"),
+            }
+            assert_eq!(
+                Store::extraction_status(&paths),
+                ExtractionStatus::Uninitialized,
+                "boundary={boundary:?} must leave authenticated interrupted-uninit state"
+            );
+            assert!(paths.current_root().is_dir(), "boundary={boundary:?}");
+            assert!(paths.permanent_lock().is_file());
+            assert!(paths.state_slots().iter().all(|slot| slot.is_file()));
+            assert_eq!(
+                paths.tombstone().is_file(),
+                tombstone_present,
+                "unexpected tombstone frontier at {boundary:?}"
+            );
+            let artifacts = [
+                paths.current_db(),
+                db_artifact(&paths, "-wal"),
+                db_artifact(&paths, "-shm"),
+                paths.config_toml(),
+                paths.extension_config(),
+                paths.daemon_pid(),
+                paths.daemon_log(),
+                paths.daemon_socket(),
+            ];
+            for (index, artifact) in artifacts.iter().enumerate() {
+                assert_eq!(
+                    artifact.exists(),
+                    index >= removed_count,
+                    "unexpected deletion frontier at {boundary:?}: artifact #{index} {}",
+                    artifact.display()
+                );
+            }
+            assert_unchanged(&legacy_before, &snapshot(&legacy));
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn non_utf8_database_sidecars_are_removed_without_touching_lossy_lookalikes() {
+        use std::ffi::OsString;
+        use std::os::unix::ffi::OsStringExt;
+
+        let outer = TempProject::new("non-utf8-sidecar");
+        let project_path = outer.0.join(OsString::from_vec(b"project-\xff".to_vec()));
+        std::fs::create_dir(&project_path).expect("create non-UTF-8 project");
+        let project = TempProject(project_path.canonicalize().expect("canonicalize project"));
+        let paths = project.paths();
+        stage_building_with_all_residue(&paths);
+
+        let native_wal = db_artifact(&paths, "-wal");
+        let native_shm = db_artifact(&paths, "-shm");
+        let lossy_wal = PathBuf::from(format!("{}-wal", paths.current_db().display()));
+        assert_ne!(native_wal, lossy_wal, "fixture must expose lossy rendering");
+        std::fs::create_dir_all(lossy_wal.parent().expect("lossy WAL parent"))
+            .expect("create lossy-lookalike parent");
+        std::fs::write(&lossy_wal, b"must survive").expect("write lossy-lookalike WAL");
+
+        uninit_index(&paths, deadline(), || false).expect("uninit non-UTF-8 namespace");
+
+        assert!(!native_wal.exists(), "true native WAL must be removed");
+        assert!(!native_shm.exists(), "true native SHM must be removed");
+        assert_eq!(
+            std::fs::read(&lossy_wal).expect("read preserved lossy lookalike"),
+            b"must survive"
+        );
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Uninitialized
+        );
+    }
+
+    #[test]
+    fn every_db_sidecar_tombstone_residue_combination_is_uninitialized() {
+        for bits in 0_u8..16 {
+            let project = TempProject::new("residue-matrix");
+            let paths = project.paths();
+            let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+                .expect("create residue namespace");
+            publish_index_state(&paths, &lease, StatePhase::Building).expect("publish Building");
+            publish_index_state(&paths, &lease, StatePhase::Uninitialized)
+                .expect("publish Uninitialized");
+            drop(lease);
+
+            for (bit, path) in [
+                (0, paths.current_db()),
+                (1, db_artifact(&paths, "-wal")),
+                (2, db_artifact(&paths, "-shm")),
+                (3, paths.tombstone()),
+            ] {
+                if bits & (1 << bit) != 0 {
+                    std::fs::write(path, format!("residue bit {bit}"))
+                        .expect("write residue combination");
+                }
+            }
+
+            assert_eq!(
+                Store::extraction_status(&paths),
+                ExtractionStatus::Uninitialized,
+                "bits={bits:04b}"
+            );
+            let status = Store::open_for_status(&paths, deadline(), || false)
+                .expect("Uninitialized residue is typed status data");
+            assert_eq!(status.status, Some(ExtractionStatus::Uninitialized));
+            let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+                .expect("acquire continuation lease");
+            assert!(matches!(
+                Store::open_for_write(&paths, lease, StoreWritePurpose::UninitContinuation,),
+                Ok(StoreWriteOpen::UninitContinuation(_))
+            ));
+        }
+    }
+
+    #[test]
+    fn repeated_uninit_uses_monotonic_publication_and_preserves_both_slots() {
+        let project = TempProject::new("continuation");
+        let paths = project.paths();
+        stage_building_with_all_residue(&paths);
+
+        uninit_index(&paths, deadline(), || false).expect("first uninit pass");
+        let first = classify(&paths);
+        let first_authority = first
+            .authoritative()
+            .expect("first uninit has authority")
+            .clone();
+        let first_bytes =
+            std::fs::read(&first_authority.path).expect("read first authoritative slot");
+        std::fs::write(paths.current_db(), b"continued residue")
+            .expect("stage continuation residue");
+
+        uninit_index(&paths, deadline(), || false).expect("continued uninit pass");
+        let second = classify(&paths);
+        let second_authority = second.authoritative().expect("second uninit has authority");
+        assert_eq!(second.status(), &ExtractionStatus::Uninitialized);
+        assert_eq!(
+            second_authority.record.sequence,
+            first_authority.record.sequence + 1
+        );
+        assert_eq!(
+            std::fs::read(&first_authority.path).expect("old authority remains readable"),
+            first_bytes
+        );
+        assert!(paths.state_slots().iter().all(|slot| slot.is_file()));
+        assert!(!paths.current_db().exists());
+    }
+
+    fn write_future_uninitialized(paths: &IndexPaths) {
+        let sequence = 0;
+        let protocol = CURRENT_STORAGE_PROTOCOL + 1;
+        let extraction = CURRENT_EXTRACTION_VERSION + 1;
+        let phase = "uninitialized";
+        let checksum = checksum_hex(
+            sequence,
+            protocol,
+            extraction,
+            phase,
+            paths.project_identity(),
+        );
+        std::fs::write(
+            &paths.state_slots()[0],
+            serde_json::to_vec(&serde_json::json!({
+                "sequence": sequence,
+                "storageProtocol": protocol,
+                "extractionVersion": extraction,
+                "phase": phase,
+                "projectIdentity": paths.project_identity(),
+                "checksum": checksum,
+            }))
+            .expect("serialize Future fixture"),
+        )
+        .expect("write Future fixture");
+    }
+
+    #[test]
+    fn future_corrupt_owner_mismatch_and_missing_lock_are_byte_nonmutating() {
+        for fixture in ["future", "corrupt", "owner-mismatch"] {
+            let project = TempProject::new("refused");
+            let paths = project.paths();
+            let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+                .expect("create refusal namespace");
+            match fixture {
+                "future" => write_future_uninitialized(&paths),
+                "corrupt" => std::fs::write(&paths.state_slots()[0], b"not-json")
+                    .expect("write Corrupt fixture"),
+                "owner-mismatch" => {
+                    let sequence = 0;
+                    let owner = "0".repeat(64);
+                    let checksum = checksum_hex(
+                        sequence,
+                        CURRENT_STORAGE_PROTOCOL,
+                        CURRENT_EXTRACTION_VERSION,
+                        "uninitialized",
+                        &owner,
+                    );
+                    std::fs::write(
+                        &paths.state_slots()[0],
+                        serde_json::to_vec(&serde_json::json!({
+                            "sequence": sequence,
+                            "storageProtocol": CURRENT_STORAGE_PROTOCOL,
+                            "extractionVersion": CURRENT_EXTRACTION_VERSION,
+                            "phase": "uninitialized",
+                            "projectIdentity": owner,
+                            "checksum": checksum,
+                        }))
+                        .expect("serialize owner-mismatch fixture"),
+                    )
+                    .expect("write owner-mismatch fixture");
+                }
+                _ => unreachable!(),
+            }
+            drop(lease);
+            let before = snapshot(&project.0);
+            assert!(matches!(
+                uninit_index(&paths, deadline(), || false),
+                Err(UninitError::StateRejected { .. })
+            ));
+            assert_unchanged(&before, &snapshot(&project.0));
+        }
+
+        let project = TempProject::new("missing-lock");
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+            .expect("create missing-lock namespace");
+        publish_index_state(&paths, &lease, StatePhase::Building).expect("publish Building");
+        publish_index_state(&paths, &lease, StatePhase::Uninitialized)
+            .expect("publish Uninitialized");
+        drop(lease);
+        std::fs::remove_file(paths.permanent_lock()).expect("remove permanent lock fixture");
+        let before = snapshot(&project.0);
+        assert!(matches!(
+            uninit_index(&paths, deadline(), || false),
+            Err(UninitError::Lease(IndexLeaseError::LockNotFound { .. }))
+        ));
+        assert_unchanged(&before, &snapshot(&project.0));
+    }
+
+    #[test]
+    fn nonmutation_snapshot_detects_equal_length_replacement() {
+        let project = TempProject::new("snapshot-self-test");
+        let path = project.0.join("same-length.bin");
+        std::fs::write(&path, b"AAAA").expect("write snapshot fixture");
+        let before = snapshot(&project.0);
+        std::fs::write(&path, b"BBBB").expect("replace fixture at equal length");
+        let after = snapshot(&project.0);
+        assert!(
+            std::panic::catch_unwind(|| assert_unchanged(&before, &after)).is_err(),
+            "snapshot oracle must reject equal-length byte replacement"
+        );
+    }
+}
diff --git a/crates/codegraph-store/tests/index_state_publisher.rs b/crates/codegraph-store/tests/index_state_publisher.rs
index 364900b..9584e97 100644
--- a/crates/codegraph-store/tests/index_state_publisher.rs
+++ b/crates/codegraph-store/tests/index_state_publisher.rs
@@ -312,7 +312,6 @@ fn invalid_lifecycle_transitions_are_byte_nonmutating() {
         (PriorStatus::Outdated, StatePhase::Current),
         (PriorStatus::Outdated, StatePhase::Uninitialized),
         (PriorStatus::Uninitialized, StatePhase::Current),
-        (PriorStatus::Uninitialized, StatePhase::Uninitialized),
         (PriorStatus::Current, StatePhase::Current),
     ];
 
diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
index 7e318ff..2ade34d 100644
--- a/crates/codegraph-store/tests/store_state_gates.rs
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -606,7 +606,7 @@ fn write_purpose_matrix_is_typed_and_rejected_pairs_are_nonmutating() {
         (
             FixtureStatus::Building,
             StoreWritePurpose::UninitContinuation,
-            "reject",
+            "uninit",
         ),
         (
             FixtureStatus::Outdated,
@@ -671,7 +671,7 @@ fn write_purpose_matrix_is_typed_and_rejected_pairs_are_nonmutating() {
             }
             ("uninit", Ok(StoreWriteOpen::UninitContinuation(authorization))) => {
                 assert_eq!(authorization.purpose(), purpose);
-                assert_eq!(authorization.status(), &ExtractionStatus::Uninitialized);
+                assert_eq!(authorization.status(), &expected_status(status));
                 assert!(authorization.retains_exclusive_lease());
                 assert_eq!(
                     run_exclusive_probe(project.path(), SHORT_DEADLINE),
@@ -707,15 +707,18 @@ fn current_state_accepts_only_current_mutation_or_explicit_full_rebuild() {
     let uninit_lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
         .expect("acquire Current continuation rejection lease");
     let before = snapshot_tree(project.path());
-    let error = Store::open_for_write(&paths, uninit_lease, StoreWritePurpose::UninitContinuation)
-        .expect_err("a continuation purpose cannot start a new Current-state uninit");
-    assert!(matches!(
-        error,
-        StoreError::WritePurposeRejected {
-            purpose: StoreWritePurpose::UninitContinuation,
-            status: ExtractionStatus::Current
-        }
-    ));
+    let StoreWriteOpen::UninitContinuation(authorization) =
+        Store::open_for_write(&paths, uninit_lease, StoreWritePurpose::UninitContinuation)
+            .expect("Current state authorizes a new uninit under the retained lease")
+    else {
+        panic!("Current uninit must return opaque authorization");
+    };
+    assert_eq!(authorization.status(), &ExtractionStatus::Current);
+    assert_eq!(
+        authorization.purpose(),
+        StoreWritePurpose::UninitContinuation
+    );
+    drop(authorization);
     assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
 }
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 6679cfd..9170893 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -1902,3 +1902,182 @@ These bytes are the input to the parent's final `make fmt` and single
 authoritative `make ci CARGO='cargo --locked'`. No later documentation edit is
 permitted; completion is decided by that post-format gate and the subsequent
 lock-hash/diff/status audit.
+
+## Batch M item 11 — interrupted uninit Red (2026-07-26)
+
+Scope was checked before mutation. Acceptance item 10,
+`interrupted_v2_rebuild_remains_fail_closed_and_legacy_untouched`, is already
+covered by the committed rebuild finalizer's deterministic pre-Current fault
+matrix (`every_rebuild_fault_leaves_building_or_missing_and_unreadable`), its
+fixed-lock replacement/refusal tests, and the rebuild implementation that removes
+only the resolved v2 DB/WAL/SHM paths. This slice therefore adds no separate
+item-10 implementation; it reuses those primitives only where item 11 shares the
+same lease-validation boundary.
+
+The item-11 public behavioral Red was added as
+`crates/codegraph-cli/tests/batch_m_uninit.rs` ::
+`interrupted_uninit_state_slot_is_recoverable_not_corrupt`. Exact command, after
+the required successful version gate:
+
+```text
+bash scripts/check-workspace-versions.sh && cargo test -p codegraph-rs --locked --test batch_m_uninit interrupted_uninit_state_slot_is_recoverable_not_corrupt -- --exact
+```
+
+Observed exit status: `101`; compilation and fixture setup succeeded, including a
+successful real `codegraph init`. The sole business assertion then failed with
+`left: Missing`, `right: Uninitialized`: existing `cmd_uninit` recursively removed
+the entire v2 root instead of durably publishing `phase=uninitialized` and
+preserving the permanent lock, tombstone, and fixed slots. This is a lifecycle
+behavior failure, not a compile, setup, fixture, or unrelated-test failure.
+
+## Batch M item 11 — interrupted uninit focused Green (2026-07-26)
+
+The Store now owns one crash-recoverable uninit lifecycle. It performs a
+nonmutating visible-state probe, acquires the pre-existing permanent lock
+exclusively without repairing it, reclassifies and authorizes under that retained
+lease, publishes a newer owner-bound `phase=uninitialized` slot, ensures the
+tombstone, and removes only the resolved v2 DB/WAL/SHM, config, and runtime
+children. The permanent lock, tombstone, both fixed state slots, parent directory,
+and every legacy-root byte remain untouched. A repeated `uninit --force`
+publishes another monotonic `uninitialized` sequence before continuing cleanup,
+as required by frozen Revision 14 lines 409-429.
+
+Current-state uninit corroborates the checkpointed main database extraction stamp
+while permitting live WAL/SHM residue. This is intentionally the same narrow
+writer-side distinction already used by incremental sync: a live reader may
+legitimately recreate sidecars, and uninit must first authenticate Current,
+publish `Uninitialized`, and only then delete those sidecars. Read and publication
+paths remain sidecar-free.
+
+Deterministic Store tests inject failure after state publication, tombstone
+creation, each DB/sidecar removal, and each config/runtime removal. Every result
+classifies `Uninitialized`, retains both slots and the permanent lock, and leaves
+legacy bytes unchanged. A complete 16-combination DB/WAL/SHM/tombstone residue
+matrix stays typed `Uninitialized`; Future, Corrupt, owner-mismatch, and
+missing-lock fixtures are byte-nonmutating refusals. The snapshot oracle records
+directories, complete regular-file bytes, and symlink targets, and its self-test
+detects equal-length replacement.
+
+Focused commands, each preceded by the successful workspace-version gate:
+
+```text
+cargo test -p codegraph-store --locked uninit -- --nocapture
+# 5 passed; 0 failed
+
+cargo test -p codegraph-rs --locked --test batch_m_uninit -- --nocapture
+# 1 passed; 0 failed
+```
+
+The public CLI acceptance runs real `init -> uninit --force -> status --json`,
+proves `initialized:false`, `extractionStatus:"uninitialized"`, and untouched
+legacy presence, then proves `sync`, forced/plain `index`, and graph reads all
+fail without changing either state slot. A repeated uninit succeeds with sequence
+`N+1`; explicit `init` then publishes `building` and `current`, rebuilds the DB,
+removes the tombstone only after Current publication, and again preserves legacy
+bytes. Status now exposes stable `extractionStatus`, detail, legacy-presence, and
+legacy-path fields for both initialized and non-initialized output.
+
+All eight changed Rust files returned `No diagnostics found` from
+`lsp_diagnostics`. Because the implementation worktree is outside the request
+CWD, diagnostics were run against a detached same-HEAD worktree with the exact
+tracked diff and both new Rust files copied byte-for-byte. Native Windows runtime
+or crash behavior remains unavailable on this Linux host and is not claimed.
+
+These bytes precede the final format and single authoritative locked CI gate; no
+CI success is claimed in this section.
+
+## Batch M item 11 — first full-gate correction (2026-07-26)
+
+The first authoritative `make ci CARGO='cargo --locked'` attempt passed formatting,
+Clippy, and all earlier workspace suites before failing two existing
+`batch_m_outdated_migration` tests. Both failures were exact CLI policy regressions:
+`sync` returned `CodeGraph not initialized` for authenticated `Outdated` state, so
+the already-implemented under-lease migration gate was unreachable. No uninit,
+Store, publisher, or golden test failed.
+
+Root cause was the item-11 change from DB-presence initialization to typed Current
+initialization while `cmd_sync` still called `resolve_required_project`. The fix is
+to use `resolve_required_rebuild_project` for sync discovery, matching the frozen
+command matrix: authenticated Outdated/Building reaches migration;
+Uninitialized reaches the Store gate only to receive its typed nonmutating refusal.
+No authorization was widened.
+
+Focused correction command, after the workspace-version gate:
+
+```text
+cargo test -p codegraph-rs --locked --test batch_m_outdated_migration --test batch_m_uninit -- --nocapture
+# batch_m_outdated_migration: 5 passed; 0 failed
+# batch_m_uninit: 1 passed; 0 failed
+```
+
+This correction is included before the final formatting pass and the one remaining
+full-gate retry; that retry's result is not claimed here.
+
+## Batch M item 11 — second full-gate result and stale-test correction (2026-07-26)
+
+The second and final permitted `make ci CARGO='cargo --locked'` attempt passed the
+workspace-version gate, formatting, Clippy, and all workspace tests reached through
+the new Store/CLI uninit suites, Outdated migration, v2 namespace, and related CLI
+coverage. It then stopped at one pre-existing `cli_commands` assertion named
+`uninit_requires_force_then_removes`: the test still required the entire
+`.codegraph-v2` root to disappear. That expectation directly contradicted frozen
+Revision 14, which requires preserving the root, permanent lock, tombstone, and
+both fixed state slots after successful cleanup. No production behavior failed at
+that point.
+
+The stale test was updated, not weakened: it still proves uninit without `--force`
+is refused and nonmutating, then proves forced uninit succeeds, classifies
+`Uninitialized`, preserves the lifecycle root/lock/tombstone/two slots, and removes
+the v2 database. The test is renamed
+`uninit_requires_force_then_preserves_recovery_state` to state the protocol
+contract accurately.
+
+Per the two-check ceiling, no third complete CI run is claimed. Closure uses one
+post-format targeted command covering the corrected existing CLI suite together
+with the new item-11 acceptance suite, followed by the lock-hash and scoped-diff
+audit; its actual result is reported in the task handoff rather than retroactively
+represented as a full-CI success.
+
+## Batch M item 11 — independent-review blocker correction (2026-07-26)
+
+An independent review rejected the preceding candidate on four concrete defects;
+this append preserves the prior evidence and records the corrective implementation
+without claiming another full workspace CI run.
+
+1. SQLite sidecar paths no longer pass through `Path::display()`. Store uninit and
+   rebuild append `-wal` / `-shm` directly to the database's native `OsString`, and
+   every item-11 test helper uses the same lossless construction. A Unix-only
+   regression creates a non-UTF-8 project path, proves the true native WAL/SHM are
+   removed, and proves the distinct lossy-rendered lookalike WAL survives.
+2. An absolute `CODEGRAPH_DIR` is exact-project-only for implicit CLI discovery.
+   From a nested directory, `uninit --force` now fails with the stable remedy
+   `pass the project root explicitly` and a complete namespace snapshot proves no
+   byte or entry changed; the same command with the explicit project root remains
+   accepted. Default/relative roots retain ancestor discovery.
+3. Status ancestor discovery now uses authenticated lifecycle state rather than
+   readable-Current alone. Nested status reports parent `Uninitialized`,
+   `Outdated`, `Building`, `Future`, and `Corrupt` state, while a lock-only parent
+   remains a non-marker. Discovery still never opens SQLite or authorizes a
+   mutation; those decisions remain in Store's typed state gates. Outdated sync
+   migration reachability and Uninitialized sync refusal are unchanged.
+4. The public negative command matrix now compares a fail-closed whole-namespace
+   snapshot: directory presence, complete regular-file bytes, symlink targets,
+   and native `PathBuf` keys. Every I/O/unsupported-kind failure panics, comparison
+   diagnostics list only changed paths, and an equal-length replacement self-test
+   proves the oracle catches same-size mutation.
+
+The Store uninit fault matrix now pins the exact `Interrupted.step`, exact
+tombstone state, and exact ordered deletion frontier at every checkpoint while
+also requiring the retained root, permanent lock, two fixed slots, unchanged
+legacy namespace, and `Uninitialized` classification. Rebuild fault evidence now
+independently interrupts explicit-init recovery immediately after Building and
+Current publication. Building interruption retains the tombstone and remains
+Building; Current interruption retains the tombstone and remains Current; both
+keep two valid slots, never become accidental Corrupt, and a later explicit init
+successfully reaches Current before removing the tombstone.
+
+Focused tests for each correction passed during implementation, each after the
+workspace-version gate. Final affected-package tests, diagnostics, formatting,
+Clippy, and lock/scope audit are recorded in the task handoff after their actual
+execution. Native Windows runtime/crash coverage remains unavailable on this Linux
+host and is not claimed.

From ead6c264f1df627ba875a53def9bb11e30e8d901 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 08:15:36 +0800
Subject: [PATCH 24/91] test(store): cover writer process lifecycle

---
 .../tests/writer_process_lifecycle.rs         | 856 ++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 192 ++++
 2 files changed, 1048 insertions(+)
 create mode 100644 crates/codegraph-store/tests/writer_process_lifecycle.rs

diff --git a/crates/codegraph-store/tests/writer_process_lifecycle.rs b/crates/codegraph-store/tests/writer_process_lifecycle.rs
new file mode 100644
index 0000000..7908557
--- /dev/null
+++ b/crates/codegraph-store/tests/writer_process_lifecycle.rs
@@ -0,0 +1,856 @@
+//! Process-level acceptance for the production v2 full-writer lifecycle.
+
+#![cfg(unix)]
+
+use std::collections::BTreeMap;
+use std::fs::{self, File, Metadata};
+use std::io::{BufRead, BufReader, Read, Write};
+use std::os::unix::fs::MetadataExt as _;
+use std::os::unix::process::ExitStatusExt;
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, Command, ExitStatus, Stdio};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::mpsc;
+use std::thread::JoinHandle;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{
+    ExtractionStatus, IndexLeaseError, RebuildError, RebuildKind, Store, begin_full_rebuild,
+};
+
+const CHILD_ACTION: &str = "CODEGRAPH_WRITER_LIFECYCLE_CHILD_ACTION";
+const CHILD_PROJECT: &str = "CODEGRAPH_WRITER_LIFECYCLE_CHILD_PROJECT";
+const CHILD_WAIT: Duration = Duration::from_secs(10);
+const LOSER_DEADLINE: Duration = Duration::from_millis(80);
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum NamespaceEntry {
+    Directory,
+    RegularFile(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SnapshotCheckpoint {
+    DirectoryPathValidated,
+    DirectoryHandleAndPathCorroborated,
+    DirectoryEnumerationCorroborated,
+    RegularPathValidated,
+    RegularHandleCorroborated,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum NamespaceSnapshotError {
+    PathChangedDuringRead(PathBuf),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct FileIdentity {
+    device: u64,
+    inode: u64,
+}
+
+impl FileIdentity {
+    fn from_metadata(metadata: &Metadata) -> Self {
+        Self {
+            device: metadata.dev(),
+            inode: metadata.ino(),
+        }
+    }
+}
+
+struct TempProject(PathBuf);
+
+impl TempProject {
+    fn new(label: &str) -> Self {
+        let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-writer-lifecycle-{label}-{}-{serial}",
+            std::process::id()
+        ));
+        fs::create_dir(&path)
+            .unwrap_or_else(|error| panic!("create temp project {}: {error}", path.display()));
+        Self(path.canonicalize().expect("canonical temp project"))
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(&self.0, None).expect("resolve test IndexPaths")
+    }
+}
+
+impl Drop for TempProject {
+    fn drop(&mut self) {
+        fs::remove_dir_all(&self.0)
+            .unwrap_or_else(|error| panic!("remove temp project {}: {error}", self.0.display()));
+    }
+}
+
+fn deadline_after(duration: Duration) -> Instant {
+    Instant::now()
+        .checked_add(duration)
+        .expect("test deadline is representable")
+}
+
+fn snapshot_namespace(root: &Path) -> BTreeMap<PathBuf, NamespaceEntry> {
+    snapshot_namespace_with_checkpoint(root, |_, _| {})
+        .expect("snapshot namespace without path replacement")
+}
+
+fn snapshot_namespace_with_checkpoint<F>(
+    root: &Path,
+    mut checkpoint: F,
+) -> Result<BTreeMap<PathBuf, NamespaceEntry>, NamespaceSnapshotError>
+where
+    F: FnMut(&Path, SnapshotCheckpoint),
+{
+    fn corroborate_directory_path(
+        directory: &Path,
+        initial_identity: FileIdentity,
+        stage: &str,
+    ) -> Result<(), NamespaceSnapshotError> {
+        let metadata = match fs::symlink_metadata(directory) {
+            Ok(metadata) => metadata,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                return Err(NamespaceSnapshotError::PathChangedDuringRead(
+                    directory.to_path_buf(),
+                ));
+            }
+            Err(error) => panic!(
+                "reinspect namespace directory {stage} {}: {error}",
+                directory.display()
+            ),
+        };
+        if !metadata.file_type().is_dir()
+            || FileIdentity::from_metadata(&metadata) != initial_identity
+        {
+            return Err(NamespaceSnapshotError::PathChangedDuringRead(
+                directory.to_path_buf(),
+            ));
+        }
+        Ok(())
+    }
+
+    fn walk<F>(
+        root: &Path,
+        directory: &Path,
+        initial_identity: FileIdentity,
+        snapshot: &mut BTreeMap<PathBuf, NamespaceEntry>,
+        checkpoint: &mut F,
+    ) -> Result<(), NamespaceSnapshotError>
+    where
+        F: FnMut(&Path, SnapshotCheckpoint),
+    {
+        let opened_directory = match File::open(directory) {
+            Ok(directory) => directory,
+            Err(error) => {
+                corroborate_directory_path(directory, initial_identity, "after failed open")?;
+                panic!("open namespace directory {}: {error}", directory.display());
+            }
+        };
+        let opened_metadata = opened_directory.metadata().unwrap_or_else(|error| {
+            panic!(
+                "inspect opened namespace directory {}: {error}",
+                directory.display()
+            )
+        });
+        if !opened_metadata.file_type().is_dir()
+            || FileIdentity::from_metadata(&opened_metadata) != initial_identity
+        {
+            return Err(NamespaceSnapshotError::PathChangedDuringRead(
+                directory.to_path_buf(),
+            ));
+        }
+
+        corroborate_directory_path(directory, initial_identity, "before enumeration")?;
+        checkpoint(
+            directory,
+            SnapshotCheckpoint::DirectoryHandleAndPathCorroborated,
+        );
+        let entries = match fs::read_dir(directory) {
+            Ok(entries) => entries,
+            Err(error) => {
+                corroborate_directory_path(
+                    directory,
+                    initial_identity,
+                    "after failed enumeration",
+                )?;
+                panic!("read namespace directory {}: {error}", directory.display());
+            }
+        };
+        let mut paths = Vec::new();
+        for entry in entries {
+            match entry {
+                Ok(entry) => paths.push(entry.path()),
+                Err(error) => {
+                    corroborate_directory_path(
+                        directory,
+                        initial_identity,
+                        "after failed entry enumeration",
+                    )?;
+                    panic!(
+                        "read namespace entry under {}: {error}",
+                        directory.display()
+                    );
+                }
+            }
+        }
+        corroborate_directory_path(directory, initial_identity, "after enumeration")?;
+        checkpoint(
+            directory,
+            SnapshotCheckpoint::DirectoryEnumerationCorroborated,
+        );
+        paths.sort();
+
+        for path in paths {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|error| {
+                    panic!(
+                        "namespace entry {} escaped root {}: {error}",
+                        path.display(),
+                        root.display()
+                    )
+                })
+                .to_path_buf();
+            let metadata = match fs::symlink_metadata(&path) {
+                Ok(metadata) => metadata,
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                    return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                }
+                Err(error) => panic!("inspect namespace entry {}: {error}", path.display()),
+            };
+            let file_type = metadata.file_type();
+            let entry = if file_type.is_dir() {
+                NamespaceEntry::Directory
+            } else if file_type.is_file() {
+                let initial_identity = FileIdentity::from_metadata(&metadata);
+                checkpoint(&path, SnapshotCheckpoint::RegularPathValidated);
+                let mut file = match File::open(&path) {
+                    Ok(file) => file,
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                        return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                    }
+                    Err(error) => panic!("open namespace file {}: {error}", path.display()),
+                };
+                let opened = file.metadata().unwrap_or_else(|error| {
+                    panic!("inspect opened namespace file {}: {error}", path.display())
+                });
+                if !opened.file_type().is_file()
+                    || FileIdentity::from_metadata(&opened) != initial_identity
+                {
+                    return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                }
+                let before_read = match fs::symlink_metadata(&path) {
+                    Ok(metadata) => metadata,
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                        return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                    }
+                    Err(error) => {
+                        panic!(
+                            "reinspect namespace file before read {}: {error}",
+                            path.display()
+                        )
+                    }
+                };
+                if !before_read.file_type().is_file()
+                    || FileIdentity::from_metadata(&before_read) != initial_identity
+                {
+                    return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                }
+
+                checkpoint(&path, SnapshotCheckpoint::RegularHandleCorroborated);
+                let mut bytes = Vec::new();
+                file.read_to_end(&mut bytes).unwrap_or_else(|error| {
+                    panic!("read opened namespace file {}: {error}", path.display())
+                });
+                let after_read = match fs::symlink_metadata(&path) {
+                    Ok(metadata) => metadata,
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                        return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                    }
+                    Err(error) => {
+                        panic!(
+                            "reinspect namespace file after read {}: {error}",
+                            path.display()
+                        )
+                    }
+                };
+                if !after_read.file_type().is_file()
+                    || FileIdentity::from_metadata(&after_read) != initial_identity
+                {
+                    return Err(NamespaceSnapshotError::PathChangedDuringRead(path));
+                }
+                NamespaceEntry::RegularFile(bytes)
+            } else if file_type.is_symlink() {
+                NamespaceEntry::Symlink(fs::read_link(&path).unwrap_or_else(|error| {
+                    panic!("read namespace symlink {}: {error}", path.display())
+                }))
+            } else {
+                panic!("unsupported namespace entry kind at {}", path.display());
+            };
+            assert!(
+                snapshot.insert(relative, entry).is_none(),
+                "duplicate native namespace path while snapshotting {}",
+                path.display()
+            );
+            if file_type.is_dir() {
+                let identity = FileIdentity::from_metadata(&metadata);
+                checkpoint(&path, SnapshotCheckpoint::DirectoryPathValidated);
+                walk(root, &path, identity, snapshot, checkpoint)?;
+            }
+        }
+        corroborate_directory_path(directory, initial_identity, "after processing entries")?;
+        Ok(())
+    }
+
+    let metadata = match fs::symlink_metadata(root) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(BTreeMap::new());
+        }
+        Err(error) => panic!("inspect namespace root {}: {error}", root.display()),
+    };
+    assert!(
+        metadata.file_type().is_dir(),
+        "namespace root is not a directory: {}",
+        root.display()
+    );
+    let identity = FileIdentity::from_metadata(&metadata);
+    checkpoint(root, SnapshotCheckpoint::DirectoryPathValidated);
+    let mut snapshot = BTreeMap::new();
+    snapshot.insert(PathBuf::new(), NamespaceEntry::Directory);
+    walk(root, root, identity, &mut snapshot, &mut checkpoint)?;
+    Ok(snapshot)
+}
+
+fn entry_label(entry: Option<&NamespaceEntry>) -> String {
+    match entry {
+        None => "missing".to_string(),
+        Some(NamespaceEntry::Directory) => "directory".to_string(),
+        Some(NamespaceEntry::RegularFile(bytes)) => format!("file[{} bytes]", bytes.len()),
+        Some(NamespaceEntry::Symlink(target)) => format!("symlink -> {}", target.display()),
+    }
+}
+
+fn assert_namespace_unchanged(
+    before: &BTreeMap<PathBuf, NamespaceEntry>,
+    after: &BTreeMap<PathBuf, NamespaceEntry>,
+    label: &str,
+) {
+    let changed = before
+        .keys()
+        .chain(after.keys())
+        .collect::<std::collections::BTreeSet<_>>()
+        .into_iter()
+        .filter(|path| before.get(*path) != after.get(*path))
+        .map(|path| {
+            format!(
+                "{}: {} -> {}",
+                path.display(),
+                entry_label(before.get(path)),
+                entry_label(after.get(path))
+            )
+        })
+        .collect::<Vec<_>>();
+    assert!(
+        changed.is_empty(),
+        "{label} changed: {}",
+        changed.join(", ")
+    );
+}
+
+fn stage_legacy_namespace(project: &Path) -> PathBuf {
+    let legacy = project.join(".codegraph");
+    fs::create_dir(&legacy).expect("create independent legacy namespace");
+    fs::write(legacy.join("codegraph.db"), b"legacy-db-sentinel\0\xff")
+        .expect("write legacy DB sentinel");
+    fs::create_dir(legacy.join("empty-directory")).expect("create legacy empty directory");
+    legacy
+}
+
+fn finish_rebuild(project: &Path) {
+    let paths = IndexPaths::resolve(project, None).expect("resolve recovery IndexPaths");
+    let rebuild = begin_full_rebuild(
+        &paths,
+        RebuildKind::ExplicitInit,
+        deadline_after(CHILD_WAIT),
+        || false,
+    )
+    .expect("fresh writer acquires released kernel lease");
+    rebuild
+        .open_store()
+        .expect("open recovery writer")
+        .finish()
+        .expect("complete recovery rebuild");
+}
+
+/// Child entry point. READY is emitted only after `begin_full_rebuild` has
+/// acquired the production outer exclusive lease and completed its destructive
+/// prologue. The parent then controls release or deliberately kills this process.
+#[test]
+fn writer_lifecycle_child_process() {
+    let Ok(action) = std::env::var(CHILD_ACTION) else {
+        return;
+    };
+    let project = PathBuf::from(std::env::var_os(CHILD_PROJECT).expect("child project env"));
+    let paths = IndexPaths::resolve(&project, None).expect("child resolve IndexPaths");
+
+    match action.as_str() {
+        "hold" => {
+            let rebuild = begin_full_rebuild(
+                &paths,
+                RebuildKind::ExplicitInit,
+                deadline_after(CHILD_WAIT),
+                || false,
+            )
+            .expect("holder enters production full-writer lifecycle");
+            println!("READY");
+            std::io::stdout().flush().expect("flush READY");
+            let mut release = [0_u8; 1];
+            std::io::stdin()
+                .read_exact(&mut release)
+                .expect("read release byte");
+            drop(rebuild);
+            println!("RELEASED");
+            std::io::stdout().flush().expect("flush RELEASED");
+        }
+        "lose" => match begin_full_rebuild(
+            &paths,
+            RebuildKind::ExplicitInit,
+            deadline_after(LOSER_DEADLINE),
+            || false,
+        ) {
+            Err(RebuildError::Lease(IndexLeaseError::TimedOut { .. })) => {
+                println!("LEASE_TIMED_OUT")
+            }
+            Err(error) => panic!("losing writer failed for unrelated reason: {error:?}"),
+            Ok(rebuild) => {
+                drop(rebuild);
+                panic!("losing writer unexpectedly acquired the production writer lease");
+            }
+        },
+        "recover" => {
+            finish_rebuild(&project);
+            println!("RECOVERED_CURRENT");
+        }
+        other => panic!("unknown writer lifecycle child action {other}"),
+    }
+}
+
+struct Holder {
+    child: Option<Child>,
+    stdin: Option<ChildStdin>,
+    reader: Option<JoinHandle<Result<String, String>>>,
+}
+
+impl Holder {
+    fn spawn(project: &Path) -> Self {
+        let mut child = child_command(project, "hold")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::inherit())
+            .spawn()
+            .expect("spawn production writer holder");
+        let stdin = child.stdin.take().expect("holder stdin");
+        let stdout = child.stdout.take().expect("holder stdout");
+        let (ready_tx, ready_rx) = mpsc::channel();
+        let reader = std::thread::spawn(move || {
+            let mut reader = BufReader::new(stdout);
+            loop {
+                let mut line = String::new();
+                let read = reader
+                    .read_line(&mut line)
+                    .map_err(|error| format!("read holder output: {error}"))?;
+                if read == 0 {
+                    return Err("holder exited before READY".to_string());
+                }
+                if line.trim() == "READY" {
+                    ready_tx
+                        .send(line)
+                        .map_err(|_| "holder READY receiver was dropped".to_string())?;
+                    break;
+                }
+            }
+            let mut tail = String::new();
+            reader
+                .read_to_string(&mut tail)
+                .map_err(|error| format!("read holder tail: {error}"))?;
+            Ok(tail)
+        });
+        let ready = match ready_rx.recv_timeout(CHILD_WAIT) {
+            Ok(ready) => ready,
+            Err(error) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                let reader_result = reader.join();
+                panic!("holder READY before finite deadline: {error}; reader={reader_result:?}");
+            }
+        };
+        assert_eq!(ready.trim(), "READY");
+        Self {
+            child: Some(child),
+            stdin: Some(stdin),
+            reader: Some(reader),
+        }
+    }
+
+    fn join_reader(&mut self) -> String {
+        self.reader
+            .take()
+            .expect("holder reader")
+            .join()
+            .expect("join holder reader")
+            .expect("holder reader completed")
+    }
+
+    fn release(mut self) {
+        let mut stdin = self.stdin.take().expect("holder release stdin");
+        stdin.write_all(b"x").expect("signal holder release");
+        drop(stdin);
+        let status = wait_bounded(self.child.as_mut().expect("holder child"), CHILD_WAIT);
+        assert!(status.success(), "holder child failed: {status}");
+        let tail = self.join_reader();
+        assert!(
+            tail.lines().any(|line| line == "RELEASED"),
+            "holder emitted no RELEASED sentinel: {tail:?}"
+        );
+        self.child.take();
+    }
+
+    fn crash(mut self) -> ExitStatus {
+        let child = self.child.as_mut().expect("holder child");
+        child.kill().expect("send OS kill to holder");
+        let status = wait_bounded(child, CHILD_WAIT);
+        self.join_reader();
+        self.child.take();
+        self.stdin.take();
+        status
+    }
+}
+
+impl Drop for Holder {
+    fn drop(&mut self) {
+        if let Some(child) = self.child.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+        self.stdin.take();
+        if let Some(reader) = self.reader.take() {
+            let _ = reader.join();
+        }
+    }
+}
+
+fn child_command(project: &Path, action: &str) -> Command {
+    let mut command = Command::new(std::env::current_exe().expect("current test executable"));
+    command
+        .arg("--exact")
+        .arg("writer_lifecycle_child_process")
+        .arg("--nocapture")
+        .env(CHILD_ACTION, action)
+        .env(CHILD_PROJECT, project);
+    command
+}
+
+fn run_child(project: &Path, action: &str) -> (ExitStatus, String, String) {
+    let mut child = child_command(project, action)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .unwrap_or_else(|error| panic!("spawn writer child {action}: {error}"));
+    let stdout = child.stdout.take().expect("child stdout");
+    let stderr = child.stderr.take().expect("child stderr");
+    let (output_tx, output_rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let mut stdout_reader = BufReader::new(stdout);
+        let mut stderr_reader = BufReader::new(stderr);
+        let mut stdout_text = String::new();
+        let mut stderr_text = String::new();
+        stdout_reader
+            .read_to_string(&mut stdout_text)
+            .expect("read child stdout");
+        stderr_reader
+            .read_to_string(&mut stderr_text)
+            .expect("read child stderr");
+        output_tx
+            .send((stdout_text, stderr_text))
+            .expect("send child output");
+    });
+    let status = wait_bounded(&mut child, CHILD_WAIT);
+    let (stdout, stderr) = output_rx
+        .recv_timeout(CHILD_WAIT)
+        .expect("child output before finite deadline");
+    (status, stdout, stderr)
+}
+
+fn wait_bounded(child: &mut Child, timeout: Duration) -> ExitStatus {
+    let deadline = deadline_after(timeout);
+    loop {
+        if let Some(status) = child.try_wait().expect("poll child status") {
+            return status;
+        }
+        if Instant::now() >= deadline {
+            let _ = child.kill();
+            let _ = child.wait();
+            panic!("child process exceeded finite {timeout:?} bound");
+        }
+        std::thread::park_timeout(Duration::from_millis(5));
+    }
+}
+
+#[test]
+fn namespace_oracle_detects_equal_length_content_mutation() {
+    let project = TempProject::new("oracle-equal-length");
+    let root = project.path().join("namespace");
+    fs::create_dir(&root).expect("create oracle namespace");
+    let file = root.join("payload.bin");
+    fs::write(&file, b"AAAA").expect("write first equal-length payload");
+    let before = snapshot_namespace(&root);
+    fs::write(&file, b"BBBB").expect("write second equal-length payload");
+    let after = snapshot_namespace(&root);
+    let detection = std::panic::catch_unwind(|| {
+        assert_namespace_unchanged(&before, &after, "oracle self-test")
+    });
+    assert!(
+        detection.is_err(),
+        "namespace oracle missed an equal-length byte mutation"
+    );
+}
+
+#[test]
+fn namespace_oracle_accepts_only_typed_root_absence_and_rejects_aliases() {
+    use std::ffi::OsString;
+    use std::os::unix::ffi::OsStringExt as _;
+
+    let project = TempProject::new("oracle-root-validation");
+    let missing = project.path().join("missing");
+    assert!(snapshot_namespace(&missing).is_empty());
+
+    let external = project.path().join("external");
+    fs::create_dir(&external).expect("create external root target");
+    fs::write(external.join("must-not-be-traversed"), b"outside")
+        .expect("write external root target payload");
+    let alias = project.path().join("alias");
+    std::os::unix::fs::symlink(&external, &alias).expect("create root symlink");
+    assert!(
+        std::panic::catch_unwind(|| snapshot_namespace(&alias)).is_err(),
+        "a root symlink must be rejected before traversal"
+    );
+
+    let regular = project.path().join("regular");
+    fs::write(&regular, b"not-a-directory").expect("write regular root path");
+    assert!(
+        std::panic::catch_unwind(|| snapshot_namespace(&regular)).is_err(),
+        "a regular root path must be rejected before traversal"
+    );
+
+    let invalid = project
+        .path()
+        .join(OsString::from_vec(b"invalid\0root".to_vec()));
+    assert!(
+        std::panic::catch_unwind(|| snapshot_namespace(&invalid)).is_err(),
+        "a non-NotFound root metadata error must fail closed"
+    );
+}
+
+#[test]
+fn namespace_oracle_detects_regular_path_replaced_by_symlink_before_read() {
+    let project = TempProject::new("oracle-symlink-replacement");
+    let root = project.path().join("namespace");
+    fs::create_dir(&root).expect("create replacement-test namespace");
+    let file = root.join("payload.bin");
+    fs::write(&file, b"original-namespace-bytes").expect("write original namespace file");
+    let external = project.path().join("external.bin");
+    fs::write(&external, b"external-target-must-not-be-authoritative")
+        .expect("write external symlink target");
+
+    let mut read_boundary_reached = false;
+    let result = snapshot_namespace_with_checkpoint(&root, |path, checkpoint| {
+        if path == file && checkpoint == SnapshotCheckpoint::RegularPathValidated {
+            fs::remove_file(path).expect("remove validated regular path");
+            std::os::unix::fs::symlink(&external, path)
+                .expect("replace regular path with external symlink");
+        } else if path == file && checkpoint == SnapshotCheckpoint::RegularHandleCorroborated {
+            read_boundary_reached = true;
+        }
+    });
+
+    assert_eq!(
+        result,
+        Err(NamespaceSnapshotError::PathChangedDuringRead(file)),
+        "a replacement symlink must be detected explicitly rather than accepting its external target bytes"
+    );
+    assert!(
+        !read_boundary_reached,
+        "the external symlink target must be rejected before any authoritative byte read"
+    );
+}
+
+fn assert_directory_replacement_rejected(
+    result: Result<BTreeMap<PathBuf, NamespaceEntry>, NamespaceSnapshotError>,
+    changed_path: &Path,
+    external_sentinel: &Path,
+) {
+    match result {
+        Err(error) => assert_eq!(
+            error,
+            NamespaceSnapshotError::PathChangedDuringRead(changed_path.to_path_buf())
+        ),
+        Ok(snapshot) => {
+            assert!(
+                !snapshot.contains_key(external_sentinel),
+                "external-tree entry escaped into a successful authoritative snapshot: {}",
+                external_sentinel.display()
+            );
+            panic!(
+                "directory replacement unexpectedly produced a successful authoritative snapshot: {}",
+                changed_path.display()
+            );
+        }
+    }
+}
+
+#[test]
+fn namespace_oracle_detects_root_directory_replaced_by_external_symlink() {
+    let project = TempProject::new("oracle-root-directory-replacement");
+    let root = project.path().join("namespace");
+    fs::create_dir(&root).expect("create root replacement-test namespace");
+    let external = project.path().join("external-root-directory");
+    fs::create_dir(&external).expect("create external root directory");
+    let sentinel_name = PathBuf::from("external-root-sentinel-must-never-be-authoritative");
+    fs::write(external.join(&sentinel_name), b"outside-root-tree")
+        .expect("write external root sentinel");
+
+    let mut replaced = false;
+    let result = snapshot_namespace_with_checkpoint(&root, |path, checkpoint| {
+        if path == root && checkpoint == SnapshotCheckpoint::DirectoryPathValidated {
+            fs::remove_dir(path).expect("remove validated root directory");
+            std::os::unix::fs::symlink(&external, path)
+                .expect("replace root directory with external symlink");
+            replaced = true;
+        }
+    });
+
+    assert!(replaced, "root replacement checkpoint was not reached");
+    assert_directory_replacement_rejected(result, &root, &sentinel_name);
+}
+
+#[test]
+fn namespace_oracle_detects_nested_directory_replaced_by_external_symlink() {
+    let project = TempProject::new("oracle-nested-directory-replacement");
+    let root = project.path().join("namespace");
+    let nested = root.join("nested");
+    fs::create_dir_all(&nested).expect("create nested replacement-test namespace");
+    let external = project.path().join("external-nested-directory");
+    fs::create_dir(&external).expect("create external nested directory");
+    let sentinel_name = PathBuf::from("external-nested-sentinel-must-never-be-authoritative");
+    fs::write(external.join(&sentinel_name), b"outside-nested-tree")
+        .expect("write external nested sentinel");
+    let sentinel_relative = Path::new("nested").join(&sentinel_name);
+
+    let mut replaced = false;
+    let result = snapshot_namespace_with_checkpoint(&root, |path, checkpoint| {
+        if path == nested && checkpoint == SnapshotCheckpoint::DirectoryHandleAndPathCorroborated {
+            fs::remove_dir(path).expect("remove validated nested directory");
+            std::os::unix::fs::symlink(&external, path)
+                .expect("replace nested directory with external symlink");
+            replaced = true;
+        }
+    });
+
+    assert!(replaced, "nested replacement checkpoint was not reached");
+    assert_directory_replacement_rejected(result, &nested, &sentinel_relative);
+}
+
+#[test]
+fn concurrent_v2_writers_serialize_and_loser_is_nonmutating() {
+    let project = TempProject::new("concurrent-writers");
+    let paths = project.paths();
+    let legacy = stage_legacy_namespace(project.path());
+    let legacy_before = snapshot_namespace(&legacy);
+
+    let holder = Holder::spawn(project.path());
+    assert!(matches!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Building { .. }
+    ));
+    let current_before_loser = snapshot_namespace(paths.current_root());
+
+    let (status, stdout, stderr) = run_child(project.path(), "lose");
+    assert!(
+        status.success(),
+        "losing writer child did not report its typed contention result: status={status}, stdout={stdout:?}, stderr={stderr:?}"
+    );
+    assert_eq!(
+        stdout.lines().find(|line| *line == "LEASE_TIMED_OUT"),
+        Some("LEASE_TIMED_OUT"),
+        "losing writer must fail for exact bounded lease contention: stdout={stdout:?}, stderr={stderr:?}"
+    );
+
+    assert_namespace_unchanged(
+        &current_before_loser,
+        &snapshot_namespace(paths.current_root()),
+        "v2 namespace while winner retains the production lease",
+    );
+    assert_namespace_unchanged(
+        &legacy_before,
+        &snapshot_namespace(&legacy),
+        "legacy namespace during writer contention",
+    );
+    holder.release();
+    assert_namespace_unchanged(
+        &legacy_before,
+        &snapshot_namespace(&legacy),
+        "legacy namespace after winner release",
+    );
+}
+
+#[test]
+fn crashed_writer_releases_permanent_kernel_lease() {
+    let project = TempProject::new("crashed-writer");
+    let paths = project.paths();
+    let legacy = stage_legacy_namespace(project.path());
+    let legacy_before = snapshot_namespace(&legacy);
+
+    let holder = Holder::spawn(project.path());
+    assert!(matches!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Building { .. }
+    ));
+    let crash_status = holder.crash();
+    assert_eq!(
+        crash_status.signal(),
+        Some(9),
+        "holder must terminate abnormally by SIGKILL, bypassing Rust cleanup: {crash_status:?}"
+    );
+    assert_namespace_unchanged(
+        &legacy_before,
+        &snapshot_namespace(&legacy),
+        "legacy namespace immediately after holder crash",
+    );
+
+    let (status, stdout, stderr) = run_child(project.path(), "recover");
+    assert!(
+        status.success(),
+        "fresh writer failed to recover after holder crash: status={status}, stdout={stdout:?}, stderr={stderr:?}"
+    );
+    assert!(
+        stdout.lines().any(|line| line == "RECOVERED_CURRENT"),
+        "fresh writer emitted no recovery sentinel: stdout={stdout:?}, stderr={stderr:?}"
+    );
+    assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    let readable = Store::open_for_read(&paths, deadline_after(CHILD_WAIT), || false)
+        .expect("public read gate corroborates recovered Current");
+    drop(readable);
+    assert_namespace_unchanged(
+        &legacy_before,
+        &snapshot_namespace(&legacy),
+        "legacy namespace across crash recovery",
+    );
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 9170893..1dad556 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2081,3 +2081,195 @@ workspace-version gate. Final affected-package tests, diagnostics, formatting,
 Clippy, and lock/scope audit are recorded in the task handoff after their actual
 execution. Native Windows runtime/crash coverage remains unavailable on this Linux
 host and is not claimed.
+
+## Batch M item 12 — process writer serialization and crash recovery (2026-07-26)
+
+Production already owned the required one-outer-lease architecture, so item 12
+adds acceptance/regression evidence only. New integration target
+`crates/codegraph-store/tests/writer_process_lifecycle.rs` drives actual child
+processes through `begin_full_rebuild`: the holder reports `READY` only after
+that shipped full-writer entry point has acquired and retained the outer
+exclusive `IndexLease`, published Building, and completed its destructive
+prologue. The parent launches the losing production writer only after `READY`;
+the child accepts exactly `RebuildError::Lease(IndexLeaseError::TimedOut)` and
+reports `LEASE_TIMED_OUT`. Any acquisition or unrelated setup/state/config
+error fails the test.
+
+While the holder still owns the lease, the parent snapshots the complete v2
+namespace before the loser starts and compares it immediately after the loser
+exits. The fail-closed oracle keys entries by native `PathBuf` and records root
+and nested directories, complete regular-file bytes, and symlink targets without
+following aliases. Every traversal, metadata, read, or unsupported-entry error
+panics with bounded path/kind diagnostics; comparison never prints database
+bytes. `namespace_oracle_detects_equal_length_content_mutation` replaces four
+bytes with four different bytes and proves the oracle rejects the same-size
+mutation. A separately staged legacy namespace is byte-identical before and
+after contention, holder release, and crash recovery.
+
+The crash test sends the acknowledged holder an OS `SIGKILL` through
+`Child::kill`, asserts signal 9 rather than treating it as a harness failure,
+then starts a fresh child through the same `begin_full_rebuild` production path.
+That writer completes `ActiveFullRebuild::finish`, reports
+`RECOVERED_CURRENT`, and the parent independently requires both typed
+`ExtractionStatus::Current` and successful `Store::open_for_read`
+corroboration. This proves kernel release on abnormal process termination; no
+Rust `Drop` cleanup is involved in releasing the crashed holder's lease.
+
+Initial focused execution, after the workspace-version guard:
+
+```text
+cargo test -p codegraph-store --locked --test writer_process_lifecycle -- --nocapture --test-threads=1
+# 4 passed; 0 failed
+```
+
+The first compile attempt found two test-only pattern errors for the structured
+`Building { built }` status; the first behavioral execution then exposed a
+harness bug where the parent treated libtest's blank preamble as the READY line,
+dropped the fixture, and caused child publication I/O failures. Neither was
+counted as Red or production evidence. The READY reader now ignores all lines
+until the exact sentinel, matching the established `index_lease` harness. No
+production source, extraction, schema, node-id, golden, manifest, dependency, or
+lockfile byte changed. Native Windows runtime/crash behavior remains unavailable
+from this Linux environment and is not claimed.
+
+The guarded affected-package validation subsequently passed the exact item-12
+target (4/4), existing `index_lease` integration target (12/12), complete
+`codegraph-store` package (175 tests, 0 failures), all-target check, and
+all-target Clippy with `-D warnings`. The first trailing `cargo fmt --all --check`
+reported formatting-only diffs in the new test; no behavioral diagnostic failed.
+Those bytes were normalized before the final format/hash/scope audit. Direct LSP
+diagnostics were attempted and rejected with the exact environment error
+`LSP file path must be inside request cwd` because this required worktree is
+under `/tmp/opencode/codegraph-rust-v15-impl`; the clean Cargo check and Clippy
+results are the diagnostics fallback.
+
+## Batch M item 12 correction — fail-closed snapshot reads and joined holder output (2026-07-26)
+
+Manual review rejected two proof claims in the item-12 entry above and one
+harness-lifecycle detail. The earlier claim that every metadata/read error
+failed closed was false because `root.exists()` followed aliases and converted
+all root metadata failures into apparent absence. The claim that regular-file
+bytes were read without following aliases was also incomplete:
+`symlink_metadata(path)` followed by `fs::read(path)` left a check-then-path-read
+window. Finally, `Holder::crash` dropped the tail receiver without joining the
+stdout reader, so its detached `tail_tx.send(...).expect(...)` could panic after
+the holder was killed. The prior history remains intact; this section supersedes
+only those proof-harness claims. Production behavior is unchanged.
+
+The corrected Unix-only namespace oracle performs one no-follow
+`symlink_metadata(root)` and accepts absence only for the typed
+`io::ErrorKind::NotFound`; every other metadata error panics. A root symlink or
+non-directory is rejected before `read_dir`. For each regular file, the oracle
+records the initial no-follow regular-file identity `(st_dev, st_ino)`, opens the
+path once, requires the opened handle to be regular and have that identity,
+corroborates the fixed path with no-follow metadata immediately before reading,
+reads the complete bytes through that same handle, and corroborates the fixed
+path again afterward. Disappearance, alias replacement, kind drift, or identity
+drift returns the explicit test-only `PathChangedDuringRead(PathBuf)` result.
+This is pre/open/pre-read/post-read identity corroboration; it does not claim a
+portable atomic path-check-and-read primitive.
+
+The deterministic self-test
+`namespace_oracle_detects_regular_path_replaced_by_symlink_before_read` replaces
+the validated regular path with a symlink at the exact
+`RegularPathValidated` checkpoint, with no sleep or probabilistic race. Before
+the correction it failed because the snapshot returned the external target's
+complete bytes as `RegularFile`; afterward it receives the explicit changed-path
+result and proves the authoritative read-boundary checkpoint was never reached.
+The existing equal-length mutation self-test remains unchanged and effective. A
+second root-validation self-test proves typed NotFound absence and fail-closed
+rejection of a root symlink, regular root, and non-NotFound metadata error.
+
+Holder output is now owned by a `JoinHandle<Result<String, String>>`, not a
+detached sender. Normal release waits for the child and joins the reader before
+checking `RELEASED`; crash waits for SIGKILL termination and joins/drains the
+reader before dropping receiver state; defensive `Drop` also kills/reaps the
+child and joins any remaining reader. READY semantics are unchanged: the child
+emits it only after `begin_full_rebuild` returns with the production exclusive
+lease held.
+
+The corrected focused target passed 6/6 after the workspace-version gate,
+including the two real child-process behavior tests and both prior oracle tests.
+Locked validation then passed: corrected `writer_process_lifecycle` 6/6,
+existing `index_lease` 12/12, and complete `codegraph-store` 177/177 (94 unit +
+6 bulk-pragmas + 12 lease + 20 classifier + 14 publisher + 4 schema + 21 Store
+gate + 6 process-lifecycle; doc tests 0). Workspace all-target `cargo check` and
+all-target Clippy with `-D warnings` were clean. Every Cargo batch was preceded
+by `bash scripts/check-workspace-versions.sh`, and every dependency-resolving
+Cargo command used `--locked`. Rust formatting and the repository doc-format
+check passed after the final evidence bytes were written. Changed-file LSP was
+attempted and again rejected by the environment with
+`LSP file path must be inside request cwd` for the required external worktree;
+the clean workspace all-target Cargo check and Clippy are the recorded fallback,
+not an LSP-clean claim. No production source, manifest, dependency, schema, node
+ID, golden, workspace version, or `Cargo.lock` byte is changed.
+
+## Batch M item 12 correction #2 — directory identity-corroborated traversal (2026-07-26)
+
+Manual review rejected one remaining claim in the correction above: regular-file
+reads were identity-corroborated, but root and nested directories still went from
+`symlink_metadata(directory)` to path-based `read_dir(directory)` without proving
+that an opened directory handle and the fixed path identified the initially
+observed directory. A replacement external-directory symlink could therefore be
+enumerated before later entry checks. This append supersedes only that proof
+claim; the prior history remains intact and production code is unchanged.
+
+The Unix-only snapshot helper now captures `(st_dev, st_ino)` from the initial
+no-follow observation for the root and every discovered nested directory. It
+opens each directory once, requires the opened handle to be a directory with the
+same identity, and rechecks the no-follow fixed path against that identity before
+path-based enumeration, after the complete entry list is collected, and after
+the collected entries are processed. A disappearance, alias/type replacement,
+or identity drift returns `PathChangedDuringRead(PathBuf)`. A failed non-NotFound
+open, `read_dir`, or entry read still fails loudly after corroboration; only the
+initial root's typed NotFound maps to an empty namespace. Collected paths are not
+processed until the post-enumeration check passes, so failed corroboration cannot
+produce a successful authoritative snapshot.
+
+This is an honest identity-corroborated successful-return boundary around
+path-based `read_dir`, not a claim that portable `std` supplies atomic no-follow
+enumeration. Exact checkpoints distinguish initial no-follow directory validation,
+opened-handle plus fixed-path corroboration before enumeration, and successful
+post-enumeration corroboration.
+
+Two deterministic no-sleep tests cover both replacement frontiers. The root test
+replaces the root immediately after its initial no-follow validation; the nested
+test replaces an already opened/corroborated nested directory immediately before
+enumeration. Each replacement is a symlink to an external directory containing a
+unique sentinel entry, requires the exact changed directory in
+`PathChangedDuringRead`, and contains a fail-branch assertion that the sentinel
+cannot occur in any successful authoritative snapshot. The pre-existing regular
+file, equal-length mutation, typed root-validation, writer contention, and
+SIGKILL recovery tests remain unchanged. Focused implementation execution passed
+8/8 after the workspace-version gate. Final locked package/check/Clippy/format,
+LSP, lock-hash, and scope results are appended only after they run.
+
+### 2026-07-26 Batch M item 12 final-gate formatting correction
+
+The parent validation run for the directory-proof correction is recorded here
+exactly as it happened, superseding the pending-results sentence above without
+deleting it. After the workspace-version gate, the guarded locked runs passed in
+order: the focused item-12 target 8/8, the existing `index_lease` target 12/12,
+the complete `codegraph-store` package test suite, `cargo check --workspace
+--all-targets --locked`, and `cargo clippy --workspace --all-targets --locked -D
+warnings`. The chain then failed at `cargo fmt --all --check`, which reported a
+single formatting-only diff in
+`crates/codegraph-store/tests/writer_process_lifecycle.rs` at line 756: rustfmt
+requires the nested-directory replacement callback's
+`if path == nested && checkpoint == SnapshotCheckpoint::DirectoryHandleAndPathCorroborated`
+condition on one line instead of the manually wrapped multiline form. Because the
+commands were joined with `&&`, nothing after that check ran, so no `make
+fmt-check`, `git diff --check`, or lock-hash result from that attempt is claimed.
+
+The correction changes formatting only — no test name, assertion, checkpoint,
+child-process protocol, or oracle behavior is altered. After normalizing those
+bytes and appending this evidence, the reruns that actually executed and passed
+are: `bash scripts/check-workspace-versions.sh`, `cargo fmt --all --check`, `make
+fmt-check`, the guarded focused item-12 target, `cargo check --workspace
+--all-targets --locked`, `cargo clippy --workspace --all-targets --locked -D
+warnings`, `git diff --check`, and the frozen `Cargo.lock` SHA-256 audit. The
+changed-file LSP diagnostics attempt and its exact result are reported in the
+notepads; no LSP-clean claim is made when the request is rejected for being
+outside the request cwd. Native Windows runtime/crash coverage and portable
+atomic no-follow enumeration remain explicitly unclaimed, and the authoritative
+full locked CI gate remains the parent's.

From 3863c2694583564964c36b6953dfec96046c9ab3 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 08:15:59 +0800
Subject: [PATCH 25/91] fix(watch): retain watcher trigger paths

---
 crates/codegraph-daemon/src/lib.rs        |  5 +-
 crates/codegraph-watch/src/sync.rs        |  5 ++
 crates/codegraph-watch/src/watcher.rs     | 27 +++++++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 61 +++++++++++++++++++++++
 4 files changed, 96 insertions(+), 2 deletions(-)

diff --git a/crates/codegraph-daemon/src/lib.rs b/crates/codegraph-daemon/src/lib.rs
index a53ca5a..6829f22 100644
--- a/crates/codegraph-daemon/src/lib.rs
+++ b/crates/codegraph-daemon/src/lib.rs
@@ -567,7 +567,10 @@ fn start_project_watcher(
     watch_options.on_sync_complete =
         Some(Arc::new(move |outcome: codegraph_watch::SyncOutcome| {
             let n = counter.fetch_add(1, Ordering::SeqCst) + 1;
-            let tail = changed_paths_tail(&outcome.changed_paths);
+            // Report the watcher event batch even when startup catch-up won the
+            // writer lease and already indexed it. `changed_paths` deliberately
+            // remains the set this particular sync actually mutated.
+            let tail = changed_paths_tail(&outcome.trigger_paths);
             // The subscriber prepends the RFC3339 timestamp; this daemon's stderr
             // is redirected to `.codegraph/daemon.log`, so events land there timed.
             info!(
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index 455982e..9f8396d 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -30,6 +30,11 @@ pub struct SyncOutcome {
     /// Reindexed or removed paths this sync, root-relative and SORTED — the
     /// source set is a `HashSet`, so sorting is required for a stable log line.
     pub changed_paths: Vec<String>,
+    /// Root-relative paths that triggered a watcher sync, sorted and deduplicated
+    /// by the watcher. Empty for direct/full sync callers. Unlike `changed_paths`,
+    /// this remains populated when another writer (for example startup catch-up)
+    /// indexed the same event first and this sync consequently skips it unchanged.
+    pub trigger_paths: Vec<String>,
 }
 
 pub fn sync_project_once(project_root: impl AsRef<Path>) -> Result<SyncOutcome> {
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index dba2996..af6a4af 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -587,10 +587,15 @@ fn event_loop(ctx: EventLoopCtx) {
                 let paths = pending.keys().cloned().collect::<Vec<_>>();
                 pending.clear();
                 deadline = None;
-                let attempt = run_sync_with_backoff(&sync_fn, paths);
+                let attempt = run_sync_with_backoff(&sync_fn, paths.clone());
                 let decision = classify_persistent_failure(&attempt, &mut consecutive_sync_errors);
                 match attempt {
                     SyncAttempt::Done(outcome) => {
+                        // Preserve the event batch independently of actual DB
+                        // mutations. Startup catch-up can win the writer lease and
+                        // index the same file first; the watcher still handled this
+                        // event and its callback must be able to report that fact.
+                        let outcome = with_trigger_paths(outcome, paths);
                         if let Some(callback) = &on_sync_complete {
                             callback(outcome);
                         }
@@ -618,6 +623,11 @@ fn event_loop(ctx: EventLoopCtx) {
     }
 }
 
+fn with_trigger_paths(mut outcome: SyncOutcome, trigger_paths: Vec<String>) -> SyncOutcome {
+    outcome.trigger_paths = trigger_paths;
+    outcome
+}
+
 /// Apply the EMFILE/ENFILE → degrade-once, ENOSPC → warn classification to a
 /// backend watch error. Returns the class so the event loop can stop the watch
 /// on `Degrade`. `on_degraded` fires at most once across the watcher's life.
@@ -779,6 +789,21 @@ mod tests {
     use std::fs;
     use std::sync::{Arc, Mutex};
 
+    #[test]
+    fn noop_watcher_completion_preserves_trigger_paths() {
+        let outcome = with_trigger_paths(
+            SyncOutcome::default(),
+            vec!["src/brand_new_symbol.ts".to_string()],
+        );
+
+        assert_eq!(outcome.files_reindexed, 0);
+        assert!(outcome.changed_paths.is_empty());
+        assert_eq!(
+            outcome.trigger_paths,
+            vec!["src/brand_new_symbol.ts".to_string()]
+        );
+    }
+
     #[test]
     fn rapid_save_burst_triggers_exactly_one_reindex() {
         let dir = crate::sync::tests::TestDir::new("watch-debounce");
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 1dad556..4e9f418 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2273,3 +2273,64 @@ notepads; no LSP-clean claim is made when the request is rejected for being
 outside the request cwd. Native Windows runtime/crash coverage and portable
 atomic no-follow enumeration remain explicitly unclaimed, and the authoritative
 full locked CI gate remains the parent's.
+
+## Daemon watcher startup catch-up race correction (2026-07-26)
+
+The pre-existing `daemon_single_watcher_fires_once` timing failure was reproduced
+before any production edit with the exact focused target. Its first daemon event
+was `watcher sync #1: 0 file(s) reindexed, 0 removed`, and the unchanged test then
+failed because that line did not name `brand_new_symbol.ts`. A diagnostic-only
+assertion-message expansion, which merely rebuilt the test binary, made the same
+target pass; this timing switch confirmed a startup-order race rather than an
+extraction defect.
+
+Source and call-path inspection proved the exact ordering: the daemon registers
+one shared `ProjectWatcher`, starts one full-project catch-up thread, and then
+accepts clients. Catch-up and a queued watcher event contend for the same
+exclusive writer. When catch-up wins, it indexes the new file first; the queued
+watcher sync subsequently sees identical content and correctly reports zero DB
+mutations. No second watcher exists, and the catch-up log is not the source of the
+failing `watcher sync` line.
+
+The correction preserves those two distinct facts. `SyncOutcome.changed_paths`
+still means paths actually reindexed or removed by that sync. A new sorted watcher
+event field, `trigger_paths`, records the exact debounced event batch even when a
+concurrent writer already applied the bytes. `event_loop` attaches that batch only
+to watcher completion outcomes, and the daemon's bounded filename tail now uses
+`trigger_paths`; reindexed/removed counters remain actual mutation counters.
+Direct/full sync callers retain an empty trigger set. The one-watcher topology,
+catch-up concurrency, immediate client handling, debounce, and `--no-watch`
+behavior are unchanged. A pure regression pins that a zero-mutation watcher
+completion still retains its trigger path; no sleep, retry-until-pass, assertion
+weakening, or test serialization was added.
+
+Validation was run once after the final implementation, with
+`bash scripts/check-workspace-versions.sh` first and `--locked` on every
+dependency-resolving Cargo command. The exact focused daemon test passed five
+consecutive runs; the complete `daemon_single_watcher` target passed 2/2,
+including `daemon_no_watch_does_not_autosync`. `codegraph-watch` passed 90 unit +
+2 integration tests, and `codegraph-daemon` passed all unit/integration targets.
+Workspace all-target `cargo check`, workspace all-target Clippy with
+`-D warnings`, `cargo fmt --all --check`, and `scripts/guardrail.sh` all passed.
+Changed-file LSP diagnostics were attempted for all three modified Rust files but
+the environment rejected the external worktree with `LSP file path must be inside
+request cwd`; the clean workspace Cargo check and Clippy are the recorded
+diagnostics fallback, not an LSP-clean claim. No dependency, schema, node-id
+formula, extraction/golden output, manifest, workspace version, or item-12
+process-lifecycle test was changed.
+
+### 2026-07-26 authoritative locked-CI closure
+
+After the complete item-12 acceptance and watcher correction bytes above were
+finalized and repository formatting was applied, the parent authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'`
+completed successfully. That exact final-byte run passed fmt-check, workspace
+Clippy with `-D warnings`, the full workspace test suite including the Unix
+writer-process lifecycle and watcher/process targets, and the no-AI/vector/LLM
+guardrail. `Cargo.lock` remained frozen at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+Changed-file LSP diagnostics remain unavailable because this required external
+worktree is rejected with `LSP file path must be inside request cwd`; Cargo
+check, Clippy, tests, formatting, and the guardrail are the diagnostics fallback,
+not an LSP-clean claim. Native Windows runtime/crash validation remains
+unavailable and is not claimed.

From 3ea02c511281c38fbf252e0fc9c17705a1a3ea3d Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 10:14:12 +0800
Subject: [PATCH 26/91] test(store): cover lease owner drop ordering

---
 crates/codegraph-store/tests/index_lease.rs | 127 +++++++++++++++++++-
 1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/crates/codegraph-store/tests/index_lease.rs b/crates/codegraph-store/tests/index_lease.rs
index 34a0446..4c45bed 100644
--- a/crates/codegraph-store/tests/index_lease.rs
+++ b/crates/codegraph-store/tests/index_lease.rs
@@ -10,7 +10,9 @@ use std::sync::mpsc::{self, Receiver};
 use std::time::{Duration, Instant};
 
 use codegraph_core::IndexPaths;
-use codegraph_store::{IndexLease, IndexLeaseError, IndexLeaseValidationError};
+use codegraph_store::{
+    IndexLease, IndexLeaseError, IndexLeaseValidationError, RebuildKind, Store, begin_full_rebuild,
+};
 
 const CHILD_ACTION: &str = "CODEGRAPH_INDEX_LEASE_CHILD_ACTION";
 const CHILD_MODE: &str = "CODEGRAPH_INDEX_LEASE_CHILD_MODE";
@@ -344,6 +346,129 @@ fn a_clone_keeps_the_single_lock_alive_until_the_final_drop() {
     );
 }
 
+#[test]
+fn lease_mode_parent_and_clone_drop_order_are_enforced() {
+    // Use two clones so both the original parent and a clone are observed as
+    // non-final owners. Every contender is a separate process synchronized by
+    // its result sentinel; no same-process lock semantics or sleeps are evidence.
+    let shared_project = TempProject::new("shared-parent-clones");
+    let shared_paths = shared_project.paths();
+    stage_existing_lock(&shared_paths, LOCK_BYTES);
+    let shared_parent =
+        IndexLease::acquire_shared_existing(&shared_paths, deadline_after(CHILD_WAIT), || false)
+            .expect("acquire shared parent lease");
+    let shared_clone_a = shared_parent.clone();
+    let shared_clone_b = shared_parent.clone();
+
+    drop(shared_parent);
+    assert_eq!(
+        run_probe(shared_project.path(), "exclusive", SHORT_DEADLINE),
+        "TIMED_OUT",
+        "dropping a non-final shared parent must keep exclusives blocked"
+    );
+    drop(shared_clone_a);
+    assert_eq!(
+        run_probe(shared_project.path(), "exclusive", SHORT_DEADLINE),
+        "TIMED_OUT",
+        "dropping a non-final shared clone must keep exclusives blocked"
+    );
+    drop(shared_clone_b);
+    assert_eq!(
+        run_probe(shared_project.path(), "exclusive", SHORT_DEADLINE),
+        "ACQUIRED",
+        "the final shared owner must release immediately"
+    );
+
+    let exclusive_project = TempProject::new("exclusive-parent-clones");
+    let exclusive_paths = exclusive_project.paths();
+    stage_existing_lock(&exclusive_paths, LOCK_BYTES);
+    let exclusive_parent = IndexLease::acquire_exclusive_existing(
+        &exclusive_paths,
+        deadline_after(CHILD_WAIT),
+        || false,
+    )
+    .expect("acquire exclusive parent lease");
+    let exclusive_clone_a = exclusive_parent.clone();
+    let exclusive_clone_b = exclusive_parent.clone();
+
+    drop(exclusive_parent);
+    for mode in ["shared", "exclusive"] {
+        assert_eq!(
+            run_probe(exclusive_project.path(), mode, SHORT_DEADLINE),
+            "TIMED_OUT",
+            "dropping a non-final exclusive parent must keep {mode} contenders blocked"
+        );
+    }
+    drop(exclusive_clone_a);
+    for mode in ["shared", "exclusive"] {
+        assert_eq!(
+            run_probe(exclusive_project.path(), mode, SHORT_DEADLINE),
+            "TIMED_OUT",
+            "dropping a non-final exclusive clone must keep {mode} contenders blocked"
+        );
+    }
+    drop(exclusive_clone_b);
+    assert_eq!(
+        run_probe(exclusive_project.path(), "shared", SHORT_DEADLINE),
+        "ACQUIRED",
+        "the final exclusive owner must release immediately"
+    );
+
+    // Build a real Current namespace exclusively through public production APIs,
+    // then let Store own the final shared lease capability and both SQLite
+    // handles. Store's declared field order must close those handles before its
+    // retained lease drops and admits the next exclusive contender.
+    let store_project = TempProject::new("current-store-final-owner");
+    let store_paths = store_project.paths();
+    let rebuild = begin_full_rebuild(
+        &store_paths,
+        RebuildKind::ExplicitInit,
+        deadline_after(CHILD_WAIT),
+        || false,
+    )
+    .expect("begin Current Store fixture rebuild");
+    rebuild
+        .open_store()
+        .expect("open Current Store fixture writer")
+        .finish()
+        .expect("finish Current Store fixture");
+
+    #[cfg(windows)]
+    let replacement = {
+        let replacement = store_paths.current_root().join("replacement.db");
+        std::fs::copy(store_paths.current_db(), &replacement)
+            .expect("stage Windows database replacement");
+        replacement
+    };
+
+    let store = Store::open_for_read(&store_paths, deadline_after(CHILD_WAIT), || false)
+        .expect("open Current Store with retained shared lease");
+    assert_eq!(
+        run_probe(store_project.path(), "exclusive", SHORT_DEADLINE),
+        "TIMED_OUT",
+        "a live Current Store must retain its lease through its SQLite handles"
+    );
+    drop(store);
+
+    #[cfg(windows)]
+    {
+        // Windows refuses renaming an open SQLite database. Performing the
+        // replacement synchronously after Store::drop therefore proves its two
+        // connections closed before the final retained lease capability dropped.
+        let retired = store_paths.current_root().join("retired.db");
+        std::fs::rename(store_paths.current_db(), &retired)
+            .expect("final Current Store drop closes Windows database handles");
+        std::fs::rename(replacement, store_paths.current_db())
+            .expect("install Windows database replacement immediately after Store drop");
+    }
+
+    assert_eq!(
+        run_probe(store_project.path(), "exclusive", SHORT_DEADLINE),
+        "ACQUIRED",
+        "dropping the final Store owner must admit a fresh contender immediately"
+    );
+}
+
 #[test]
 fn writer_validation_rejects_shared_and_wrong_parent_capabilities() {
     let project_a = TempProject::new("capability-a");

From fdb2df09145e81bb1774ef1874fe8521c27af054 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 10:15:08 +0800
Subject: [PATCH 27/91] test(store): prove read opens never migrate

---
 .../tests/store_state_gates.rs                | 207 +++++++++++++++++-
 1 file changed, 203 insertions(+), 4 deletions(-)

diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
index 2ade34d..901a7a1 100644
--- a/crates/codegraph-store/tests/store_state_gates.rs
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -122,10 +122,7 @@ fn create_database(paths: &IndexPaths, stamp: Option<&str>) {
 
 fn remove_sidecars(paths: &IndexPaths) {
     let db = paths.current_db();
-    for path in [
-        PathBuf::from(format!("{}-wal", db.display())),
-        PathBuf::from(format!("{}-shm", db.display())),
-    ] {
+    for path in [sqlite_sidecar(&db, "-wal"), sqlite_sidecar(&db, "-shm")] {
         match std::fs::remove_file(&path) {
             Ok(()) => {}
             Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
@@ -134,6 +131,12 @@ fn remove_sidecars(paths: &IndexPaths) {
     }
 }
 
+fn sqlite_sidecar(db: &Path, suffix: &str) -> PathBuf {
+    let mut path = db.as_os_str().to_os_string();
+    path.push(suffix);
+    PathBuf::from(path)
+}
+
 fn stage_current(project: &TempProject, stamp: Option<&str>) -> IndexPaths {
     let paths = project.paths();
     let lease = create_namespace(&paths);
@@ -301,6 +304,202 @@ fn assert_snapshot_unchanged(
     assert!(changed.is_empty(), "filesystem changed at {changed:?}");
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DatabaseObservation {
+    schema: Vec<(String, String, String, Option<String>)>,
+    schema_versions: Vec<(i64, i64, String)>,
+    project_metadata: Vec<(String, String, i64)>,
+}
+
+fn observe_database_without_touching_namespace(paths: &IndexPaths) -> DatabaseObservation {
+    let proof = TempProject::new("database-observation");
+    let copy = proof.path().join("observation.db");
+    let mut bytes = std::fs::read(paths.current_db()).unwrap_or_else(|error| {
+        panic!(
+            "read database observation source {}: {error}",
+            paths.current_db().display()
+        )
+    });
+    assert!(
+        bytes.len() >= 20 && bytes.starts_with(b"SQLite format 3\0"),
+        "database observation source is not a SQLite main file"
+    );
+    // A checkpointed WAL database keeps WAL format bytes in its main header.
+    // Normalize only this private copy so observation never asks SQLite's pager
+    // to inspect or author sidecars beside the authoritative database.
+    bytes[18] = 1;
+    bytes[19] = 1;
+    std::fs::write(&copy, bytes)
+        .unwrap_or_else(|error| panic!("write private database observation: {error}"));
+    let conn = Connection::open_with_flags(&copy, OpenFlags::SQLITE_OPEN_READ_ONLY)
+        .expect("open private database observation read-only");
+
+    let schema = conn
+        .prepare(
+            "SELECT type, name, tbl_name, sql FROM sqlite_schema \
+             ORDER BY type, name, tbl_name, sql",
+        )
+        .expect("prepare schema observation")
+        .query_map([], |row| {
+            Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
+        })
+        .expect("query schema observation")
+        .collect::<rusqlite::Result<Vec<_>>>()
+        .expect("collect schema observation");
+    let schema_versions = conn
+        .prepare(
+            "SELECT version, applied_at, description FROM schema_versions \
+             ORDER BY version, applied_at, description",
+        )
+        .expect("prepare schema-version observation")
+        .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
+        .expect("query schema-version observation")
+        .collect::<rusqlite::Result<Vec<_>>>()
+        .expect("collect schema-version observation");
+    let project_metadata = conn
+        .prepare(
+            "SELECT key, value, updated_at FROM project_metadata \
+             ORDER BY key, value, updated_at",
+        )
+        .expect("prepare project-metadata observation")
+        .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
+        .expect("query project-metadata observation")
+        .collect::<rusqlite::Result<Vec<_>>>()
+        .expect("collect project-metadata observation");
+
+    DatabaseObservation {
+        schema,
+        schema_versions,
+        project_metadata,
+    }
+}
+
+fn assert_read_open_did_not_mutate(
+    project: &TempProject,
+    paths: &IndexPaths,
+    before_tree: &BTreeMap<PathBuf, SnapshotKind>,
+    before_database: &DatabaseObservation,
+) {
+    for (label, path) in [
+        ("WAL", sqlite_sidecar(&paths.current_db(), "-wal")),
+        ("SHM", sqlite_sidecar(&paths.current_db(), "-shm")),
+    ] {
+        match std::fs::symlink_metadata(&path) {
+            Ok(_) => panic!(
+                "read/status open must not create a {label} sidecar at {}",
+                path.display()
+            ),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => panic!("inspect {label} sidecar {}: {error}", path.display()),
+        }
+    }
+    assert_snapshot_unchanged(before_tree, &snapshot_tree(project.path()));
+    assert_eq!(
+        &observe_database_without_touching_namespace(paths),
+        before_database,
+        "read/status open changed SQLite schema or metadata rows"
+    );
+}
+
+#[test]
+fn read_and_status_open_are_sqlite_read_only_and_never_migrate() {
+    let project = TempProject::new("read-status-never-migrate");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    std::fs::write(
+        &paths.state_slots()[1],
+        wire_bytes(
+            0,
+            CURRENT_STORAGE_PROTOCOL,
+            CURRENT_EXTRACTION_VERSION,
+            "current",
+            paths.project_identity(),
+        ),
+    )
+    .expect("stage older valid Current state slot");
+
+    // Keep the physical schema at the latest shape but lower its recorded
+    // version. Any accidental call to the legacy migration path will insert a
+    // version-7 row and change both the logical and byte snapshots.
+    let conn = Connection::open_with_flags(paths.current_db(), OpenFlags::SQLITE_OPEN_READ_WRITE)
+        .expect("open migration-canary fixture");
+    conn.execute(
+        "UPDATE schema_versions \
+         SET version = ?1, applied_at = ?2, description = ?3 \
+         WHERE version = ?4",
+        rusqlite::params![
+            codegraph_store::migrations::CURRENT_SCHEMA_VERSION - 1,
+            -7_i64,
+            "acceptance migration canary",
+            codegraph_store::migrations::CURRENT_SCHEMA_VERSION,
+        ],
+    )
+    .expect("stage migration-version canary");
+    conn.execute(
+        "INSERT INTO project_metadata (key, value, updated_at) VALUES (?1, ?2, ?3)",
+        rusqlite::params!["acceptance_canary", "must-remain-byte-exact", -11_i64],
+    )
+    .expect("stage metadata-repair canary");
+    conn.pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .expect("checkpoint migration-canary fixture");
+    drop(conn);
+    remove_sidecars(&paths);
+
+    let before_tree = snapshot_tree(project.path());
+    let before_database = observe_database_without_touching_namespace(&paths);
+    assert_eq!(
+        before_database.schema_versions.last(),
+        Some(&(
+            codegraph_store::migrations::CURRENT_SCHEMA_VERSION - 1,
+            -7,
+            "acceptance migration canary".to_string(),
+        )),
+        "fixture must be migration-eligible if a read path invokes maintenance"
+    );
+
+    let store = Store::open_for_read(&paths, deadline(), || false)
+        .expect("Current read accepts an intentionally migration-eligible schema");
+    assert_eq!(
+        store.schema_version().expect("observe canary version"),
+        codegraph_store::migrations::CURRENT_SCHEMA_VERSION - 1
+    );
+    assert_read_open_did_not_mutate(&project, &paths, &before_tree, &before_database);
+    drop(store);
+    assert_read_open_did_not_mutate(&project, &paths, &before_tree, &before_database);
+
+    let opened = Store::open_for_status(&paths, deadline(), || false)
+        .expect("Current status accepts an intentionally migration-eligible schema");
+    assert_eq!(opened.status, Some(ExtractionStatus::Current));
+    assert!(opened.store().is_some());
+    assert_read_open_did_not_mutate(&project, &paths, &before_tree, &before_database);
+    drop(opened);
+    assert_read_open_did_not_mutate(&project, &paths, &before_tree, &before_database);
+
+    for open in ["read", "status"] {
+        let mismatch = TempProject::new("read-status-stamp-mismatch");
+        let mismatch_paths = stage_current(&mismatch, Some("1"));
+        let before_tree = snapshot_tree(mismatch.path());
+        let before_database = observe_database_without_touching_namespace(&mismatch_paths);
+        let error = match open {
+            "read" => Store::open_for_read(&mismatch_paths, deadline(), || false)
+                .expect_err("Current/DB stamp mismatch rejects read"),
+            "status" => Store::open_for_status(&mismatch_paths, deadline(), || false)
+                .expect_err("Current/DB stamp mismatch rejects status"),
+            other => panic!("unknown acceptance open {other}"),
+        };
+        assert!(matches!(
+            error,
+            StoreError::InvalidExtractionStamp {
+                path,
+                issue: ExtractionStampIssue::Mismatch {
+                    expected: CURRENT_EXTRACTION_VERSION,
+                    found: 1,
+                },
+            } if path == mismatch_paths.current_db()
+        ));
+        assert_read_open_did_not_mutate(&mismatch, &mismatch_paths, &before_tree, &before_database);
+    }
+}
+
 #[test]
 fn extraction_status_never_opens_sqlite_or_mutates_bytes() {
     let project = TempProject::new("classifier-boundary");

From 4aa6c383525a3ba3f24be19b56c72a3c9c0e09b5 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 10:16:06 +0800
Subject: [PATCH 28/91] fix(watch): resync removed directories

---
 crates/codegraph-watch/src/sync.rs    |  24 +-
 crates/codegraph-watch/src/watcher.rs | 532 +++++++++++++++++++++++++-
 2 files changed, 546 insertions(+), 10 deletions(-)

diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index 9f8396d..c860ba5 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -41,16 +41,36 @@ pub fn sync_project_once(project_root: impl AsRef<Path>) -> Result<SyncOutcome>
     sync_project_once_with_progress(project_root, |_, _| {})
 }
 
+/// Whole-project sync using watcher-owned path patterns while preserving every
+/// other scan option from the normal sync path.
+pub(crate) fn sync_project_once_with_patterns(
+    project_root: impl AsRef<Path>,
+    include: &[String],
+    exclude: &[String],
+) -> Result<SyncOutcome> {
+    let mut options = scan_options();
+    options.include = include.to_vec();
+    options.exclude = exclude.to_vec();
+    sync_project_once_with_options(project_root.as_ref(), options, |_, _| {})
+}
+
 /// Like [`sync_project_once`] but invokes `on_progress(done, total)` after each
 /// candidate file is processed, letting a caller drive a progress bar. The
 /// callback is a pure side effect: it never gates or reorders work, so the
 /// result stays byte-equivalent to `index --force`.
 pub fn sync_project_once_with_progress(
     project_root: impl AsRef<Path>,
-    mut on_progress: impl FnMut(usize, usize),
+    on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
-    let project_root = project_root.as_ref();
     let options = scan_options();
+    sync_project_once_with_options(project_root.as_ref(), options, on_progress)
+}
+
+fn sync_project_once_with_options(
+    project_root: &Path,
+    options: ExtractOptions,
+    mut on_progress: impl FnMut(usize, usize),
+) -> Result<SyncOutcome> {
     let include = options.include.clone();
     let exclude = options.exclude.clone();
     let started = Instant::now();
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index af6a4af..1c4eb9c 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -1,4 +1,4 @@
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 use std::fs;
 use std::io;
 use std::path::{Path, PathBuf};
@@ -9,13 +9,19 @@ use std::thread::{self, JoinHandle};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use anyhow::Result;
+use notify::event::{EventKind, RemoveKind};
 use notify::{Event, RecommendedWatcher, RecursiveMode, Watcher};
 
 use crate::policy::{WatchPolicy, watch_disabled_reason};
-use crate::sync::{SyncOutcome, default_db_path, sync_changed_paths_with_patterns};
+use crate::sync::{
+    SyncOutcome, default_db_path, sync_changed_paths_with_patterns, sync_project_once_with_patterns,
+};
 
 type SyncCallback = Arc<dyn Fn(SyncOutcome) + Send + Sync>;
 type SyncFn = Arc<dyn Fn(Vec<String>) -> Result<SyncOutcome> + Send + Sync>;
+/// Whole-project sync, used when an event cannot be expressed as a path list —
+/// currently only a removed DIRECTORY (see [`RemovalHint`]).
+type FullSyncFn = Arc<dyn Fn() -> Result<SyncOutcome> + Send + Sync>;
 type NoticeCallback = Arc<dyn Fn(String) + Send + Sync>;
 
 /// The OS watcher, shared between [`ProjectWatcher`] (which owns its lifetime)
@@ -182,6 +188,13 @@ fn collect_watch_dirs(root: &Path, policy: &WatchPolicy) -> Vec<PathBuf> {
     dirs
 }
 
+fn known_directory_paths(root: &Path, policy: &WatchPolicy) -> BTreeSet<String> {
+    collect_watch_dirs(root, policy)
+        .into_iter()
+        .filter_map(|dir| policy.normalize_relative(dir))
+        .collect()
+}
+
 fn initial_watch_targets(
     backend: WatchBackend,
     project_root: &Path,
@@ -289,6 +302,9 @@ pub struct WatchOptions {
     pub include: Vec<String>,
     pub exclude: Vec<String>,
     sync_fn: Option<SyncFn>,
+    /// Override for the whole-project sync a removed directory escalates to.
+    /// Defaults to [`crate::sync::sync_project_once`]; tests inject a counter.
+    full_sync_fn: Option<FullSyncFn>,
 }
 
 impl Default for WatchOptions {
@@ -306,6 +322,7 @@ impl Default for WatchOptions {
             include: Vec::new(),
             exclude: Vec::new(),
             sync_fn: None,
+            full_sync_fn: None,
         }
     }
 }
@@ -350,8 +367,22 @@ impl ProjectWatcher {
                 sync_changed_paths_with_patterns(&project_root, &db_path, paths, &include, &exclude)
             })
         });
+        // A removed directory cannot be expressed as a path list (its tracked
+        // descendants are only discoverable by diffing the whole index against
+        // disk), so it escalates to the SAME full sync `codegraph sync` runs.
+        let full_sync_fn = options.full_sync_fn.clone().unwrap_or_else(|| {
+            let project_root = project_root.clone();
+            let include = options.include.clone();
+            let exclude = options.exclude.clone();
+            Arc::new(move || sync_project_once_with_patterns(&project_root, &include, &exclude))
+        });
         let (tx, rx) = mpsc::channel();
         let degraded = Arc::new(DegradedState::default());
+        // Capture directory identity before registering the backend. Windows emits
+        // `RemoveKind::Any` after deletion, so this pre-event snapshot is the only
+        // deterministic way to distinguish a known directory from an extensionless
+        // file without inspecting a path that no longer exists.
+        let known_dirs = known_directory_paths(&project_root, &policy);
 
         // Build the OS watcher and register the pruned watch set BEFORE spawning
         // the loop, so its create-event handler can share the same watcher to add
@@ -363,7 +394,10 @@ impl ProjectWatcher {
             let mut watcher =
                 notify::recommended_watcher(move |event: notify::Result<Event>| match event {
                     Ok(event) => {
-                        let _ = callback_tx.send(LoopMessage::Event(event.paths));
+                        let _ = callback_tx.send(LoopMessage::Event(WatchEventBatch::from_event(
+                            &event.kind,
+                            event.paths,
+                        )));
                     }
                     Err(err) => {
                         let _ = callback_tx.send(LoopMessage::WatchError(err));
@@ -432,11 +466,13 @@ impl ProjectWatcher {
                 policy: loop_policy,
                 debounce,
                 sync_fn,
+                full_sync_fn,
                 on_sync_complete,
                 on_degraded,
                 on_sync_error,
                 degraded: loop_degraded,
                 watcher: loop_watcher,
+                known_dirs,
             });
         });
 
@@ -457,7 +493,35 @@ impl ProjectWatcher {
     }
 
     pub fn ingest_event_for_tests(&self, relative: impl Into<PathBuf>) {
-        let _ = self.tx.send(LoopMessage::Event(vec![relative.into()]));
+        let _ = self.tx.send(LoopMessage::Event(WatchEventBatch::paths(vec![
+            relative.into(),
+        ])));
+    }
+
+    /// Feed a REMOVED-DIRECTORY event, the notify `Remove(RemoveKind::Folder)`
+    /// shape, without needing a real OS watcher.
+    pub fn ingest_removed_dir_for_tests(&self, relative: impl Into<PathBuf>) {
+        let _ = self.tx.send(LoopMessage::Event(WatchEventBatch::from_event(
+            &EventKind::Remove(RemoveKind::Folder),
+            vec![relative.into()],
+        )));
+    }
+
+    /// Feed the ambiguous removal shape emitted by Windows
+    /// `ReadDirectoryChangesW`, without requiring a native Windows runner.
+    pub fn ingest_ambiguous_remove_for_tests(&self, relative: impl Into<PathBuf>) {
+        let _ = self.tx.send(LoopMessage::Event(WatchEventBatch::from_event(
+            &EventKind::Remove(RemoveKind::Any),
+            vec![relative.into()],
+        )));
+    }
+
+    #[cfg(test)]
+    fn flush_for_tests(&self) {
+        let (tx, rx) = mpsc::channel();
+        let _ = self.tx.send(LoopMessage::Flush(tx));
+        rx.recv_timeout(Duration::from_secs(1))
+            .expect("event loop accepted deterministic flush");
     }
 
     pub fn pending_files(&self) -> Vec<PendingFile> {
@@ -488,12 +552,71 @@ impl Drop for ProjectWatcher {
 }
 
 enum LoopMessage {
-    Event(Vec<PathBuf>),
+    Event(WatchEventBatch),
     WatchError(notify::Error),
     Snapshot(Sender<Vec<PendingFile>>),
+    #[cfg(test)]
+    Flush(Sender<()>),
     Stop,
 }
 
+/// One notify event, reduced to exactly what the debounce loop needs: the paths,
+/// plus the backend's removal classification.
+///
+/// The distinction has to travel with the event because it cannot be recovered
+/// later: a removed directory is already gone from disk, so `path.is_dir()` is
+/// false and its extensionless name is indistinguishable from a deleted
+/// extensionless file. Carrying the notify `EventKind` forward keeps the
+/// escalation deterministic instead of guessing from a missing path.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+struct WatchEventBatch {
+    paths: Vec<PathBuf>,
+    removal: RemovalHint,
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+enum RemovalHint {
+    #[default]
+    None,
+    Directory,
+    Ambiguous,
+}
+
+impl WatchEventBatch {
+    fn paths(paths: Vec<PathBuf>) -> Self {
+        Self {
+            paths,
+            removal: RemovalHint::None,
+        }
+    }
+
+    fn from_event(kind: &EventKind, paths: Vec<PathBuf>) -> Self {
+        let removal = match kind {
+            EventKind::Remove(RemoveKind::Folder) => RemovalHint::Directory,
+            EventKind::Remove(RemoveKind::Any) => RemovalHint::Ambiguous,
+            _ => RemovalHint::None,
+        };
+        Self { paths, removal }
+    }
+}
+
+fn classify_removed_directory(
+    hint: RemovalHint,
+    relative: &str,
+    known_dirs: &mut BTreeSet<String>,
+) -> bool {
+    let removed_dir = match hint {
+        RemovalHint::Directory => true,
+        RemovalHint::Ambiguous => known_dirs.contains(relative),
+        RemovalHint::None => false,
+    };
+    if removed_dir {
+        let descendant_prefix = format!("{relative}/");
+        known_dirs.retain(|known| known != relative && !known.starts_with(&descendant_prefix));
+    }
+    removed_dir
+}
+
 #[derive(Debug, Clone)]
 struct PendingInfo {
     first_seen_ms: u128,
@@ -505,11 +628,13 @@ struct EventLoopCtx {
     policy: WatchPolicy,
     debounce: Duration,
     sync_fn: SyncFn,
+    full_sync_fn: FullSyncFn,
     on_sync_complete: Option<SyncCallback>,
     on_degraded: Option<NoticeCallback>,
     on_sync_error: Option<NoticeCallback>,
     degraded: Arc<DegradedState>,
     watcher: SharedWatcher,
+    known_dirs: BTreeSet<String>,
 }
 
 fn event_loop(ctx: EventLoopCtx) {
@@ -518,15 +643,21 @@ fn event_loop(ctx: EventLoopCtx) {
         policy,
         debounce,
         sync_fn,
+        full_sync_fn,
         on_sync_complete,
         on_degraded,
         on_sync_error,
         degraded,
         watcher,
+        mut known_dirs,
     } = ctx;
     let mut pending = BTreeMap::<String, PendingInfo>::new();
     let mut deadline = None::<Instant>;
     let mut consecutive_sync_errors = 0u32;
+    // Set by a removed-directory event in the current burst. It DOMINATES the
+    // per-path list (one full sync instead of N incremental ones) yet still
+    // flushes exactly once, on the same debounce deadline.
+    let mut full_sync_pending = false;
     loop {
         let message = match deadline {
             Some(when) => match rx.recv_timeout(when.saturating_duration_since(Instant::now())) {
@@ -541,9 +672,30 @@ fn event_loop(ctx: EventLoopCtx) {
         };
 
         match message {
-            Some(LoopMessage::Event(paths)) => {
+            Some(LoopMessage::Event(batch)) => {
+                let WatchEventBatch { paths, removal } = batch;
                 for path in paths {
                     if let Some(relative) = policy.normalize_relative(&path) {
+                        // A removed DIRECTORY bypasses extension filtering: it has
+                        // no source extension, so the file gate below would drop it
+                        // and every tracked descendant would linger in the index
+                        // forever. The watch policy still applies (an ignored dir is
+                        // still ignored), and the removal escalates the burst to one
+                        // full sync — the only pass that can find those descendants.
+                        if classify_removed_directory(removal, &relative, &mut known_dirs) {
+                            if policy.should_watch_dir(&relative) {
+                                full_sync_pending = true;
+                                let now = epoch_millis();
+                                pending
+                                    .entry(relative)
+                                    .and_modify(|info| info.last_seen_ms = now)
+                                    .or_insert(PendingInfo {
+                                        first_seen_ms: now,
+                                        last_seen_ms: now,
+                                    });
+                            }
+                            continue;
+                        }
                         // A brand-new non-ignored directory holds no inotify watch
                         // yet (Linux watches are per-dir NonRecursive — see
                         // `collect_watch_dirs`). Register it (and any non-ignored
@@ -551,6 +703,7 @@ fn event_loop(ctx: EventLoopCtx) {
                         // edits inside it are seen without a server restart.
                         if path.is_dir() && policy.should_watch_dir(&relative) {
                             register_new_dirs(&watcher, &policy, &path);
+                            known_dirs.extend(known_directory_paths(&path, &policy));
                         }
                         if policy.should_handle_file(&relative)
                             || (policy.allows_file_path(&relative)
@@ -582,12 +735,24 @@ fn event_loop(ctx: EventLoopCtx) {
             Some(LoopMessage::Snapshot(reply)) => {
                 let _ = reply.send(snapshot(&pending));
             }
+            #[cfg(test)]
+            Some(LoopMessage::Flush(reply)) => {
+                if !pending.is_empty() {
+                    deadline = Some(Instant::now());
+                }
+                let _ = reply.send(());
+            }
             Some(LoopMessage::Stop) => break,
             None => {
                 let paths = pending.keys().cloned().collect::<Vec<_>>();
                 pending.clear();
                 deadline = None;
-                let attempt = run_sync_with_backoff(&sync_fn, paths.clone());
+                let full_sync = std::mem::take(&mut full_sync_pending);
+                let attempt = if full_sync {
+                    run_full_sync_with_backoff(&full_sync_fn)
+                } else {
+                    run_sync_with_backoff(&sync_fn, paths.clone())
+                };
                 let decision = classify_persistent_failure(&attempt, &mut consecutive_sync_errors);
                 match attempt {
                     SyncAttempt::Done(outcome) => {
@@ -712,18 +877,35 @@ fn run_sync_with_backoff(sync_fn: &SyncFn, paths: Vec<String>) -> SyncAttempt {
     run_sync_with_backoff_inner(sync_fn, paths, MAX_BACKOFF, thread::sleep)
 }
 
+/// Same bounded-backoff contract as [`run_sync_with_backoff`], for the
+/// whole-project sync a removed directory escalates to.
+fn run_full_sync_with_backoff(full_sync_fn: &FullSyncFn) -> SyncAttempt {
+    run_with_backoff(MAX_BACKOFF, thread::sleep, || full_sync_fn())
+}
+
 /// Inner retry loop with an injectable budget and sleeper so the cap can be
 /// unit-tested without sleeping a real 30 seconds.
 fn run_sync_with_backoff_inner(
     sync_fn: &SyncFn,
     paths: Vec<String>,
+    budget: Duration,
+    sleeper: impl FnMut(Duration),
+) -> SyncAttempt {
+    run_with_backoff(budget, sleeper, || sync_fn(paths.clone()))
+}
+
+/// The shared retry policy: retry on write-lock contention with bounded
+/// exponential backoff capped at [`MAX_BACKOFF`], degrade once the cumulative
+/// sleep budget is spent, and surface any non-contention error immediately.
+fn run_with_backoff(
     budget: Duration,
     mut sleeper: impl FnMut(Duration),
+    mut run: impl FnMut() -> Result<SyncOutcome>,
 ) -> SyncAttempt {
     let mut backoff = Duration::ZERO;
     let mut slept = Duration::ZERO;
     loop {
-        match sync_fn(paths.clone()) {
+        match run() {
             Ok(outcome) => return SyncAttempt::Done(outcome),
             Err(err) => {
                 if !is_lock_contention(&err) {
@@ -853,6 +1035,340 @@ mod tests {
         assert_eq!(outcomes[0].files_checked, 1);
     }
 
+    #[test]
+    fn deleted_directory_event_schedules_one_full_sync() {
+        // A removed DIRECTORY has no source extension, so extension-based event
+        // filtering drops it and every tracked descendant lingers in the index
+        // forever. The watcher must escalate the removal to exactly ONE
+        // full-project sync — the only pass that discovers every absent tracked
+        // descendant — instead of an incremental path-scoped sync.
+        let dir = crate::sync::tests::TestDir::new("watch-deleted-dir");
+        let _ = codegraph_core::config::init_config(None, dir.path());
+        fs::write(dir.path().join(".gitignore"), "Tools/\n").unwrap();
+        fs::create_dir_all(dir.path().join("Tools/feature")).unwrap();
+        fs::create_dir_all(dir.path().join("src")).unwrap();
+        fs::write(
+            dir.path().join("Tools/feature/alpha.ts"),
+            "export function alpha() { return 1; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("Tools/feature/beta.ts"),
+            "export function beta() { return 2; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("Tools/keep.ts"),
+            "export function includedBefore() { return 3; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("src/excluded.ts"),
+            "export function excludedBefore() { return 4; }\n",
+        )
+        .unwrap();
+        let db = crate::sync::default_db_path(dir.path()).unwrap();
+        let indexed = crate::sync::sync_changed_paths_with_patterns(
+            dir.path(),
+            &db,
+            [
+                "Tools/feature/alpha.ts",
+                "Tools/feature/beta.ts",
+                "Tools/keep.ts",
+                "src/excluded.ts",
+            ],
+            &["Tools/".to_string()],
+            &[],
+        )
+        .unwrap();
+        assert_eq!(
+            indexed.files_reindexed, 4,
+            "all fixture files indexed first"
+        );
+
+        // The watcher-local patterns deliberately oppose the process-global/default
+        // full-sync scope: include the gitignored Tools tree, but exclude one normal
+        // source file. Both surviving files change before the directory removal so
+        // the resulting stored symbols prove which patterns the full sync used.
+        fs::write(
+            dir.path().join("Tools/keep.ts"),
+            "export function includedAfter() { return 30; }\n",
+        )
+        .unwrap();
+        fs::write(
+            dir.path().join("src/excluded.ts"),
+            "export function excludedAfter() { return 40; }\n",
+        )
+        .unwrap();
+
+        let (outcome_tx, outcome_rx) = mpsc::channel();
+        // An injected INCREMENTAL sync_fn that must never run: a directory
+        // removal is not a per-path event.
+        let incremental_calls = Arc::new(AtomicUsize::new(0));
+        let incremental = Arc::clone(&incremental_calls);
+        let sync_fn: SyncFn = Arc::new(move |_paths| {
+            incremental.fetch_add(1, AtomicOrdering::SeqCst);
+            Ok(SyncOutcome::default())
+        });
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                debounce: Duration::from_secs(30),
+                inert_for_tests: true,
+                db_path: Some(db.clone()),
+                sync_fn: Some(sync_fn),
+                include: vec!["Tools/".to_string()],
+                exclude: vec!["src/excluded.ts".to_string()],
+                on_sync_complete: Some(Arc::new(move |outcome| {
+                    outcome_tx.send(outcome).unwrap();
+                })),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        // When: the directory disappears and the backend reports the ambiguous
+        // Windows removal shape. The watcher must recover directory identity from
+        // its startup registration state rather than inspecting the missing path.
+        fs::remove_dir_all(dir.path().join("Tools/feature")).unwrap();
+        watcher.ingest_ambiguous_remove_for_tests("Tools/feature");
+        watcher.flush_for_tests();
+        let outcome = outcome_rx
+            .recv_timeout(Duration::from_secs(2))
+            .expect("removed-directory sync completion");
+        watcher.stop();
+
+        // Then: exactly one sync fired, it was the FULL sync (not the injected
+        // incremental one), it removed both tracked descendants, and the removed
+        // directory is reported as the trigger path.
+        assert!(outcome_rx.try_recv().is_err(), "only one sync may complete");
+        assert_eq!(
+            incremental_calls.load(AtomicOrdering::SeqCst),
+            0,
+            "a directory removal must NOT take the incremental per-path sync"
+        );
+        assert_eq!(
+            outcome.files_removed, 2,
+            "the full sync must drop every tracked descendant of the missing dir"
+        );
+        assert_eq!(outcome.trigger_paths, vec!["Tools/feature".to_string()]);
+        let store = codegraph_store::Store::open(&db).unwrap();
+        for gone in ["Tools/feature/alpha.ts", "Tools/feature/beta.ts"] {
+            assert!(
+                store.file_by_path(gone).unwrap().is_none(),
+                "{gone} must be gone from the store after the directory removal"
+            );
+        }
+        let included_names = store
+            .nodes_by_file_path("Tools/keep.ts")
+            .unwrap()
+            .into_iter()
+            .map(|node| node.name)
+            .collect::<Vec<_>>();
+        assert!(
+            included_names.iter().any(|name| name == "includedAfter"),
+            "watcher-local include must let full sync refresh Tools/keep.ts: {included_names:?}"
+        );
+        let excluded_names = store
+            .nodes_by_file_path("src/excluded.ts")
+            .unwrap()
+            .into_iter()
+            .map(|node| node.name)
+            .collect::<Vec<_>>();
+        assert!(
+            excluded_names.iter().any(|name| name == "excludedBefore")
+                && !excluded_names.iter().any(|name| name == "excludedAfter"),
+            "watcher-local exclude must keep src/excluded.ts untouched: {excluded_names:?}"
+        );
+    }
+
+    #[test]
+    fn ambiguous_remove_of_known_directory_keeps_directory_semantics() {
+        // Windows ReadDirectoryChangesW reports directory deletion as Any. The
+        // current dirty implementation loses that identity unconditionally;
+        // the corrected classifier must corroborate it from the watcher's known
+        // directory state rather than from extension or the now-missing path.
+        let dir = crate::sync::tests::TestDir::new("watch-ambiguous-remove");
+        fs::create_dir_all(dir.path().join("src/feature")).unwrap();
+        fs::write(dir.path().join("src/README"), "extensionless file\n").unwrap();
+        let policy = WatchPolicy::new(dir.path());
+        let mut known_dirs = known_directory_paths(dir.path(), &policy);
+        fs::remove_dir_all(dir.path().join("src/feature")).unwrap();
+        fs::remove_file(dir.path().join("src/README")).unwrap();
+
+        let directory_batch = WatchEventBatch::from_event(
+            &EventKind::Remove(RemoveKind::Any),
+            vec![PathBuf::from("src/feature")],
+        );
+        assert!(
+            classify_removed_directory(directory_batch.removal, "src/feature", &mut known_dirs,),
+            "an ambiguous removal of a watcher-known directory must remain a directory removal"
+        );
+
+        let file_batch = WatchEventBatch::from_event(
+            &EventKind::Remove(RemoveKind::Any),
+            vec![PathBuf::from("src/README")],
+        );
+        assert!(
+            !classify_removed_directory(file_batch.removal, "src/README", &mut known_dirs),
+            "an extensionless deleted file must not be guessed to be a directory"
+        );
+    }
+
+    #[test]
+    fn real_watcher_classifies_a_removed_directory_as_a_full_sync() {
+        // End-to-end with a REAL notify watcher: proves the OS actually delivers
+        // either an explicit Folder removal or Windows' ambiguous Any removal,
+        // and that the watcher escalates the known directory to a full sync.
+        let dir = crate::sync::tests::TestDir::new("watch-real-deleted-dir");
+        fs::create_dir_all(dir.path().join("src/feature")).unwrap();
+        fs::write(
+            dir.path().join("src/feature/mod.ts"),
+            "export const x = 1;\n",
+        )
+        .unwrap();
+
+        let full_calls = Arc::new(AtomicUsize::new(0));
+        let full_counter = Arc::clone(&full_calls);
+        let full_sync_fn: FullSyncFn = Arc::new(move || {
+            full_counter.fetch_add(1, AtomicOrdering::SeqCst);
+            Ok(SyncOutcome::default())
+        });
+        let sync_fn: SyncFn = Arc::new(|_paths| Ok(SyncOutcome::default()));
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                debounce: Duration::from_millis(50),
+                sync_fn: Some(sync_fn),
+                full_sync_fn: Some(full_sync_fn),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        std::thread::sleep(Duration::from_millis(150));
+        fs::remove_dir_all(dir.path().join("src/feature")).unwrap();
+
+        let mut saw_full = false;
+        for _ in 0..40 {
+            std::thread::sleep(Duration::from_millis(50));
+            if full_calls.load(AtomicOrdering::SeqCst) > 0 {
+                saw_full = true;
+                break;
+            }
+        }
+        watcher.stop();
+        assert!(
+            saw_full,
+            "removing a watched directory must escalate to the full sync"
+        );
+    }
+
+    #[test]
+    fn directory_removal_burst_deduplicates_to_one_full_sync() {
+        // A `rm -rf` burst surfaces the folder removal AND each child removal.
+        // The full-sync escalation must dominate the per-file paths yet still
+        // collapse to ONE sync, with every event path retained as a trigger.
+        let dir = crate::sync::tests::TestDir::new("watch-deleted-dir-burst");
+        let full_calls = Arc::new(AtomicUsize::new(0));
+        let full_counter = Arc::clone(&full_calls);
+        let full_sync_fn: FullSyncFn = Arc::new(move || {
+            full_counter.fetch_add(1, AtomicOrdering::SeqCst);
+            Ok(SyncOutcome {
+                files_removed: 2,
+                ..Default::default()
+            })
+        });
+        let incremental_calls = Arc::new(AtomicUsize::new(0));
+        let incremental = Arc::clone(&incremental_calls);
+        let sync_fn: SyncFn = Arc::new(move |_paths| {
+            incremental.fetch_add(1, AtomicOrdering::SeqCst);
+            Ok(SyncOutcome::default())
+        });
+        let (outcome_tx, outcome_rx) = mpsc::channel();
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                debounce: Duration::from_secs(30),
+                inert_for_tests: true,
+                sync_fn: Some(sync_fn),
+                full_sync_fn: Some(full_sync_fn),
+                on_sync_complete: Some(Arc::new(move |outcome| {
+                    outcome_tx.send(outcome).unwrap();
+                })),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        watcher.ingest_event_for_tests("src/feature/beta.ts");
+        watcher.ingest_removed_dir_for_tests("src/feature");
+        watcher.ingest_event_for_tests("src/feature/alpha.ts");
+        watcher.ingest_event_for_tests("src/feature/beta.ts");
+        watcher.flush_for_tests();
+        let outcome = outcome_rx
+            .recv_timeout(Duration::from_secs(2))
+            .expect("burst sync completion");
+        assert!(watcher.pending_files().is_empty());
+        watcher.stop();
+
+        assert!(
+            outcome_rx.try_recv().is_err(),
+            "the burst must collapse to one sync"
+        );
+        assert_eq!(
+            full_calls.load(AtomicOrdering::SeqCst),
+            1,
+            "the full sync must run exactly once for the burst"
+        );
+        assert_eq!(
+            incremental_calls.load(AtomicOrdering::SeqCst),
+            0,
+            "a full-sync burst must not also run the incremental sync"
+        );
+        assert_eq!(
+            outcome.trigger_paths,
+            vec![
+                "src/feature".to_string(),
+                "src/feature/alpha.ts".to_string(),
+                "src/feature/beta.ts".to_string(),
+            ],
+            "every event path in the burst stays a sorted, deduped trigger path"
+        );
+    }
+
+    #[test]
+    fn removed_ignored_directory_does_not_schedule_a_full_sync() {
+        // The escalation honors the watch policy: an ignored directory removal
+        // is still dropped, so no sync is scheduled at all.
+        let dir = crate::sync::tests::TestDir::new("watch-deleted-dir-ignored");
+        let full_calls = Arc::new(AtomicUsize::new(0));
+        let full_counter = Arc::clone(&full_calls);
+        let full_sync_fn: FullSyncFn = Arc::new(move || {
+            full_counter.fetch_add(1, AtomicOrdering::SeqCst);
+            Ok(SyncOutcome::default())
+        });
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                debounce: Duration::from_secs(30),
+                inert_for_tests: true,
+                full_sync_fn: Some(full_sync_fn),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        watcher.ingest_removed_dir_for_tests("node_modules/pkg");
+        watcher.flush_for_tests();
+        watcher.stop();
+        assert_eq!(full_calls.load(AtomicOrdering::SeqCst), 0);
+    }
+
     #[test]
     fn ignored_directory_event_does_not_schedule_reindex() {
         let dir = crate::sync::tests::TestDir::new("watch-ignore");

From 496afa2809e777e058ff64c729dff44be1a17ddc Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 10:16:57 +0800
Subject: [PATCH 29/91] feat(core): add project-scoped config loading

---
 crates/codegraph-core/src/config.rs | 308 ++++++++++++++++++++++++++--
 1 file changed, 291 insertions(+), 17 deletions(-)

diff --git a/crates/codegraph-core/src/config.rs b/crates/codegraph-core/src/config.rs
index f677168..0fc5821 100644
--- a/crates/codegraph-core/src/config.rs
+++ b/crates/codegraph-core/src/config.rs
@@ -1,7 +1,8 @@
 //! Configuration module for CodeGraph.
 //!
-//! Reads `<project_root>/.codegraph/config.toml` via Pattern B (runtime discovery).
-//! Config is optional — missing file uses all defaults, matching the upstream zero-config UX.
+//! Project-scoped callers load immutable [`Config`] values from the current
+//! [`IndexPaths`] root. Config is optional — a missing current-root file uses all
+//! defaults, matching the upstream zero-config UX.
 //!
 //! ### Config Sources
 //! - `max_file_size`: upstream extraction/index.ts:101 (skip files >1MB)
@@ -15,13 +16,16 @@
 //! - watch.enabled: true
 //! - watch.debounce_ms: 2000
 //!
-//! Loaded once into a global OnceLock; consumers borrow &'static Config.
-//! For libraries: this module returns Result; the binary owns the failure policy.
+//! The process-global [`init_config`] / [`get_config`] API remains temporarily for
+//! transitional bootstrap callers. New library code must use
+//! [`Config::load_for_paths`] and pass the returned [`Arc`] through project-scoped
+//! operations instead of consulting that singleton.
 
+use crate::IndexPaths;
 use anyhow::{Context, Result};
 use serde::Deserialize;
 use std::path::{Path, PathBuf};
-use std::sync::OnceLock;
+use std::sync::{Arc, OnceLock};
 
 /// Top-level configuration.
 #[derive(Debug, Clone, Deserialize)]
@@ -236,6 +240,19 @@ impl Default for WatchConfig {
     }
 }
 
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            app: AppConfig {
+                name: "codegraph".to_string(),
+                log_level: default_log_level(),
+            },
+            indexing: IndexingConfig::default(),
+            watch: WatchConfig::default(),
+        }
+    }
+}
+
 impl Config {
     /// Read and parse a TOML file at `path`.
     pub fn from_path(path: impl AsRef<Path>) -> Result<Self> {
@@ -247,13 +264,47 @@ impl Config {
         Ok(cfg)
     }
 
-    /// Discover the config file with a clear precedence:
+    /// Load an immutable config for one resolved project's current index root.
+    ///
+    /// Precedence is deliberately narrow and project-authoritative:
+    ///
+    /// 1. explicit `cli_path`;
+    /// 2. the process-wide `APP_CONFIG` override;
+    /// 3. [`IndexPaths::config_toml`] for this project.
+    ///
+    /// A missing current-root config returns defaults. An explicitly selected
+    /// CLI or environment path must exist and parse successfully. This API never
+    /// consults a legacy `.codegraph/config.toml`, the process working directory,
+    /// or another project's paths, and it does not cache across calls.
+    pub fn load_for_paths(cli_path: Option<&Path>, paths: &IndexPaths) -> Result<Arc<Self>> {
+        if let Some(path) = cli_path {
+            return Self::from_path(path).map(Arc::new);
+        }
+        if let Some(path) = std::env::var_os("APP_CONFIG") {
+            return Self::from_path(PathBuf::from(path)).map(Arc::new);
+        }
+
+        let project_config = paths.config_toml();
+        let config = if project_config
+            .try_exists()
+            .with_context(|| format!("checking config file: {}", project_config.display()))?
+        {
+            Self::from_path(project_config)?
+        } else {
+            Self::default()
+        };
+        Ok(Arc::new(config))
+    }
+
+    /// Transitional legacy discovery with a clear precedence:
     ///   1. explicit `cli_path` (passed in directly)
     ///   2. `APP_CONFIG` env var
     ///   3. `./.codegraph/config.toml` (current working directory)
     ///   4. `<project_root>/.codegraph/config.toml` (if provided)
     ///
-    /// If no file is found, returns all defaults.
+    /// If no file is found, returns all defaults. New project-scoped callers
+    /// should use [`Config::load_for_paths`]; this compatibility path retains the
+    /// old `.codegraph` and CWD behavior only until downstream callers migrate.
     pub fn discover(cli_path: Option<&Path>, project_root: &Path) -> Result<Self> {
         if let Some(p) = cli_path {
             return Self::from_path(p);
@@ -275,21 +326,16 @@ impl Config {
         }
 
         // No file found — return all defaults
-        Ok(Self {
-            app: AppConfig {
-                name: "codegraph".to_string(),
-                log_level: default_log_level(),
-            },
-            indexing: IndexingConfig::default(),
-            watch: WatchConfig::default(),
-        })
+        Ok(Self::default())
     }
 }
 
 static CONFIG: OnceLock<Config> = OnceLock::new();
 
-/// Initialize the global config once, early in `main`. Returns the parsed config
-/// so `main` can react to errors before continuing.
+/// Initialize the transitional global config once, early in `main`.
+///
+/// This exists so unmigrated bootstrap callers continue to compile. New
+/// project-scoped operations must use [`Config::load_for_paths`] instead.
 pub fn init_config(cli_path: Option<&Path>, project_root: &Path) -> Result<&'static Config> {
     let cfg = Config::discover(cli_path, project_root)?;
     CONFIG
@@ -321,6 +367,51 @@ pub fn get_config() -> &'static Config {
 mod tests {
     use super::*;
 
+    static APP_CONFIG_ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    /// Panic-safe process-environment mutation for APP_CONFIG precedence tests.
+    /// The serialization lock is retained until after the previous value is
+    /// restored, including when an assertion unwinds through this guard.
+    struct AppConfigEnvGuard {
+        previous: Option<std::ffi::OsString>,
+        _lock: std::sync::MutexGuard<'static, ()>,
+    }
+
+    impl AppConfigEnvGuard {
+        fn set(value: Option<&Path>) -> Self {
+            let lock = APP_CONFIG_ENV_LOCK
+                .lock()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            let previous = std::env::var_os("APP_CONFIG");
+            // SAFETY: every APP_CONFIG read/mutation in this test module that can
+            // overlap these tests is serialized by APP_CONFIG_ENV_LOCK. Drop
+            // restores the prior value while the same lock is still held.
+            match value {
+                Some(path) => unsafe { std::env::set_var("APP_CONFIG", path) },
+                None => unsafe { std::env::remove_var("APP_CONFIG") },
+            }
+            Self {
+                previous,
+                _lock: lock,
+            }
+        }
+
+        fn unset() -> Self {
+            Self::set(None)
+        }
+    }
+
+    impl Drop for AppConfigEnvGuard {
+        fn drop(&mut self) {
+            // SAFETY: the serialization guard is still held while restoring the
+            // process environment on both normal return and panic unwind.
+            match self.previous.take() {
+                Some(value) => unsafe { std::env::set_var("APP_CONFIG", value) },
+                None => unsafe { std::env::remove_var("APP_CONFIG") },
+            }
+        }
+    }
+
     #[test]
     fn test_default_config_parses() {
         let toml_str = r#"
@@ -408,6 +499,7 @@ max_file_size = 2097152
 
     #[test]
     fn test_missing_file_returns_defaults() {
+        let _env = AppConfigEnvGuard::unset();
         let cfg = Config::discover(None, Path::new("/tmp/nonexistent"))
             .expect("should not error on missing file");
         assert_eq!(cfg.app.log_level, "info");
@@ -475,6 +567,7 @@ max_file_size = 2097152
 
     #[test]
     fn discover_reads_project_root_codegraph_config() {
+        let _env = AppConfigEnvGuard::unset();
         let project = temp_dir("project-root");
         let cfg_dir = project.join(".codegraph");
         std::fs::create_dir_all(&cfg_dir).unwrap();
@@ -491,6 +584,186 @@ max_file_size = 2097152
         let _ = std::fs::remove_dir_all(&project);
     }
 
+    fn project_paths(label: &str) -> (PathBuf, IndexPaths) {
+        let project = temp_dir(label);
+        let paths = IndexPaths::resolve(&project, None).expect("resolve project paths");
+        (project, paths)
+    }
+
+    fn write_current_config(paths: &IndexPaths, contents: &str) {
+        let path = paths.config_toml();
+        std::fs::create_dir_all(path.parent().expect("config has parent")).unwrap();
+        std::fs::write(path, contents).unwrap();
+    }
+
+    #[test]
+    fn load_for_paths_prefers_explicit_cli_path_over_app_config_and_project() {
+        let (project, paths) = project_paths("scoped-explicit");
+        write_current_config(&paths, "[app]\nname = \"project\"\n");
+
+        let override_path = project.join("override.toml");
+        std::fs::write(&override_path, "[app]\nname = \"override\"\n").unwrap();
+        let explicit_path = project.join("explicit.toml");
+        std::fs::write(&explicit_path, "[app]\nname = \"explicit\"\n").unwrap();
+        let _env = AppConfigEnvGuard::set(Some(&override_path));
+
+        let config = Config::load_for_paths(Some(&explicit_path), &paths).unwrap();
+        assert_eq!(config.app.name, "explicit");
+
+        let _ = std::fs::remove_dir_all(project);
+    }
+
+    #[test]
+    fn load_for_paths_reads_only_the_resolved_current_root() {
+        let _env = AppConfigEnvGuard::unset();
+        let (project, paths) = project_paths("scoped-current-root");
+        write_current_config(
+            &paths,
+            "[app]\nname = \"current-root\"\n[indexing]\nmax_file_size = 321\n",
+        );
+
+        let config = Config::load_for_paths(None, &paths).unwrap();
+        assert_eq!(config.app.name, "current-root");
+        assert_eq!(config.indexing.max_file_size, 321);
+
+        let _ = std::fs::remove_dir_all(project);
+    }
+
+    #[test]
+    fn load_for_paths_missing_current_config_returns_defaults() {
+        let _env = AppConfigEnvGuard::unset();
+        let (project, paths) = project_paths("scoped-missing");
+
+        let config = Config::load_for_paths(None, &paths).unwrap();
+        assert_eq!(config.app.name, "codegraph");
+        assert_eq!(config.app.log_level, "info");
+        assert_eq!(config.indexing.max_file_size, default_max_file_size());
+        assert!(config.indexing.include.is_empty());
+        assert!(config.indexing.exclude.is_empty());
+
+        let _ = std::fs::remove_dir_all(project);
+    }
+
+    #[test]
+    fn load_for_paths_reports_malformed_current_config() {
+        let _env = AppConfigEnvGuard::unset();
+        let (project, paths) = project_paths("scoped-malformed");
+        write_current_config(&paths, "this is not = valid toml [[[");
+
+        let error = Config::load_for_paths(None, &paths).unwrap_err();
+        let message = format!("{error:#}");
+        assert!(
+            message.contains("parsing TOML"),
+            "unexpected error: {message}"
+        );
+        assert!(
+            message.contains(&paths.config_toml().display().to_string()),
+            "error must name the project config: {message}"
+        );
+
+        let _ = std::fs::remove_dir_all(project);
+    }
+
+    #[test]
+    fn load_for_paths_keeps_two_projects_isolated_without_app_config() {
+        let _env = AppConfigEnvGuard::unset();
+        let (alpha_project, alpha_paths) = project_paths("scoped-alpha");
+        let (beta_project, beta_paths) = project_paths("scoped-beta");
+        write_current_config(
+            &alpha_paths,
+            "[app]\nname = \"alpha\"\n[indexing]\nmax_file_size = 111\ninclude = [\"alpha/**\"]\nexclude = [\"beta/**\"]\n",
+        );
+        write_current_config(
+            &beta_paths,
+            "[app]\nname = \"beta\"\n[indexing]\nmax_file_size = 222\ninclude = [\"beta/**\"]\nexclude = [\"alpha/**\"]\n",
+        );
+
+        let alpha = Config::load_for_paths(None, &alpha_paths).unwrap();
+        let beta = Config::load_for_paths(None, &beta_paths).unwrap();
+        assert!(!Arc::ptr_eq(&alpha, &beta));
+        assert_eq!(alpha.indexing.max_file_size, 111);
+        assert_eq!(alpha.indexing.include, ["alpha/**"]);
+        assert_eq!(alpha.indexing.exclude, ["beta/**"]);
+        assert_eq!(beta.indexing.max_file_size, 222);
+        assert_eq!(beta.indexing.include, ["beta/**"]);
+        assert_eq!(beta.indexing.exclude, ["alpha/**"]);
+
+        let _ = std::fs::remove_dir_all(alpha_project);
+        let _ = std::fs::remove_dir_all(beta_project);
+    }
+
+    #[test]
+    fn load_for_paths_app_config_intentionally_overrides_two_projects() {
+        let (alpha_project, alpha_paths) = project_paths("override-alpha");
+        let (beta_project, beta_paths) = project_paths("override-beta");
+        write_current_config(&alpha_paths, "[app]\nname = \"alpha\"\n");
+        write_current_config(&beta_paths, "[app]\nname = \"beta\"\n");
+        let override_path = alpha_project.join("global-override.toml");
+        std::fs::write(
+            &override_path,
+            "[app]\nname = \"global\"\n[indexing]\nmax_file_size = 777\ninclude = [\"shared/**\"]\nexclude = [\"private/**\"]\n",
+        )
+        .unwrap();
+        let _env = AppConfigEnvGuard::set(Some(&override_path));
+
+        let alpha = Config::load_for_paths(None, &alpha_paths).unwrap();
+        let beta = Config::load_for_paths(None, &beta_paths).unwrap();
+        for config in [&alpha, &beta] {
+            assert_eq!(config.app.name, "global");
+            assert_eq!(config.indexing.max_file_size, 777);
+            assert_eq!(config.indexing.include, ["shared/**"]);
+            assert_eq!(config.indexing.exclude, ["private/**"]);
+        }
+
+        let _ = std::fs::remove_dir_all(alpha_project);
+        let _ = std::fs::remove_dir_all(beta_project);
+    }
+
+    #[test]
+    fn load_for_paths_ignores_legacy_project_and_cwd_configs() {
+        const CHILD_PROJECT: &str = "CODEGRAPH_CONFIG_CWD_CHILD_PROJECT";
+
+        if let Some(project) = std::env::var_os(CHILD_PROJECT) {
+            let paths = IndexPaths::resolve(Path::new(&project), None).unwrap();
+            let config = Config::load_for_paths(None, &paths).unwrap();
+            assert_eq!(config.app.name, "codegraph");
+            return;
+        }
+
+        let outer = temp_dir("scoped-no-legacy");
+        let project = outer.join("project");
+        std::fs::create_dir_all(project.join(".codegraph")).unwrap();
+        std::fs::write(
+            project.join(".codegraph/config.toml"),
+            "[app]\nname = \"legacy-project\"\n",
+        )
+        .unwrap();
+        std::fs::create_dir_all(outer.join(".codegraph")).unwrap();
+        std::fs::write(
+            outer.join(".codegraph/config.toml"),
+            "[app]\nname = \"legacy-cwd\"\n",
+        )
+        .unwrap();
+
+        let output = std::process::Command::new(std::env::current_exe().unwrap())
+            .arg("--exact")
+            .arg("config::tests::load_for_paths_ignores_legacy_project_and_cwd_configs")
+            .arg("--nocapture")
+            .current_dir(&outer)
+            .env(CHILD_PROJECT, &project)
+            .env_remove("APP_CONFIG")
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "child failed\nstdout:\n{}\nstderr:\n{}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+
+        let _ = std::fs::remove_dir_all(outer);
+    }
+
     #[test]
     fn indexing_config_default_carries_ignore_dirs_and_empty_exclude() {
         let indexing = IndexingConfig::default();
@@ -567,6 +840,7 @@ ignore_paths = ["custom/gen*"]
     }
     #[test]
     fn init_and_get_config_share_the_global_singleton() {
+        let _env = AppConfigEnvGuard::unset();
         let dir = std::env::temp_dir().join(format!(
             "codegraph-config-init-{}-{}",
             std::process::id(),

From a8c0f5c9ff3621743d26523ffc588eb0c9257b22 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 10:17:46 +0800
Subject: [PATCH 30/91] docs(upstream-sync): record Batch M acceptance evidence

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 107 ++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 4e9f418..8be7c3d 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2334,3 +2334,110 @@ worktree is rejected with `LSP file path must be inside request cwd`; Cargo
 check, Clippy, tests, formatting, and the guardrail are the diagnostics fallback,
 not an LSP-clean claim. Native Windows runtime/crash validation remains
 unavailable and is not claimed.
+
+## Batch M acceptance closure — items 13, 14, 18, and item 19 config-core prerequisite (2026-07-26)
+
+This append records the parent-reviewed acceptance evidence for four frozen
+slices on implementation HEAD
+`3863c2694583564964c36b6953dfec96046c9ab3`. The parent reviewed the exact Rust
+bytes later committed by this closure; those bytes were not edited during the
+closure. Their pre-commit SHA-256 values were:
+
+| Slice    | File                                                | SHA-256                                                            |
+| -------- | --------------------------------------------------- | ------------------------------------------------------------------ |
+| M13      | `crates/codegraph-store/tests/index_lease.rs`       | `41a929b7ab0048ec8b385e90d3e00cead515ac79e877d7321433c0e5ece5963f` |
+| M14      | `crates/codegraph-store/tests/store_state_gates.rs` | `8948cc04f30c2335cb335f85d3c8c78d122c5c30a52e3e86ddaa66f38f8f7a53` |
+| M18      | `crates/codegraph-watch/src/sync.rs`                | `81705e5be3da7abea26dfb58710e2e93108707a0cd5b3f6d294746fa6ab4b2b2` |
+| M18      | `crates/codegraph-watch/src/watcher.rs`             | `e6bc6c2ef64f4db000e3a8bf66f68a44ed1daddcb5beca4f3168c34cff91fb18` |
+| M19-core | `crates/codegraph-core/src/config.rs`               | `e600ad0a3908655814be82e0246f01cc43f11696b4bee16276b5f3fe268d27cb` |
+
+The frozen Revision 14 plan remained unchanged at SHA-256
+`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`.
+No manifest, lockfile, golden, schema, node-ID formula, `UPSTREAM.md`, or
+`KNOWN_DIFFS.md` byte is part of these slices.
+
+### M13 — lease owner and Store drop ordering
+
+`index_lease` now proves shared and exclusive parent/clone ownership through
+separate synchronized contender processes. Dropping a non-final parent or clone
+keeps incompatible contenders blocked; dropping the final owner admits a fresh
+contender immediately. A real finalized Current namespace additionally proves
+that a live read `Store` retains its shared lease through both SQLite handles and
+that `Store` closes those handles before its final retained lease is released.
+The Windows-only replacement branch is compile/injected-branch evidence; it was
+not executed on native Windows.
+
+Parent focused result: `index_lease` **13/13 passed**. The M13 target acceptance
+passed on these exact bytes.
+
+### M14 — read/status opens never migrate
+
+`store_state_gates` stages a physically current SQLite schema whose recorded
+schema version is deliberately migration-eligible, plus exact metadata canaries.
+Both `Store::open_for_read` and `Store::open_for_status` must accept the Current
+namespace without running migration or metadata repair. The acceptance oracle
+checks the complete namespace snapshot, absence of WAL/SHM creation, SQLite
+schema rows, schema-version rows, and project-metadata rows before, during, and
+after Store lifetime. Stamp-mismatch refusal is covered through the same
+nonmutation oracle. SQLite sidecars are derived losslessly by appending to the
+native `OsString`, never through `display()`.
+
+Parent focused result: `store_state_gates` **22/22 passed**. The M14 target
+acceptance passed on these exact bytes.
+
+### M18 — removed directories escalate to a pattern-aware full sync
+
+The watcher now preserves notify removal classification through the debounce
+loop. Explicit `RemoveKind::Folder` is a directory removal; Windows
+`RemoveKind::Any` regains directory semantics only when its normalized path is in
+the watcher-owned known-directory set captured at startup and extended when new
+directories are registered. This avoids guessing from a missing path or filename
+extension and keeps extensionless file removals distinct.
+
+A removed watched directory dominates its debounce burst and schedules exactly
+one full-project sync so every absent tracked descendant can be removed. Ignored
+directory removals remain ignored. The default full-sync closure passes the
+watcher's own `WatchOptions.include` and `WatchOptions.exclude` into the scan,
+rather than falling back to process-global patterns; sorted/deduplicated trigger
+paths remain attached to the outcome.
+
+Parent focused result: all **5 focused removal tests passed**; the complete
+`codegraph-watch` package passed **95 unit + 2 integration tests**.
+
+### M19-core — project-scoped config API prerequisite only
+
+This is deliberately **M19-core, not complete item 19**. It adds
+`Config::load_for_paths(cli_path, paths) -> Result<Arc<Config>>` with precedence
+explicit CLI path → `APP_CONFIG` → the resolved project's
+`IndexPaths::config_toml()` → defaults. The API does not consult legacy
+`.codegraph/config.toml`, the process working directory, or another project's
+paths, and it does not cache across projects. Its seven focused tests cover
+explicit/environment/project precedence, missing defaults, malformed current
+config, two-project isolation, intentional shared override, and rejection of
+legacy/CWD discovery. The transitional global `init_config`/`get_config` and
+legacy `Config::discover` remain for unmigrated callers.
+
+Parent focused result: `codegraph-core` **65/65 passed**, including
+`load_for_paths` **7/7 passed**. Production CLI, MCP, daemon, and watch config
+plumbing has **not** migrated to this API and remains the downstream portion of
+item 19.
+
+### Parent authoritative verification and environment limits
+
+The parent ran the focused suites above, workspace all-target check, workspace
+Clippy with `-D warnings`, and formatting on these exact Rust bytes. It then ran
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'`;
+the workspace-version gate, fmt-check, Clippy, complete workspace tests, and
+guardrail all passed, and the terminal printed `✅ All CI checks passed!`.
+
+Changed-file LSP diagnostics were attempted but the tool rejected this required
+external worktree with `LSP file path must be inside request cwd`. The clean
+locked Cargo check, Clippy, tests, and formatting are the diagnostics fallback;
+this ledger does not claim LSP-clean results. The platform-independent injected
+`RemoveKind::Any` branch tests cover Windows watcher classification logic, but no
+native Windows runtime validation was run and none is claimed.
+
+`Cargo.lock` remained byte-identical at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+This evidence was appended before the closure's final `make fmt` and authoritative
+locked CI run so no post-CI documentation edit can invalidate formatting.

From 00a755dbfa6016ed3888d642c497af7c13538044 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 15:01:09 +0800
Subject: [PATCH 31/91] fix(mcp): retain reader leases through requests

---
 crates/codegraph-cli/Cargo.toml               |   4 +
 crates/codegraph-cli/src/main.rs              |  67 +-
 crates/codegraph-cli/tests/lease_lifetime.rs  | 970 ++++++++++++++++++
 crates/codegraph-mcp/Cargo.toml               |   2 +-
 crates/codegraph-mcp/src/engine.rs            |  18 +-
 crates/codegraph-mcp/src/rmcp_handler.rs      |  95 +-
 crates/codegraph-mcp/src/server.rs            | 133 +--
 .../codegraph-mcp/tests/godot_honesty_mcp.rs  |   2 +
 crates/codegraph-mcp/tests/golden_mcp.rs      |   4 +
 .../tests/mcp_configured_root.rs              |  25 +-
 crates/codegraph-mcp/tests/reopen.rs          | 128 ++-
 crates/codegraph-mcp/tests/support/parity.rs  |   2 +
 crates/codegraph-store/Cargo.toml             |   6 +
 crates/codegraph-store/src/index_lease.rs     |  56 +-
 crates/codegraph-store/src/lib.rs             |   2 +
 crates/codegraph-store/src/test_support.rs    |  67 ++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  61 ++
 17 files changed, 1422 insertions(+), 220 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/lease_lifetime.rs
 create mode 100644 crates/codegraph-store/src/test_support.rs

diff --git a/crates/codegraph-cli/Cargo.toml b/crates/codegraph-cli/Cargo.toml
index 1a3292c..b6a6add 100644
--- a/crates/codegraph-cli/Cargo.toml
+++ b/crates/codegraph-cli/Cargo.toml
@@ -44,6 +44,10 @@ time = { workspace = true }
 
 [dev-dependencies]
 codegraph-bench = { path = "../codegraph-bench" }
+# Feature-unifies the Store's lease barrier into `CARGO_BIN_EXE_codegraph` only
+# while this package's test targets are built. A normal binary build uses the
+# feature-free dependency declared above.
+codegraph-store = { path = "../codegraph-store", features = ["test-hooks"] }
 rstest = { workspace = true }
 assert_fs = { workspace = true }
 assert_cmd = { workspace = true }
diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 9cf5cc0..f7e980e 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1272,7 +1272,6 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let index_root = resolved.current_root().to_path_buf();
     let db = resolved.current_db();
     let db_exists = db.is_file();
-    let extraction_status = Store::extraction_status(&resolved);
     let legacy_index_paths = resolved
         .legacy_roots()
         .iter()
@@ -1284,7 +1283,47 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
     let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project);
     let daemon_socket_path = codegraph_daemon::recorded_socket_path(&project);
     let daemon_log_path = codegraph_daemon::daemon_log_path(&project);
-    if !is_initialized(&project) {
+    let status_open = Store::open_for_status(
+        &resolved,
+        std::time::Instant::now() + STATUS_LEASE_TIMEOUT,
+        || false,
+    )?;
+    if status_open.rebuilding {
+        if json_output {
+            print_json(&json!({
+                // The exclusive owner may be between lifecycle publications.
+                // DB presence alone cannot corroborate a readable Current index.
+                "initialized": false,
+                "version": VERSION,
+                "projectPath": project,
+                "indexPath": index_root,
+                "lastIndexed": null,
+                "rebuilding": true,
+                "dbPath": db,
+                "dbExists": db_exists,
+                "extractionStatus": null,
+                "extractionStatusDetail": "rebuilding",
+                "legacyIndexPresent": legacy_index_present,
+                "legacyIndexPaths": legacy_index_paths,
+                "daemonRunning": daemon_running,
+                "daemonPidPath": daemon_pid_path,
+                "daemonSocketPath": daemon_socket_path,
+                "daemonLogPath": daemon_log_path,
+            }))?;
+        } else {
+            println!("\nCodeGraph Status\n");
+            println!("Project: {}", project.display());
+            println!("DB Path: {}", db.display());
+            println!("State:   rebuilding");
+        }
+        return Ok(());
+    }
+    let extraction_status = status_open
+        .status
+        .clone()
+        .expect("a non-busy status probe always classifies the namespace");
+    let store = status_open.into_store();
+    if store.is_none() {
         if json_output {
             print_json(&json!({
                 "initialized": false,
@@ -1324,7 +1363,7 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
         return Ok(());
     }
 
-    let store = open_store(&project)?;
+    let store = store.expect("Current status retains its corroborated read store");
     let counts = store.counts()?;
     let nodes_by_kind = store.node_counts_by_kind()?;
     let files_by_language = store.file_counts_by_language()?;
@@ -3509,6 +3548,8 @@ struct BulkIndexPragmaGuard {
 /// Bounded wall-clock budget for acquiring the one outer exclusive lease. Never a
 /// blocking wait: `IndexLease` polls `try_lock` against this monotonic deadline.
 const REBUILD_LEASE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+const READ_LEASE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+const STATUS_LEASE_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(100);
 
 impl BulkIndexPragmaGuard {
     fn begin(
@@ -4338,7 +4379,13 @@ fn exact_or_top_matches<'a>(matches: &'a [Node], symbol: &str) -> Vec<&'a Node>
 }
 
 fn open_store(project: &Path) -> Result<Store> {
-    Store::open(&db_path(project)?).map_err(Into::into)
+    let paths = index_paths(project)?;
+    Store::open_for_read(
+        &paths,
+        std::time::Instant::now() + READ_LEASE_TIMEOUT,
+        || false,
+    )
+    .map_err(Into::into)
 }
 
 /// Whether `project` has a current-namespace index DB. An unsafe/aliased
@@ -4544,6 +4591,18 @@ fn latest_indexed_at(store: &Store) -> Result<Option<i64>> {
 }
 
 fn journal_mode(store: &Store) -> Result<String> {
+    // A state-gated reader executes queries against a private deserialized
+    // in-memory image so it cannot create `-wal`/`-shm` sidecars. Its PRAGMA
+    // therefore reports `memory`, not the authoritative main database's mode.
+    // While the Store retains its shared lease, inspect SQLite's two format
+    // bytes instead: 2/2 is the durable WAL marker. Fall back to PRAGMA for
+    // legacy/non-WAL stores where the header cannot distinguish every rollback
+    // journal variant.
+    let mut header = [0_u8; 20];
+    fs::File::open(store.path())?.read_exact(&mut header)?;
+    if header.starts_with(b"SQLite format 3\0") && header[18] == 2 && header[19] == 2 {
+        return Ok("wal".to_string());
+    }
     store
         .connection()
         .query_row("PRAGMA journal_mode", [], |row| row.get(0))
diff --git a/crates/codegraph-cli/tests/lease_lifetime.rs b/crates/codegraph-cli/tests/lease_lifetime.rs
new file mode 100644
index 0000000..9e3ad0c
--- /dev/null
+++ b/crates/codegraph-cli/tests/lease_lifetime.rs
@@ -0,0 +1,970 @@
+//! Deterministic acceptance tests for v2 reader/writer lease topology.
+
+use std::fs;
+use std::io::{Cursor, Read, Write};
+use std::net::{SocketAddr, TcpListener, TcpStream};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, Output, Stdio};
+use std::sync::{Arc, Mutex, MutexGuard, OnceLock, mpsc};
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::{IndexLease, IndexLeaseError, Store, StoreError};
+
+const CHILD_ACTION: &str = "CODEGRAPH_LEASE_LIFETIME_CHILD_ACTION";
+const CHILD_PROJECT: &str = "CODEGRAPH_LEASE_LIFETIME_CHILD_PROJECT";
+const BARRIER_ADDR: &str = "CODEGRAPH_TEST_LEASE_BARRIER_ADDR";
+const BARRIER_MODE: &str = "CODEGRAPH_TEST_LEASE_BARRIER_MODE";
+const WAIT: Duration = Duration::from_secs(10);
+const PROBE_WAIT: Duration = Duration::from_millis(100);
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn copy_tree(source: &Path, target: &Path) {
+    fs::create_dir_all(target).expect("create fixture target");
+    for entry in fs::read_dir(source).expect("read fixture source") {
+        let entry = entry.expect("fixture entry");
+        let destination = target.join(entry.file_name());
+        if entry.path().is_dir() {
+            copy_tree(&entry.path(), &destination);
+        } else {
+            fs::copy(entry.path(), destination).expect("copy fixture file");
+        }
+    }
+}
+
+struct TestProject(PathBuf);
+
+impl TestProject {
+    fn indexed(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-lease-lifetime-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock")
+                .as_nanos()
+        ));
+        copy_tree(
+            &workspace_root().join("crates/codegraph-bench/fixtures/mini"),
+            &path,
+        );
+        let output = Command::new(bin())
+            .args(["init", path.to_str().expect("utf8 fixture path")])
+            .env("CODEGRAPH_NO_DAEMON", "1")
+            .output()
+            .expect("run fixture init");
+        assert!(
+            output.status.success(),
+            "fixture init failed: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(self.path(), None).expect("fixture IndexPaths")
+    }
+
+    fn http_registry_dir(&self) -> PathBuf {
+        self.path().join("http-registry")
+    }
+}
+
+impl Drop for TestProject {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+struct LeaseBarrier {
+    address: SocketAddr,
+    arrived: mpsc::Receiver<(u8, TcpStream)>,
+}
+
+impl LeaseBarrier {
+    fn new() -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind lease barrier");
+        let address = listener.local_addr().expect("lease barrier address");
+        let (arrived_tx, arrived_rx) = mpsc::channel();
+        std::thread::spawn(move || {
+            let Ok((mut stream, _)) = listener.accept() else {
+                return;
+            };
+            let _ = stream.set_read_timeout(Some(WAIT));
+            let mut marker = [0_u8; 1];
+            if stream.read_exact(&mut marker).is_ok() {
+                // The receiver can be gone during failure cleanup. That is not a
+                // listener-thread failure and must not add a secondary panic.
+                let _ = arrived_tx.send((marker[0], stream));
+            }
+        });
+        Self {
+            address,
+            arrived: arrived_rx,
+        }
+    }
+
+    fn configure(&self, command: &mut Command, mode: &str) {
+        command
+            .env(BARRIER_ADDR, self.address.to_string())
+            .env(BARRIER_MODE, mode);
+    }
+
+    fn child_command(&self, mode: &str) -> Command {
+        let mut command = Command::new(bin());
+        self.configure(&mut command, mode);
+        command
+    }
+
+    fn wait(&self, expected: u8) -> TcpStream {
+        match self.arrived.recv_timeout(WAIT) {
+            Ok((actual, stream)) => {
+                assert_eq!(actual, expected, "wrong lease mode reached barrier");
+                stream
+            }
+            Err(error) => {
+                // Unblock the bounded listener before failing. This cancellation
+                // connection is harness cleanup, never lease-order evidence.
+                if let Ok(mut cancel) = TcpStream::connect(self.address) {
+                    let _ = cancel.write_all(b"C");
+                }
+                panic!("lease barrier was not reached before its finite deadline: {error}");
+            }
+        }
+    }
+}
+
+struct ChildGuard(Option<Child>);
+
+impl ChildGuard {
+    fn new(child: Child) -> Self {
+        Self(Some(child))
+    }
+
+    fn child_mut(&mut self) -> &mut Child {
+        self.0.as_mut().expect("child still owned")
+    }
+
+    fn finish(mut self) -> Output {
+        wait_child(self.child_mut());
+        self.0
+            .take()
+            .expect("child still owned")
+            .wait_with_output()
+            .expect("collect child output")
+    }
+}
+
+impl Drop for ChildGuard {
+    fn drop(&mut self) {
+        if let Some(child) = self.0.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+fn wait_child(child: &mut Child) -> std::process::ExitStatus {
+    let deadline = Instant::now() + WAIT;
+    loop {
+        if let Some(status) = child.try_wait().expect("poll child status") {
+            return status;
+        }
+        assert!(Instant::now() < deadline, "child exceeded finite deadline");
+        std::thread::park_timeout(Duration::from_millis(5));
+    }
+}
+
+fn run_probe(project: &Path, action: &str) -> String {
+    let output = Command::new(std::env::current_exe().expect("current test binary"))
+        .arg("--exact")
+        .arg("lease_lifetime_child_process")
+        .arg("--nocapture")
+        .env(CHILD_ACTION, action)
+        .env(CHILD_PROJECT, project)
+        .output()
+        .expect("run lease probe child");
+    assert!(
+        output.status.success(),
+        "lease probe child failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    String::from_utf8(output.stdout)
+        .expect("probe utf8")
+        .lines()
+        .find(|line| matches!(*line, "ACQUIRED" | "TIMED_OUT"))
+        .expect("probe result sentinel")
+        .to_string()
+}
+
+fn assert_writer_blocked(project: &Path, context: &str) {
+    assert_eq!(
+        run_probe(project, "probe-exclusive"),
+        "TIMED_OUT",
+        "{context} must retain its shared lease through final result production"
+    );
+}
+
+fn mcp_frames(project: &Path) -> Vec<u8> {
+    let project = project.to_str().expect("utf8 project path");
+    format!(
+        "{}\n{}\n{}\n",
+        serde_json::json!({
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"lease-test","version":"0"}}
+        }),
+        serde_json::json!({"jsonrpc":"2.0","method":"notifications/initialized"}),
+        serde_json::json!({
+            "jsonrpc":"2.0", "id":2, "method":"tools/call",
+            "params":{"name":"codegraph_search","arguments":{"query":"add","projectPath":project}}
+        }),
+    )
+    .into_bytes()
+}
+
+fn spawn_stdio_reader(project: &Path, barrier: &LeaseBarrier) -> ChildGuard {
+    let mut command = barrier.child_command("shared");
+    command
+        .args(["serve", "--mcp", "--path"])
+        .arg(project)
+        .arg("--no-watch")
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = command.spawn().expect("spawn stdio MCP reader");
+    child
+        .stdin
+        .take()
+        .expect("stdio MCP stdin")
+        .write_all(&mcp_frames(project))
+        .expect("write stdio MCP frames");
+    ChildGuard::new(child)
+}
+
+fn assert_successful_mcp_output(output: &Output, context: &str) {
+    assert!(
+        output.status.success(),
+        "{context} failed: stdout={} stderr={}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("\"id\":2") && stdout.contains("add"),
+        "{context} did not return the tool result: {stdout}"
+    );
+}
+
+fn unused_loopback_addr() -> SocketAddr {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("reserve HTTP port");
+    let address = listener.local_addr().expect("reserved HTTP address");
+    drop(listener);
+    address
+}
+
+fn connect_http(address: SocketAddr) -> TcpStream {
+    let deadline = Instant::now() + WAIT;
+    loop {
+        match TcpStream::connect_timeout(&address, Duration::from_millis(100)) {
+            Ok(stream) => return stream,
+            Err(error) if Instant::now() < deadline => {
+                let _ = error;
+                std::thread::park_timeout(Duration::from_millis(5));
+            }
+            Err(error) => panic!("HTTP server did not bind before deadline: {error}"),
+        }
+    }
+}
+
+fn send_http_tool_call(stream: &mut TcpStream, address: SocketAddr, project: &Path) {
+    stream
+        .set_read_timeout(Some(WAIT))
+        .expect("set HTTP read timeout");
+    stream
+        .set_write_timeout(Some(WAIT))
+        .expect("set HTTP write timeout");
+    let body = serde_json::json!({
+        "jsonrpc":"2.0", "id":7, "method":"tools/call",
+        "params":{"name":"codegraph_search","arguments":{"query":"add","projectPath":project}}
+    })
+    .to_string();
+    write!(
+        stream,
+        "POST /mcp HTTP/1.1\r\nHost: {address}\r\nContent-Type: application/json\r\nAccept: application/json, text/event-stream\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+        body.len()
+    )
+    .expect("send HTTP MCP request");
+    stream.flush().expect("flush HTTP MCP request");
+}
+
+fn wait_for_daemon(project: &Path) {
+    let deadline = Instant::now() + WAIT;
+    loop {
+        let socket = codegraph_daemon::recorded_socket_path(project);
+        if codegraph_daemon::attach_to_daemon(&socket).is_ok() {
+            return;
+        }
+        assert!(Instant::now() < deadline, "daemon did not become ready");
+        std::thread::park_timeout(Duration::from_millis(5));
+    }
+}
+
+#[derive(Clone)]
+struct SharedSink(Arc<Mutex<Vec<u8>>>);
+
+impl Write for SharedSink {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        self.0
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .extend_from_slice(buf);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
+
+fn test_serial_guard() -> MutexGuard<'static, ()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+struct LeaseHookEnv {
+    old_addr: Option<std::ffi::OsString>,
+    old_mode: Option<std::ffi::OsString>,
+}
+
+impl LeaseHookEnv {
+    fn exclusive(barrier: &LeaseBarrier) -> Self {
+        let guard = Self {
+            old_addr: std::env::var_os(BARRIER_ADDR),
+            old_mode: std::env::var_os(BARRIER_MODE),
+        };
+        // SAFETY: both named tests are serialized by `test_serial_guard`; child
+        // processes receive explicit env values and no other test mutates them.
+        unsafe {
+            std::env::set_var(BARRIER_ADDR, barrier.address.to_string());
+            std::env::set_var(BARRIER_MODE, "exclusive");
+        }
+        guard
+    }
+}
+
+impl Drop for LeaseHookEnv {
+    fn drop(&mut self) {
+        // SAFETY: serialized by `test_serial_guard`, as above.
+        unsafe {
+            match self.old_addr.take() {
+                Some(value) => std::env::set_var(BARRIER_ADDR, value),
+                None => std::env::remove_var(BARRIER_ADDR),
+            }
+            match self.old_mode.take() {
+                Some(value) => std::env::set_var(BARRIER_MODE, value),
+                None => std::env::remove_var(BARRIER_MODE),
+            }
+        }
+    }
+}
+
+fn existing_metadata(path: &Path, operation: &str) -> fs::Metadata {
+    fs::symlink_metadata(path)
+        .unwrap_or_else(|error| panic!("{operation} {} failed: {error}", path.display()))
+}
+
+fn is_regular_non_alias(metadata: &fs::Metadata) -> bool {
+    if !metadata.file_type().is_file() || metadata.file_type().is_symlink() {
+        return false;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
+        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT == 0;
+    }
+    #[cfg(not(windows))]
+    true
+}
+
+#[cfg(windows)]
+fn open_sqlite_artifact(path: &Path) -> std::io::Result<fs::File> {
+    use std::os::windows::fs::OpenOptionsExt;
+    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+    fs::OpenOptions::new()
+        .read(true)
+        .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT)
+        .open(path)
+}
+
+#[cfg(not(windows))]
+fn open_sqlite_artifact(path: &Path) -> std::io::Result<fs::File> {
+    fs::File::open(path)
+}
+
+#[cfg(unix)]
+fn assert_same_file_identity(
+    path: &Path,
+    expected: &fs::Metadata,
+    actual: &fs::Metadata,
+    operation: &str,
+) {
+    use std::os::unix::fs::MetadataExt;
+
+    assert_eq!(
+        (actual.dev(), actual.ino()),
+        (expected.dev(), expected.ino()),
+        "{operation} changed the fixed SQLite artifact {}",
+        path.display()
+    );
+}
+
+#[cfg(windows)]
+fn assert_same_file_identity(
+    path: &Path,
+    expected: &fs::Metadata,
+    actual: &fs::Metadata,
+    operation: &str,
+) {
+    use std::os::windows::fs::MetadataExt;
+
+    assert!(
+        expected.file_attributes() == actual.file_attributes()
+            && expected.creation_time() == actual.creation_time()
+            && expected.last_write_time() == actual.last_write_time()
+            && expected.file_size() == actual.file_size(),
+        "{operation} changed the fixed SQLite artifact {}",
+        path.display()
+    );
+}
+
+#[cfg(not(any(unix, windows)))]
+fn assert_same_file_identity(
+    path: &Path,
+    expected: &fs::Metadata,
+    actual: &fs::Metadata,
+    operation: &str,
+) {
+    assert_eq!(
+        expected.len(),
+        actual.len(),
+        "{operation} changed the fixed SQLite artifact {}",
+        path.display()
+    );
+}
+
+#[cfg(windows)]
+fn windows_file_identity(file: &fs::File) -> std::io::Result<(u64, [u8; 16])> {
+    use std::os::windows::io::AsRawHandle;
+
+    const FILE_ID_INFO_CLASS: i32 = 18;
+    #[repr(C)]
+    struct FileIdInfo {
+        volume_serial_number: u64,
+        file_id: [u8; 16],
+    }
+    #[link(name = "kernel32")]
+    unsafe extern "system" {
+        fn GetFileInformationByHandleEx(
+            h_file: isize,
+            file_information_class: i32,
+            lp_file_information: *mut core::ffi::c_void,
+            dw_buffer_size: u32,
+        ) -> i32;
+    }
+
+    let mut info = FileIdInfo {
+        volume_serial_number: 0,
+        file_id: [0; 16],
+    };
+    // SAFETY: `file` owns a live handle and `info` is the exact writable
+    // FILE_ID_INFO layout required by FileIdInfo.
+    let ok = unsafe {
+        GetFileInformationByHandleEx(
+            file.as_raw_handle() as isize,
+            FILE_ID_INFO_CLASS,
+            (&mut info as *mut FileIdInfo).cast(),
+            core::mem::size_of::<FileIdInfo>() as u32,
+        )
+    };
+    if ok == 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok((info.volume_serial_number, info.file_id))
+}
+
+#[cfg(unix)]
+fn assert_path_still_names_opened_file(path: &Path, opened: &fs::File) {
+    let opened_metadata = opened.metadata().unwrap_or_else(|error| {
+        panic!(
+            "inspect opened SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    let path_metadata = existing_metadata(path, "reinspect SQLite artifact");
+    assert!(
+        is_regular_non_alias(&path_metadata),
+        "SQLite artifact {} changed to an alias or other entry type during snapshot",
+        path.display()
+    );
+    assert_same_file_identity(path, &opened_metadata, &path_metadata, "reading artifact");
+}
+
+#[cfg(windows)]
+fn assert_path_still_names_opened_file(path: &Path, opened: &fs::File) {
+    let path_file = open_sqlite_artifact(path).unwrap_or_else(|error| {
+        panic!(
+            "reopen fixed SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    let path_metadata = path_file.metadata().unwrap_or_else(|error| {
+        panic!(
+            "reinspect fixed SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    assert!(
+        is_regular_non_alias(&path_metadata),
+        "SQLite artifact {} changed to an alias or other entry type during snapshot",
+        path.display()
+    );
+    let opened_identity = windows_file_identity(opened).unwrap_or_else(|error| {
+        panic!(
+            "identify opened SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    let path_identity = windows_file_identity(&path_file).unwrap_or_else(|error| {
+        panic!(
+            "identify fixed SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    assert_eq!(
+        opened_identity,
+        path_identity,
+        "fixed SQLite artifact {} changed identity during snapshot",
+        path.display()
+    );
+}
+
+#[cfg(not(any(unix, windows)))]
+fn assert_path_still_names_opened_file(path: &Path, opened: &fs::File) {
+    let opened_metadata = opened.metadata().unwrap_or_else(|error| {
+        panic!(
+            "inspect opened SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    let path_metadata = existing_metadata(path, "reinspect SQLite artifact");
+    assert!(
+        is_regular_non_alias(&path_metadata),
+        "SQLite artifact {} changed to an alias or other entry type during snapshot",
+        path.display()
+    );
+    assert_same_file_identity(path, &opened_metadata, &path_metadata, "reading artifact");
+}
+
+fn sqlite_artifact_bytes(path: &Path) -> Option<Vec<u8>> {
+    let initial = match fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return None,
+        Err(error) => panic!("inspect SQLite artifact {} failed: {error}", path.display()),
+    };
+    assert!(
+        is_regular_non_alias(&initial),
+        "SQLite artifact {} must be a regular file, not an alias or other entry type",
+        path.display()
+    );
+
+    let mut file = open_sqlite_artifact(path)
+        .unwrap_or_else(|error| panic!("open SQLite artifact {} failed: {error}", path.display()));
+    let opened = file.metadata().unwrap_or_else(|error| {
+        panic!(
+            "inspect opened SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    assert!(
+        is_regular_non_alias(&opened),
+        "opened SQLite artifact {} is not a regular file",
+        path.display()
+    );
+    assert_same_file_identity(path, &initial, &opened, "opening artifact");
+
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes)
+        .unwrap_or_else(|error| panic!("read SQLite artifact {} failed: {error}", path.display()));
+    let opened_after = file.metadata().unwrap_or_else(|error| {
+        panic!(
+            "reinspect opened SQLite artifact {} failed: {error}",
+            path.display()
+        )
+    });
+    assert_same_file_identity(path, &opened, &opened_after, "reading artifact");
+
+    assert_path_still_names_opened_file(path, &file);
+    let bytes_len = u64::try_from(bytes.len()).expect("SQLite artifact length fits u64");
+    assert_eq!(
+        opened_after.len(),
+        bytes_len,
+        "SQLite artifact {} changed length during snapshot",
+        path.display()
+    );
+    assert_eq!(
+        opened.len(),
+        bytes_len,
+        "opened SQLite artifact {} changed length during snapshot",
+        path.display()
+    );
+    Some(bytes)
+}
+
+fn sqlite_snapshot(paths: &IndexPaths) -> Vec<(PathBuf, Option<Vec<u8>>)> {
+    let db = paths.current_db();
+    let sidecar = |suffix: &str| {
+        let mut path = db.as_os_str().to_os_string();
+        path.push(suffix);
+        PathBuf::from(path)
+    };
+    [db.clone(), sidecar("-wal"), sidecar("-shm")]
+        .into_iter()
+        .map(|path| (path.clone(), sqlite_artifact_bytes(&path)))
+        .collect()
+}
+
+fn assert_sqlite_snapshot_unchanged(
+    before: &[(PathBuf, Option<Vec<u8>>)],
+    after: &[(PathBuf, Option<Vec<u8>>)],
+    context: &str,
+) {
+    assert_eq!(before.len(), after.len(), "{context}: artifact set changed");
+    for ((before_path, before_bytes), (after_path, after_bytes)) in before.iter().zip(after) {
+        assert_eq!(before_path, after_path, "{context}: artifact path changed");
+        assert_eq!(
+            before_bytes.is_some(),
+            after_bytes.is_some(),
+            "{context}: artifact presence changed at {}",
+            before_path.display()
+        );
+        assert!(
+            before_bytes == after_bytes,
+            "{context}: artifact bytes changed at {}",
+            before_path.display()
+        );
+    }
+}
+
+#[test]
+fn sqlite_snapshot_rejects_non_regular_artifact() {
+    let project = TestProject::indexed("snapshot-non-regular");
+    let paths = project.paths();
+    let mut wal = paths.current_db().as_os_str().to_os_string();
+    wal.push("-wal");
+    let wal = PathBuf::from(wal);
+    fs::create_dir(&wal).expect("stage non-regular SQLite artifact");
+
+    let result = std::panic::catch_unwind(|| sqlite_snapshot(&paths));
+    assert!(
+        result.is_err(),
+        "the nonmutation oracle must fail closed on a non-regular artifact"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn sqlite_snapshot_rejects_alias_artifact_without_following_it() {
+    use std::os::unix::fs::symlink;
+
+    let project = TestProject::indexed("snapshot-alias");
+    let paths = project.paths();
+    let mut wal = paths.current_db().as_os_str().to_os_string();
+    wal.push("-wal");
+    let wal = PathBuf::from(wal);
+    let outside = project.path().join("outside-sentinel");
+    fs::write(&outside, b"outside").expect("stage alias target");
+    symlink(&outside, &wal).expect("stage SQLite artifact alias");
+
+    let result = std::panic::catch_unwind(|| sqlite_snapshot(&paths));
+    assert!(
+        result.is_err(),
+        "the nonmutation oracle must reject aliases without reading their targets"
+    );
+    assert_eq!(
+        fs::read(&outside).expect("read untouched alias target"),
+        b"outside"
+    );
+}
+
+#[test]
+fn reader_lease_spans_stamp_check_through_last_row() {
+    let _serial = test_serial_guard();
+    let project = TestProject::indexed("reader-topologies");
+
+    // CLI query.
+    {
+        let barrier = LeaseBarrier::new();
+        let mut command = barrier.child_command("shared");
+        command
+            .args(["query", "add", "--path"])
+            .arg(project.path())
+            .arg("--json")
+            .env("CODEGRAPH_NO_DAEMON", "1")
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+        let reader = ChildGuard::new(command.spawn().expect("spawn CLI reader"));
+        let mut release = barrier.wait(b'S');
+        assert_writer_blocked(project.path(), "CLI query");
+        release.write_all(b"R").expect("release CLI reader");
+        let output = reader.finish();
+        assert!(output.status.success(), "CLI reader failed after release");
+    }
+
+    // Direct stdio MCP.
+    {
+        let barrier = LeaseBarrier::new();
+        let reader = spawn_stdio_reader(project.path(), &barrier);
+        let mut release = barrier.wait(b'S');
+        assert_writer_blocked(project.path(), "stdio MCP");
+        release.write_all(b"R").expect("release stdio MCP reader");
+        assert_successful_mcp_output(&reader.finish(), "stdio MCP reader");
+    }
+
+    // Daemon session reached through the real local-handshake proxy.
+    {
+        let barrier = LeaseBarrier::new();
+        let mut daemon_command = Command::new(bin());
+        daemon_command
+            .args(["serve", "--mcp", "--path"])
+            .arg(project.path())
+            .arg("--no-watch")
+            .env(codegraph_daemon::CODEGRAPH_DAEMON_INTERNAL, "1")
+            .env("CODEGRAPH_NO_WATCH", "1")
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::piped());
+        barrier.configure(&mut daemon_command, "shared");
+        let mut daemon = ChildGuard::new(daemon_command.spawn().expect("spawn daemon reader"));
+        wait_for_daemon(project.path());
+
+        let output = Arc::new(Mutex::new(Vec::new()));
+        let sink = SharedSink(Arc::clone(&output));
+        let socket = codegraph_daemon::recorded_socket_path(project.path());
+        let frames = mcp_frames(project.path());
+        let (done_tx, done_rx) = mpsc::channel();
+        std::thread::spawn(move || {
+            let result = codegraph_daemon::run_proxy(
+                &socket,
+                Some(codegraph_daemon::current_ppid()),
+                Cursor::new(frames),
+                sink,
+            );
+            let _ = done_tx.send(result);
+        });
+
+        let mut release = barrier.wait(b'S');
+        assert_writer_blocked(project.path(), "daemon proxy MCP");
+        release
+            .write_all(b"R")
+            .expect("release daemon proxy reader");
+        let proxy = done_rx
+            .recv_timeout(WAIT)
+            .expect("proxy completed before deadline")
+            .expect("proxy completed successfully");
+        assert_eq!(proxy, codegraph_daemon::ProxyOutcome::Proxied);
+        let proxy_output = String::from_utf8(
+            output
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .clone(),
+        )
+        .expect("proxy output utf8");
+        assert!(
+            proxy_output.contains("\"id\":2"),
+            "proxy output: {proxy_output}"
+        );
+        let _ = daemon.child_mut().kill();
+        let _ = daemon.child_mut().wait();
+    }
+
+    // Streamable HTTP MCP.
+    {
+        let barrier = LeaseBarrier::new();
+        let address = unused_loopback_addr();
+        let registry_dir = project.http_registry_dir();
+        assert!(
+            registry_dir.starts_with(project.path()),
+            "HTTP registry must be owned by the fixture"
+        );
+        let mut command = barrier.child_command("shared");
+        command
+            .args(["serve", "--http", "--path"])
+            .arg(project.path())
+            .arg("--http-addr")
+            .arg(address.to_string())
+            .env("CODEGRAPH_HTTP_REGISTRY_DIR", &registry_dir)
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+        let mut reader = ChildGuard::new(command.spawn().expect("spawn HTTP MCP reader"));
+        let mut stream = connect_http(address);
+        send_http_tool_call(&mut stream, address, project.path());
+        let mut release = barrier.wait(b'S');
+        assert_writer_blocked(project.path(), "HTTP MCP");
+        release.write_all(b"R").expect("release HTTP MCP reader");
+        let mut response = String::new();
+        stream
+            .read_to_string(&mut response)
+            .expect("read HTTP MCP response");
+        assert!(response.contains("200 OK"), "HTTP response: {response}");
+        assert!(response.contains("add"), "HTTP tool response: {response}");
+        let _ = reader.child_mut().kill();
+        let _ = reader.child_mut().wait();
+        fs::remove_dir_all(&registry_dir).expect("remove fixture-owned HTTP registry");
+        match fs::symlink_metadata(&registry_dir) {
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Ok(_) => panic!("fixture-owned HTTP registry survived explicit cleanup"),
+            Err(error) => panic!("inspect cleaned HTTP registry failed: {error}"),
+        }
+    }
+
+    // Status uses the same retained shared lease as ordinary reads.
+    {
+        let barrier = LeaseBarrier::new();
+        let mut command = barrier.child_command("shared");
+        command
+            .args(["status", "--json"])
+            .arg(project.path())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+        let reader = ChildGuard::new(command.spawn().expect("spawn status reader"));
+        let mut release = barrier.wait(b'S');
+        assert_writer_blocked(project.path(), "status");
+        release.write_all(b"R").expect("release status reader");
+        let output = reader.finish();
+        assert!(output.status.success(), "status failed after release");
+        let value: serde_json::Value =
+            serde_json::from_slice(&output.stdout).expect("status JSON response");
+        assert_eq!(value["initialized"], serde_json::Value::Bool(true));
+    }
+}
+
+#[test]
+fn writer_blocks_new_reads_without_sqlite_open() {
+    let _serial = test_serial_guard();
+    let project = TestProject::indexed("writer-watcher");
+    let paths = project.paths();
+    let source = project.path().join("src/math.ts");
+    fs::write(
+        &source,
+        "export function add(a: number, b: number) { return a + b + 1; }\n",
+    )
+    .expect("change watched source");
+
+    let barrier = LeaseBarrier::new();
+    let _env = LeaseHookEnv::exclusive(&barrier);
+    let root = project.path().to_path_buf();
+    let db = paths.current_db();
+    let changed = source.clone();
+    let (done_tx, done_rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let result = codegraph_watch::sync_changed_paths(&root, &db, [changed]);
+        let _ = done_tx.send(result);
+    });
+
+    // The watcher acknowledged exclusive ownership immediately after the kernel
+    // lock and before Store::open_for_write can open SQLite.
+    let mut release = barrier.wait(b'X');
+    let before = sqlite_snapshot(&paths);
+    assert_eq!(
+        run_probe(project.path(), "probe-read"),
+        "TIMED_OUT",
+        "a new reader must not pass a held watcher writer"
+    );
+    let after_blocked_read = sqlite_snapshot(&paths);
+    assert_sqlite_snapshot_unchanged(
+        &before,
+        &after_blocked_read,
+        "the blocked reader must not open or mutate SQLite artifacts",
+    );
+
+    // Status contention is data, not an SQLite open or an error.
+    let output = Command::new(bin())
+        .args(["status", "--json"])
+        .arg(project.path())
+        .output()
+        .expect("run busy status");
+    assert!(output.status.success(), "busy status must succeed");
+    let status: serde_json::Value =
+        serde_json::from_slice(&output.stdout).expect("busy status JSON");
+    assert_eq!(status["rebuilding"], serde_json::Value::Bool(true));
+    assert_eq!(
+        status["initialized"],
+        serde_json::Value::Bool(false),
+        "busy status cannot corroborate a readable Current index"
+    );
+    let after_busy_status = sqlite_snapshot(&paths);
+    assert_sqlite_snapshot_unchanged(
+        &before,
+        &after_busy_status,
+        "busy status must not open or mutate SQLite artifacts",
+    );
+
+    release.write_all(b"R").expect("release watcher writer");
+    done_rx
+        .recv_timeout(WAIT)
+        .expect("watcher completed before deadline")
+        .expect("watcher sync succeeded after release");
+}
+
+#[test]
+fn lease_lifetime_child_process() {
+    let Ok(action) = std::env::var(CHILD_ACTION) else {
+        return;
+    };
+    let project = PathBuf::from(std::env::var_os(CHILD_PROJECT).expect("child project env"));
+    let paths = IndexPaths::resolve(&project, None).expect("child IndexPaths");
+    match action.as_str() {
+        "probe-exclusive" => match IndexLease::acquire_exclusive_existing(
+            &paths,
+            Instant::now() + PROBE_WAIT,
+            || false,
+        ) {
+            Ok(lease) => {
+                println!("ACQUIRED");
+                drop(lease);
+            }
+            Err(IndexLeaseError::TimedOut { .. }) => println!("TIMED_OUT"),
+            Err(error) => panic!("unexpected exclusive probe error: {error}"),
+        },
+        "probe-read" => match Store::open_for_read(&paths, Instant::now() + PROBE_WAIT, || false) {
+            Ok(store) => {
+                println!("ACQUIRED");
+                drop(store);
+            }
+            Err(StoreError::Lease(IndexLeaseError::TimedOut { .. })) => println!("TIMED_OUT"),
+            Err(error) => panic!("unexpected read probe error: {error}"),
+        },
+        other => panic!("unknown lease-lifetime child action {other}"),
+    }
+}
diff --git a/crates/codegraph-mcp/Cargo.toml b/crates/codegraph-mcp/Cargo.toml
index 26feebb..060c05b 100644
--- a/crates/codegraph-mcp/Cargo.toml
+++ b/crates/codegraph-mcp/Cargo.toml
@@ -52,7 +52,7 @@ tokio-util = { version = "0.7" }
 # dependency of an integration test binary, so a Cargo feature (auto-enabled for
 # this crate's own dev/test builds via the dev-dependency self-reference below)
 # is the only reliable gate. NEVER enabled in the shipped binary.
-test-hooks = []
+test-hooks = ["codegraph-store/test-hooks"]
 
 [dev-dependencies]
 # Self-reference with `test-hooks` so the seams above are compiled into the lib
diff --git a/crates/codegraph-mcp/src/engine.rs b/crates/codegraph-mcp/src/engine.rs
index b8272a2..1c9b3be 100644
--- a/crates/codegraph-mcp/src/engine.rs
+++ b/crates/codegraph-mcp/src/engine.rs
@@ -9,6 +9,7 @@
 use std::collections::{HashMap, HashSet};
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
 
 use codegraph_core::types::{EdgeKind, FileRecord, Node, NodeKind};
 use codegraph_graph::graph::{GodotReach, GraphTraverser, NodeEdge};
@@ -59,27 +60,28 @@ const TYPE_KINDS: [NodeKind; 7] = [
 /// for forward-compatibility, but extraction-widening is DEFERRED per the plan).
 const SIG_EDGE_KINDS: [EdgeKind; 3] = [EdgeKind::References, EdgeKind::TypeOf, EdgeKind::Returns];
 
-/// Holds an opened project store. One engine per project path; the server keeps
-/// a cache keyed by resolved project path (mirrors `ToolHandler.projectCache`,
-/// `tools.ts:591`).
+/// Holds one request-scoped project store. Its retained shared lease remains
+/// live until the request has produced its final result.
 pub struct CodeGraphEngine {
     store: Store,
     project_root: PathBuf,
 }
 
 impl CodeGraphEngine {
+    const READ_LEASE_TIMEOUT: Duration = Duration::from_secs(30);
+
     /// Open the store at the project's current (v2) index DB, resolved
     /// fail-closed through the single `codegraph-core::IndexPaths` authority
     /// (`.codegraph-v2/codegraph.db` by default; a `<name>-v2-<projectIdentity>`
     /// sibling for a configured `CODEGRAPH_DIR`). An unsafe/aliased/overlapping
     /// configured root errors here rather than opening a reconstructed path.
     pub fn open(project_root: &Path) -> anyhow::Result<Self> {
-        let db_path = codegraph_core::IndexPaths::resolve(
+        let paths = codegraph_core::IndexPaths::resolve(
             project_root,
             std::env::var("CODEGRAPH_DIR").ok().as_deref(),
-        )?
-        .current_db();
-        let store = Store::open(&db_path)?;
+        )?;
+        let store =
+            Store::open_for_read(&paths, Instant::now() + Self::READ_LEASE_TIMEOUT, || false)?;
         Ok(Self {
             store,
             project_root: project_root.to_path_buf(),
@@ -3878,6 +3880,8 @@ mod tests {
             let db = base.join(".codegraph-v2").join("codegraph.db");
             Store::open(&db).unwrap();
         }
+        let paths = codegraph_core::IndexPaths::resolve(&base, None).unwrap();
+        codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
         let engine = CodeGraphEngine::open(&base).unwrap();
         let tr = engine.execute("codegraph_status", &serde_json::json!({}));
         assert!(text_of(&tr).contains("## CodeGraph Status"));
diff --git a/crates/codegraph-mcp/src/rmcp_handler.rs b/crates/codegraph-mcp/src/rmcp_handler.rs
index dc64d19..fba383c 100644
--- a/crates/codegraph-mcp/src/rmcp_handler.rs
+++ b/crates/codegraph-mcp/src/rmcp_handler.rs
@@ -7,14 +7,11 @@
 //!
 //! ## Sync engine bridge
 //!
-//! [`CodeGraphEngine`] wraps a `rusqlite::Connection` — `Send + !Sync`. rmcp
-//! handler futures are `Send + 'static`, so a `&CodeGraphEngine` borrowed
-//! through the cache mutex may NOT cross an `.await`, and a `spawn_blocking`
-//! closure (`'static + Send`) cannot borrow `&self`. `call_tool` therefore does
-//! the WHOLE "open-or-get-cached engine + execute + render to an OWNED
-//! [`ToolResult`]" inside ONE `spawn_blocking` closure: it moves in an `Arc`
-//! clone of the cache + owned project path + owned args and returns an owned
-//! result. No engine borrow crosses the closure boundary.
+//! [`CodeGraphEngine`] wraps a `rusqlite::Connection` — `Send + !Sync` — and is
+//! deliberately request-scoped so its retained shared lease spans the complete
+//! query but never survives into the next request. `call_tool` therefore does
+//! the WHOLE "open + execute + render to an OWNED [`ToolResult`]" inside ONE
+//! `spawn_blocking` closure. No engine borrow crosses the closure boundary.
 //!
 //! ## Panic isolation
 //!
@@ -23,7 +20,6 @@
 //! to an `isError` [`CallToolResult`] — a tool bug returns an error and the
 //! process/runtime stays alive (parity with the sync stdio server).
 
-use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
@@ -101,20 +97,17 @@ fn tool_timeout() -> Option<Duration> {
     parse_tool_timeout(std::env::var(TOOL_TIMEOUT_ENV).ok().as_deref())
 }
 
-type EngineCache = Arc<Mutex<HashMap<PathBuf, CodeGraphEngine>>>;
-
 /// The default project may be DISPLACED at runtime by roots adoption
 /// (`on_initialized`, non-pinned mode), and adoption runs through a `&self`
 /// handler, so it lives behind a `Mutex` for interior mutability. In pinned /
 /// `no_roots` mode it never changes after construction.
 type DefaultProject = Arc<Mutex<Option<PathBuf>>>;
 
-/// rmcp handler state: the shared engine cache plus the default project /
-/// cwd used to resolve a per-call `projectPath`. `no_roots` mirrors the
+/// rmcp handler state: the default project / cwd used to resolve a per-call
+/// `projectPath`. `no_roots` mirrors the
 /// [`crate::McpServer::http`] pin — when set, roots adoption is OFF (HTTP /
 /// pinned mode); when clear, `on_initialized` may adopt an indexed client root.
 pub struct CodeGraphHandler {
-    engines: EngineCache,
     default_project: DefaultProject,
     cwd: Option<PathBuf>,
     no_roots: bool,
@@ -123,7 +116,6 @@ pub struct CodeGraphHandler {
 impl CodeGraphHandler {
     pub fn new(default_project: Option<PathBuf>) -> Self {
         Self {
-            engines: Arc::new(Mutex::new(HashMap::new())),
             default_project: Arc::new(Mutex::new(default_project)),
             cwd: std::env::current_dir().ok(),
             no_roots: true,
@@ -146,7 +138,6 @@ impl CodeGraphHandler {
     /// cwd-derived, possibly unindexed dir.
     pub fn serve_with_roots(default_project: Option<PathBuf>, cwd: Option<PathBuf>) -> Self {
         Self {
-            engines: Arc::new(Mutex::new(HashMap::new())),
             default_project: Arc::new(Mutex::new(default_project)),
             cwd,
             no_roots: false,
@@ -159,7 +150,6 @@ impl CodeGraphHandler {
     #[doc(hidden)]
     pub fn new_with_cwd(default_project: Option<PathBuf>, cwd: Option<PathBuf>) -> Self {
         Self {
-            engines: Arc::new(Mutex::new(HashMap::new())),
             default_project: Arc::new(Mutex::new(default_project)),
             cwd,
             no_roots: true,
@@ -274,16 +264,10 @@ fn tool_result_to_call_result(result: &ToolResult) -> CallToolResult {
     }
 }
 
-/// Open-or-get-cached engine + execute + render — the ENTIRE Decision-10 unit,
-/// run inside a `spawn_blocking` closure. Takes owned inputs (an `Arc` cache
-/// clone, owned project path, tool name, args) and returns an owned
-/// [`ToolResult`]; no `&self` / engine borrow crosses the closure boundary.
-fn execute_owned(
-    engines: &EngineCache,
-    project_path: &Path,
-    tool_name: &str,
-    args: &Value,
-) -> ToolResult {
+/// Open a request-scoped engine + execute + render inside a `spawn_blocking`
+/// closure. The engine (and therefore SQLite handle + shared lease) drops only
+/// after the owned result has been fully produced.
+fn execute_owned(project_path: &Path, tool_name: &str, args: &Value) -> ToolResult {
     #[cfg(feature = "test-hooks")]
     if tool_name == PANIC_TOOL {
         panic!("simulated tool handler panic (Q5-unwind test)");
@@ -296,23 +280,15 @@ fn execute_owned(
         return ToolResult::text(format!("slept {secs}s"));
     }
 
-    let mut guard = engines
-        .lock()
-        .unwrap_or_else(std::sync::PoisonError::into_inner);
-    if !guard.contains_key(project_path) {
-        match CodeGraphEngine::open(project_path) {
-            Ok(engine) => {
-                guard.insert(project_path.to_path_buf(), engine);
-            }
-            Err(e) => {
-                return ToolResult::error(format!(
-                    "Failed to open project at {}: {e}",
-                    project_path.display()
-                ));
-            }
+    let engine = match CodeGraphEngine::open(project_path) {
+        Ok(engine) => engine,
+        Err(e) => {
+            return ToolResult::error(format!(
+                "Failed to open project at {}: {e}",
+                project_path.display()
+            ));
         }
-    }
-    let engine = guard.get(project_path).expect("engine present after open");
+    };
     engine.execute(tool_name, args)
 }
 
@@ -448,11 +424,9 @@ impl ServerHandler for CodeGraphHandler {
         // work; interrupting sync SQLite mid-read is unsafe. The client is
         // unblocked fast with an isError result; the orphaned thread drains
         // on its own. `tool_timeout() == None` (env `0`) opts out entirely.
-        let engines = Arc::clone(&self.engines);
         let outcome_tool = tool_name.clone();
-        let join_future = tokio::task::spawn_blocking(move || {
-            execute_owned(&engines, &project_path, &tool_name, &args)
-        });
+        let join_future =
+            tokio::task::spawn_blocking(move || execute_owned(&project_path, &tool_name, &args));
 
         let timed_out;
         let join = match tool_timeout() {
@@ -499,7 +473,6 @@ impl ServerHandler for CodeGraphHandler {
     }
 }
 
-/// Serve `CodeGraphHandler` over stdio via rmcp, building a multi-thread tokio
 /// Serve `CodeGraphHandler` over stdio via rmcp, building a multi-thread tokio
 /// runtime (the sync engine work runs on `spawn_blocking` pool threads). Blocks
 /// until the client disconnects (EOF). This is the CLI `serve --mcp` direct
@@ -1002,8 +975,7 @@ mod handler_tests {
     #[test]
     fn execute_owned_open_failure_returns_error_result() {
         let project = placeholder_indexed("exec-open-fail");
-        let engines: EngineCache = Arc::new(Mutex::new(HashMap::new()));
-        let result = execute_owned(&engines, &project.path, "codegraph_search", &json!({}));
+        let result = execute_owned(&project.path, "codegraph_search", &json!({}));
         assert_eq!(result.is_error, Some(true));
         let text: String = result.content.iter().map(|c| c.text.clone()).collect();
         assert!(
@@ -1153,8 +1125,7 @@ mod handler_tests {
     }
 
     /// Materialize a real indexed project (golden mini db + fixture sources) so
-    /// `CodeGraphEngine::open` succeeds — the only way to reach the cache-insert
-    /// + `engine.execute` success arm of `execute_owned`.
+    /// `CodeGraphEngine::open` succeeds and `execute_owned` reaches tool dispatch.
     fn real_indexed_project(tag: &str) -> TempDir {
         let dir = unique_dir(tag);
         let db = db_path_for(&dir.path).expect("default project resolves");
@@ -1167,34 +1138,30 @@ mod handler_tests {
             std::fs::create_dir_all(dst.parent().unwrap()).unwrap();
             std::fs::copy(fixtures.join(rel), &dst).unwrap();
         }
+        let paths = codegraph_core::IndexPaths::resolve(&dir.path, None).unwrap();
+        codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
         dir
     }
 
     #[test]
-    fn execute_owned_success_caches_engine_and_runs_tool() {
+    fn execute_owned_success_opens_request_scoped_engine_and_runs_tool() {
         let project = real_indexed_project("exec-ok");
-        let engines: EngineCache = Arc::new(Mutex::new(HashMap::new()));
         let first = execute_owned(
-            &engines,
             &project.path,
             "codegraph_search",
             &json!({ "query": "add" }),
         );
         assert_ne!(first.is_error, Some(true), "search on indexed project");
-        assert!(
-            engines
-                .lock()
-                .unwrap_or_else(|p| p.into_inner())
-                .contains_key(&project.path),
-            "engine cached after first open"
-        );
         let second = execute_owned(
-            &engines,
             &project.path,
             "codegraph_search",
             &json!({ "query": "add" }),
         );
-        assert_ne!(second.is_error, Some(true), "cached engine reused");
+        assert_ne!(
+            second.is_error,
+            Some(true),
+            "second request reopens cleanly"
+        );
     }
 
     fn rt() -> tokio::runtime::Runtime {
diff --git a/crates/codegraph-mcp/src/server.rs b/crates/codegraph-mcp/src/server.rs
index 0d6e25b..db79290 100644
--- a/crates/codegraph-mcp/src/server.rs
+++ b/crates/codegraph-mcp/src/server.rs
@@ -69,7 +69,7 @@ struct DbIdentity {
 ///
 /// Deliberately EXCLUDED:
 /// - bytes `[24..28]` — file change counter: increments on EVERY transaction
-///   including a plain WAL write, which would false-fire a reopen.
+///   including a plain WAL write, which would false-report a replacement.
 /// - bytes `[92..100]` — version-valid-for / SQLite version: mutate on writes.
 ///
 /// No timestamp (mtime) is involved, so a normal WAL write that
@@ -123,10 +123,9 @@ fn header_sig(db_path: &std::path::Path) -> u64 {
 }
 
 impl DbIdentity {
-    /// Identity of the db file, or `None` when it is missing — which the caller
-    /// treats as "must reopen". Honors "never miss a replace": a metadata error
-    /// yields `None` (reopen); a header read error degrades `header_sig` to `0`
-    /// (the slices simply do not contribute), never a panic.
+    /// Identity of the db file, or `None` when it cannot be observed. A header
+    /// read error degrades `header_sig` to `0` (the slices simply do not
+    /// contribute), never a panic.
     fn read(db_path: &std::path::Path) -> Option<Self> {
         let meta = std::fs::metadata(db_path).ok()?;
         #[cfg(unix)]
@@ -161,28 +160,26 @@ impl DbIdentity {
     }
 }
 
-/// A cached engine plus the db-file identity recorded when it was opened.
-///
-/// `engine` is `Option` so [`McpServer::close_cached_handles`] can drop the live
-/// DB connection (releasing the OS file handle) while keeping the recorded
-/// `identity`. [`McpServer::engine_for`] treats a `None` engine as stale, so it
-/// reopens and counts the reopen exactly as a replaced-on-disk db would. Normal
-/// serve flow always holds `Some`.
-struct CachedEngine {
-    engine: Option<CodeGraphEngine>,
-    identity: DbIdentity,
-}
+/// Last successfully observed file identity for one project. SQLite connections
+/// and leases remain request-scoped and are never retained in this map.
+struct ObservedDbIdentity(DbIdentity);
 
-/// Process-global count of engine reopens (drop the cached engine + open a
-/// fresh one because the db file went missing or was replaced). The first open
-/// of a never-cached path is not a reopen. `tests/reopen.rs` reads it via
-/// [`reopen_count`] to prove a same-inode project triggers no needless reopen.
-static REOPEN_COUNT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+/// Process-global count of DB identity changes observed between successful
+/// requests. Request-scoped engines open on every call, so this metric does not
+/// count engine or connection opens. The first observation is not a change.
+static DB_IDENTITY_CHANGE_COUNT: std::sync::atomic::AtomicU64 =
+    std::sync::atomic::AtomicU64::new(0);
 
-/// Number of engine reopens since process start. Test-observability hook for
-/// the #925 replacement rule; cheap enough to keep unconditionally.
+/// Number of DB identity changes observed between successful requests since
+/// process start.
+pub fn db_identity_change_count() -> u64 {
+    DB_IDENTITY_CHANGE_COUNT.load(std::sync::atomic::Ordering::Relaxed)
+}
+
+/// Compatibility alias for the former cached-engine diagnostic name.
+#[doc(hidden)]
 pub fn reopen_count() -> u64 {
-    REOPEN_COUNT.load(std::sync::atomic::Ordering::Relaxed)
+    db_identity_change_count()
 }
 
 pub enum RunUntilAdoption<R> {
@@ -190,14 +187,12 @@ pub enum RunUntilAdoption<R> {
     Adopted { project_root: PathBuf, reader: R },
 }
 
-/// Holds the default project path and a per-path engine cache (mirrors
-/// `ToolHandler.projectCache`, `tools.ts:591`). Each cached engine carries the
-/// db-file identity it was opened against, so [`McpServer::engine_for`] can
-/// reopen when the database is REPLACED on disk (#925).
+/// Holds the default project path and per-path DB identities used to observe
+/// replacements (#925). Every request opens and drops its own engine.
 pub struct McpServer {
     default_project: Option<PathBuf>,
     cwd: Option<PathBuf>,
-    engines: HashMap<PathBuf, CachedEngine>,
+    observed_identities: HashMap<PathBuf, ObservedDbIdentity>,
     workspace_roots: WorkspaceRoots,
     no_roots: bool,
 }
@@ -207,7 +202,7 @@ impl McpServer {
         Self {
             default_project,
             cwd: std::env::current_dir().ok(),
-            engines: HashMap::new(),
+            observed_identities: HashMap::new(),
             workspace_roots: WorkspaceRoots::new(),
             no_roots: false,
         }
@@ -516,13 +511,9 @@ impl McpServer {
         crate::roots::resolve_project_arg(raw, self.cwd.as_deref(), self.default_project.as_deref())
     }
 
-    /// Open-on-demand + cache the engine for a project path
-    /// (`ToolHandler.getCodeGraph`, `tools.ts`), reopening when the db file was
-    /// REPLACED on disk (#925). Before returning a cached engine, re-stat the db
-    /// path: reopen iff it is MISSING or its identity differs from the recorded
-    /// one (inode/file-index changed). An in-place write keeps the same identity,
-    /// so the common path returns the cached engine without reopening.
-    fn engine_for(&mut self, project_path: &PathBuf) -> anyhow::Result<&CodeGraphEngine> {
+    /// Open one request-scoped engine and update the #925 identity-change
+    /// observation. No SQLite handle or lease is cached.
+    fn engine_for(&mut self, project_path: &PathBuf) -> anyhow::Result<CodeGraphEngine> {
         // A resolvable configured root yields its DB path. An invalid one is
         // already rejected upstream by `roots::resolve_project_arg`, which carries
         // the stable `IndexPaths` diagnostic to the caller before a tool call ever
@@ -535,48 +526,28 @@ impl McpServer {
                 project_path.display()
             )
         })?;
-        let current = DbIdentity::read(&db_path);
-
-        let stale = match self.engines.get(project_path) {
-            None => true,
-            Some(cached) => cached.engine.is_none() || current != Some(cached.identity),
-        };
-
-        if stale {
-            if self.engines.remove(project_path).is_some() {
-                REOPEN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
-            }
-            let engine = CodeGraphEngine::open(project_path)?;
-            let identity = DbIdentity::read(&db_path).ok_or_else(|| {
-                anyhow::anyhow!("database vanished after open at {}", db_path.display())
-            })?;
-            self.engines.insert(
-                project_path.clone(),
-                CachedEngine {
-                    engine: Some(engine),
-                    identity,
-                },
-            );
-        }
-
-        Ok(self
-            .engines
+        let previous = self
+            .observed_identities
             .get(project_path)
-            .and_then(|c| c.engine.as_ref())
-            .expect("engine present after open"))
+            .map(|observed| observed.0);
+        let engine = CodeGraphEngine::open(project_path)?;
+        let identity = DbIdentity::read(&db_path).ok_or_else(|| {
+            anyhow::anyhow!("database vanished after open at {}", db_path.display())
+        })?;
+        if previous.is_some_and(|recorded| recorded != identity) {
+            DB_IDENTITY_CHANGE_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+        }
+        self.observed_identities
+            .insert(project_path.clone(), ObservedDbIdentity(identity));
+        Ok(engine)
     }
 
-    /// Test/diagnostic only: drop every cached engine's live DB connection while
-    /// keeping its recorded identity, so the underlying db files can be replaced
-    /// on platforms (windows) where an open handle blocks delete/overwrite. The
-    /// next [`McpServer::engine_for`] reopens the still-recorded path and counts
-    /// it as a reopen, identical to a replaced-on-disk db. Normal serve flow
-    /// never calls this; the cache reopens on demand.
+    /// Backward-compatible diagnostic seam. There are no cached handles to close;
+    /// this forgets DB identity observations so the next request establishes a
+    /// new baseline without reporting a synthetic identity change.
     #[doc(hidden)]
     pub fn close_cached_handles(&mut self) {
-        for cached in self.engines.values_mut() {
-            cached.engine = None;
-        }
+        self.observed_identities.clear();
     }
 
     /// Test/diagnostic only: the currently adopted default project path.
@@ -593,7 +564,7 @@ impl McpServer {
         Self {
             default_project,
             cwd,
-            engines: HashMap::new(),
+            observed_identities: HashMap::new(),
             workspace_roots: WorkspaceRoots::new(),
             no_roots: false,
         }
@@ -1245,11 +1216,15 @@ mod tests {
     }
 
     #[test]
-    fn close_cached_handles_forces_reopen_counter() {
-        let before = reopen_count();
-        let mut server = McpServer::new(None);
+    fn close_cached_handles_clears_only_identity_observations() {
+        let project = indexed_project("close-identity-observations");
+        let mut server = McpServer::new(Some(project.path().to_path_buf()));
+        server.observed_identities.insert(
+            project.path().to_path_buf(),
+            ObservedDbIdentity(DbIdentity::read(&db_path_for(project.path()).unwrap()).unwrap()),
+        );
         server.close_cached_handles();
-        assert!(reopen_count() >= before);
+        assert!(server.observed_identities.is_empty());
     }
 
     #[test]
diff --git a/crates/codegraph-mcp/tests/godot_honesty_mcp.rs b/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
index d6126a2..e8520ad 100644
--- a/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
+++ b/crates/codegraph-mcp/tests/godot_honesty_mcp.rs
@@ -93,6 +93,8 @@ fn pipeline_project(files: &[(&str, &str)]) -> TestProject {
     resolver.resolve_and_persist(&mut store).unwrap();
     resolver.run_post_extract(&mut store).unwrap();
     drop(store);
+    let paths = codegraph_core::IndexPaths::resolve(&base, None).unwrap();
+    codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
 
     TestProject { path: base }
 }
diff --git a/crates/codegraph-mcp/tests/golden_mcp.rs b/crates/codegraph-mcp/tests/golden_mcp.rs
index 63daef3..a7f906f 100644
--- a/crates/codegraph-mcp/tests/golden_mcp.rs
+++ b/crates/codegraph-mcp/tests/golden_mcp.rs
@@ -94,6 +94,8 @@ fn setup_mini_project() -> TestProject {
         &root.join("reference/golden/mini/colby.db"),
         &base.join(".codegraph-v2").join("codegraph.db"),
     );
+    let paths = codegraph_core::IndexPaths::resolve(&base, None).unwrap();
+    codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
 
     let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
     for rel in ["src/app.ts", "src/math.ts", "tools/greeter.py"] {
@@ -772,6 +774,8 @@ fn index_fixture(files: &[(&str, &str)]) -> TestProject {
     }
     store.insert_edges(&all_edges).unwrap();
     drop(store);
+    let paths = codegraph_core::IndexPaths::resolve(&base, None).unwrap();
+    codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
     TestProject { path: base }
 }
 
diff --git a/crates/codegraph-mcp/tests/mcp_configured_root.rs b/crates/codegraph-mcp/tests/mcp_configured_root.rs
index fd6d5b5..85d5433 100644
--- a/crates/codegraph-mcp/tests/mcp_configured_root.rs
+++ b/crates/codegraph-mcp/tests/mcp_configured_root.rs
@@ -83,16 +83,18 @@ fn unique_dir(tag: &str) -> TempDir {
     TempDir { path }
 }
 
-fn stage_mini_db_at(db: &Path, project: &Path) {
+fn stage_mini_db_at(paths: &codegraph_core::IndexPaths, project: &Path) {
     let root = workspace_root();
+    let db = paths.current_db();
     fs::create_dir_all(db.parent().unwrap()).unwrap();
-    fs::copy(root.join("reference/golden/mini/colby.db"), db).unwrap();
+    fs::copy(root.join("reference/golden/mini/colby.db"), &db).unwrap();
     let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
     for rel in ["src/app.ts", "src/math.ts"] {
         let dst = project.join(rel);
         fs::create_dir_all(dst.parent().unwrap()).unwrap();
         fs::copy(fixtures.join(rel), &dst).unwrap();
     }
+    codegraph_store::test_support::finalize_current_test_fixture(paths).unwrap();
 }
 
 fn tool_call_search(project: &Path, project_path_arg: &str) -> Value {
@@ -126,7 +128,7 @@ fn configured_relative_root_mcp_opens_identity_sibling_db() {
     let _env = EnvGuard::set("cache");
 
     let paths = codegraph_core::IndexPaths::resolve(base, Some("cache")).expect("resolve");
-    stage_mini_db_at(&paths.current_db(), base);
+    stage_mini_db_at(&paths, base);
     assert!(
         !base.join("cache").join("codegraph.db").is_file(),
         "configured root must resolve to the identity sibling, not the simple-join"
@@ -167,7 +169,7 @@ fn two_projects_sharing_absolute_root_cannot_cross_read_via_mcp() {
     let _env = EnvGuard::set(&shared_str);
 
     let paths_a = codegraph_core::IndexPaths::resolve(&project_a, Some(&shared_str)).expect("a");
-    stage_mini_db_at(&paths_a.current_db(), &project_a);
+    stage_mini_db_at(&paths_a, &project_a);
 
     let paths_b = codegraph_core::IndexPaths::resolve(&project_b, Some(&shared_str)).expect("b");
     assert_ne!(
@@ -374,10 +376,9 @@ fn invalid_configured_root_mcp_fails_closed_and_never_serves_trap_default_db() {
     let project = dir.path.join("mini");
     fs::create_dir_all(&project).unwrap();
 
-    let trap_db = project
-        .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
-        .join("codegraph.db");
-    stage_mini_db_at(&trap_db, &project);
+    let trap_paths = codegraph_core::IndexPaths::resolve(&project, None).unwrap();
+    let trap_db = trap_paths.current_db();
+    stage_mini_db_at(&trap_paths, &project);
     assert!(
         trap_db.is_file(),
         "sanity: the trap DB must exist at the default namespace a fallback would open"
@@ -438,12 +439,8 @@ fn invalid_configured_root_rmcp_fails_closed_and_never_serves_trap_default_db()
     let dir = unique_dir("trap-rmcp");
     let project = dir.path.join("mini");
     fs::create_dir_all(&project).unwrap();
-    stage_mini_db_at(
-        &project
-            .join(codegraph_core::index_paths::DEFAULT_CURRENT_DIR)
-            .join("codegraph.db"),
-        &project,
-    );
+    let trap_paths = codegraph_core::IndexPaths::resolve(&project, None).unwrap();
+    stage_mini_db_at(&trap_paths, &project);
 
     let _env = EnvGuard::set(".");
 
diff --git a/crates/codegraph-mcp/tests/reopen.rs b/crates/codegraph-mcp/tests/reopen.rs
index 41e2d5f..bc74c01 100644
--- a/crates/codegraph-mcp/tests/reopen.rs
+++ b/crates/codegraph-mcp/tests/reopen.rs
@@ -1,10 +1,10 @@
-//! T6 (#925): `McpServer` reopens its cached `CodeGraphEngine` when the
-//! project's `.codegraph/codegraph.db` is REPLACED on disk, so a long-lived
-//! `serve` never keeps serving a stale database.
+//! T6 (#925): a long-lived `McpServer` serves replacement database contents
+//! without retaining a `CodeGraphEngine`, SQLite connection, or read lease
+//! between requests.
 //!
 //! The decision is keyed on the db file IDENTITY (unix inode / a content-based
 //! signature on non-unix), NOT on modified-time: an in-place WAL write bumps
-//! mtime but does not replace the file, so it must NOT trigger a reopen. On
+//! mtime but does not replace the file, so it must NOT record a change. On
 //! non-unix the signature is a hash of the WAL-stable SQLite header slices
 //! (page count + schema cookie + structural header), which is deterministic and
 //! mtime-independent — it changes only when the db is rebuilt.
@@ -13,17 +13,25 @@ use std::fs;
 use std::io::Cursor;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Mutex, MutexGuard, OnceLock};
 
 use codegraph_core::types::FileRecord;
 use codegraph_extract::engine::{detect_language, extract_file};
 use codegraph_mcp::McpServer;
-use codegraph_mcp::server::reopen_count;
+use codegraph_mcp::server::db_identity_change_count;
 
 use codegraph_store::Store;
 use serde_json::{Value, json};
 
 static TEMP_SEQ: AtomicU64 = AtomicU64::new(0);
 
+fn counter_test_guard() -> MutexGuard<'static, ()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
 /// Owns a temp project dir and removes it on drop.
 struct TestProject {
     path: PathBuf,
@@ -48,7 +56,7 @@ fn unique_base(tag: &str) -> PathBuf {
         .as_nanos();
     let seq = TEMP_SEQ.fetch_add(1, Ordering::Relaxed);
     std::env::temp_dir().join(format!(
-        "cg-mcp-reopen-{tag}-{}-{nanos}-{seq}",
+        "cg-mcp-identity-{tag}-{}-{nanos}-{seq}",
         std::process::id()
     ))
 }
@@ -85,11 +93,13 @@ fn index_into(base: &Path, files: &[(&str, &str)]) {
     }
     store.insert_edges(&all_edges).unwrap();
     drop(store);
+    let paths = codegraph_core::IndexPaths::resolve(base, None).unwrap();
+    codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
 }
 
 /// Drive one `codegraph_search` `tools/call` against `server`, returning the
-/// rendered text body (NOT a fresh server — reuse the SAME server so its engine
-/// cache persists across calls, which is the whole point of the test).
+/// rendered text body. Reusing the SAME server proves request-scoped engines do
+/// not leave stale graph state attached to the long-lived protocol session.
 fn search(server: &mut McpServer, project: &Path, query: &str) -> String {
     let req = json!({
         "jsonrpc": "2.0",
@@ -115,7 +125,8 @@ fn search(server: &mut McpServer, project: &Path, query: &str) -> String {
 }
 
 #[test]
-fn reopens_cached_engine_when_db_replaced_with_new_inode() {
+fn same_server_reads_replacement_graph_without_close_helper() {
+    let _counter = counter_test_guard();
     // Given: an indexed project whose db (inode A) contains `alphaSymbol`.
     let project = TestProject {
         path: unique_base("replace"),
@@ -127,66 +138,60 @@ fn reopens_cached_engine_when_db_replaced_with_new_inode() {
 
     let mut server = McpServer::new(Some(project.path().to_path_buf()));
 
-    // Populate the engine cache against inode A.
     let first = search(&mut server, project.path(), "alphaSymbol");
     assert!(
         first.contains("alphaSymbol"),
         "first call should find the original symbol; got:\n{first}"
     );
-    let reopens_before = reopen_count();
+    let changes_before = db_identity_change_count();
+    let identity_before = db_identity(project.path());
 
     // When: the db is REPLACED on disk with a fresh index whose content differs
-    // (a new symbol `betaSymbol`). The cached engine still holds an open WAL
-    // connection, which on windows blocks deleting the db dir (OS error 32).
-    // Drop the live connections first — `close_cached_handles` releases the file
-    // handle while keeping the cache RECORD, so the next call reopens exactly
-    // once and re-reads the freshly built db from disk. Removing the dir first
-    // guarantees a freshly built db.
-    //
-    // We deliberately do NOT assert the raw `DbIdentity` changed here. On unix
-    // the identity is the inode, and the OS is free to RECYCLE the just-deleted
-    // db's inode for the rebuilt file (observed under `cargo llvm-cov`: both =
-    // 1343671), so an `assert_ne!(id_before, id_after)` gambles on an OS
-    // implementation detail that delete+rebuild does not guarantee. That inode
-    // assertion was the sole flake source and is redundant with #925's real
-    // contract, which is the BEHAVIORAL outcome asserted below and does not
-    // depend on inode luck: the SAME cached server reopens its engine and serves
-    // the NEW on-disk content. Serving `betaSymbol` (not `alphaSymbol`, not an
-    // open error) is itself the proof the engine reopened against the fresh db.
-    server.close_cached_handles();
+    // (a new symbol `betaSymbol`). No compatibility helper participates: every
+    // request must already have dropped its engine, SQLite handles, and lease.
     fs::remove_dir_all(project.path().join(".codegraph-v2")).unwrap();
     index_into(
         project.path(),
         &[("src/b.ts", "export function betaSymbol() {}\n")],
     );
+    let identity_after = db_identity(project.path());
 
-    // Then: the SAME server's SAME tool call must REOPEN the engine — without the
-    // #925 fix the cached engine keeps serving the old db and `reopen_count`
-    // never advances (this delta is the deterministic RED probe).
+    // Then: the SAME server's next request serves only the replacement graph.
     let after = search(&mut server, project.path(), "betaSymbol");
-    let reopens_after = reopen_count();
+    let changes_after = db_identity_change_count();
+    #[cfg(unix)]
     assert_eq!(
-        reopens_after - reopens_before,
-        1,
-        "a db replacement (new inode) must trigger exactly one reopen \
-         (before={reopens_before}, after={reopens_after})"
+        changes_after - changes_before,
+        u64::from(identity_before != identity_after),
+        "the observation counter must match the inode actually allocated \
+         (before={changes_before}, after={changes_after})"
+    );
+    #[cfg(not(unix))]
+    let _ = (
+        changes_before,
+        changes_after,
+        identity_before,
+        identity_after,
     );
 
-    // And: it returns FRESH data from inode B, not an open error.
     assert!(
         after.contains("betaSymbol"),
-        "after replacement the engine must reopen and serve the new index; got:\n{after}"
+        "after replacement the next request must serve the new index; got:\n{after}"
+    );
+    assert!(
+        !after.contains("alphaSymbol"),
+        "after replacement the old graph must not leak into the response; got:\n{after}"
     );
     assert!(
         !after.to_lowercase().contains("failed to open"),
-        "reopen must not surface an open error; got:\n{after}"
+        "the replacement request must not surface an open error; got:\n{after}"
     );
 }
 
 #[test]
-fn does_not_reopen_when_inode_is_unchanged() {
-    // Given: an indexed project; one tool call populates the cache (one open,
-    // which is NOT counted as a reopen).
+fn unchanged_identity_does_not_increment_observation_count() {
+    let _counter = counter_test_guard();
+    // Given: one request establishes the server's identity observation baseline.
     let project = TestProject {
         path: unique_base("stable"),
     };
@@ -198,7 +203,7 @@ fn does_not_reopen_when_inode_is_unchanged() {
     let mut server = McpServer::new(Some(project.path().to_path_buf()));
 
     let _ = search(&mut server, project.path(), "gammaSymbol");
-    let after_first = reopen_count();
+    let after_first = db_identity_change_count();
 
     // When: more calls run WITHOUT replacing the db (same file), even after an
     // in-place mtime bump (a normal WAL write) — that must NOT be treated as a
@@ -215,19 +220,44 @@ fn does_not_reopen_when_inode_is_unchanged() {
     for _ in 0..5 {
         let _ = search(&mut server, project.path(), "gammaSymbol");
     }
-    let after_many = reopen_count();
+    let after_many = db_identity_change_count();
 
-    // Then: the engine identity is stable — no reopen fired after the initial
-    // open, despite the changed mtime.
+    // Then: the stable identity produced no replacement observation.
     assert_eq!(
         after_first, after_many,
-        "a same-file (in-place) project must NOT trigger any reopen \
+        "a same-file (in-place) project must NOT record an identity change \
          (after_first_call={after_first}, after_many={after_many})"
     );
 }
 
+#[test]
+fn close_cached_handles_resets_diagnostics_without_forcing_replacement() {
+    let _counter = counter_test_guard();
+    let project = TestProject {
+        path: unique_base("close-diagnostic"),
+    };
+    index_into(
+        project.path(),
+        &[("src/a.ts", "export function deltaSymbol() {}\n")],
+    );
+    let mut server = McpServer::new(Some(project.path().to_path_buf()));
+    assert!(search(&mut server, project.path(), "deltaSymbol").contains("deltaSymbol"));
+    let before = db_identity_change_count();
+
+    server.close_cached_handles();
+    let after = search(&mut server, project.path(), "deltaSymbol");
+
+    assert!(after.contains("deltaSymbol"));
+    assert_eq!(
+        db_identity_change_count(),
+        before,
+        "clearing diagnostic identity state must not synthesize a replacement"
+    );
+}
+
 /// Mirror of the production `DbIdentity` for the project's db file, folded into
-/// a single `u128` so the replace test can assert the identity actually changed.
+/// a single `u128` so the replacement test can condition its metric assertion
+/// on the identity the filesystem actually allocated.
 /// Unix uses the inode; non-unix mirrors the production `(len, creation_time,
 /// header_sig)` fold where `header_sig` hashes the SAME WAL-stable SQLite header
 /// slices (`[16..24]`, `[28..32]`, `[40..44]`) — NO mtime, so a pure mtime touch
diff --git a/crates/codegraph-mcp/tests/support/parity.rs b/crates/codegraph-mcp/tests/support/parity.rs
index c7cf88f..039d12f 100644
--- a/crates/codegraph-mcp/tests/support/parity.rs
+++ b/crates/codegraph-mcp/tests/support/parity.rs
@@ -89,6 +89,8 @@ pub fn setup_mini_project() -> TestProject {
         &root.join("reference/golden/mini/colby.db"),
         &base.join(".codegraph-v2").join("codegraph.db"),
     );
+    let paths = codegraph_core::IndexPaths::resolve(&base, None).unwrap();
+    codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap();
 
     let fixtures = root.join("crates/codegraph-bench/fixtures/mini");
     for rel in ["src/app.ts", "src/math.ts", "tools/greeter.py"] {
diff --git a/crates/codegraph-store/Cargo.toml b/crates/codegraph-store/Cargo.toml
index b1c8d00..94d2256 100644
--- a/crates/codegraph-store/Cargo.toml
+++ b/crates/codegraph-store/Cargo.toml
@@ -12,6 +12,12 @@ rust-version.workspace = true
 description = "SQLite + FTS5 persistence layer for CodeGraph-rs (fixed, byte-stable schema)."
 readme = "../../README.md"
 
+[features]
+# Enables the deterministic lease-acquisition barrier used by cross-process
+# integration tests. Normal/release builds never enable this feature, so the
+# environment-controlled hook is absent from shipped binaries.
+test-hooks = []
+
 [dependencies]
 codegraph-core = { path = "../codegraph-core" }
 serde = { workspace = true }
diff --git a/crates/codegraph-store/src/index_lease.rs b/crates/codegraph-store/src/index_lease.rs
index a1ce8d9..804a4ac 100644
--- a/crates/codegraph-store/src/index_lease.rs
+++ b/crates/codegraph-store/src/index_lease.rs
@@ -11,6 +11,9 @@ use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
+#[cfg(feature = "test-hooks")]
+use std::io::{Read, Write};
+
 use codegraph_core::IndexPaths;
 use thiserror::Error;
 
@@ -388,14 +391,17 @@ impl IndexLease {
                         return Err(changed(&lock_path));
                     }
                     checkpoint(AcquireCheckpoint::FinalPathCorroborated);
-                    return Ok(Self {
+                    let lease = Self {
                         inner: Arc::new(LeaseInner {
                             file,
                             mode,
                             db_parent,
                             lock_path,
                         }),
-                    });
+                    };
+                    #[cfg(feature = "test-hooks")]
+                    lease_test_barrier(mode);
+                    return Ok(lease);
                 }
                 Err(std::fs::TryLockError::WouldBlock) => {
                     // Check cancellation after every observed contention, then
@@ -423,6 +429,52 @@ impl IndexLease {
     }
 }
 
+/// Deterministic cross-process checkpoint used only by integration-test builds.
+///
+/// A test child opts in by supplying a loopback listener address and the lease
+/// mode it wants to stop. The hook writes one acknowledged mode byte only after
+/// the kernel lock and final path corroboration both succeeded, then waits for a
+/// release byte with bounded socket timeouts. No corresponding strings or I/O
+/// path are compiled into normal/release builds.
+#[cfg(feature = "test-hooks")]
+fn lease_test_barrier(mode: LeaseMode) {
+    const ADDR_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_ADDR";
+    const MODE_ENV: &str = "CODEGRAPH_TEST_LEASE_BARRIER_MODE";
+    const WAIT: Duration = Duration::from_secs(10);
+
+    let expected = match std::env::var(MODE_ENV) {
+        Ok(value) => value,
+        Err(_) => return,
+    };
+    let (mode_name, marker) = match mode {
+        LeaseMode::Shared => ("shared", b'S'),
+        LeaseMode::Exclusive => ("exclusive", b'X'),
+    };
+    if expected != mode_name {
+        return;
+    }
+    let address = std::env::var(ADDR_ENV)
+        .unwrap_or_else(|_| panic!("{MODE_ENV} requires {ADDR_ENV}"))
+        .parse()
+        .unwrap_or_else(|error| panic!("invalid {ADDR_ENV}: {error}"));
+    let mut stream = std::net::TcpStream::connect_timeout(&address, WAIT)
+        .unwrap_or_else(|error| panic!("connect lease test barrier {address}: {error}"));
+    stream
+        .set_read_timeout(Some(WAIT))
+        .expect("set lease test barrier read timeout");
+    stream
+        .set_write_timeout(Some(WAIT))
+        .expect("set lease test barrier write timeout");
+    stream
+        .write_all(&[marker])
+        .expect("acknowledge lease test barrier arrival");
+    let mut release = [0_u8; 1];
+    stream
+        .read_exact(&mut release)
+        .expect("receive lease test barrier release");
+    assert_eq!(release, [b'R'], "invalid lease test barrier release byte");
+}
+
 fn validated_path_metadata(lock_path: &Path) -> Result<std::fs::Metadata, IndexLeaseError> {
     let metadata = std::fs::symlink_metadata(lock_path).map_err(|source| {
         if source.kind() == io::ErrorKind::NotFound {
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index 8a0e7f8..b121c22 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -7,6 +7,8 @@ pub mod migrations;
 pub mod queries;
 pub mod rebuild;
 pub mod schema;
+#[cfg(feature = "test-hooks")]
+pub mod test_support;
 pub mod uninit;
 
 pub use connection::{
diff --git a/crates/codegraph-store/src/test_support.rs b/crates/codegraph-store/src/test_support.rs
new file mode 100644
index 0000000..b1852c6
--- /dev/null
+++ b/crates/codegraph-store/src/test_support.rs
@@ -0,0 +1,67 @@
+//! Test-only helpers for materializing state-gated index fixtures.
+
+use std::fs::OpenOptions;
+use std::time::{Duration, Instant};
+
+use anyhow::{Context, Result, ensure};
+use codegraph_core::IndexPaths;
+
+use crate::{
+    CURRENT_EXTRACTION_VERSION, EXTRACTION_VERSION_KEY, IndexLease, StatePhase, Store,
+    publish_index_state,
+};
+
+/// Complete a freshly created or copied SQLite fixture as a readable `Current`
+/// namespace.
+///
+/// Production code must never repair a database artifact that lacks its state
+/// protocol. Tests, however, frequently construct the SQLite bytes directly.
+/// This feature-gated helper gives those fixtures the same permanent lock,
+/// extraction stamp, and monotonic `Building -> Current` state publication that
+/// a successful rebuild would leave behind, without weakening any production
+/// read gate.
+pub fn finalize_current_test_fixture(paths: &IndexPaths) -> Result<()> {
+    let db = paths.current_db();
+    ensure!(
+        db.is_file(),
+        "test fixture database does not exist at {}",
+        db.display()
+    );
+
+    let lock_path = paths.permanent_lock();
+    if !lock_path.exists() {
+        let lock = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create_new(true)
+            .open(&lock_path)
+            .with_context(|| format!("create test fixture lock {}", lock_path.display()))?;
+        lock.sync_all()
+            .with_context(|| format!("sync test fixture lock {}", lock_path.display()))?;
+    }
+
+    let lease = IndexLease::acquire_exclusive_existing(
+        paths,
+        Instant::now() + Duration::from_secs(5),
+        || false,
+    )
+    .context("acquire test fixture lease")?;
+
+    let store = Store::open(&db).context("open test fixture database")?;
+    store
+        .set_project_metadata(
+            EXTRACTION_VERSION_KEY,
+            &CURRENT_EXTRACTION_VERSION.to_string(),
+        )
+        .context("stamp test fixture extraction version")?;
+    store
+        .restore_default_pragmas()
+        .context("checkpoint test fixture database")?;
+    drop(store);
+
+    publish_index_state(paths, &lease, StatePhase::Building)
+        .context("publish test fixture Building state")?;
+    publish_index_state(paths, &lease, StatePhase::Current)
+        .context("publish test fixture Current state")?;
+    Ok(())
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 8be7c3d..c85c0f4 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2441,3 +2441,64 @@ native Windows runtime validation was run and none is claimed.
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
 This evidence was appended before the closure's final `make fmt` and authoritative
 locked CI run so no post-CI documentation edit can invalidate formatting.
+
+## Batch M item 15 acceptance closure — request-scoped reader leases (2026-07-26)
+
+The CLI and both MCP request paths now open a state-gated `Store` through a
+request-scoped `CodeGraphEngine`. The retained shared `IndexLease` spans SQLite
+corroboration, query execution, and complete owned result materialization, then
+drops before the next request. No SQLite connection or lease remains cached in a
+long-lived MCP session. Status contention is reported as `rebuilding: true` and
+`initialized: false`; raw DB-path presence is not represented as a corroborated
+readable Current index.
+
+The deterministic cross-process acceptance barrier is feature-gated through
+`codegraph-store/test-hooks` and is feature-unified only into package test builds.
+It acknowledges shared or exclusive ownership only after kernel locking and
+final fixed-path corroboration, then waits on a bounded loopback socket rather
+than inferring ordering from sleeps. The reader acceptance covers CLI query,
+direct stdio MCP, the real daemon proxy, streamable HTTP MCP, and status. The
+writer acceptance holds the watcher's exclusive lease before SQLite open and
+proves that a new read and busy status neither open nor mutate DB/WAL/SHM bytes.
+The HTTP child uses a fixture-owned `CODEGRAPH_HTTP_REGISTRY_DIR`, which is
+explicitly removed and checked absent after child termination.
+
+The SQLite nonmutation oracle treats only typed `NotFound` as absence. Every
+other metadata, open, read, kind, length, or identity error fails closed. It
+rejects aliases and non-regular entries, reads complete bytes from one handle,
+and re-corroborates that the fixed path still names that handle. Unix uses
+device/inode identity; the Windows branch uses `FileIdInfo`. Executable self-tests
+prove rejection of a non-regular artifact and, on Unix, an alias without reading
+or changing its external target.
+
+Replacement freshness is behavioral rather than cache-seam dependent: one
+long-lived `McpServer` serves only the replacement graph on its next request
+without calling `close_cached_handles()`. The retained diagnostic counts observed
+DB identity changes between successful requests; it does not count engine or
+connection opens. The compatibility seam only clears identity observations and
+has a separate regression proving that it cannot synthesize a replacement event.
+Fixture builders used by MCP tests now finalize directly created/copied SQLite
+bytes with a permanent lock, extraction stamp, and `Building -> Current` state
+publication through the feature-gated test helper; production read gates remain
+strict.
+
+Focused tests on the reviewed bytes passed before this append, with
+`bash scripts/check-workspace-versions.sh` before Cargo batches and `--locked` on
+dependency-resolving commands: `lease_lifetime` passed **5/5** and `reopen`
+passed **3/3**. Targeted package check, Clippy with `-D warnings`, formatting, and
+`git diff --check` also passed. Changed-file LSP diagnostics were retried for all
+modified and new Rust files, but the tool rejected this required external
+worktree with `LSP file path must be inside request cwd`; locked Cargo diagnostics
+are the fallback, and this ledger does not claim LSP-clean results. Native Windows
+runtime validation was unavailable and is not claimed; Windows-only identity
+code remains compile/CI-owned evidence.
+
+The frozen Revision 14 plan remains required at SHA-256
+`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`, and
+`Cargo.lock` remains required at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+No schema, node-ID formula, extraction/golden byte, workflow, `UPSTREAM.md`, or
+`KNOWN_DIFFS.md` change belongs to this slice. These evidence bytes are written
+before formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run;
+no final Green is claimed until that post-documentation gate passes.

From 25b78a8969e9b0c51674b0d03b62ea2a6f49735b Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 15:47:15 +0800
Subject: [PATCH 32/91] test(index): add verified v0.40.4 legacy fixture

---
 .github/workflows/ci.yml                      |   15 +
 .../batch_m_legacy_extension_override.rs      | 1825 +++++++++++++++++
 .../fixtures/legacy-v0.40.4/manifest.toml     |   52 +
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |   99 +
 scripts/setup-legacy-fixture.sh               |  373 ++++
 5 files changed, 2364 insertions(+)
 create mode 100644 crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
 create mode 100644 crates/codegraph-cli/tests/fixtures/legacy-v0.40.4/manifest.toml
 create mode 100755 scripts/setup-legacy-fixture.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e376ea9..10054bb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,6 +39,14 @@ jobs:
       - name: Clippy lint
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      # Materializes the frozen v0.40.4 legacy CLI for the Batch M legacy
+      # compatibility tests, using THIS host's NATIVE asset (linux x86_64). The
+      # script verifies the archive digest, the extracted executable digest, and
+      # the real `--version` before exporting the path. A network or digest
+      # failure fails the job here — legacy tests are never skipped.
+      - name: Prepare legacy v0.40.4 fixture (native linux asset)
+        run: echo "CODEGRAPH_LEGACY_BIN=$(bash scripts/setup-legacy-fixture.sh)" >> "$GITHUB_ENV"
+
       - name: Run tests (incl. golden oracle + sync equivalence)
         run: cargo test --workspace
 
@@ -69,6 +77,13 @@ jobs:
         # codegraph-bench is a Unix-only dev harness (publish=false); excluded from the Windows job.
         run: cargo clippy --workspace --exclude codegraph-bench --all-targets -- -D warnings
 
+      # Same fixture step, but the script selects THIS host's NATIVE asset
+      # (windows x86_64 .zip). There is no cross-execution and no emulation:
+      # the Windows legacy proof runs only here, on a real Windows runner.
+      - name: Prepare legacy v0.40.4 fixture (native windows asset)
+        shell: bash
+        run: echo "CODEGRAPH_LEGACY_BIN=$(bash scripts/setup-legacy-fixture.sh)" >> "$GITHUB_ENV"
+
       - name: Run tests
         run: cargo test --workspace --exclude codegraph-bench
 
diff --git a/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs b/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
new file mode 100644
index 0000000..cadbb34
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
@@ -0,0 +1,1825 @@
+//! Batch M acceptance item 22 — legacy scan under a runtime extension override.
+//!
+//! This target executes the REAL published v0.40.4 CLI (tag `v0.40.4` /
+//! commit `aba40799ecacb94515f7e1690914d2accc4c8973`), materialized and
+//! digest-verified by `scripts/setup-legacy-fixture.sh` from the checked-in
+//! manifest at `tests/fixtures/legacy-v0.40.4/manifest.toml`. Nothing here is
+//! built from this worktree, and there is no skip path: an unavailable or
+//! unverifiable fixture is a fixture-setup FAILURE.
+//!
+//! # The two distinct claims item 22 separates
+//!
+//! 1. **Source visibility is configuration-dependent.** The acceptance claim
+//!    "the legacy scan produces only the expected graph" holds for the DEFAULT
+//!    supported-extension configuration. An unmodified old scanner that is
+//!    EXPLICITLY configured (legacy `.codegraph/codegraph.json`) to index
+//!    `.json`/`.toml` will legitimately report v2 files such as
+//!    `.codegraph-v2/config.toml` and `.codegraph-v2/index-state.0.json` as
+//!    SOURCE. That is documented here as accepted behavior, not a defect: the
+//!    user asked for those extensions.
+//!
+//! 2. **Storage authority is configuration-independent.** For EVERY
+//!    configuration, including the override above, the old scanner writes only
+//!    into its own legacy namespace and leaves every byte of the v2 namespace
+//!    unchanged, and the v2 graph stays readable by the v2 reader afterwards.
+//!
+//! Reading a v2 artifact's TEXT as source is therefore never the same thing as
+//! holding authority over v2 storage. Assertion names below keep the two apart.
+//!
+//! # Explicit non-claims
+//!
+//! * This target says nothing about deliberately pointing the OLD binary's own
+//!   `CODEGRAPH_DIR` at the v2 root. The v0.40.4 binary predates the v2 state
+//!   protocol, treats any configured root as a plain directory, and derives no
+//!   identity-suffixed sibling; storage separation in that scenario rests on
+//!   root naming/identity, which is a different acceptance item. Item 22 is
+//!   scoped to the EXTENSION override, so the legacy runs below always use the
+//!   legacy binary's own default `.codegraph` root.
+//! * The nonmutation oracle is a sequential full-byte snapshot taken while no
+//!   other codegraph process is running. It never follows aliases and fails
+//!   closed on every I/O or unexpected-type error. Root, nested directories,
+//!   and regular files are opened and identity-corroborated before their data
+//!   becomes authoritative. Unix uses `(dev, ino)` and Windows uses raw
+//!   `GetFileInformationByHandleEx(FileIdInfo)` handle identity — an EXACT
+//!   identity on both platforms, never a size/timestamp approximation.
+//!   Only a typed `NotFound` root yields an empty snapshot; an existing root
+//!   that is an alias, a reparse point, or a non-directory fails closed.
+//!   The oracle's own gates are proven by deterministic checkpoint self-tests
+//!   below (static root alias, root replacement, nested-directory replacement,
+//!   regular-file replacement), and the frozen-binary expectation is read from
+//!   the checked-in manifest rather than duplicated here.
+
+use std::collections::BTreeMap;
+use std::fs::{self, File, Metadata, OpenOptions};
+use std::io::Read as _;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// The release-asset target triple this host would execute natively, or `None`
+/// when no v0.40.4 asset is pinned for it. Derived from RUNTIME host facts and
+/// cross-checked against the manifest by
+/// [`pinned_host_set_matches_the_fixture_manifest`].
+fn native_asset_target() -> Option<&'static str> {
+    match (std::env::consts::OS, std::env::consts::ARCH) {
+        ("linux", "x86_64") => Some("x86_64-unknown-linux-musl"),
+        ("windows", "x86_64") => Some("x86_64-pc-windows-msvc"),
+        _ => None,
+    }
+}
+
+fn new_bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LegacyExpectation {
+    executable_sha256: String,
+    version_stdout: String,
+}
+
+/// `key = "value"` from a manifest line, or `None` when the line is not that key.
+fn manifest_string_value(line: &str, key: &str) -> Option<String> {
+    let rest = line.trim_start().strip_prefix(key)?;
+    let rest = rest.trim_start().strip_prefix('=')?.trim();
+    let inner = rest.strip_prefix('"')?.strip_suffix('"')?;
+    Some(inner.to_string())
+}
+
+/// The single `[fixture]` value for `key`. Absent or duplicated is fatal: the
+/// manifest is the only authority for what the legacy binary must be.
+fn fixture_field(manifest: &str, key: &str) -> String {
+    let mut in_fixture = false;
+    let mut found: Vec<String> = Vec::new();
+    for line in manifest.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with('[') {
+            in_fixture = trimmed == "[fixture]";
+            continue;
+        }
+        if !in_fixture {
+            continue;
+        }
+        if let Some(value) = manifest_string_value(trimmed, key) {
+            found.push(value);
+        }
+    }
+    match found.len() {
+        1 => found.remove(0),
+        0 => panic!("fixture manifest [fixture] is missing key '{key}'"),
+        n => panic!("fixture manifest [fixture] declares key '{key}' {n} times"),
+    }
+}
+
+/// One `[[asset]]` block's parsed fields. Blocks are materialized as RECORDS so
+/// block cardinality survives the parse: a streaming "am I inside a matching
+/// block" boolean cannot tell one matching block from two.
+#[derive(Debug, Default)]
+struct AssetBlock {
+    targets: Vec<String>,
+    executable_sha256s: Vec<String>,
+}
+
+/// Every `[[asset]]` block in `manifest`, in file order.
+fn asset_blocks(manifest: &str) -> Vec<AssetBlock> {
+    let mut blocks: Vec<AssetBlock> = Vec::new();
+    let mut current: Option<AssetBlock> = None;
+    for line in manifest.lines() {
+        let trimmed = line.trim();
+        if trimmed == "[[asset]]" {
+            if let Some(block) = current.take() {
+                blocks.push(block);
+            }
+            current = Some(AssetBlock::default());
+            continue;
+        }
+        if trimmed.starts_with('[') {
+            if let Some(block) = current.take() {
+                blocks.push(block);
+            }
+            continue;
+        }
+        let Some(block) = current.as_mut() else {
+            continue;
+        };
+        if let Some(value) = manifest_string_value(trimmed, "target") {
+            block.targets.push(value);
+        } else if let Some(value) = manifest_string_value(trimmed, "executable_sha256") {
+            block.executable_sha256s.push(value);
+        }
+    }
+    if let Some(block) = current.take() {
+        blocks.push(block);
+    }
+    blocks
+}
+
+/// The `executable_sha256` of the single `[[asset]]` block whose `target` equals
+/// `target`.
+///
+/// Block uniqueness is structural and independent of digest presence: two blocks
+/// naming the same target are fatal even when only one of them carries a digest.
+fn asset_executable_sha256(manifest: &str, target: &str) -> String {
+    let matching = asset_blocks(manifest)
+        .into_iter()
+        .filter(|block| block.targets.iter().any(|value| value == target))
+        .collect::<Vec<_>>();
+    let block = match matching.len() {
+        1 => matching.into_iter().next().expect("one matching block"),
+        0 => panic!("fixture manifest has no [[asset]] block with target='{target}'"),
+        n => panic!("fixture manifest declares {n} [[asset]] blocks with target='{target}'"),
+    };
+
+    let digest = match block.executable_sha256s.len() {
+        1 => block
+            .executable_sha256s
+            .into_iter()
+            .next()
+            .expect("one digest"),
+        0 => panic!("fixture manifest [[asset]] target='{target}' has no executable_sha256"),
+        n => {
+            panic!(
+                "fixture manifest [[asset]] target='{target}' declares {n} executable_sha256 values"
+            )
+        }
+    };
+    assert!(
+        digest.len() == 64
+            && digest
+                .bytes()
+                .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase()),
+        "manifest executable_sha256 for {target} is not 64 lowercase hex chars: {digest:?}"
+    );
+    digest
+}
+
+/// The frozen expectation for THIS host, read from the checked-in manifest so
+/// the manifest stays the single authority (no duplicated digests in Rust).
+fn native_legacy_expectation() -> LegacyExpectation {
+    let target = native_asset_target()
+        .unwrap_or_else(|| panic!("no pinned legacy asset for this native host"));
+    let manifest = manifest_text();
+    LegacyExpectation {
+        executable_sha256: asset_executable_sha256(&manifest, target),
+        version_stdout: fixture_field(&manifest, "expected_version_stdout"),
+    }
+}
+
+fn verify_legacy_binary(path: &Path, expectation: &LegacyExpectation) -> Result<(), String> {
+    let metadata = fs::symlink_metadata(path).map_err(|error| {
+        format!(
+            "inspect configured legacy binary {}: {error}",
+            path.display()
+        )
+    })?;
+    if !is_regular(&metadata) {
+        return Err(format!(
+            "configured legacy binary is not a non-alias regular file: {}",
+            path.display()
+        ));
+    }
+    let initial_identity = identity_for_validated_path(path, &metadata).map_err(|error| {
+        format!(
+            "identify configured legacy binary {}: {error}",
+            path.display()
+        )
+    })?;
+    let mut file = open_no_follow(path, false)
+        .map_err(|error| format!("open configured legacy binary {}: {error}", path.display()))?;
+    let opened = file
+        .metadata()
+        .map_err(|error| format!("inspect opened legacy binary {}: {error}", path.display()))?;
+    if !is_regular(&opened) {
+        return Err(format!(
+            "opened configured legacy binary is not regular: {}",
+            path.display()
+        ));
+    }
+    let opened_identity = identity_for_file(&file)
+        .map_err(|error| format!("identify opened legacy binary {}: {error}", path.display()))?;
+    if opened_identity != initial_identity {
+        return Err(format!(
+            "configured legacy binary changed between validation and open: {}",
+            path.display()
+        ));
+    }
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes)
+        .map_err(|error| format!("read configured legacy binary {}: {error}", path.display()))?;
+    if identity_for_file(&file).map_err(|error| {
+        format!(
+            "reidentify legacy binary handle {}: {error}",
+            path.display()
+        )
+    })? != initial_identity
+    {
+        return Err(format!(
+            "configured legacy binary handle changed while reading: {}",
+            path.display()
+        ));
+    }
+    corroborate_fixed_path(path, initial_identity, EntryKind::RegularFile)
+        .map_err(|error| format!("configured legacy binary changed after reading: {error}"))?;
+
+    let observed_digest = sha256_hex(&bytes);
+    if observed_digest != expectation.executable_sha256 {
+        return Err(format!(
+            "configured legacy binary SHA-256 mismatch for {}: expected {}, observed {}",
+            path.display(),
+            expectation.executable_sha256,
+            observed_digest
+        ));
+    }
+
+    let output = Command::new(path)
+        .arg("--version")
+        .output()
+        .map_err(|error| {
+            format!(
+                "run configured legacy binary {} --version: {error}",
+                path.display()
+            )
+        })?;
+    if !output.status.success() {
+        return Err(format!(
+            "configured legacy binary {} --version failed with {}: {}",
+            path.display(),
+            output.status,
+            String::from_utf8_lossy(&output.stderr)
+        ));
+    }
+    let observed_version = String::from_utf8_lossy(&output.stdout)
+        .replace('\r', "")
+        .trim_end_matches('\n')
+        .to_string();
+    if observed_version != expectation.version_stdout {
+        return Err(format!(
+            "configured legacy binary version mismatch for {}: expected {:?}, observed {:?}",
+            path.display(),
+            expectation.version_stdout,
+            observed_version
+        ));
+    }
+    corroborate_fixed_path(path, initial_identity, EntryKind::RegularFile)
+        .map_err(|error| format!("configured legacy binary changed after --version: {error}"))?;
+    Ok(())
+}
+
+/// Absolute path of the verified v0.40.4 executable.
+///
+/// CI exports `CODEGRAPH_LEGACY_BIN` from an explicit setup step; a local run
+/// falls back to invoking the setup script directly. Either way the binary is
+/// digest- and `--version`-verified before any test uses it, and any failure
+/// panics as a fixture-setup failure rather than skipping the test.
+fn legacy_bin() -> PathBuf {
+    let expectation = native_legacy_expectation();
+    if let Some(configured) = std::env::var_os("CODEGRAPH_LEGACY_BIN") {
+        let path = PathBuf::from(configured);
+        verify_legacy_binary(&path, &expectation).unwrap_or_else(|error| {
+            panic!("CODEGRAPH_LEGACY_BIN failed frozen fixture verification: {error}")
+        });
+        return path;
+    }
+
+    let script = workspace_root().join("scripts/setup-legacy-fixture.sh");
+    let output = Command::new("bash")
+        .arg(&script)
+        .current_dir(workspace_root())
+        .output()
+        .unwrap_or_else(|error| {
+            panic!(
+                "fixture setup could not run {}: {error}\n\
+                 The legacy-compatibility fixture is mandatory; this is a setup failure.",
+                script.display()
+            )
+        });
+    assert!(
+        output.status.success(),
+        "fixture setup failed ({}). This is a FIXTURE-SETUP FAILURE, never a skipped test.\n\
+         stdout:\n{}\nstderr:\n{}",
+        output.status,
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+    let path = stdout
+        .lines()
+        .rfind(|line| !line.trim().is_empty())
+        .map(str::trim)
+        .unwrap_or_else(|| panic!("fixture setup printed no executable path"));
+    let path = PathBuf::from(path);
+    verify_legacy_binary(&path, &expectation)
+        .unwrap_or_else(|error| panic!("fixture setup returned an unverified binary: {error}"));
+    path
+}
+
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-batchm-item22-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock after epoch")
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).expect("create item-22 test directory");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    fs::create_dir_all(dst).expect("create fixture destination");
+    for entry in fs::read_dir(src).expect("read fixture directory") {
+        let entry = entry.expect("read fixture entry");
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            fs::copy(&from, &to).expect("copy fixture file");
+        }
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+impl Run {
+    fn expect_ok(self, what: &str) -> Self {
+        assert!(
+            self.ok,
+            "{what} must succeed.\nstdout:\n{}\nstderr:\n{}",
+            self.stdout, self.stderr
+        );
+        self
+    }
+}
+
+/// Runs a codegraph binary with a deliberately clean environment: no inherited
+/// `CODEGRAPH_DIR`, no daemon, and an isolated HTTP registry.
+fn run(binary: &Path, project: &Path, args: &[&str]) -> Run {
+    let output = Command::new(binary)
+        .current_dir(project)
+        .args(args)
+        .env_remove("CODEGRAPH_DIR")
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1")
+        .env("CODEGRAPH_HTTP_REGISTRY_DIR", project)
+        .output()
+        .unwrap_or_else(|error| panic!("run {}: {error}", binary.display()));
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+/// The root-relative paths reported by `codegraph files`, normalized to `/`.
+///
+/// `files` prints `  <path> (<language>, <n> symbols)`; only those lines carry a
+/// path, so the parse is exact rather than a substring search.
+fn reported_files(listing: &str) -> Vec<String> {
+    let mut out = listing
+        .lines()
+        .filter_map(|line| {
+            let body = line.strip_prefix("  ")?;
+            if body.starts_with(' ') {
+                return None;
+            }
+            let (path, rest) = body.rsplit_once(" (")?;
+            if !rest.ends_with(')') {
+                return None;
+            }
+            Some(path.trim().replace('\\', "/"))
+        })
+        .collect::<Vec<_>>();
+    out.sort();
+    out.dedup();
+    out
+}
+
+// ---------------------------------------------------------------------------
+// Fail-closed nonmutation oracle
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, PartialEq, Eq)]
+enum Entry {
+    Directory,
+    RegularFile(Vec<u8>),
+    Symlink(PathBuf),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum SnapshotCheckpoint {
+    DirectoryPathValidated,
+    DirectoryHandleAndPathCorroborated,
+    DirectoryEnumerationCorroborated,
+    RegularPathValidated,
+    RegularHandleCorroborated,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum SnapshotError {
+    /// A fixed path's identity stopped matching the identity captured for it, so
+    /// nothing observed through that path may be trusted.
+    PathChangedDuringRead(PathBuf),
+    /// The snapshot root exists but is not a non-alias directory (a symlink, a
+    /// Windows reparse point, or a non-directory). Never a successful snapshot:
+    /// only a typed `NotFound` may yield an empty one.
+    RootNotANonAliasDirectory(PathBuf),
+}
+
+impl std::fmt::Display for SnapshotError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::PathChangedDuringRead(path) => {
+                write!(f, "path identity changed during read: {}", path.display())
+            }
+            Self::RootNotANonAliasDirectory(path) => write!(
+                f,
+                "snapshot root is not a non-alias directory: {}",
+                path.display()
+            ),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum EntryKind {
+    Directory,
+    RegularFile,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum FileIdentity {
+    #[cfg(unix)]
+    Unix { device: u64, inode: u64 },
+    #[cfg(windows)]
+    Windows {
+        volume_serial_number: u64,
+        file_id: [u8; 16],
+    },
+    #[cfg(not(any(unix, windows)))]
+    Portable {
+        len: u64,
+        modified: Option<std::time::SystemTime>,
+        created: Option<std::time::SystemTime>,
+    },
+}
+
+fn is_alias(metadata: &Metadata) -> bool {
+    if metadata.file_type().is_symlink() {
+        return true;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt as _;
+        const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
+        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0;
+    }
+    #[cfg(not(windows))]
+    false
+}
+
+fn is_kind(metadata: &Metadata, kind: EntryKind) -> bool {
+    !is_alias(metadata)
+        && match kind {
+            EntryKind::Directory => metadata.file_type().is_dir(),
+            EntryKind::RegularFile => metadata.file_type().is_file(),
+        }
+}
+
+fn is_regular(metadata: &Metadata) -> bool {
+    is_kind(metadata, EntryKind::RegularFile)
+}
+
+fn identity_for_file(file: &File) -> std::io::Result<FileIdentity> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt as _;
+        let metadata = file.metadata()?;
+        Ok(FileIdentity::Unix {
+            device: metadata.dev(),
+            inode: metadata.ino(),
+        })
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::io::AsRawHandle as _;
+
+        const FILE_ID_INFO_CLASS: i32 = 18;
+        #[repr(C)]
+        struct FileIdInfo {
+            volume_serial_number: u64,
+            file_id: [u8; 16],
+        }
+        #[link(name = "kernel32")]
+        unsafe extern "system" {
+            fn GetFileInformationByHandleEx(
+                h_file: isize,
+                file_information_class: i32,
+                lp_file_information: *mut core::ffi::c_void,
+                dw_buffer_size: u32,
+            ) -> i32;
+        }
+
+        let mut info = FileIdInfo {
+            volume_serial_number: 0,
+            file_id: [0; 16],
+        };
+        let ok = unsafe {
+            GetFileInformationByHandleEx(
+                file.as_raw_handle() as isize,
+                FILE_ID_INFO_CLASS,
+                (&mut info as *mut FileIdInfo).cast(),
+                core::mem::size_of::<FileIdInfo>() as u32,
+            )
+        };
+        if ok == 0 {
+            return Err(std::io::Error::last_os_error());
+        }
+        Ok(FileIdentity::Windows {
+            volume_serial_number: info.volume_serial_number,
+            file_id: info.file_id,
+        })
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let metadata = file.metadata()?;
+        Ok(FileIdentity::Portable {
+            len: metadata.len(),
+            modified: metadata.modified().ok(),
+            created: metadata.created().ok(),
+        })
+    }
+}
+
+fn open_no_follow(path: &Path, directory: bool) -> std::io::Result<File> {
+    let mut options = OpenOptions::new();
+    options.read(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt as _;
+        #[cfg(any(target_os = "linux", target_os = "android"))]
+        const O_NOFOLLOW: i32 = 0x0002_0000;
+        #[cfg(not(any(target_os = "linux", target_os = "android")))]
+        const O_NOFOLLOW: i32 = 0x0000_0100;
+        let _ = directory;
+        options.custom_flags(O_NOFOLLOW);
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::OpenOptionsExt as _;
+        const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;
+        const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
+        let flags = FILE_FLAG_OPEN_REPARSE_POINT
+            | if directory {
+                FILE_FLAG_BACKUP_SEMANTICS
+            } else {
+                0
+            };
+        options.custom_flags(flags);
+    }
+    #[cfg(not(any(unix, windows)))]
+    let _ = directory;
+    options.open(path)
+}
+
+fn identity_for_validated_path(path: &Path, metadata: &Metadata) -> std::io::Result<FileIdentity> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt as _;
+        let _ = path;
+        Ok(FileIdentity::Unix {
+            device: metadata.dev(),
+            inode: metadata.ino(),
+        })
+    }
+    #[cfg(windows)]
+    {
+        let directory = metadata.file_type().is_dir();
+        let file = open_no_follow(path, directory)?;
+        let opened = file.metadata()?;
+        if !is_kind(
+            &opened,
+            if directory {
+                EntryKind::Directory
+            } else {
+                EntryKind::RegularFile
+            },
+        ) {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                "validated path changed type before identity capture",
+            ));
+        }
+        identity_for_file(&file)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = path;
+        Ok(FileIdentity::Portable {
+            len: metadata.len(),
+            modified: metadata.modified().ok(),
+            created: metadata.created().ok(),
+        })
+    }
+}
+
+fn corroborate_fixed_path(
+    path: &Path,
+    expected: FileIdentity,
+    kind: EntryKind,
+) -> Result<(), SnapshotError> {
+    let metadata = match fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+        }
+        Err(error) => panic!("snapshot reinspect {}: {error}", path.display()),
+    };
+    if !is_kind(&metadata, kind) {
+        return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+    }
+    let reopened = match open_no_follow(path, kind == EntryKind::Directory) {
+        Ok(file) => file,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+        }
+        Err(error) => panic!("snapshot reopen {}: {error}", path.display()),
+    };
+    let reopened_metadata = reopened
+        .metadata()
+        .unwrap_or_else(|error| panic!("snapshot reopened metadata {}: {error}", path.display()));
+    let reopened_identity = identity_for_file(&reopened)
+        .unwrap_or_else(|error| panic!("snapshot reopened identity {}: {error}", path.display()));
+    if !is_kind(&reopened_metadata, kind) || reopened_identity != expected {
+        return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+    }
+    Ok(())
+}
+
+/// Full-byte, alias-free snapshot of `root`.
+///
+/// Directories are recorded as entries (so an added empty directory is visible),
+/// regular files carry their COMPLETE bytes read through an opened handle,
+/// and symlinks record their target without ever being followed. Every I/O
+/// error and every unsupported entry kind panics, so the helper can never
+/// report a false "unchanged".
+fn snapshot(root: &Path) -> BTreeMap<PathBuf, Entry> {
+    snapshot_with_checkpoint(root, |_, _| {}).expect("snapshot path identities remain stable")
+}
+
+fn snapshot_with_checkpoint<F>(
+    root: &Path,
+    mut checkpoint: F,
+) -> Result<BTreeMap<PathBuf, Entry>, SnapshotError>
+where
+    F: FnMut(&Path, SnapshotCheckpoint),
+{
+    fn read_regular_bytes<F>(
+        path: &Path,
+        initial_identity: FileIdentity,
+        checkpoint: &mut F,
+    ) -> Result<Vec<u8>, SnapshotError>
+    where
+        F: FnMut(&Path, SnapshotCheckpoint),
+    {
+        let mut file = match open_no_follow(path, false) {
+            Ok(file) => file,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+            }
+            Err(error) => panic!("snapshot open {}: {error}", path.display()),
+        };
+        let opened = file
+            .metadata()
+            .unwrap_or_else(|error| panic!("snapshot opened metadata {}: {error}", path.display()));
+        let opened_identity = identity_for_file(&file)
+            .unwrap_or_else(|error| panic!("snapshot opened identity {}: {error}", path.display()));
+        if !is_regular(&opened) || opened_identity != initial_identity {
+            return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+        }
+        corroborate_fixed_path(path, initial_identity, EntryKind::RegularFile)?;
+        checkpoint(path, SnapshotCheckpoint::RegularHandleCorroborated);
+        let mut bytes = Vec::new();
+        file.read_to_end(&mut bytes)
+            .unwrap_or_else(|error| panic!("snapshot read {}: {error}", path.display()));
+        let after_read_identity = identity_for_file(&file).unwrap_or_else(|error| {
+            panic!("snapshot post-read identity {}: {error}", path.display())
+        });
+        if after_read_identity != initial_identity {
+            return Err(SnapshotError::PathChangedDuringRead(path.to_path_buf()));
+        }
+        corroborate_fixed_path(path, initial_identity, EntryKind::RegularFile)?;
+        Ok(bytes)
+    }
+
+    fn walk<F>(
+        root: &Path,
+        directory: &Path,
+        initial_identity: FileIdentity,
+        out: &mut BTreeMap<PathBuf, Entry>,
+        checkpoint: &mut F,
+    ) -> Result<(), SnapshotError>
+    where
+        F: FnMut(&Path, SnapshotCheckpoint),
+    {
+        let opened_directory = match open_no_follow(directory, true) {
+            Ok(file) => file,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                return Err(SnapshotError::PathChangedDuringRead(
+                    directory.to_path_buf(),
+                ));
+            }
+            Err(error) => panic!("snapshot open directory {}: {error}", directory.display()),
+        };
+        let opened_metadata = opened_directory.metadata().unwrap_or_else(|error| {
+            panic!(
+                "snapshot opened directory metadata {}: {error}",
+                directory.display()
+            )
+        });
+        let opened_identity = identity_for_file(&opened_directory).unwrap_or_else(|error| {
+            panic!(
+                "snapshot opened directory identity {}: {error}",
+                directory.display()
+            )
+        });
+        if !is_kind(&opened_metadata, EntryKind::Directory) || opened_identity != initial_identity {
+            return Err(SnapshotError::PathChangedDuringRead(
+                directory.to_path_buf(),
+            ));
+        }
+        corroborate_fixed_path(directory, initial_identity, EntryKind::Directory)?;
+        checkpoint(
+            directory,
+            SnapshotCheckpoint::DirectoryHandleAndPathCorroborated,
+        );
+
+        let entries = fs::read_dir(directory)
+            .unwrap_or_else(|error| panic!("snapshot read_dir {}: {error}", directory.display()));
+        let mut children = Vec::new();
+        for entry in entries {
+            children.push(
+                entry
+                    .unwrap_or_else(|error| {
+                        panic!("snapshot entry in {}: {error}", directory.display())
+                    })
+                    .path(),
+            );
+        }
+        corroborate_fixed_path(directory, initial_identity, EntryKind::Directory)?;
+        checkpoint(
+            directory,
+            SnapshotCheckpoint::DirectoryEnumerationCorroborated,
+        );
+        children.sort();
+
+        for path in children {
+            let relative = path
+                .strip_prefix(root)
+                .unwrap_or_else(|error| panic!("snapshot strip {}: {error}", path.display()))
+                .to_path_buf();
+            let metadata = match fs::symlink_metadata(&path) {
+                Ok(metadata) => metadata,
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                    return Err(SnapshotError::PathChangedDuringRead(path));
+                }
+                Err(error) => panic!("snapshot metadata {}: {error}", path.display()),
+            };
+            let file_type = metadata.file_type();
+            let entry = if is_kind(&metadata, EntryKind::Directory) {
+                Entry::Directory
+            } else if is_regular(&metadata) {
+                let identity =
+                    identity_for_validated_path(&path, &metadata).unwrap_or_else(|error| {
+                        panic!("snapshot initial file identity {}: {error}", path.display())
+                    });
+                checkpoint(&path, SnapshotCheckpoint::RegularPathValidated);
+                Entry::RegularFile(read_regular_bytes(&path, identity, checkpoint)?)
+            } else if file_type.is_symlink() || is_alias(&metadata) {
+                Entry::Symlink(fs::read_link(&path).unwrap_or_else(|error| {
+                    panic!("snapshot read_link {}: {error}", path.display())
+                }))
+            } else {
+                panic!("snapshot unsupported entry kind: {}", path.display());
+            };
+            assert!(
+                out.insert(relative, entry).is_none(),
+                "duplicate snapshot path under {}",
+                root.display()
+            );
+            if is_kind(&metadata, EntryKind::Directory) {
+                let identity =
+                    identity_for_validated_path(&path, &metadata).unwrap_or_else(|error| {
+                        panic!(
+                            "snapshot initial directory identity {}: {error}",
+                            path.display()
+                        )
+                    });
+                checkpoint(&path, SnapshotCheckpoint::DirectoryPathValidated);
+                walk(root, &path, identity, out, checkpoint)?;
+            }
+        }
+        corroborate_fixed_path(directory, initial_identity, EntryKind::Directory)?;
+        Ok(())
+    }
+
+    let metadata = match fs::symlink_metadata(root) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(BTreeMap::new());
+        }
+        Err(error) => panic!("snapshot root metadata {}: {error}", root.display()),
+    };
+    if !is_kind(&metadata, EntryKind::Directory) {
+        return Err(SnapshotError::RootNotANonAliasDirectory(root.to_path_buf()));
+    }
+    let identity = identity_for_validated_path(root, &metadata)
+        .unwrap_or_else(|error| panic!("snapshot root identity {}: {error}", root.display()));
+    checkpoint(root, SnapshotCheckpoint::DirectoryPathValidated);
+    let mut out = BTreeMap::new();
+    walk(root, root, identity, &mut out, &mut checkpoint)?;
+    Ok(out)
+}
+
+fn assert_unchanged(
+    before: &BTreeMap<PathBuf, Entry>,
+    after: &BTreeMap<PathBuf, Entry>,
+    what: &str,
+) {
+    let mut paths = before
+        .keys()
+        .chain(after.keys())
+        .cloned()
+        .collect::<Vec<_>>();
+    paths.sort();
+    paths.dedup();
+    let changed = paths
+        .into_iter()
+        .filter(|path| before.get(path) != after.get(path))
+        .map(|path| {
+            let label = |entry: Option<&Entry>| match entry {
+                None => "absent".to_string(),
+                Some(Entry::Directory) => "directory".to_string(),
+                Some(Entry::RegularFile(bytes)) => format!("file[{} bytes]", bytes.len()),
+                Some(Entry::Symlink(target)) => format!("symlink -> {}", target.display()),
+            };
+            format!(
+                "{}: {} => {}",
+                path.display(),
+                label(before.get(&path)),
+                label(after.get(&path))
+            )
+        })
+        .collect::<Vec<_>>();
+    assert!(changed.is_empty(), "{what} changed entries: {changed:?}");
+}
+
+/// The checked-in fixture manifest's text.
+fn manifest_text() -> String {
+    fs::read_to_string(
+        Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/legacy-v0.40.4/manifest.toml"),
+    )
+    .expect("read the legacy fixture manifest")
+}
+
+/// A v2 artifact path, as the legacy scanner would report it.
+const V2_CONFIG_TOML: &str = ".codegraph-v2/config.toml";
+const V2_EXTENSION_JSON: &str = ".codegraph-v2/codegraph.json";
+/// A symbol that exists ONLY inside the v2 database — its source file is deleted
+/// before any legacy run, so any legacy graph that surfaced it could only have
+/// read v2 storage.
+const V2_ONLY_SYMBOL: &str = "v2OnlyTrapSymbol";
+
+/// Item 22. Both halves in one target so the two claims cannot drift apart:
+/// the DEFAULT-configuration graph claim, and the every-configuration storage
+/// claim under an explicit `.json`/`.toml` extension override.
+///
+/// The proof runs natively on every host that has a pinned v0.40.4 asset
+/// (linux/x86_64 and windows/x86_64 — the two CI jobs). A host with no pinned
+/// asset cannot execute the real legacy binary at all; it says so LOUDLY and
+/// asserts the manifest genuinely has no entry for it, so an unpinned pass can
+/// never be mistaken for legacy coverage.
+#[test]
+fn legacy_scan_with_runtime_extension_override_does_not_weaken_storage_safety() {
+    let Some(asset_target) = native_asset_target() else {
+        let manifest = manifest_text();
+        assert!(
+            !manifest.contains(&format!("target_os = \"{}\"", std::env::consts::OS))
+                || !manifest.contains(&format!("target_arch = \"{}\"", std::env::consts::ARCH)),
+            "the manifest appears to pin {}/{} — the real item-22 proof must run here \
+             instead of reporting no coverage",
+            std::env::consts::OS,
+            std::env::consts::ARCH
+        );
+        eprintln!(
+            "item 22 NOT COVERED on this host: no pinned v0.40.4 asset for {}/{}. \
+             The legacy proof executes the real published binary natively on \
+             linux/x86_64 and windows/x86_64 only; do NOT read this pass as \
+             legacy-compatibility coverage.",
+            std::env::consts::OS,
+            std::env::consts::ARCH
+        );
+        return;
+    };
+    assert!(
+        manifest_text().contains(&format!("target = \"{asset_target}\"")),
+        "the fixture manifest must pin an asset for this native host ({asset_target})"
+    );
+
+    let legacy = legacy_bin();
+    let dir = TestDir::new("override");
+    let project = dir.path().join("mini");
+    copy_tree(&mini_fixture(), &project);
+
+    // A v2-only symbol: indexed by the CURRENT binary, then its source removed.
+    // Afterwards the string lives in v2 storage and nowhere on disk as source.
+    let trap_source = project.join("src").join("v2_trap.ts");
+    fs::write(
+        &trap_source,
+        format!("export function {V2_ONLY_SYMBOL}(): number {{\n  return 42;\n}}\n"),
+    )
+    .expect("write v2-only trap source");
+    run(&new_bin(), &project, &["init", "."]).expect_ok("v2 init");
+    fs::remove_file(&trap_source).expect("remove v2-only trap source");
+
+    let v2_root = project.join(".codegraph-v2");
+    // Project-scoped v2 config/extension artifacts: exactly the TOML/JSON files
+    // an extension override would claim as source.
+    fs::write(v2_root.join("config.toml"), "[app]\nname = \"codegraph\"\n")
+        .expect("write v2 project config");
+    fs::write(
+        v2_root.join("codegraph.json"),
+        "{\"extensions\":{\".zz\":\"lua\"}}\n",
+    )
+    .expect("write v2 extension config");
+
+    let v2_before = snapshot(&v2_root);
+    assert!(
+        v2_before.contains_key(Path::new("codegraph.db")),
+        "setup: the v2 namespace must hold a database before the legacy runs"
+    );
+    let v2_db_bytes = fs::read(v2_root.join("codegraph.db")).expect("read v2 database bytes");
+    assert!(
+        contains_bytes(&v2_db_bytes, V2_ONLY_SYMBOL.as_bytes()),
+        "setup: the v2-only symbol must be present in v2 storage"
+    );
+    let sources_before = snapshot(&project.join("src"));
+    let tools_before = snapshot(&project.join("tools"));
+
+    // ---------------------------------------------------------------------
+    // Claim 1 — DEFAULT supported-extension configuration: only the expected
+    // source graph. No legacy extension override exists yet.
+    // ---------------------------------------------------------------------
+    run(&legacy, &project, &["init", "."]).expect_ok("legacy init with default extensions");
+    let default_listing = run(&legacy, &project, &["files"])
+        .expect_ok("legacy files with default extensions")
+        .stdout;
+    assert_eq!(
+        reported_files(&default_listing),
+        vec![
+            "src/app.ts".to_string(),
+            "src/math.ts".to_string(),
+            "tools/greeter.py".to_string(),
+        ],
+        "with the DEFAULT supported-extension configuration the legacy scan must \
+         report only the expected source graph"
+    );
+
+    let legacy_root = project.join(".codegraph");
+    assert!(
+        legacy_root.join("codegraph.db").is_file(),
+        "the legacy binary must write its own legacy-namespace database"
+    );
+    assert_unchanged(
+        &v2_before,
+        &snapshot(&v2_root),
+        "default-configuration legacy scan",
+    );
+
+    // ---------------------------------------------------------------------
+    // Claim 2 — EXPLICIT runtime extension override. The old scanner is told to
+    // treat `.json`/`.toml` as source, so it MAY now report v2 artifacts as
+    // source. Storage authority must not move an inch.
+    // ---------------------------------------------------------------------
+    fs::write(
+        legacy_root.join("codegraph.json"),
+        "{\"extensions\":{\".json\":\"javascript\",\".toml\":\"javascript\"}}\n",
+    )
+    .expect("write legacy runtime extension override");
+
+    run(&legacy, &project, &["index", "--force", "."])
+        .expect_ok("legacy index --force under the extension override");
+    let override_listing = run(&legacy, &project, &["files"])
+        .expect_ok("legacy files under the extension override")
+        .stdout;
+    let override_reported = reported_files(&override_listing);
+
+    // DOCUMENTED, ACCEPTED source visibility: this is the whole point of item 22.
+    // The old scanner was explicitly configured for these extensions, so
+    // reporting v2 JSON/TOML as SOURCE is correct behavior, not a leak.
+    assert!(
+        override_reported.iter().any(|path| path == V2_CONFIG_TOML),
+        "an explicitly configured `.toml` extension is expected to make the old \
+         scanner report {V2_CONFIG_TOML} as source; reported: {override_reported:?}"
+    );
+    assert!(
+        override_reported
+            .iter()
+            .any(|path| path == V2_EXTENSION_JSON),
+        "an explicitly configured `.json` extension is expected to make the old \
+         scanner report {V2_EXTENSION_JSON} as source; reported: {override_reported:?}"
+    );
+    // The expected source graph is still fully present; the override only ADDS.
+    for expected in ["src/app.ts", "src/math.ts", "tools/greeter.py"] {
+        assert!(
+            override_reported.iter().any(|path| path == expected),
+            "the override must not drop expected source {expected}; reported: \
+             {override_reported:?}"
+        );
+    }
+
+    // STORAGE AUTHORITY — unchanged for this configuration too.
+    assert_unchanged(
+        &v2_before,
+        &snapshot(&v2_root),
+        "extension-override legacy scan",
+    );
+    assert_unchanged(
+        &sources_before,
+        &snapshot(&project.join("src")),
+        "extension-override legacy scan (source tree)",
+    );
+    assert_unchanged(
+        &tools_before,
+        &snapshot(&project.join("tools")),
+        "extension-override legacy scan (tools tree)",
+    );
+
+    // Reading a v2 file's TEXT never grants v2 graph authority: the v2-only
+    // symbol is absent from the legacy database and from the legacy graph, even
+    // though the override let the scanner read v2 config text.
+    let legacy_db_bytes =
+        fs::read(legacy_root.join("codegraph.db")).expect("read legacy database bytes");
+    assert!(
+        !contains_bytes(&legacy_db_bytes, V2_ONLY_SYMBOL.as_bytes()),
+        "the legacy database must not contain the v2-only symbol"
+    );
+    let legacy_query = run(&legacy, &project, &["query", V2_ONLY_SYMBOL])
+        .expect_ok("legacy query for the v2-only symbol");
+    // The query echoes the search term, so match on the RESULT shape instead of
+    // the term: a hit prints `Search Results for "…":` followed by rows, a miss
+    // prints `No results found for "…"`.
+    assert!(
+        legacy_query.stdout.contains("No results found"),
+        "the legacy graph must not serve the v2-only symbol.\nstdout:\n{}",
+        legacy_query.stdout
+    );
+    assert!(
+        !legacy_query.stdout.contains("Search Results for"),
+        "the legacy graph must return no result rows for the v2-only symbol.\nstdout:\n{}",
+        legacy_query.stdout
+    );
+
+    // And the v2 graph is still fully usable by the v2 reader afterwards.
+    let v2_query = run(&new_bin(), &project, &["query", V2_ONLY_SYMBOL])
+        .expect_ok("v2 query after the legacy override runs");
+    assert!(
+        v2_query.stdout.contains("Search Results for") && v2_query.stdout.contains("v2_trap.ts"),
+        "the v2 graph must still serve its own symbol after the legacy runs.\nstdout:\n{}",
+        v2_query.stdout
+    );
+    assert_unchanged(
+        &v2_before,
+        &snapshot(&v2_root),
+        "v2 read after the extension-override legacy scan",
+    );
+}
+
+fn contains_bytes(haystack: &[u8], needle: &[u8]) -> bool {
+    haystack
+        .windows(needle.len())
+        .any(|window| window == needle)
+}
+
+/// FIPS 180-4 SHA-256 over `bytes`, lowercase hex.
+///
+/// Test-local on purpose: the crate under test must gain no dependency for a
+/// fixture check. Correctness is pinned by [`sha256_hex_matches_known_vectors`]
+/// against the published NIST vectors, so the legacy-binary digest gate never
+/// rests on an unverified hash.
+fn sha256_hex(bytes: &[u8]) -> String {
+    const K: [u32; 64] = [
+        0x428a_2f98,
+        0x7137_4491,
+        0xb5c0_fbcf,
+        0xe9b5_dba5,
+        0x3956_c25b,
+        0x59f1_11f1,
+        0x923f_82a4,
+        0xab1c_5ed5,
+        0xd807_aa98,
+        0x1283_5b01,
+        0x2431_85be,
+        0x550c_7dc3,
+        0x72be_5d74,
+        0x80de_b1fe,
+        0x9bdc_06a7,
+        0xc19b_f174,
+        0xe49b_69c1,
+        0xefbe_4786,
+        0x0fc1_9dc6,
+        0x240c_a1cc,
+        0x2de9_2c6f,
+        0x4a74_84aa,
+        0x5cb0_a9dc,
+        0x76f9_88da,
+        0x983e_5152,
+        0xa831_c66d,
+        0xb003_27c8,
+        0xbf59_7fc7,
+        0xc6e0_0bf3,
+        0xd5a7_9147,
+        0x06ca_6351,
+        0x1429_2967,
+        0x27b7_0a85,
+        0x2e1b_2138,
+        0x4d2c_6dfc,
+        0x5338_0d13,
+        0x650a_7354,
+        0x766a_0abb,
+        0x81c2_c92e,
+        0x9272_2c85,
+        0xa2bf_e8a1,
+        0xa81a_664b,
+        0xc24b_8b70,
+        0xc76c_51a3,
+        0xd192_e819,
+        0xd699_0624,
+        0xf40e_3585,
+        0x106a_a070,
+        0x19a4_c116,
+        0x1e37_6c08,
+        0x2748_774c,
+        0x34b0_bcb5,
+        0x391c_0cb3,
+        0x4ed8_aa4a,
+        0x5b9c_ca4f,
+        0x682e_6ff3,
+        0x748f_82ee,
+        0x78a5_636f,
+        0x84c8_7814,
+        0x8cc7_0208,
+        0x90be_fffa,
+        0xa450_6ceb,
+        0xbef9_a3f7,
+        0xc671_78f2,
+    ];
+    let mut state: [u32; 8] = [
+        0x6a09_e667,
+        0xbb67_ae85,
+        0x3c6e_f372,
+        0xa54f_f53a,
+        0x510e_527f,
+        0x9b05_688c,
+        0x1f83_d9ab,
+        0x5be0_cd19,
+    ];
+
+    let mut message = bytes.to_vec();
+    let bit_length = (bytes.len() as u64) * 8;
+    message.push(0x80);
+    while message.len() % 64 != 56 {
+        message.push(0);
+    }
+    message.extend_from_slice(&bit_length.to_be_bytes());
+
+    for chunk in message.chunks_exact(64) {
+        let mut w = [0u32; 64];
+        for (index, word) in chunk.chunks_exact(4).enumerate() {
+            w[index] = u32::from_be_bytes([word[0], word[1], word[2], word[3]]);
+        }
+        for index in 16..64 {
+            let s0 = w[index - 15].rotate_right(7)
+                ^ w[index - 15].rotate_right(18)
+                ^ (w[index - 15] >> 3);
+            let s1 = w[index - 2].rotate_right(17)
+                ^ w[index - 2].rotate_right(19)
+                ^ (w[index - 2] >> 10);
+            w[index] = w[index - 16]
+                .wrapping_add(s0)
+                .wrapping_add(w[index - 7])
+                .wrapping_add(s1);
+        }
+
+        let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut h] = state;
+        for index in 0..64 {
+            let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
+            let ch = (e & f) ^ ((!e) & g);
+            let temp1 = h
+                .wrapping_add(s1)
+                .wrapping_add(ch)
+                .wrapping_add(K[index])
+                .wrapping_add(w[index]);
+            let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
+            let maj = (a & b) ^ (a & c) ^ (b & c);
+            let temp2 = s0.wrapping_add(maj);
+
+            h = g;
+            g = f;
+            f = e;
+            e = d.wrapping_add(temp1);
+            d = c;
+            c = b;
+            b = a;
+            a = temp1.wrapping_add(temp2);
+        }
+        for (slot, value) in state.iter_mut().zip([a, b, c, d, e, f, g, h]) {
+            *slot = slot.wrapping_add(value);
+        }
+    }
+
+    let mut out = String::with_capacity(64);
+    for word in state {
+        for byte in word.to_be_bytes() {
+            out.push(char::from_digit((byte >> 4) as u32, 16).expect("hex nibble"));
+            out.push(char::from_digit((byte & 0x0f) as u32, 16).expect("hex nibble"));
+        }
+    }
+    out
+}
+
+/// Harness self-test: the nonmutation oracle must FAIL on an equal-length
+/// in-place byte change, so an "unchanged" verdict above is real byte proof and
+/// not a size comparison.
+#[test]
+fn snapshot_detects_equal_length_byte_mutation() {
+    let dir = TestDir::new("selftest");
+    let root = dir.path().join("ns");
+    fs::create_dir_all(root.join("nested")).expect("create nested snapshot directory");
+    let file = root.join("nested").join("a.bin");
+    fs::write(&file, b"AAAA").expect("write self-test bytes");
+
+    let before = snapshot(&root);
+    fs::write(&file, b"AAAB").expect("equal-length in-place mutation");
+    let after = snapshot(&root);
+
+    let failed =
+        std::panic::catch_unwind(|| assert_unchanged(&before, &after, "self-test")).is_err();
+    assert!(
+        failed,
+        "the nonmutation oracle must reject an equal-length byte mutation"
+    );
+}
+
+/// Guards the native-host mapping against silent drift from the fixture
+/// manifest and the two CI jobs that execute the proof.
+#[test]
+fn pinned_host_set_matches_the_fixture_manifest() {
+    let manifest = manifest_text();
+    let targets = manifest
+        .lines()
+        .filter_map(|line| line.trim().strip_prefix("target = "))
+        .map(|value| value.trim().trim_matches('"').to_string())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        targets,
+        vec![
+            "x86_64-unknown-linux-musl".to_string(),
+            "x86_64-pc-windows-msvc".to_string(),
+        ],
+        "the manifest must pin exactly the two natively-executed CI hosts"
+    );
+    // The runtime host mapping must agree with the manifest: a mapped host has
+    // a manifest entry, and an unmapped host has none.
+    match native_asset_target() {
+        Some(target) => assert!(
+            targets.iter().any(|pinned| pinned == target),
+            "native_asset_target() returned {target}, absent from the manifest: {targets:?}"
+        ),
+        None => assert!(
+            !manifest.contains(&format!("target_os = \"{}\"", std::env::consts::OS))
+                || !manifest.contains(&format!("target_arch = \"{}\"", std::env::consts::ARCH)),
+            "native_asset_target() reported no pinned asset for {}/{} while the \
+             manifest pins it",
+            std::env::consts::OS,
+            std::env::consts::ARCH
+        ),
+    }
+}
+
+/// The published NIST SHA-256 vectors. Without this the legacy-binary digest
+/// gate would rest on an unverified hand-written hash.
+#[test]
+fn sha256_hex_matches_known_vectors() {
+    assert_eq!(
+        sha256_hex(b""),
+        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    );
+    assert_eq!(
+        sha256_hex(b"abc"),
+        "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+    );
+    assert_eq!(
+        sha256_hex(b"abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"),
+        "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"
+    );
+    // Spans the 56-byte padding boundary, where a length-encoding slip hides.
+    assert_eq!(
+        sha256_hex(&[b'a'; 64]),
+        "ffe054fe7ae0cb6dc65c3af9b61d5209f439851db43d0ba5997337df154668eb"
+    );
+}
+
+/// The expectation must come from the checked-in manifest, not from constants
+/// duplicated in this file.
+#[test]
+fn native_legacy_expectation_is_read_from_the_manifest() {
+    if native_asset_target().is_none() {
+        return;
+    }
+    let expectation = native_legacy_expectation();
+    let manifest = manifest_text();
+    assert!(
+        manifest.contains(&expectation.executable_sha256),
+        "the native executable digest must be the manifest's own value"
+    );
+    assert!(
+        manifest.contains(&format!(
+            "expected_version_stdout = \"{}\"",
+            expectation.version_stdout
+        )),
+        "the expected version must be the manifest's own value"
+    );
+}
+
+#[test]
+fn manifest_asset_lookup_rejects_an_unpinned_target() {
+    let manifest = manifest_text();
+    let missing = std::panic::catch_unwind(|| {
+        asset_executable_sha256(&manifest, "aarch64-unknown-linux-gnu")
+    });
+    assert!(
+        missing.is_err(),
+        "an unpinned target must fail loudly instead of yielding a digest"
+    );
+}
+
+/// A synthetic `[[asset]]` block for the parser regressions below.
+fn synthetic_asset(target: &str, digests: &[&str]) -> String {
+    let mut block = format!("[[asset]]\ntarget = \"{target}\"\n");
+    for digest in digests {
+        block.push_str(&format!("executable_sha256 = \"{digest}\"\n"));
+    }
+    block
+}
+
+fn lookup_panics(manifest: &str, target: &str) -> bool {
+    let manifest = manifest.to_string();
+    let target = target.to_string();
+    std::panic::catch_unwind(move || asset_executable_sha256(&manifest, &target)).is_err()
+}
+
+/// Both carry hex LETTERS, so `to_uppercase()` in the malformed-digest test is a
+/// real change rather than a no-op on an all-digit string.
+const GOOD_DIGEST: &str = "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1";
+const OTHER_DIGEST: &str = "b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2";
+
+/// A single well-formed block is the ONLY accepting shape, so the rejections
+/// below are attributable to the defect under test and not to a broken parser.
+#[test]
+fn manifest_asset_lookup_accepts_exactly_one_well_formed_block() {
+    let manifest = format!(
+        "[fixture]\ntag = \"v0.40.4\"\n\n{}{}",
+        synthetic_asset("target-a", &[GOOD_DIGEST]),
+        synthetic_asset("target-b", &[OTHER_DIGEST])
+    );
+    assert_eq!(asset_executable_sha256(&manifest, "target-a"), GOOD_DIGEST);
+    assert_eq!(asset_executable_sha256(&manifest, "target-b"), OTHER_DIGEST);
+}
+
+/// The regression this test exists for: TWO blocks name the same target and only
+/// ONE carries a digest. Counting digests alone yields exactly one value and
+/// silently accepts; block cardinality must reject it.
+#[test]
+fn manifest_asset_lookup_rejects_duplicate_target_blocks_when_only_one_has_a_digest() {
+    let manifest = format!(
+        "{}{}",
+        synthetic_asset("target-a", &[GOOD_DIGEST]),
+        synthetic_asset("target-a", &[])
+    );
+    assert!(
+        lookup_panics(&manifest, "target-a"),
+        "two blocks naming the same target must be fatal even when only one has a digest"
+    );
+
+    // Also in the other order, so the rejection is not an artifact of which
+    // block happens to come first.
+    let reversed = format!(
+        "{}{}",
+        synthetic_asset("target-a", &[]),
+        synthetic_asset("target-a", &[GOOD_DIGEST])
+    );
+    assert!(
+        lookup_panics(&reversed, "target-a"),
+        "block-order must not change the duplicate-target verdict"
+    );
+}
+
+#[test]
+fn manifest_asset_lookup_rejects_duplicate_target_blocks_that_both_have_digests() {
+    let manifest = format!(
+        "{}{}",
+        synthetic_asset("target-a", &[GOOD_DIGEST]),
+        synthetic_asset("target-a", &[OTHER_DIGEST])
+    );
+    assert!(
+        lookup_panics(&manifest, "target-a"),
+        "two blocks naming the same target must be fatal"
+    );
+}
+
+#[test]
+fn manifest_asset_lookup_rejects_duplicate_digest_fields_in_one_block() {
+    let manifest = synthetic_asset("target-a", &[GOOD_DIGEST, OTHER_DIGEST]);
+    assert!(
+        lookup_panics(&manifest, "target-a"),
+        "one block declaring two digests must be fatal"
+    );
+}
+
+#[test]
+fn manifest_asset_lookup_rejects_a_block_without_a_digest() {
+    let manifest = synthetic_asset("target-a", &[]);
+    assert!(
+        lookup_panics(&manifest, "target-a"),
+        "a matching block with no digest must be fatal"
+    );
+}
+
+#[test]
+fn manifest_asset_lookup_rejects_a_malformed_digest() {
+    let uppercase = GOOD_DIGEST.to_uppercase();
+    assert_ne!(
+        uppercase, GOOD_DIGEST,
+        "the uppercase case must actually differ from the accepted digest"
+    );
+    for bad in [
+        uppercase.as_str(),
+        &GOOD_DIGEST[..63],
+        &format!("{GOOD_DIGEST}a"),
+        &format!("{}g", &GOOD_DIGEST[..63]),
+    ] {
+        let manifest = synthetic_asset("target-a", &[bad]);
+        assert!(
+            lookup_panics(&manifest, "target-a"),
+            "a malformed digest must be fatal: {bad:?}"
+        );
+    }
+}
+
+/// A following `[fixture]` table must CLOSE the preceding asset block, so its
+/// keys can never be attributed to that block.
+#[test]
+fn manifest_asset_blocks_are_closed_by_the_next_table() {
+    let manifest = format!(
+        "{}\n[fixture]\nexecutable_sha256 = \"{OTHER_DIGEST}\"\n",
+        synthetic_asset("target-a", &[GOOD_DIGEST])
+    );
+    assert_eq!(
+        asset_executable_sha256(&manifest, "target-a"),
+        GOOD_DIGEST,
+        "a key after the next table header must not join the asset block"
+    );
+}
+
+/// A root that is a symlink to a real directory must be REFUSED, and the alias
+/// target must be neither enumerated nor modified.
+#[cfg(unix)]
+#[test]
+fn snapshot_refuses_a_symlinked_root_without_touching_the_target() {
+    let dir = TestDir::new("rootalias");
+    let target = dir.path().join("target");
+    fs::create_dir_all(&target).expect("create alias target directory");
+    let secret = target.join("secret.bin");
+    fs::write(&secret, b"TARGET-BYTES").expect("write alias target bytes");
+    let link = dir.path().join("root-link");
+    std::os::unix::fs::symlink(&target, &link).expect("create root symlink");
+
+    let outcome = snapshot_with_checkpoint(&link, |_, _| {});
+    assert_eq!(
+        outcome,
+        Err(SnapshotError::RootNotANonAliasDirectory(link.clone())),
+        "an aliased root must fail closed with the typed root error"
+    );
+
+    // The alias target is untouched: the same bytes, and the direct snapshot of
+    // the real directory still sees exactly one entry.
+    assert_eq!(
+        fs::read(&secret).expect("reread alias target bytes"),
+        b"TARGET-BYTES".to_vec(),
+        "refusing an aliased root must not modify the target"
+    );
+    let direct = snapshot(&target);
+    assert_eq!(
+        direct.keys().cloned().collect::<Vec<_>>(),
+        vec![PathBuf::from("secret.bin")],
+        "the alias target must be unchanged in shape"
+    );
+}
+
+/// A root that exists but is a regular file is refused with the same typed
+/// error: only a typed `NotFound` may produce an empty snapshot.
+#[test]
+fn snapshot_refuses_a_non_directory_root_and_only_notfound_is_empty() {
+    let dir = TestDir::new("rootkind");
+    let file_root = dir.path().join("not-a-dir");
+    fs::write(&file_root, b"x").expect("write non-directory root");
+    assert_eq!(
+        snapshot_with_checkpoint(&file_root, |_, _| {}),
+        Err(SnapshotError::RootNotANonAliasDirectory(file_root)),
+        "a non-directory root must fail closed"
+    );
+
+    let absent = dir.path().join("absent");
+    assert_eq!(
+        snapshot_with_checkpoint(&absent, |_, _| {}),
+        Ok(BTreeMap::new()),
+        "a typed NotFound root is the ONLY empty-snapshot case"
+    );
+}
+
+/// Replaces `path` (a directory) with a fresh directory of different content,
+/// deterministically and without sleeping.
+fn replace_directory(path: &Path, marker: &str) {
+    let stash = path.with_extension("replaced-away");
+    fs::rename(path, &stash).expect("move the original directory aside");
+    fs::create_dir_all(path).expect("create the replacement directory");
+    fs::write(path.join(marker), b"REPLACEMENT").expect("write replacement marker");
+}
+
+/// The post-corroboration gate is real: swapping the fixed ROOT directory after
+/// its handle and path were corroborated must reject the run, so children
+/// collected from the replacement are never accepted.
+#[test]
+fn snapshot_rejects_root_replaced_after_handle_corroboration() {
+    let dir = TestDir::new("rootswap");
+    let root = dir.path().join("ns");
+    fs::create_dir_all(&root).expect("create snapshot root");
+    fs::write(root.join("original.bin"), b"ORIGINAL").expect("write original bytes");
+
+    let mut trace: Vec<(PathBuf, SnapshotCheckpoint)> = Vec::new();
+    let mut swapped = false;
+    let outcome = snapshot_with_checkpoint(&root, |path, checkpoint| {
+        trace.push((path.to_path_buf(), checkpoint));
+        if !swapped
+            && path == root
+            && checkpoint == SnapshotCheckpoint::DirectoryHandleAndPathCorroborated
+        {
+            swapped = true;
+            replace_directory(&root, "injected.bin");
+        }
+    });
+
+    assert!(swapped, "the root checkpoint must have been reached");
+    assert_eq!(
+        outcome,
+        Err(SnapshotError::PathChangedDuringRead(root.clone())),
+        "a root replaced after corroboration must be rejected"
+    );
+    // Pins the POST-ENUMERATION gate specifically: enumeration ran against the
+    // replacement, so the run must die BEFORE that checkpoint. Without the
+    // post-enumeration recheck this checkpoint fires and the test fails.
+    assert!(
+        !trace.contains(&(
+            root.clone(),
+            SnapshotCheckpoint::DirectoryEnumerationCorroborated
+        )),
+        "the post-enumeration recheck must reject the swapped root before its \
+         collected children are usable; trace: {trace:?}"
+    );
+}
+
+/// Same gate one level down: a NESTED directory swapped after its own
+/// corroboration must reject the run.
+#[test]
+fn snapshot_rejects_nested_directory_replaced_after_handle_corroboration() {
+    let dir = TestDir::new("nestedswap");
+    let root = dir.path().join("ns");
+    let nested = root.join("nested");
+    fs::create_dir_all(&nested).expect("create nested snapshot directory");
+    fs::write(nested.join("original.bin"), b"ORIGINAL").expect("write nested original bytes");
+
+    let mut trace: Vec<(PathBuf, SnapshotCheckpoint)> = Vec::new();
+    let mut swapped = false;
+    let outcome = snapshot_with_checkpoint(&root, |path, checkpoint| {
+        trace.push((path.to_path_buf(), checkpoint));
+        if !swapped
+            && path == nested
+            && checkpoint == SnapshotCheckpoint::DirectoryHandleAndPathCorroborated
+        {
+            swapped = true;
+            replace_directory(&nested, "injected.bin");
+        }
+    });
+
+    assert!(swapped, "the nested checkpoint must have been reached");
+    assert_eq!(
+        outcome,
+        Err(SnapshotError::PathChangedDuringRead(nested.clone())),
+        "a nested directory replaced after corroboration must be rejected"
+    );
+    assert!(
+        !trace.contains(&(
+            nested.clone(),
+            SnapshotCheckpoint::DirectoryEnumerationCorroborated
+        )),
+        "the post-enumeration recheck must reject the swapped nested directory \
+         before its collected children are usable; trace: {trace:?}"
+    );
+}
+
+/// A regular file replaced by a DIFFERENT object after its handle was
+/// corroborated must be rejected by the post-read fixed-path check, so bytes
+/// read through the old handle are never attributed to the new path.
+#[test]
+fn snapshot_rejects_regular_file_replaced_after_handle_corroboration() {
+    let dir = TestDir::new("fileswap");
+    let root = dir.path().join("ns");
+    fs::create_dir_all(&root).expect("create snapshot root");
+    let file = root.join("a.bin");
+    fs::write(&file, b"ORIGINAL").expect("write original file bytes");
+
+    let mut swapped = false;
+    let outcome = snapshot_with_checkpoint(&root, |path, checkpoint| {
+        if !swapped && path == file && checkpoint == SnapshotCheckpoint::RegularHandleCorroborated {
+            swapped = true;
+            let replacement = root.join("replacement.tmp");
+            fs::write(&replacement, b"REPLACED").expect("write replacement bytes");
+            fs::rename(&replacement, &file).expect("atomically replace the snapshot file");
+        }
+    });
+
+    assert!(
+        swapped,
+        "the regular-file checkpoint must have been reached"
+    );
+    assert_eq!(
+        outcome,
+        Err(SnapshotError::PathChangedDuringRead(file.clone())),
+        "a file replaced after handle corroboration must be rejected"
+    );
+}
+
+/// A temporary executable that prints `line` on stdout, or `None` when this
+/// platform has no dependency-free way to make one.
+#[cfg(unix)]
+fn write_version_stub(path: &Path, line: &str) -> Option<()> {
+    use std::os::unix::fs::PermissionsExt as _;
+    fs::write(path, format!("#!/bin/sh\necho '{line}'\n")).expect("write version stub");
+    fs::set_permissions(path, fs::Permissions::from_mode(0o755)).expect("mark stub executable");
+    Some(())
+}
+
+#[cfg(not(unix))]
+fn write_version_stub(_path: &Path, _line: &str) -> Option<()> {
+    None
+}
+
+/// A wrong digest must be rejected BEFORE the candidate is ever executed.
+#[test]
+fn verify_legacy_binary_rejects_a_wrong_executable_digest() {
+    let dir = TestDir::new("badsha");
+    let candidate = dir.path().join("fake-legacy");
+    fs::write(&candidate, b"not the frozen legacy binary").expect("write fake legacy binary");
+
+    let expectation = LegacyExpectation {
+        executable_sha256: "0".repeat(64),
+        version_stdout: "codegraph 0.40.4".to_string(),
+    };
+    let error = verify_legacy_binary(&candidate, &expectation)
+        .expect_err("a wrong digest must be rejected");
+    assert!(
+        error.contains("SHA-256 mismatch"),
+        "the digest branch must be the rejection reason, got: {error}"
+    );
+    assert!(
+        error.contains(&sha256_hex(b"not the frozen legacy binary")),
+        "the observed digest must be reported, got: {error}"
+    );
+}
+
+/// With the candidate's REAL digest as the expectation, verification reaches the
+/// `--version` branch and rejects the wrong version. No collision is needed.
+#[test]
+fn verify_legacy_binary_rejects_a_wrong_executable_version() {
+    let dir = TestDir::new("badversion");
+    let candidate = dir.path().join("stub-legacy");
+    if write_version_stub(&candidate, "codegraph 9.9.9").is_none() {
+        eprintln!(
+            "verify_legacy_binary version branch NOT self-tested on {}: no \
+             dependency-free executable stub. Production verification still runs \
+             the real `--version` natively.",
+            std::env::consts::OS
+        );
+        return;
+    }
+
+    let bytes = fs::read(&candidate).expect("read the stub bytes");
+    let expectation = LegacyExpectation {
+        executable_sha256: sha256_hex(&bytes),
+        version_stdout: "codegraph 0.40.4".to_string(),
+    };
+    let error = verify_legacy_binary(&candidate, &expectation)
+        .expect_err("a wrong --version must be rejected");
+    assert!(
+        error.contains("version mismatch") && error.contains("codegraph 9.9.9"),
+        "the version branch must be the rejection reason, got: {error}"
+    );
+}
+
+/// A matching digest AND matching version is the only accepting path.
+#[test]
+fn verify_legacy_binary_accepts_a_matching_digest_and_version() {
+    let dir = TestDir::new("goodstub");
+    let candidate = dir.path().join("stub-legacy");
+    if write_version_stub(&candidate, "codegraph 0.40.4").is_none() {
+        return;
+    }
+    let bytes = fs::read(&candidate).expect("read the stub bytes");
+    let expectation = LegacyExpectation {
+        executable_sha256: sha256_hex(&bytes),
+        version_stdout: "codegraph 0.40.4".to_string(),
+    };
+    verify_legacy_binary(&candidate, &expectation)
+        .expect("a matching digest and version must verify");
+}
diff --git a/crates/codegraph-cli/tests/fixtures/legacy-v0.40.4/manifest.toml b/crates/codegraph-cli/tests/fixtures/legacy-v0.40.4/manifest.toml
new file mode 100644
index 0000000..d2e5eef
--- /dev/null
+++ b/crates/codegraph-cli/tests/fixtures/legacy-v0.40.4/manifest.toml
@@ -0,0 +1,52 @@
+# Frozen legacy-compatibility fixture manifest (Batch M).
+#
+# Legacy compatibility tests execute the PUBLISHED v0.40.4 release binary — the
+# last release whose index namespace was the fixed legacy `.codegraph` root — to
+# prove that an UNMODIFIED old scanner cannot reach v2 storage. Nothing here is
+# built from this worktree: the bytes below are the exact published artifacts.
+#
+# Provenance (GitHub release `v0.40.4` of sunerpy/codegraph-rust):
+#   tag    = v0.40.4
+#   commit = aba40799ecacb94515f7e1690914d2accc4c8973
+#
+# Every digest was taken from the real downloaded bytes, and
+# `expected_version_stdout` from the real `--version` run of the extracted
+# executable. `scripts/setup-legacy-fixture.sh` re-verifies all three
+# (archive digest, executable digest, `--version`) on EVERY use; a mismatch or a
+# missing network is a hard fixture-setup failure, never a skipped test.
+#
+# Only the two natively-executed CI hosts are pinned: Linux x86_64 and Windows
+# x86_64. Each CI job uses its OWN native asset — there is no cross-execution
+# and no emulation. A host outside this set has no pinned asset, and the test
+# suite says so explicitly instead of pretending coverage.
+
+[fixture]
+tag = "v0.40.4"
+commit = "aba40799ecacb94515f7e1690914d2accc4c8973"
+version = "0.40.4"
+expected_version_stdout = "codegraph 0.40.4"
+release_download_prefix = "https://github.com/sunerpy/codegraph-rust/releases/download/v0.40.4/"
+
+[[asset]]
+target = "x86_64-unknown-linux-musl"
+target_os = "linux"
+target_arch = "x86_64"
+url = "https://github.com/sunerpy/codegraph-rust/releases/download/v0.40.4/codegraph-0.40.4-x86_64-unknown-linux-musl.tar.gz"
+archive_name = "codegraph-0.40.4-x86_64-unknown-linux-musl.tar.gz"
+archive_format = "tar.gz"
+archive_size = 10026272
+archive_sha256 = "b549c0980b0f52f6b753f529322cdbc8892e03ef3736ec227a9e8f49985a3bd2"
+member = "codegraph"
+executable_sha256 = "1a14d195be755b27d0e1625d7d7e4662412a07d77cc0d0e518793cd50f2182d1"
+
+[[asset]]
+target = "x86_64-pc-windows-msvc"
+target_os = "windows"
+target_arch = "x86_64"
+url = "https://github.com/sunerpy/codegraph-rust/releases/download/v0.40.4/codegraph-0.40.4-x86_64-pc-windows-msvc.zip"
+archive_name = "codegraph-0.40.4-x86_64-pc-windows-msvc.zip"
+archive_format = "zip"
+archive_size = 9988644
+archive_sha256 = "eda7cfd6d2d0cc85fd8bd6ba66be1d7130a9b00609255730ad155ce6fa1351db"
+member = "codegraph.exe"
+executable_sha256 = "e52703f3a3d5bef90997ce23d9a3b49c980e6bcc1a078fdb1245ad1305a5bc09"
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index c85c0f4..e5f1a42 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2502,3 +2502,102 @@ No schema, node-ID formula, extraction/golden byte, workflow, `UPSTREAM.md`, or
 before formatting and the one authoritative
 `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run;
 no final Green is claimed until that post-documentation gate passes.
+
+## Batch M item 22 acceptance closure — verified v0.40.4 legacy fixture (2026-07-26)
+
+Item 22 asserts two DIFFERENT claims about an unmodified old scanner, and keeps
+them apart. Source visibility is configuration-dependent: with the DEFAULT
+supported-extension configuration the published v0.40.4 `files` output is exactly
+`src/app.ts`, `src/math.ts`, and `tools/greeter.py`. Storage authority is
+configuration-independent: under an EXPLICIT legacy `.codegraph/codegraph.json`
+override for `.json`/`.toml`, the same binary additionally reports
+`.codegraph-v2/config.toml` and `.codegraph-v2/codegraph.json` as SOURCE — accepted
+and documented, because the user asked for those extensions — while every v2
+namespace byte stays identical, the v2-only symbol never enters the legacy
+database or graph, and the v2 reader still serves that symbol afterwards. Reading
+a v2 artifact's text is never the same thing as holding authority over v2 storage.
+
+Nothing in this slice is built from this worktree. The fixture executes the REAL
+published release: tag `v0.40.4`, commit
+`aba40799ecacb94515f7e1690914d2accc4c8973`, version stdout `codegraph 0.40.4`.
+Only the two natively-executed CI hosts are pinned, each running its own asset —
+no cross-execution and no emulation. Linux x86_64 musl: archive
+`10026272` bytes, archive SHA-256
+`b549c0980b0f52f6b753f529322cdbc8892e03ef3736ec227a9e8f49985a3bd2`, member
+`codegraph`, executable SHA-256
+`1a14d195be755b27d0e1625d7d7e4662412a07d77cc0d0e518793cd50f2182d1`. Windows
+x86_64 MSVC: archive `9988644` bytes, archive SHA-256
+`eda7cfd6d2d0cc85fd8bd6ba66be1d7130a9b00609255730ad155ce6fa1351db`, member
+`codegraph.exe`, executable SHA-256
+`e52703f3a3d5bef90997ce23d9a3b49c980e6bcc1a078fdb1245ad1305a5bc09`.
+
+`scripts/setup-legacy-fixture.sh` is the only sanctioned way to obtain that
+binary. It selects the CURRENT NATIVE host's asset, downloads over HTTPS, and
+verifies every declared field — archive size, archive SHA-256, extracted
+executable SHA-256, and the exact `--version` stdout — before printing a path.
+Exactly one archive member is extracted by name, so an archive-supplied path can
+never escape the destination. The cache is digest-addressed and revalidated on
+EVERY run, so a stale or corrupt entry is re-downloaded rather than trusted. An
+EXIT trap sweeps the staging directory and any partial archive, and never touches
+an executable that already passed full verification. There is no skip path: a
+missing network, a size or digest mismatch, a missing member, or a wrong
+`--version` all exit nonzero, and an unavailable fixture is a fixture-setup
+FAILURE rather than a skipped test.
+
+The manifest is the single authority for what the legacy binary must be; no
+executable digest or version string is duplicated in Rust. Asset-block uniqueness
+is STRUCTURAL: `[[asset]]` blocks are parsed as records so block cardinality
+survives the parse, exactly one block may name the requested target regardless of
+whether duplicate blocks carry a digest, that sole block must declare exactly one
+`executable_sha256`, and the digest must be exactly 64 lowercase hexadecimal
+characters. Missing target, duplicate target blocks, missing digest, duplicate
+digest fields, and malformed digests all fail loudly, each proven by a compact
+synthetic-manifest regression rather than by the production manifest.
+
+The nonmutation oracle fails closed. Only a typed `NotFound` root yields an empty
+snapshot; an existing root that is an alias, a Windows reparse point, or a
+non-directory is refused with a typed error. Root and nested directories are
+opened without following aliases, identity-corroborated against the fixed path
+before enumeration AND re-corroborated after enumeration, so collected children
+become usable only once the directory still proves to be the same object. Regular
+files are read completely through one opened handle, with the handle and the fixed
+path re-checked after the full read. Unix uses `(dev, ino)`; Windows uses raw
+`GetFileInformationByHandleEx(FileIdInfo)` — an exact identity on both platforms,
+never a size or timestamp approximation. The test-local SHA-256 is pinned to
+published NIST vectors, so the executable digest gate does not rest on an
+unverified hash. Deterministic checkpoint self-tests prove each gate: static root
+alias refusal without reading or modifying the alias target, root replacement,
+nested-directory replacement, and regular-file replacement.
+
+Linux runtime QA on the integrated bytes: a fresh-cache setup downloaded and
+verified `1a14d195…0f2182d1`; cache-only `--print` exited 0 on a valid cache and
+nonzero on both a missing cache and a cache corrupted by an appended byte; normal
+setup then re-downloaded and revalidated it back to the pinned digest, leaving
+only the executable in the slot; unknown and surplus arguments exited 2; and an
+offline attempt under `unshare -rn` against a fresh cache failed nonzero with the
+fixture-setup message and left no partial archive and no extraction residue.
+`bash -n` and `shellcheck` are clean.
+
+`cargo test --locked -p codegraph-rs --test batch_m_legacy_extension_override`
+passes **21/21** on the integrated bytes, with
+`bash scripts/check-workspace-versions.sh` run before every Cargo batch. Targeted
+package check, Clippy with `-D warnings`, formatting, guardrail, and
+`git diff --check` also pass. Changed-file LSP diagnostics were attempted for the
+new Rust target and the tool again rejected this required external worktree with
+`LSP file path must be inside request cwd`; locked Cargo diagnostics are the
+fallback and this ledger claims no LSP-clean result.
+
+Native Windows/MSVC runtime was NOT executed and is not claimed. Windows coverage
+in this slice is CI WIRING plus compile-gated code: the `windows-latest` job gains
+a `bash`-shell step that selects the Windows `.zip` asset, and the exact
+`FileIdInfo` identity, reparse-point refusal, and `FILE_FLAG_BACKUP_SEMANTICS`
+directory opens follow the repository-proven layout already used by
+`codegraph-store` and `codegraph-core`. The version-branch verifier self-test is
+Unix-gated and says so explicitly on other platforms, while production
+`--version` verification stays unconditional. This slice adds no dependency and
+changes no schema, node-ID formula, extraction or golden byte, `UPSTREAM.md`, or
+`KNOWN_DIFFS.md`; `Cargo.lock` remains required at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. These
+evidence bytes are written BEFORE repository formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run
+over these exact final bytes; no final Green is claimed until that gate passes.
diff --git a/scripts/setup-legacy-fixture.sh b/scripts/setup-legacy-fixture.sh
new file mode 100755
index 0000000..28e729a
--- /dev/null
+++ b/scripts/setup-legacy-fixture.sh
@@ -0,0 +1,373 @@
+#!/usr/bin/env bash
+# setup-legacy-fixture.sh — materialize the frozen v0.40.4 legacy CLI binary.
+#
+# Batch M legacy-compatibility tests execute the PUBLISHED v0.40.4 release
+# binary (tag v0.40.4 / commit aba40799ecacb94515f7e1690914d2accc4c8973) to
+# prove that an unmodified OLD scanner cannot open or mutate v2 storage. This
+# script is the only sanctioned way to obtain that binary.
+#
+# Contract (deliberately strict — a legacy test must never silently "pass"
+# against a binary that is not the real v0.40.4 release):
+#
+#   1. The asset for the CURRENT NATIVE host is selected from the checked-in
+#      manifest. An unpinned host is a hard error; no cross-execution, no
+#      emulation, no substitution of a locally built binary.
+#   2. The archive is downloaded over HTTPS from the immutable release-download
+#      URL and its SHA-256 must equal the manifest digest. Redirects are
+#      followed, but only the FINAL bytes are trusted (the digest is computed
+#      over what landed on disk).
+#   3. Exactly ONE archive member — the manifest's `member` name — is extracted.
+#      Archive-supplied paths are never honored, so a crafted archive cannot
+#      write outside the destination.
+#   4. Every declared integrity field is checked: the downloaded archive's SIZE
+#      (`archive_size`) and SHA-256 (`archive_sha256`), then the extracted
+#      executable's SHA-256 and its exact `--version` stdout. The SHA-256 values
+#      remain the authority; the size is an additional declared-field check, not
+#      a substitute for it.
+#   5. The cache is DIGEST-ADDRESSED (`<exe-sha256>/<member>`) and revalidated
+#      on EVERY run. A stale or corrupt cached file is re-downloaded, never
+#      trusted.
+#   6. Missing network, a size or digest mismatch, a missing member, or a wrong
+#      `--version` all exit NONZERO with an actionable message. There is no
+#      skip path: an unavailable fixture is a fixture-setup FAILURE.
+#   7. Every failure path is swept: an EXIT trap removes the staging directory
+#      and any partial archive. Cleanup NEVER touches an executable that has
+#      already passed full verification.
+#
+# Usage:
+#   scripts/setup-legacy-fixture.sh              # prepare (download if needed),
+#                                                # then print the exe path
+#   scripts/setup-legacy-fixture.sh --print      # print the path ONLY if the
+#                                                # cached exe already validates;
+#                                                # never downloads
+# `--print` is the only accepted argument; anything else is a usage error.
+#
+# Output: the absolute path of the verified legacy executable on stdout (last
+# line). All diagnostics go to stderr. Tests consume the path via
+# CODEGRAPH_LEGACY_BIN, which this script's caller exports.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd -P)"
+MANIFEST="$REPO_ROOT/crates/codegraph-cli/tests/fixtures/legacy-v0.40.4/manifest.toml"
+
+# Cache root: overridable so CI can point at a cached directory. Default keeps
+# the artifacts out of the source tree entirely.
+CACHE_ROOT="${CODEGRAPH_LEGACY_FIXTURE_CACHE:-${TMPDIR:-/tmp}/codegraph-legacy-fixture}"
+
+# Swept on EVERY exit path (success, `die`, `set -e` abort, signal). Populated
+# only with the in-flight staging directory and partial archive; a fully
+# verified executable is never registered here.
+STAGE_DIR=""
+PARTIAL_ARCHIVE=""
+
+sweep() {
+    [ -n "$STAGE_DIR" ] && [ -d "$STAGE_DIR" ] && rm -rf "$STAGE_DIR"
+    [ -n "$PARTIAL_ARCHIVE" ] && [ -e "$PARTIAL_ARCHIVE" ] && rm -f "$PARTIAL_ARCHIVE"
+    return 0
+}
+trap sweep EXIT HUP INT TERM
+
+# print_usage FD — the usage text, kept in one place so docs cannot drift.
+print_usage() {
+    cat >&"$1" <<'USAGE'
+usage: setup-legacy-fixture.sh [--print]
+  (no argument)  prepare the frozen v0.40.4 fixture (download if needed) and
+                 print the verified executable path
+  --print        print the path ONLY if the cached executable already validates;
+                 never downloads
+USAGE
+}
+
+die() {
+    printf 'setup-legacy-fixture: %s\n' "$1" >&2
+    exit 1
+}
+
+need() {
+    command -v "$1" >/dev/null 2>&1 || die "required tool not found on PATH: $1"
+}
+
+# ---------------------------------------------------------------------------
+# Manifest reading. The manifest is a small, fixed-shape TOML file authored in
+# this repo, so a line-oriented reader is sufficient and avoids adding a TOML
+# dependency to a shell script. Every lookup FAILS LOUDLY when absent.
+# ---------------------------------------------------------------------------
+
+[ -f "$MANIFEST" ] || die "fixture manifest missing: $MANIFEST"
+
+# fixture_field KEY -> value of `KEY = "value"` inside the [fixture] table.
+fixture_field() {
+    local key="$1" value
+    value="$(
+        awk -v key="$key" '
+            /^\[/ { in_fixture = ($0 == "[fixture]"); next }
+            in_fixture && $1 == key {
+                # strip up to the first quote, then the trailing quote
+                line = $0
+                sub(/^[^"]*"/, "", line)
+                sub(/"[^"]*$/, "", line)
+                print line
+                exit
+            }
+        ' "$MANIFEST"
+    )"
+    [ -n "$value" ] || die "manifest [fixture] is missing key '$key'"
+    printf '%s' "$value"
+}
+
+# asset_field TARGET KEY -> value of KEY inside the [[asset]] block whose
+# `target` equals TARGET. Numeric values are returned unquoted.
+asset_field() {
+    local target="$1" key="$2" value
+    value="$(
+        awk -v want="$target" -v key="$key" '
+            /^\[\[asset\]\]/ { current = ""; matched = 0; next }
+            /^\[/ { current = ""; matched = 0; next }
+            $1 == "target" {
+                line = $0
+                sub(/^[^"]*"/, "", line); sub(/"[^"]*$/, "", line)
+                current = line
+                matched = (current == want)
+                next
+            }
+            matched && $1 == key {
+                line = $0
+                sub(/^[[:space:]]*[A-Za-z0-9_]+[[:space:]]*=[[:space:]]*/, "", line)
+                gsub(/^"|"$/, "", line)
+                print line
+                exit
+            }
+        ' "$MANIFEST"
+    )"
+    [ -n "$value" ] || die "manifest [[asset]] target='$target' is missing key '$key'"
+    printf '%s' "$value"
+}
+
+# ---------------------------------------------------------------------------
+# Native host selection. NO cross-execution: the host's own OS/arch decides.
+# ---------------------------------------------------------------------------
+
+detect_target() {
+    local os arch uname_s uname_m
+    uname_s="$(uname -s 2>/dev/null || printf 'unknown')"
+    uname_m="$(uname -m 2>/dev/null || printf 'unknown')"
+
+    case "$uname_s" in
+        Linux) os="linux" ;;
+        MINGW* | MSYS* | CYGWIN* | Windows_NT) os="windows" ;;
+        *) os="$uname_s" ;;
+    esac
+    case "$uname_m" in
+        x86_64 | amd64) arch="x86_64" ;;
+        *) arch="$uname_m" ;;
+    esac
+
+    case "$os/$arch" in
+        linux/x86_64) printf 'x86_64-unknown-linux-musl' ;;
+        windows/x86_64) printf 'x86_64-pc-windows-msvc' ;;
+        *)
+            die "no pinned v0.40.4 asset for this host ($os/$arch).
+The legacy-compatibility fixture executes the REAL published binary natively.
+Pinned hosts: linux/x86_64 and windows/x86_64 (see $MANIFEST).
+This host cannot run the legacy fixture; do NOT interpret that as coverage."
+            ;;
+    esac
+}
+
+sha256_of() {
+    local path="$1"
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$path" | awk '{print $1}'
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$path" | awk '{print $1}'
+    else
+        die "no sha256 tool available (need sha256sum or shasum)"
+    fi
+}
+
+download() {
+    local url="$1" dest="$2"
+    if command -v curl >/dev/null 2>&1; then
+        # -f: HTTP errors are failures; -L: follow redirects (final bytes are
+        # digest-verified below, so a redirect cannot substitute content).
+        curl -fsSL --retry 3 --retry-delay 2 --connect-timeout 20 -o "$dest" "$url" \
+            || return 1
+    elif command -v wget >/dev/null 2>&1; then
+        wget -q --tries=3 --timeout=20 -O "$dest" "$url" || return 1
+    else
+        die "no downloader available (need curl or wget)"
+    fi
+}
+
+# extract_member ARCHIVE FORMAT MEMBER DEST
+#   Extracts exactly MEMBER to the file DEST. The archive's own path is never
+#   used as a filesystem destination, so `../` members cannot escape.
+extract_member() {
+    local archive="$1" format="$2" member="$3" dest="$4" stage
+    stage="$(mktemp -d "$CACHE_ROOT/extract.XXXXXX")"
+    STAGE_DIR="$stage"
+    case "$format" in
+        tar.gz)
+            need tar
+            # Refuse an archive whose member set is not exactly the expected name.
+            local listing
+            listing="$(tar -tzf "$archive")" || die "cannot list archive: $archive"
+            [ "$listing" = "$member" ] \
+                || die "archive member set is not exactly '$member': $listing"
+            tar -xzf "$archive" -C "$stage" "$member" \
+                || die "cannot extract '$member' from $archive"
+            ;;
+        zip)
+            need unzip
+            local listing
+            listing="$(unzip -Z1 "$archive")" || die "cannot list archive: $archive"
+            [ "$listing" = "$member" ] \
+                || die "archive member set is not exactly '$member': $listing"
+            # -j flattens any path component; the member name is matched exactly.
+            unzip -o -j -q "$archive" "$member" -d "$stage" \
+                || die "cannot extract '$member' from $archive"
+            ;;
+        *) die "unsupported archive format: $format" ;;
+    esac
+    [ -f "$stage/$(basename "$member")" ] \
+        || die "expected member '$member' absent after extraction"
+    mv -f "$stage/$(basename "$member")" "$dest"
+    rm -rf "$stage"
+    STAGE_DIR=""
+}
+
+size_of() {
+    local path="$1" size
+    if size="$(wc -c <"$path" 2>/dev/null)"; then
+        printf '%s' "${size// /}"
+    else
+        die "cannot measure size of $path"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+PRINT_ONLY=0
+case "${1-}" in
+    "") ;;
+    --print) PRINT_ONLY=1 ;;
+    -h | --help)
+        print_usage 1
+        exit 0
+        ;;
+    *)
+        printf 'setup-legacy-fixture: unknown argument: %s\n' "$1" >&2
+        print_usage 2
+        exit 2
+        ;;
+esac
+if [ "$#" -gt 1 ]; then
+    printf 'setup-legacy-fixture: too many arguments\n' >&2
+    print_usage 2
+    exit 2
+fi
+
+TAG="$(fixture_field tag)"
+COMMIT="$(fixture_field commit)"
+EXPECTED_VERSION="$(fixture_field expected_version_stdout)"
+
+TARGET="$(detect_target)"
+URL="$(asset_field "$TARGET" url)"
+ARCHIVE_NAME="$(asset_field "$TARGET" archive_name)"
+ARCHIVE_FORMAT="$(asset_field "$TARGET" archive_format)"
+ARCHIVE_SHA="$(asset_field "$TARGET" archive_sha256)"
+ARCHIVE_SIZE="$(asset_field "$TARGET" archive_size)"
+MEMBER="$(asset_field "$TARGET" member)"
+EXE_SHA="$(asset_field "$TARGET" executable_sha256)"
+
+case "$ARCHIVE_SIZE" in
+    '' | *[!0-9]*) die "manifest archive_size for $TARGET is not a decimal byte count: '$ARCHIVE_SIZE'" ;;
+esac
+
+mkdir -p "$CACHE_ROOT"
+# Digest-addressed cache slot: a different digest can never collide with this one.
+SLOT="$CACHE_ROOT/$EXE_SHA"
+EXE="$SLOT/$MEMBER"
+mkdir -p "$SLOT"
+
+revalidate() {
+    # Revalidate the cached executable on EVERY run: digest first, then the
+    # real `--version`. Any failure means the cache is not trustworthy.
+    [ -f "$EXE" ] || return 1
+    [ "$(sha256_of "$EXE")" = "$EXE_SHA" ] || return 1
+    chmod +x "$EXE" 2>/dev/null || true
+    local observed
+    observed="$("$EXE" --version 2>/dev/null | tr -d '\r')" || return 1
+    [ "$observed" = "$EXPECTED_VERSION" ] || return 1
+    return 0
+}
+
+if revalidate; then
+    printf '%s\n' "$EXE"
+    exit 0
+fi
+
+if [ "$PRINT_ONLY" -eq 1 ]; then
+    die "--print requested but the cached executable does not validate.
+  slot: $SLOT
+Run without --print to download and verify the frozen $TAG asset."
+fi
+
+printf 'setup-legacy-fixture: preparing %s %s (%s)\n' "$TAG" "$TARGET" "$COMMIT" >&2
+rm -f "$EXE"
+ARCHIVE="$SLOT/$ARCHIVE_NAME"
+rm -f "$ARCHIVE"
+PARTIAL_ARCHIVE="$ARCHIVE"
+if ! download "$URL" "$ARCHIVE"; then
+    die "cannot download the frozen legacy fixture asset.
+  url: $URL
+This is a FIXTURE-SETUP FAILURE, not a skipped test. The legacy-compatibility
+tests require the real published $TAG binary. Restore network access (or
+pre-populate CODEGRAPH_LEGACY_FIXTURE_CACHE=$CACHE_ROOT with the verified
+$EXE_SHA slot) and rerun."
+fi
+
+observed_size="$(size_of "$ARCHIVE")"
+if [ "$observed_size" != "$ARCHIVE_SIZE" ]; then
+    die "archive size mismatch for $ARCHIVE_NAME
+  expected: $ARCHIVE_SIZE bytes
+  observed: $observed_size bytes
+The downloaded bytes are not the frozen $TAG asset; refusing to run legacy tests."
+fi
+
+observed_archive="$(sha256_of "$ARCHIVE")"
+if [ "$observed_archive" != "$ARCHIVE_SHA" ]; then
+    die "archive SHA-256 mismatch for $ARCHIVE_NAME
+  expected: $ARCHIVE_SHA
+  observed: $observed_archive
+The downloaded bytes are not the frozen $TAG asset; refusing to run legacy tests."
+fi
+
+extract_member "$ARCHIVE" "$ARCHIVE_FORMAT" "$MEMBER" "$EXE"
+rm -f "$ARCHIVE"
+PARTIAL_ARCHIVE=""
+chmod +x "$EXE" 2>/dev/null || true
+
+observed_exe="$(sha256_of "$EXE")"
+if [ "$observed_exe" != "$EXE_SHA" ]; then
+    rm -f "$EXE"
+    die "extracted executable SHA-256 mismatch for $MEMBER
+  expected: $EXE_SHA
+  observed: $observed_exe"
+fi
+
+observed_version="$("$EXE" --version 2>/dev/null | tr -d '\r')" || {
+    rm -f "$EXE"
+    die "extracted executable could not run '--version' natively on this host"
+}
+if [ "$observed_version" != "$EXPECTED_VERSION" ]; then
+    rm -f "$EXE"
+    die "legacy executable reports '$observed_version', expected '$EXPECTED_VERSION'"
+fi
+printf 'setup-legacy-fixture: verified %s\n' "$EXE_SHA" >&2
+
+printf '%s\n' "$EXE"

From 24421115e18c648ac417d0b2760a530a261d839e Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 18:03:14 +0800
Subject: [PATCH 33/91] test(mcp): prove long-lived server releases handles per
 request

---
 .github/workflows/ci.yml                      |  11 +
 .../tests/batch_m_long_lived_mcp.rs           | 576 ++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  99 +++
 3 files changed, 686 insertions(+)
 create mode 100644 crates/codegraph-cli/tests/batch_m_long_lived_mcp.rs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 10054bb..582eb58 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -87,6 +87,17 @@ jobs:
       - name: Run tests
         run: cargo test --workspace --exclude codegraph-bench
 
+      # Batch M item 16 acceptance: ONE long-lived shipped `serve --mcp` process
+      # releases every SQLite handle when a request completes, so the v2 main
+      # database can be REPLACED (MoveFileEx + REPLACE_EXISTING) without the
+      # compatibility close seam, and the next request serves only the
+      # replacement graph. The replacement rename is the Windows-specific handle
+      # proof (a retained handle makes it fail with a sharing violation), so this
+      # target is selected EXPLICITLY here — never compile-only, never skipped —
+      # even though the workspace run above already covers it.
+      - name: Run Batch M item 16 native Windows replacement acceptance
+        run: cargo test -p codegraph-rs --test batch_m_long_lived_mcp
+
   audit:
     name: Security Audit
     runs-on: ubuntu-latest
diff --git a/crates/codegraph-cli/tests/batch_m_long_lived_mcp.rs b/crates/codegraph-cli/tests/batch_m_long_lived_mcp.rs
new file mode 100644
index 0000000..84cddb2
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_long_lived_mcp.rs
@@ -0,0 +1,576 @@
+//! Batch M acceptance item 16 (frozen plan lines 775-778):
+//! `long_lived_v2_mcp_releases_handles_per_request`.
+//!
+//! ONE long-lived SHIPPED MCP process (`codegraph serve --mcp --path <project>`)
+//! must complete request 1, release EVERY SQLite handle and index lease it used,
+//! permit an atomic replacement of the v2 main database file WITHOUT any
+//! participation from the compatibility close seam, and then serve ONLY the
+//! replacement graph on the next request.
+//!
+//! # Determinism: a child-process READY/CONTINUE barrier, never a sleep
+//!
+//! The barrier is the MCP wire protocol itself, so nothing here infers ordering
+//! from elapsed time:
+//!
+//! 1. **READY** — the parent blocks until the child frames the JSON-RPC response
+//!    for request 1 on stdout. rmcp writes that frame only after the request's
+//!    OWNED, fully materialized result was produced, so the arrival of the frame
+//!    is proof that request 1 completed end-to-end (not merely that its SQL
+//!    finished).
+//! 2. **HANDLES RELEASED** — the parent then acquires the namespace's EXCLUSIVE
+//!    index lease. A retained reader lease (or any request-scoped `Store` kept
+//!    alive between requests) makes this acquisition fail, so the exclusive
+//!    lease is the fail-closed observation that the child let go.
+//! 3. **REPLACEMENT** — still holding the exclusive lease, the parent renames a
+//!    separately built database over the live v2 main database file. On native
+//!    Windows this rename (`MoveFileEx` + `REPLACE_EXISTING`) FAILS with a
+//!    sharing violation while any process holds an open handle on the
+//!    destination, because SQLite opens without `FILE_SHARE_DELETE`. That is the
+//!    Windows-specific handle proof this item exists for.
+//! 4. **CONTINUE** — the parent releases the lease and writes the next request
+//!    frame. That frame is the continue signal; the child cannot have started it
+//!    earlier because it had not been written.
+//!
+//! Channel timeouts (`WAIT`) and the lease deadline are DEADLOCK GUARDS only. No
+//! assertion in this file is satisfied by waiting.
+//!
+//! # The replacement graph cannot come from a reindex
+//!
+//! `serve --mcp --path` runs a one-shot startup catch-up sync on a detached
+//! thread (`spawn_catch_up`), and `--no-watch` does not disable it. If the served
+//! project's SOURCES could produce the replacement graph, that background sync
+//! could satisfy the post-replacement assertions without the replaced bytes ever
+//! being read — and could equally delete the replacement rows again, making the
+//! test flaky in both directions.
+//!
+//! So the two distinguishing source files live under a directory the served
+//! project's own root `.gitignore` excludes:
+//!
+//! - No sync can ever CREATE those rows: `scan_project` never yields the paths.
+//!   The test asserts this with the shipped scanner before the acceptance runs.
+//! - No sync can ever DELETE those rows: the cold sync's removal pass only
+//!   considers a tracked path that is absent from disk, both files stay present,
+//!   and the same ignore policy filters them out of `should_handle_file` anyway.
+//!
+//! What remains scannable is one neutral file that is byte-identical in both
+//! graphs, so the startup catch-up is a proven no-op instead of a race. The ONLY
+//! way request 2 can observe the replacement file is by reading the database
+//! bytes the parent supplied.
+//!
+//! # Scope
+//!
+//! Query-side acceptance over the shipped binary. Nothing here is a production
+//! change and nothing weakens a state-slot, sidecar, stamp, or lease gate: both
+//! databases are produced by the real `codegraph init`, so the target namespace
+//! keeps its own valid permanent lock, its own `Current` state slots, and an
+//! exact extraction stamp in the replaced bytes.
+
+use std::fs;
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, Command, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_extract::ExtractOptions;
+use codegraph_store::IndexLease;
+use serde_json::{Value, json};
+
+/// Finite deadlock guard for every blocking wait. Never ordering evidence.
+const WAIT: Duration = Duration::from_secs(60);
+
+/// The scannable file both graphs share, byte-identical. Its only job is to keep
+/// the startup catch-up sync a proven no-op instead of a degenerate empty scan.
+const NEUTRAL_FILE: &str = "src/pwqneutral.ts";
+/// The gitignored directory holding the two supplied-graph-only sources. Nothing
+/// under it is ever scanned in the SERVED project.
+const SUPPLIED_DIR: &str = "supplied";
+/// The symbol that exists ONLY in the original graph.
+const ORIGINAL_SYMBOL: &str = "qxwoolrig";
+/// The repo-relative file that exists ONLY in the original graph.
+const ORIGINAL_FILE: &str = "supplied/mdzzplant.ts";
+/// The symbol that exists ONLY in the replacement graph.
+const REPLACEMENT_SYMBOL: &str = "hbtvancur";
+/// The repo-relative file that exists ONLY in the replacement graph.
+const REPLACEMENT_FILE: &str = "supplied/kfrnbadge.ts";
+
+/// The compatibility close seam this acceptance flow must never touch, spelled
+/// in two halves so this file's own bytes are not a match for it.
+const CLOSE_SEAM: &str = concat!("close_cached", "_handles");
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+/// A temp directory removed on drop.
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-m16-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock")
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).expect("create temp dir");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+/// Write one source file, creating parents.
+fn write_source(root: &Path, rel: &str, contents: &str) {
+    let path = root.join(rel);
+    fs::create_dir_all(path.parent().expect("source parent")).expect("create source dir");
+    fs::write(&path, contents).expect("write source file");
+}
+
+fn source_for(symbol: &str) -> String {
+    format!("export function {symbol}(): number {{\n  return 1;\n}}\n")
+}
+
+/// The neutral scannable source, byte-identical in every project here.
+fn neutral_source() -> String {
+    source_for("pwqneutral")
+}
+
+/// Run the SHIPPED `codegraph init` over `project`, producing a real v2
+/// namespace (permanent lock + `Current` state slots + stamped, checkpointed
+/// database). Never a hand-authored fixture.
+fn shipped_init(project: &Path) {
+    let output = base_command()
+        .args(["init"])
+        .arg(project)
+        .output()
+        .expect("run codegraph init");
+    assert!(
+        output.status.success(),
+        "codegraph init failed for {}: stdout={} stderr={}",
+        project.display(),
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+/// A command with the ambient index-location override cleared, so both the
+/// staging build and the served project resolve their own default v2 namespace.
+/// The daemon opt-out keeps ONE direct long-lived process (never a proxy to a
+/// shared daemon), and the watch opt-out keeps the live watcher off.
+fn base_command() -> Command {
+    let mut command = Command::new(bin());
+    command
+        .env_remove("CODEGRAPH_DIR")
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1");
+    command
+}
+
+fn index_paths(project: &Path) -> IndexPaths {
+    IndexPaths::resolve(project, None).expect("resolve v2 IndexPaths")
+}
+
+/// One long-lived shipped MCP stdio server plus the reader thread that turns its
+/// stdout into framed JSON-RPC responses.
+struct LongLivedMcp {
+    child: Child,
+    stdin: Option<ChildStdin>,
+    lines: mpsc::Receiver<String>,
+}
+
+impl LongLivedMcp {
+    /// Spawn `serve --mcp --path <project> --no-watch` with the daemon disabled,
+    /// so ONE direct, long-lived process owns the whole session.
+    fn spawn(project: &Path) -> Self {
+        let mut child = base_command()
+            .args(["serve", "--mcp", "--no-watch", "--path"])
+            .arg(project)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn long-lived serve --mcp");
+        let stdout = child.stdout.take().expect("child stdout");
+        let (tx, lines) = mpsc::channel();
+        std::thread::spawn(move || {
+            for line in BufReader::new(stdout).lines() {
+                let Ok(line) = line else { return };
+                if tx.send(line).is_err() {
+                    return;
+                }
+            }
+        });
+        let stdin = child.stdin.take().expect("child stdin");
+        Self {
+            child,
+            stdin: Some(stdin),
+            lines,
+        }
+    }
+
+    fn send(&mut self, frame: &Value) {
+        let stdin = self.stdin.as_mut().expect("child stdin still owned");
+        writeln!(stdin, "{frame}").expect("write MCP frame");
+        stdin.flush().expect("flush MCP frame");
+    }
+
+    /// Block until the child frames the response for `id`. The ARRIVAL of this
+    /// frame is the child's READY acknowledgement: rmcp writes it only after the
+    /// request's owned result was fully produced.
+    fn await_response(&self, id: i64) -> Value {
+        let deadline = Instant::now() + WAIT;
+        loop {
+            let remaining = deadline
+                .checked_duration_since(Instant::now())
+                .unwrap_or_default();
+            let line = self
+                .lines
+                .recv_timeout(remaining)
+                .unwrap_or_else(|error| panic!("no response for id {id} before deadline: {error}"));
+            let trimmed = line.trim();
+            if trimmed.is_empty() {
+                continue;
+            }
+            if let Ok(value) = serde_json::from_str::<Value>(trimmed)
+                && value.get("id").and_then(Value::as_i64) == Some(id)
+            {
+                return value;
+            }
+        }
+    }
+
+    /// Close stdin (EOF) and wait for the process to exit within the guard.
+    fn shutdown(mut self) {
+        drop(self.stdin.take());
+        let deadline = Instant::now() + WAIT;
+        loop {
+            match self.child.try_wait().expect("poll child status") {
+                Some(status) => {
+                    assert!(
+                        status.success(),
+                        "the long-lived MCP process must exit cleanly on stdin EOF: {status:?}"
+                    );
+                    return;
+                }
+                None => {
+                    assert!(
+                        Instant::now() < deadline,
+                        "the long-lived MCP process did not exit before its finite deadline"
+                    );
+                    std::thread::park_timeout(Duration::from_millis(5));
+                }
+            }
+        }
+    }
+}
+
+impl Drop for LongLivedMcp {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+fn initialize_frames() -> [Value; 2] {
+    [
+        json!({
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": { "name": "m16-acceptance", "version": "0" }
+            }
+        }),
+        json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }),
+    ]
+}
+
+fn search_frame(id: i64, project: &Path, query: &str) -> Value {
+    json!({
+        "jsonrpc": "2.0",
+        "id": id,
+        "method": "tools/call",
+        "params": {
+            "name": "codegraph_search",
+            "arguments": {
+                "query": query,
+                "projectPath": project.to_str().expect("utf8 project path")
+            }
+        }
+    })
+}
+
+/// The rendered tool text, rejecting a protocol error or an `isError` result so a
+/// failed request can never be mistaken for a graph observation.
+fn tool_text(response: &Value, context: &str) -> String {
+    assert!(
+        response.get("error").is_none(),
+        "{context} returned a JSON-RPC error: {response}"
+    );
+    assert_ne!(
+        response["result"]["isError"],
+        json!(true),
+        "{context} returned an error result: {response}"
+    );
+    response["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// Freeze the supplied-graph sources out of every future scan of the SERVED
+/// project, then PROVE it with the shipped scanner.
+///
+/// This is what makes the acceptance deterministic against the startup catch-up
+/// sync: the scanner is the same `scan_project` a sync feeds from, so an empty
+/// result for both supplied paths means no sync in this project can invent the
+/// replacement rows (or the original ones) from disk.
+fn freeze_supplied_sources_out_of_scans(project: &Path) {
+    fs::write(project.join(".gitignore"), format!("{SUPPLIED_DIR}/\n"))
+        .expect("write root .gitignore");
+
+    let scanned = codegraph_extract::engine::scan_project(project, &ExtractOptions::default())
+        .expect("scan the served project with the shipped scanner");
+    assert!(
+        scanned.contains(&NEUTRAL_FILE.to_string()),
+        "the neutral source must stay scannable so startup catch-up is a real no-op: {scanned:?}"
+    );
+    assert!(
+        !scanned.contains(&REPLACEMENT_FILE.to_string()),
+        "no sync may be able to index {REPLACEMENT_FILE}, or request 2 could pass by reindexing \
+         instead of by reading the replaced database: {scanned:?}"
+    );
+    assert!(
+        !scanned.contains(&ORIGINAL_FILE.to_string()),
+        "no sync may be able to re-index {ORIGINAL_FILE} back into the replacement graph: \
+         {scanned:?}"
+    );
+    // Both supplied sources stay PRESENT on disk, so the cold sync's removal
+    // pass (tracked-but-absent) can never delete their rows either.
+    for rel in [ORIGINAL_FILE, REPLACEMENT_FILE] {
+        assert!(
+            project.join(rel).is_file(),
+            "{rel} must remain on disk so no sync can classify it as removed"
+        );
+    }
+}
+
+/// Build the replacement database in a staging project and return its path. The
+/// staging project holds the neutral file plus ONLY the replacement supplied
+/// source and carries NO `.gitignore`, so its graph contains the replacement
+/// file and cannot contain the original one.
+fn build_replacement_database(staging: &TestDir) -> PathBuf {
+    let project = staging.path().join("replacement-build");
+    fs::create_dir_all(&project).expect("create staging project");
+    write_source(&project, NEUTRAL_FILE, &neutral_source());
+    write_source(&project, REPLACEMENT_FILE, &source_for(REPLACEMENT_SYMBOL));
+    shipped_init(&project);
+    let db = index_paths(&project).current_db();
+    assert!(
+        db.is_file(),
+        "staging build must produce a database at {}",
+        db.display()
+    );
+    db
+}
+
+/// Replace the live v2 main database file while the long-lived MCP process is
+/// still running. The project's SOURCES are deliberately left untouched.
+///
+/// The EXCLUSIVE index lease is acquired first: a retained reader lease from
+/// request 1 makes this fail, which is the fail-closed proof that the long-lived
+/// process released its lease when the request ended. `fs::rename` is then the
+/// atomic replacement — on native Windows it fails outright if any process still
+/// holds an open handle on the destination.
+fn replace_database(project: &Path, replacement_db: &Path) {
+    let paths = index_paths(project);
+    let lease = IndexLease::acquire_exclusive_existing(&paths, Instant::now() + WAIT, || false)
+        .expect(
+            "the long-lived MCP process must have released every reader lease once request 1 \
+             completed, so the exclusive lease is available for the replacement",
+        );
+
+    let target = paths.current_db();
+    fs::rename(replacement_db, &target).unwrap_or_else(|error| {
+        panic!(
+            "atomically replacing {} must succeed while the long-lived MCP process is running \
+             (a retained SQLite handle makes this fail on native Windows): {error}",
+            target.display()
+        )
+    });
+
+    // The read path refuses a `Current` namespace whose SQLite sidecars
+    // reappeared without a state change. Assert that fail-closed contract holds
+    // for the replaced artifact instead of repairing it.
+    for suffix in ["-wal", "-shm"] {
+        let mut sidecar = target.as_os_str().to_os_string();
+        sidecar.push(suffix);
+        let sidecar = PathBuf::from(sidecar);
+        assert!(
+            !sidecar.exists(),
+            "the replaced namespace must stay sidecar-free: {} exists",
+            sidecar.display()
+        );
+    }
+    assert!(
+        paths.permanent_lock().is_file(),
+        "the replacement must preserve the permanent lock at {}",
+        paths.permanent_lock().display()
+    );
+    let [slot_zero, slot_one] = paths.state_slots();
+    assert!(
+        slot_zero.is_file() || slot_one.is_file(),
+        "the replacement must preserve the published Current state slots"
+    );
+
+    drop(lease);
+}
+
+#[test]
+fn long_lived_v2_mcp_releases_handles_per_request() {
+    // GIVEN a really indexed v2 project whose graph contains the original
+    // supplied symbol, with both supplied sources frozen out of every future
+    // scan, and a separately built replacement database that contains ONLY the
+    // replacement supplied symbol.
+    let home = TestDir::new("served");
+    let project = home.path().join("project");
+    fs::create_dir_all(&project).expect("create served project");
+    write_source(&project, NEUTRAL_FILE, &neutral_source());
+    write_source(&project, ORIGINAL_FILE, &source_for(ORIGINAL_SYMBOL));
+    shipped_init(&project);
+
+    write_source(&project, REPLACEMENT_FILE, &source_for(REPLACEMENT_SYMBOL));
+    freeze_supplied_sources_out_of_scans(&project);
+
+    let staging = TestDir::new("staging");
+    let replacement_db = build_replacement_database(&staging);
+
+    // ONE long-lived shipped MCP process serves the whole session.
+    let mut server = LongLivedMcp::spawn(&project);
+    let [initialize, initialized] = initialize_frames();
+    server.send(&initialize);
+    let init_response = server.await_response(1);
+    assert_eq!(
+        init_response["result"]["serverInfo"]["name"],
+        json!("codegraph"),
+        "the long-lived process must be the shipped codegraph MCP server: {init_response}"
+    );
+    server.send(&initialized);
+
+    // WHEN request 1 completes (its framed response IS the READY barrier) ...
+    server.send(&search_frame(2, &project, ORIGINAL_SYMBOL));
+    let first = tool_text(&server.await_response(2), "request 1");
+    assert!(
+        first.contains(ORIGINAL_FILE),
+        "request 1 must observe the original graph: {first}"
+    );
+    assert!(
+        !first.contains(REPLACEMENT_FILE),
+        "request 1 must not observe the replacement graph: {first}"
+    );
+
+    // ... the parent takes the exclusive lease (handles released) and atomically
+    // replaces the v2 database. No compatibility seam participates.
+    replace_database(&project, &replacement_db);
+
+    // THEN the CONTINUE frame (request 2) serves ONLY the replacement graph.
+    server.send(&search_frame(3, &project, REPLACEMENT_SYMBOL));
+    let second = tool_text(&server.await_response(3), "request 2");
+    assert!(
+        second.contains("## Search Results ("),
+        "request 2 must render real search results, not an echo: {second}"
+    );
+    assert!(
+        second.contains(REPLACEMENT_FILE),
+        "request 2 must serve the replacement graph: {second}"
+    );
+    assert!(
+        !second.contains(ORIGINAL_FILE),
+        "request 2 must not leak the original graph: {second}"
+    );
+
+    // And the original symbol is GONE from the same long-lived session: the
+    // absence is observed through a lookup that resolves nothing, not through a
+    // response that merely omits it.
+    server.send(&search_frame(4, &project, ORIGINAL_SYMBOL));
+    let third = tool_text(&server.await_response(4), "request 3");
+    assert!(
+        third.contains("No results found"),
+        "the original symbol must be absent from the replacement graph: {third}"
+    );
+    assert!(
+        !third.contains(ORIGINAL_FILE),
+        "the original file must be absent from the replacement graph: {third}"
+    );
+
+    server.shutdown();
+}
+
+/// The acceptance flow must be independent of the compatibility close seam, so
+/// no CODE in this file may name it — not as a call, an import, an alias, or a
+/// wrapper. Checked structurally against this file's own bytes: comment lines
+/// (which document the seam by name) are excluded, and the needle itself is
+/// assembled from two halves so neither this oracle nor its failure message is a
+/// match for what it forbids.
+#[test]
+fn acceptance_flow_never_calls_the_close_helper() {
+    let offenders = code_lines_naming(include_str!("batch_m_long_lived_mcp.rs"), CLOSE_SEAM);
+    assert!(
+        offenders.is_empty(),
+        "the M16 acceptance flow must not depend on the {CLOSE_SEAM} compatibility seam, but \
+         these code lines name it: {offenders:?}"
+    );
+}
+
+/// Non-comment lines of `source` that contain `needle`, as `"<line>: <text>"`.
+/// A line whose first non-whitespace characters are `//` is documentation (this
+/// file's own module docs and comments discuss the seam by name), so only real
+/// code is inspected.
+fn code_lines_naming(source: &str, needle: &str) -> Vec<String> {
+    source
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| !line.trim_start().starts_with("//"))
+        .filter(|(_, line)| line.contains(needle))
+        .map(|(index, line)| format!("{}: {}", index + 1, line.trim()))
+        .collect()
+}
+
+#[cfg(test)]
+mod oracle_tests {
+    use super::code_lines_naming;
+
+    /// The forbidden-name oracle must SEE a real invocation and IGNORE a comment
+    /// that merely mentions the name, so it can neither pass vacuously nor fail
+    /// on this file's own documentation.
+    #[test]
+    fn code_lines_naming_sees_code_and_ignores_comments() {
+        let needle = concat!("forbidden", "_seam");
+        let source = concat!(
+            "//! docs mention forbidden_seam by name\n",
+            "    // so does an indented comment: forbidden_seam\n",
+            "let clean = other_call();\n",
+            "    store.forbidden_seam();\n"
+        );
+        let found = code_lines_naming(source, needle);
+        assert_eq!(
+            found,
+            vec!["4: store.forbidden_seam();".to_string()],
+            "only the real invocation line is an offender"
+        );
+    }
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e5f1a42..4bd5725 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2601,3 +2601,102 @@ changes no schema, node-ID formula, extraction or golden byte, `UPSTREAM.md`, or
 evidence bytes are written BEFORE repository formatting and the one authoritative
 `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run
 over these exact final bytes; no final Green is claimed until that gate passes.
+
+## Batch M item 16 acceptance closure — long-lived MCP releases handles per request (2026-07-26)
+
+Frozen plan item 16 asks for `long_lived_v2_mcp_releases_handles_per_request`: a
+long-lived shipped MCP process must let the v2 main database be REPLACED on
+Windows without the compatibility close seam and then serve only the replacement
+graph, using a child-process ready/continue barrier around request completion and
+file replacement, explicitly selected in the native Windows CI job.
+
+The acceptance lands as one new query-side test target,
+`crates/codegraph-cli/tests/batch_m_long_lived_mcp.rs`, over the SHIPPED binary
+(`CARGO_BIN_EXE_codegraph`). No production byte changed: M15 already made MCP
+engines request-scoped, so this item is the behavioral proof of that ownership,
+not a new mechanism.
+
+The barrier is the MCP wire protocol, never a sleep. ONE
+`codegraph serve --mcp --no-watch --path <project>` child (daemon opted out via
+`CODEGRAPH_NO_DAEMON=1`, so the session is a single direct process rather than a
+proxy) is driven over stdio pipes. READY is the arrival of the framed JSON-RPC
+response for request 1 — rmcp writes that frame only after the request produced
+its owned, fully materialized result, so the frame proves end-to-end completion
+rather than mere SQL completion. The parent then acquires the namespace's
+EXCLUSIVE lease through `IndexLease::acquire_exclusive_existing`; a retained
+reader lease makes that acquisition fail, so it is the fail-closed observation
+that the child released everything. Still holding the lease, the parent
+`fs::rename`s a separately built database over the live main database file — the
+Windows-specific handle proof, since `MoveFileEx` + `REPLACE_EXISTING` fails with
+a sharing violation while any process holds an open handle on the destination.
+CONTINUE is the next request frame, which cannot have been read earlier because it
+had not been written. The 60s channel/lease deadlines are deadlock guards only; no
+assertion is satisfied by waiting, and neither mtime nor process exit is used as
+ordering evidence.
+
+Both databases come from the real `codegraph init`, so the replaced namespace
+keeps its own permanent lock, its own published `Current` state slots, and an
+exact extraction stamp in the replaced bytes. The test additionally asserts the
+replaced namespace stays sidecar-free and that the lock and state slots survive,
+so no state/sidecar/stamp/lease gate is weakened or repaired.
+
+The startup catch-up race identified in manual review is CLOSED with runtime
+evidence rather than documented as a caveat. `serve --mcp --path` spawns a
+one-shot catch-up sync on a detached thread and `--no-watch` does not disable it,
+so a reindex could otherwise satisfy (or later undo) the post-replacement
+assertions. The two distinguishing sources therefore live under a directory the
+served project's own root `.gitignore` excludes, and the test PROVES the exclusion
+with the shipped `codegraph_extract::engine::scan_project` — the same scanner a
+sync feeds from — before the acceptance runs: the neutral shared file is scanned,
+both supplied files are not. No sync can create those rows (the scanner never
+yields the paths) and none can delete them (the cold removal pass only considers a
+tracked path absent from disk, and both files stay present, which the test also
+asserts). The remaining scannable file is byte-identical in both graphs, so the
+catch-up is a proven no-op. The only way request 2 can see the replacement file is
+by reading the supplied bytes.
+
+The forbidden-seam invariant is kept and strengthened rather than weakened: it now
+inspects only NON-COMMENT lines of this file's own source for a needle assembled
+from two halves, so it detects a real invocation, an import, an alias, or a
+wrapper while the module docs may still name the seam in prose. A companion unit
+test proves the oracle sees a real call line and ignores a comment mentioning the
+same name, so it cannot pass vacuously.
+
+Three negative-control runs establish the assertions are load-bearing (each
+reverted immediately, file restored to SHA-256
+`773a23abf4dee6ddac8acd6cf7bee6a0600dd9203051c8efc22d9f7502f40731`): renaming the
+target onto itself instead of installing the replacement fails request 2 with
+`No results found for "hbtvancur"`; commenting out the `.gitignore` line fails the
+scan-freeze precondition, which is exactly the reindex loophole the design closes;
+and adding a real `server.close_cached_handles()` call makes the forbidden-seam
+oracle fail and name the offending line.
+
+Local Green on the integrated bytes, with
+`bash scripts/check-workspace-versions.sh` run before every Cargo batch and
+`--locked` on every Cargo command:
+`cargo test --locked -p codegraph-rs --test batch_m_long_lived_mcp` **3/3**,
+`cargo test --locked -p codegraph-rs --test lease_lifetime` **5/5**, and
+`cargo test --locked -p codegraph-mcp --test reopen` **3/3**. Workspace all-target
+check, Clippy with `-D warnings`, formatting, guardrail, and `git diff --check`
+also pass. Changed-file LSP diagnostics were attempted for the new target and the
+tool again rejected this required external worktree with
+`LSP file path must be inside request cwd`; locked Cargo diagnostics are the
+honest fallback and this ledger claims no LSP-clean result.
+
+Native Windows/MSVC runtime was NOT executed here and is not claimed — this Linux
+host cannot provide it. Windows coverage in this slice is CI WIRING: the existing
+native `windows-latest` job gains one additional step,
+`cargo test -p codegraph-rs --test batch_m_long_lived_mcp`, which selects this
+exact target explicitly so the replacement acceptance runs natively and is never
+reduced to compile-only or skipped. Every existing Windows step — including the
+M22 legacy-fixture wiring — is byte-preserved, and the surrounding jobs, action
+pins, and the `CI Success` gate are unchanged.
+
+This slice adds no dependency and changes no schema, node-ID formula, extraction
+or golden byte, `UPSTREAM.md`, or `KNOWN_DIFFS.md`; the frozen plan is untouched
+at SHA-256 `5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450` and
+`Cargo.lock` remains required at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. These
+evidence bytes are written BEFORE repository formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run
+over these exact final bytes; no final Green is claimed until that gate passes.

From 73833fa1bdad29e77e93221b2b31c2d2295210b4 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 19:12:24 +0800
Subject: [PATCH 34/91] test(mcp): prove a failed engine open is not cached

---
 .../tests/batch_m_failed_open_recovery.rs     | 808 ++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 133 +++
 2 files changed, 941 insertions(+)
 create mode 100644 crates/codegraph-cli/tests/batch_m_failed_open_recovery.rs

diff --git a/crates/codegraph-cli/tests/batch_m_failed_open_recovery.rs b/crates/codegraph-cli/tests/batch_m_failed_open_recovery.rs
new file mode 100644
index 0000000..b5e42ce
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_failed_open_recovery.rs
@@ -0,0 +1,808 @@
+//! Batch M acceptance item 17 (frozen plan line 779):
+//! `failed_engine_open_is_not_cached_and_next_request_recovers`.
+//!
+//! ONE long-lived SHIPPED MCP process (`codegraph serve --mcp --path <project>`)
+//! receives a request whose engine/`Store` open FAILS for a real v2
+//! state/artifact reason. The process must stay healthy, must retain NOTHING
+//! from that failed open — no cached error, no partial engine, no `Store`, no
+//! SQLite handle, no lease, no stale project result — and the NEXT request in the
+//! SAME process, after the namespace is repaired without a restart, must succeed
+//! and serve ONLY the repaired graph.
+//!
+//! # The staged failure is a real v2 inconsistency, not a stub
+//!
+//! The served project is really indexed by the shipped `codegraph init`, then
+//! BOTH fixed state slots are removed and nothing else. The namespace therefore
+//! classifies `Missing` while its main database (and its permanent lock) are
+//! still present, which the read gate refuses with
+//! `state is missing but a database artifact already exists at <db>`
+//! (`reject_missing_database_artifacts`). Nothing here weakens or repairs a gate
+//! to produce the failure, and nothing teaches a production read to accept an
+//! invalid state.
+//!
+//! Crucially the failure happens AFTER project resolution: the current-namespace
+//! DB file still exists, so `roots::probe_root` classifies the project `Indexed`
+//! and `resolve_project_arg` resolves it. The test asserts request 1 carries the
+//! ENGINE-OPEN diagnostic (`Failed to open project at …`), never the
+//! resolution-miss diagnostic, so a resolution failure can never be mistaken for
+//! the engine-open failure this item is about.
+//!
+//! # Determinism: protocol frames and fail-closed gates, never a sleep
+//!
+//! 1. **READY** — the parent blocks until the child frames the JSON-RPC response
+//!    for request 1. rmcp writes that frame only after the request's OWNED result
+//!    was fully materialized, so the frame proves request 1 finished end-to-end.
+//! 2. **NO RETAINED LEASE** — the parent then acquires the namespace's EXCLUSIVE
+//!    lease. A shared reader lease retained by the FAILED open makes this
+//!    acquisition fail, so the exclusive lease is the fail-closed observation
+//!    that the failed open let go of everything.
+//! 3. **NO RETAINED SQLITE HANDLE** — still holding that exclusive lease, the
+//!    parent renames the separately built repaired database over the live main
+//!    database file. On native Windows that rename fails with a sharing violation
+//!    while any process holds an open handle on the destination, so it is the
+//!    Windows handle proof for the failed-open path.
+//! 4. **REPAIR COMPLETION** — the repair is finished by the protocol-aware
+//!    `Missing -> Building -> Current` fixture finalizer, and the parent asserts
+//!    the namespace classifies `Current` (plus lock/state-slot/sidecar
+//!    invariants) BEFORE sending request 2. Completion is observed from published
+//!    state, never from elapsed time.
+//! 5. **CONTINUE** — request 2's frame is written only after that. The child
+//!    cannot have started it earlier because it had not been written.
+//!
+//! Channel/lease deadlines (`WAIT`) are DEADLOCK GUARDS only. No assertion in
+//! this file is satisfied by waiting, by mtime, or by process exit.
+//!
+//! # Startup catch-up can neither repair the staged state nor fake the recovery
+//!
+//! `serve --mcp --path` runs a one-shot startup catch-up sync on a detached
+//! thread and `--no-watch` does not disable it, so it must be excluded as an
+//! explanation for BOTH halves of the acceptance:
+//!
+//! - It cannot repair the staged `Missing`-with-database namespace:
+//!   [`catch_up_sync_refuses_missing_state_with_database_without_mutating_bytes`]
+//!   drives the SAME `codegraph_watch::sync_project_once` entry point the
+//!   catch-up thread calls against an identically staged namespace and proves it
+//!   fails with the same state/artifact diagnostic while leaving the database
+//!   bytes byte-identical and the state slots absent. That is a gate, not a race.
+//! - It cannot invent the repaired rows: the two distinguishing sources live
+//!   under a directory the served project's own root `.gitignore` excludes, which
+//!   the test PROVES with the shipped scanner. No sync can create those rows
+//!   (`scan_project` never yields the paths) and none can delete them (the cold
+//!   removal pass only considers a tracked path that is ALSO absent from disk,
+//!   and both files stay present). The only scannable file is byte-identical in
+//!   both graphs, so a catch-up that somehow ran after the repair is a proven
+//!   no-op rather than a source of the assertions.
+//!
+//! # A legacy namespace is not a recovery source
+//!
+//! The project also carries a legacy `.codegraph/codegraph.db` holding a TRAP
+//! symbol that exists in no other graph. Request 2 must not surface it, so a
+//! silent legacy fallback cannot masquerade as recovery.
+//!
+//! # Scope
+//!
+//! Query-side acceptance over the shipped binary plus one in-process test of the
+//! same engine-open seam. M15 already made every MCP engine request-scoped, so
+//! this item is the behavioral proof of that ownership; no production byte
+//! changes here.
+
+use std::fs;
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, Command, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_extract::ExtractOptions;
+use codegraph_store::{ExtractionStatus, IndexLease, Store};
+use serde_json::{Value, json};
+
+/// Finite deadlock guard for every blocking wait. Never ordering evidence.
+const WAIT: Duration = Duration::from_secs(60);
+
+/// The scannable file every project here shares, byte-identical, so the startup
+/// catch-up sync is a proven no-op instead of a degenerate empty scan.
+const NEUTRAL_FILE: &str = "src/mkqneutral.ts";
+/// The gitignored directory holding the supplied-graph-only sources. Nothing
+/// under it is ever scanned in the SERVED project.
+const SUPPLIED_DIR: &str = "supplied";
+/// The symbol that exists ONLY in the pre-repair (original) graph.
+const ORIGINAL_SYMBOL: &str = "zrqmfoss";
+/// The repo-relative file that exists ONLY in the pre-repair graph.
+const ORIGINAL_FILE: &str = "supplied/zrqmfoss.ts";
+/// The symbol that exists ONLY in the repaired graph.
+const REPAIRED_SYMBOL: &str = "vtwkhelm";
+/// The repo-relative file that exists ONLY in the repaired graph.
+const REPAIRED_FILE: &str = "supplied/vtwkhelm.ts";
+/// The symbol that exists ONLY in the LEGACY `.codegraph` database.
+const LEGACY_TRAP_SYMBOL: &str = "jbxdlurn";
+/// The repo-relative file that exists ONLY in the legacy database.
+const LEGACY_TRAP_FILE: &str = "supplied/jbxdlurn.ts";
+
+/// The exact fail-closed diagnostic the v2 read gate produces for a `Missing`
+/// state whose database artifact still exists.
+const MISSING_WITH_DB: &str = "state is missing but a database artifact already exists";
+
+/// The compatibility close seam this recovery flow must never touch, spelled in
+/// two halves so this file's own bytes are not a match for it.
+const CLOSE_SEAM: &str = concat!("close_cached", "_handles");
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+/// A temp directory removed on drop.
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-m17-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock")
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).expect("create temp dir");
+        Self(path)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+/// Write one source file, creating parents.
+fn write_source(root: &Path, rel: &str, contents: &str) {
+    let path = root.join(rel);
+    fs::create_dir_all(path.parent().expect("source parent")).expect("create source dir");
+    fs::write(&path, contents).expect("write source file");
+}
+
+fn source_for(symbol: &str) -> String {
+    format!("export function {symbol}(): number {{\n  return 1;\n}}\n")
+}
+
+/// The neutral scannable source, byte-identical in every project here.
+fn neutral_source() -> String {
+    source_for("mkqneutral")
+}
+
+/// A command with the ambient index-location override cleared, the daemon opted
+/// out (ONE direct long-lived process, never a proxy) and the live watcher off.
+fn base_command() -> Command {
+    let mut command = Command::new(bin());
+    command
+        .env_remove("CODEGRAPH_DIR")
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1");
+    command
+}
+
+/// Run the SHIPPED `codegraph init` over `project`, producing a real v2
+/// namespace (permanent lock + published `Current` state slots + stamped,
+/// checkpointed database). Never a hand-authored fixture.
+fn shipped_init(project: &Path) {
+    let output = base_command()
+        .args(["init"])
+        .arg(project)
+        .output()
+        .expect("run codegraph init");
+    assert!(
+        output.status.success(),
+        "codegraph init failed for {}: stdout={} stderr={}",
+        project.display(),
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+fn index_paths(project: &Path) -> IndexPaths {
+    IndexPaths::resolve(project, None).expect("resolve v2 IndexPaths")
+}
+
+/// Build a project containing the neutral source plus `supplied_rel`, index it
+/// with the shipped `init`, and return its current database path. The staging
+/// project carries NO `.gitignore`, so its graph really does contain
+/// `supplied_rel` and cannot contain any other supplied source.
+fn build_graph_database(
+    staging: &TestDir,
+    label: &str,
+    supplied_rel: &str,
+    symbol: &str,
+) -> PathBuf {
+    let project = staging.path().join(label);
+    fs::create_dir_all(&project).expect("create staging project");
+    write_source(&project, NEUTRAL_FILE, &neutral_source());
+    write_source(&project, supplied_rel, &source_for(symbol));
+    shipped_init(&project);
+    let db = index_paths(&project).current_db();
+    assert!(
+        db.is_file(),
+        "staging build must produce a database at {}",
+        db.display()
+    );
+    db
+}
+
+/// Materialize a really indexed served project, freeze the supplied sources out
+/// of every future scan, plant the legacy trap graph, and then break the v2
+/// namespace into the REAL `Missing`-state-with-existing-database inconsistency
+/// by removing ONLY the two fixed state slots.
+fn stage_missing_state_with_database(project: &Path, staging: &TestDir, label: &str) -> IndexPaths {
+    fs::create_dir_all(project).expect("create served project");
+    write_source(project, NEUTRAL_FILE, &neutral_source());
+    write_source(project, ORIGINAL_FILE, &source_for(ORIGINAL_SYMBOL));
+    shipped_init(project);
+
+    // Both distinguishing sources exist on disk from here on, so no sync can
+    // classify either as removed.
+    write_source(project, REPAIRED_FILE, &source_for(REPAIRED_SYMBOL));
+    write_source(project, LEGACY_TRAP_FILE, &source_for(LEGACY_TRAP_SYMBOL));
+    freeze_supplied_sources_out_of_scans(project);
+    plant_legacy_trap_graph(project, staging, label);
+
+    let paths = index_paths(project);
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Current,
+        "the shipped init must leave a readable Current namespace before it is broken"
+    );
+
+    for slot in paths.state_slots() {
+        if slot.exists() {
+            fs::remove_file(&slot).expect("remove one fixed state slot");
+        }
+    }
+
+    // The namespace is now genuinely inconsistent: no state, but the database
+    // and the permanent lock are still there.
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Missing,
+        "removing both fixed state slots must classify the namespace Missing"
+    );
+    assert!(
+        paths.current_db().is_file(),
+        "the staged failure requires the main database to still exist at {}",
+        paths.current_db().display()
+    );
+    assert!(
+        paths.permanent_lock().is_file(),
+        "the staged failure keeps the permanent lock at {}",
+        paths.permanent_lock().display()
+    );
+    assert!(
+        !paths.tombstone().exists(),
+        "the staged failure is a missing-state inconsistency, not an uninit tombstone"
+    );
+
+    // The read gate must reject it for exactly the staged reason, checked before
+    // any server is involved so the acceptance cannot mistake another failure
+    // for this one.
+    let rejection = Store::open_for_read(&paths, Instant::now() + WAIT, || false)
+        .expect_err("a Missing state with an existing database must fail closed")
+        .to_string();
+    assert!(
+        rejection.contains(MISSING_WITH_DB),
+        "the staged condition must be the missing-state-with-database refusal: {rejection}"
+    );
+
+    paths
+}
+
+/// Freeze the supplied sources out of every future scan of `project`, then PROVE
+/// it with the shipped scanner — the same `scan_project` a sync feeds from.
+fn freeze_supplied_sources_out_of_scans(project: &Path) {
+    fs::write(project.join(".gitignore"), format!("{SUPPLIED_DIR}/\n"))
+        .expect("write root .gitignore");
+
+    let scanned = codegraph_extract::engine::scan_project(project, &ExtractOptions::default())
+        .expect("scan the served project with the shipped scanner");
+    assert!(
+        scanned.contains(&NEUTRAL_FILE.to_string()),
+        "the neutral source must stay scannable so startup catch-up is a real no-op: {scanned:?}"
+    );
+    for rel in [ORIGINAL_FILE, REPAIRED_FILE, LEGACY_TRAP_FILE] {
+        assert!(
+            !scanned.contains(&rel.to_string()),
+            "no sync may be able to index {rel}, or the recovery request could pass by reindexing \
+             instead of by reading the repaired database: {scanned:?}"
+        );
+        assert!(
+            project.join(rel).is_file(),
+            "{rel} must remain on disk so no sync can classify it as removed"
+        );
+    }
+}
+
+/// Plant a LEGACY `.codegraph/codegraph.db` holding a graph that exists nowhere
+/// else, so a silent legacy fallback cannot masquerade as recovery.
+fn plant_legacy_trap_graph(project: &Path, staging: &TestDir, label: &str) {
+    let trap_db = build_graph_database(
+        staging,
+        &format!("{label}-legacy-trap"),
+        LEGACY_TRAP_FILE,
+        LEGACY_TRAP_SYMBOL,
+    );
+    let legacy_root = project.join(".codegraph");
+    fs::create_dir_all(&legacy_root).expect("create the legacy root");
+    fs::copy(&trap_db, legacy_root.join("codegraph.db")).expect("plant the legacy trap database");
+}
+
+/// Repair the staged namespace WITHOUT restarting the server.
+///
+/// The EXCLUSIVE lease is acquired first: a shared reader lease retained by the
+/// FAILED open makes this fail, which is the fail-closed proof that the failed
+/// open released everything. `fs::rename` under that lease then installs the
+/// repaired database — on native Windows it fails outright if any process still
+/// holds an open handle on the destination. The protocol-aware fixture finalizer
+/// republishes `Missing -> Building -> Current` with the exact extraction stamp,
+/// so no production read gate is weakened to make the recovery work.
+fn repair_without_restart(paths: &IndexPaths, repaired_db: &Path) {
+    let lease = IndexLease::acquire_exclusive_existing(paths, Instant::now() + WAIT, || false)
+        .expect(
+            "the failed engine open must have retained no shared reader lease, so the exclusive \
+             lease is available for the repair",
+        );
+
+    let target = paths.current_db();
+    fs::rename(repaired_db, &target).unwrap_or_else(|error| {
+        panic!(
+            "installing the repaired database at {} must succeed while the long-lived MCP process \
+             is running (a retained SQLite handle from the failed open makes this fail on native \
+             Windows): {error}",
+            target.display()
+        )
+    });
+    drop(lease);
+
+    codegraph_store::test_support::finalize_current_test_fixture(paths)
+        .expect("republish Missing -> Building -> Current over the repaired database");
+
+    // Repair COMPLETION is observed from published state and artifact shape, not
+    // from elapsed time.
+    assert_eq!(
+        Store::extraction_status(paths),
+        ExtractionStatus::Current,
+        "the repair must publish a readable Current namespace"
+    );
+    let [slot_zero, slot_one] = paths.state_slots();
+    assert!(
+        slot_zero.is_file() || slot_one.is_file(),
+        "the repair must leave a published state slot behind"
+    );
+    assert!(
+        paths.permanent_lock().is_file(),
+        "the repair must preserve the permanent lock at {}",
+        paths.permanent_lock().display()
+    );
+    for suffix in ["-wal", "-shm"] {
+        let mut sidecar = target.as_os_str().to_os_string();
+        sidecar.push(suffix);
+        let sidecar = PathBuf::from(sidecar);
+        assert!(
+            !sidecar.exists(),
+            "the repaired namespace must stay sidecar-free: {} exists",
+            sidecar.display()
+        );
+    }
+}
+
+/// One long-lived shipped MCP stdio server plus the reader thread that turns its
+/// stdout into framed JSON-RPC responses.
+struct LongLivedMcp {
+    child: Child,
+    stdin: Option<ChildStdin>,
+    lines: mpsc::Receiver<String>,
+}
+
+impl LongLivedMcp {
+    /// Spawn `serve --mcp --path <project> --no-watch` with the daemon disabled,
+    /// so ONE direct, long-lived process owns the whole session.
+    fn spawn(project: &Path) -> Self {
+        let mut child = base_command()
+            .args(["serve", "--mcp", "--no-watch", "--path"])
+            .arg(project)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn long-lived serve --mcp");
+        let stdout = child.stdout.take().expect("child stdout");
+        let (tx, lines) = mpsc::channel();
+        std::thread::spawn(move || {
+            for line in BufReader::new(stdout).lines() {
+                let Ok(line) = line else { return };
+                if tx.send(line).is_err() {
+                    return;
+                }
+            }
+        });
+        let stdin = child.stdin.take().expect("child stdin");
+        Self {
+            child,
+            stdin: Some(stdin),
+            lines,
+        }
+    }
+
+    fn send(&mut self, frame: &Value) {
+        let stdin = self.stdin.as_mut().expect("child stdin still owned");
+        writeln!(stdin, "{frame}").expect("write MCP frame");
+        stdin.flush().expect("flush MCP frame");
+    }
+
+    /// Block until the child frames the response for `id`. The ARRIVAL of this
+    /// frame is the child's READY acknowledgement: rmcp writes it only after the
+    /// request's owned result was fully produced.
+    fn await_response(&self, id: i64) -> Value {
+        let deadline = Instant::now() + WAIT;
+        loop {
+            let remaining = deadline
+                .checked_duration_since(Instant::now())
+                .unwrap_or_default();
+            let line = self
+                .lines
+                .recv_timeout(remaining)
+                .unwrap_or_else(|error| panic!("no response for id {id} before deadline: {error}"));
+            let trimmed = line.trim();
+            if trimmed.is_empty() {
+                continue;
+            }
+            if let Ok(value) = serde_json::from_str::<Value>(trimmed)
+                && value.get("id").and_then(Value::as_i64) == Some(id)
+            {
+                return value;
+            }
+        }
+    }
+
+    /// Close stdin (EOF) and wait for the process to exit within the guard.
+    fn shutdown(mut self) {
+        drop(self.stdin.take());
+        let deadline = Instant::now() + WAIT;
+        loop {
+            match self.child.try_wait().expect("poll child status") {
+                Some(status) => {
+                    assert!(
+                        status.success(),
+                        "the long-lived MCP process must exit cleanly on stdin EOF: {status:?}"
+                    );
+                    return;
+                }
+                None => {
+                    assert!(
+                        Instant::now() < deadline,
+                        "the long-lived MCP process did not exit before its finite deadline"
+                    );
+                    std::thread::park_timeout(Duration::from_millis(5));
+                }
+            }
+        }
+    }
+}
+
+impl Drop for LongLivedMcp {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+fn initialize_frames() -> [Value; 2] {
+    [
+        json!({
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": { "name": "m17-acceptance", "version": "0" }
+            }
+        }),
+        json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }),
+    ]
+}
+
+fn search_frame(id: i64, project: &Path, query: &str) -> Value {
+    json!({
+        "jsonrpc": "2.0",
+        "id": id,
+        "method": "tools/call",
+        "params": {
+            "name": "codegraph_search",
+            "arguments": {
+                "query": query,
+                "projectPath": project.to_str().expect("utf8 project path")
+            }
+        }
+    })
+}
+
+/// The rendered text of a SUCCESSFUL tool result, rejecting a protocol error or
+/// an `isError` result so a failed request can never be mistaken for a graph
+/// observation.
+fn tool_text(response: &Value, context: &str) -> String {
+    assert!(
+        response.get("error").is_none(),
+        "{context} returned a JSON-RPC error: {response}"
+    );
+    assert_ne!(
+        response["result"]["isError"],
+        json!(true),
+        "{context} returned an error result: {response}"
+    );
+    response["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string()
+}
+
+/// The rendered text of an `isError` tool result. A JSON-RPC protocol error or a
+/// SUCCESS result is rejected: the failed open must surface as a tool error the
+/// live session survives, not as a transport failure and not as a pass.
+fn tool_error_text(response: &Value, context: &str) -> String {
+    assert!(
+        response.get("error").is_none(),
+        "{context} must fail as a tool error, not a JSON-RPC error: {response}"
+    );
+    assert_eq!(
+        response["result"]["isError"],
+        json!(true),
+        "{context} must return an isError result: {response}"
+    );
+    response["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string()
+}
+
+#[test]
+fn failed_engine_open_is_not_cached_and_next_request_recovers() {
+    // GIVEN a really indexed v2 project broken into the REAL
+    // `Missing`-state-with-existing-database inconsistency, its distinguishing
+    // sources frozen out of every scan, a legacy trap graph planted beside it,
+    // and a separately built repaired database.
+    let home = TestDir::new("served");
+    let project = home.path().join("project");
+    let staging = TestDir::new("staging");
+    let paths = stage_missing_state_with_database(&project, &staging, "served");
+    let repaired_db = build_graph_database(&staging, "repaired", REPAIRED_FILE, REPAIRED_SYMBOL);
+
+    // ONE long-lived shipped MCP process serves the whole session.
+    let mut server = LongLivedMcp::spawn(&project);
+    let [initialize, initialized] = initialize_frames();
+    server.send(&initialize);
+    let init_response = server.await_response(1);
+    assert_eq!(
+        init_response["result"]["serverInfo"]["name"],
+        json!("codegraph"),
+        "the long-lived process must be the shipped codegraph MCP server: {init_response}"
+    );
+    server.send(&initialized);
+
+    // WHEN request 1 resolves the project but FAILS opening the engine/Store on
+    // the staged v2 inconsistency (its framed response IS the READY barrier) ...
+    server.send(&search_frame(2, &project, REPAIRED_SYMBOL));
+    let failure = tool_error_text(&server.await_response(2), "request 1");
+    assert!(
+        failure.contains("Failed to open project at"),
+        "request 1 must fail in the ENGINE OPEN, after project resolution: {failure}"
+    );
+    assert!(
+        failure.contains(MISSING_WITH_DB),
+        "request 1 must fail for the staged v2 state/artifact reason: {failure}"
+    );
+    assert!(
+        !failure.contains("No indexed project"),
+        "request 1 must not be a project-resolution miss: {failure}"
+    );
+
+    // ... the namespace is repaired IN PLACE, with no restart: the exclusive
+    // lease proves no reader lease survived the failed open, the rename proves no
+    // SQLite handle did, and the fixture finalizer republishes a real Current
+    // state.
+    repair_without_restart(&paths, &repaired_db);
+
+    // THEN the very next request in the SAME process succeeds and serves ONLY
+    // the repaired graph, so the failed open was cached neither as an error nor
+    // as a stale project result.
+    server.send(&search_frame(3, &project, REPAIRED_SYMBOL));
+    let recovered = tool_text(&server.await_response(3), "request 2");
+    assert!(
+        recovered.contains("## Search Results ("),
+        "request 2 must render real search results, not an echo: {recovered}"
+    );
+    assert!(
+        recovered.contains(REPAIRED_FILE),
+        "request 2 must serve the repaired graph: {recovered}"
+    );
+    assert!(
+        !recovered.contains(ORIGINAL_FILE),
+        "request 2 must not leak the pre-repair graph: {recovered}"
+    );
+    assert!(
+        !recovered.contains(LEGACY_TRAP_FILE),
+        "request 2 must not read the legacy namespace: {recovered}"
+    );
+
+    // The pre-repair symbol is GONE from the same long-lived session, observed
+    // through a lookup that resolves nothing rather than a response that merely
+    // omits it.
+    server.send(&search_frame(4, &project, ORIGINAL_SYMBOL));
+    let original = tool_text(&server.await_response(4), "request 3");
+    assert!(
+        original.contains("No results found"),
+        "the pre-repair symbol must be absent from the repaired graph: {original}"
+    );
+
+    // And the legacy trap graph is unreachable through the recovered session.
+    server.send(&search_frame(5, &project, LEGACY_TRAP_SYMBOL));
+    let trap = tool_text(&server.await_response(5), "request 4");
+    assert!(
+        trap.contains("No results found"),
+        "the legacy trap symbol must never be reachable: {trap}"
+    );
+
+    server.shutdown();
+}
+
+/// The in-process half of the same seam: `CodeGraphEngine::open` is the exact
+/// call `execute_owned` makes per request, so a failed open must leave NOTHING
+/// behind in THIS process either — no memoized error, no lease, no handle — and a
+/// later open in the same process must observe the repaired graph.
+#[test]
+fn in_process_engine_open_failure_leaves_no_cached_state_and_reopens_repaired() {
+    let home = TestDir::new("inproc");
+    let project = home.path().join("project");
+    let staging = TestDir::new("inproc-staging");
+    let paths = stage_missing_state_with_database(&project, &staging, "inproc");
+    let repaired_db =
+        build_graph_database(&staging, "inproc-repaired", REPAIRED_FILE, REPAIRED_SYMBOL);
+
+    // `CodeGraphEngine` is deliberately not `Debug` (it owns a SQLite handle), so
+    // the failure is taken by matching instead of `expect_err`.
+    let first = match codegraph_mcp::CodeGraphEngine::open(&project) {
+        Ok(_) => panic!("the staged namespace must fail the engine open"),
+        Err(error) => error.to_string(),
+    };
+    assert!(
+        first.contains(MISSING_WITH_DB),
+        "the in-process failure must be the staged state/artifact refusal: {first}"
+    );
+
+    // Same fail-closed release proof, then the same legitimate repair.
+    repair_without_restart(&paths, &repaired_db);
+
+    let engine = codegraph_mcp::CodeGraphEngine::open(&project)
+        .expect("the SAME process must reopen the repaired namespace");
+    let result = engine.execute("codegraph_search", &json!({ "query": REPAIRED_SYMBOL }));
+    assert_ne!(
+        result.is_error,
+        Some(true),
+        "the reopened engine must serve the repaired graph"
+    );
+    let text = result
+        .content
+        .iter()
+        .map(|c| c.text.as_str())
+        .collect::<Vec<_>>()
+        .join("\n");
+    assert!(
+        text.contains(REPAIRED_FILE),
+        "the reopened engine must observe the repaired file: {text}"
+    );
+    assert!(
+        !text.contains(ORIGINAL_FILE) && !text.contains(LEGACY_TRAP_FILE),
+        "the reopened engine must not surface the pre-repair or legacy graph: {text}"
+    );
+}
+
+/// The startup catch-up sync cannot be the thing that repairs the staged
+/// namespace, and this is a GATE rather than a race: the same
+/// `sync_project_once` entry point the catch-up thread calls refuses the staged
+/// `Missing`-with-database namespace with the same diagnostic and leaves the
+/// database bytes and the (absent) state slots exactly as they were.
+#[test]
+fn catch_up_sync_refuses_missing_state_with_database_without_mutating_bytes() {
+    let home = TestDir::new("catchup");
+    let project = home.path().join("project");
+    let staging = TestDir::new("catchup-staging");
+    let paths = stage_missing_state_with_database(&project, &staging, "catchup");
+
+    let before = fs::read(paths.current_db()).expect("read the staged database bytes");
+
+    let error = codegraph_watch::sync_project_once(&project)
+        .expect_err("a catch-up sync must refuse the staged Missing-with-database namespace")
+        .to_string();
+    assert!(
+        error.contains(MISSING_WITH_DB),
+        "the catch-up refusal must be the staged state/artifact gate: {error}"
+    );
+
+    let after = fs::read(paths.current_db()).expect("re-read the staged database bytes");
+    assert_eq!(
+        before, after,
+        "the refused catch-up must leave the database bytes byte-identical"
+    );
+    for slot in paths.state_slots() {
+        assert!(
+            !slot.exists(),
+            "the refused catch-up must not publish a state slot at {}",
+            slot.display()
+        );
+    }
+    assert!(
+        !paths.tombstone().exists(),
+        "the refused catch-up must not create a tombstone"
+    );
+    assert!(
+        paths.permanent_lock().is_file(),
+        "the refused catch-up must preserve the permanent lock"
+    );
+}
+
+/// The recovery flow must be independent of the compatibility close seam, so no
+/// CODE in this file may name it — not as a call, an import, an alias, or a
+/// wrapper. Checked structurally against this file's own bytes: comment lines
+/// (which document the seam by name) are excluded, and the needle itself is
+/// assembled from two halves so neither this oracle nor its failure message is a
+/// match for what it forbids.
+#[test]
+fn recovery_flow_never_calls_the_close_helper() {
+    let offenders = code_lines_naming(include_str!("batch_m_failed_open_recovery.rs"), CLOSE_SEAM);
+    assert!(
+        offenders.is_empty(),
+        "the M17 recovery flow must not depend on the {CLOSE_SEAM} compatibility seam, but these \
+         code lines name it: {offenders:?}"
+    );
+}
+
+/// Non-comment lines of `source` that contain `needle`, as `"<line>: <text>"`.
+/// A line whose first non-whitespace characters are `//` is documentation (this
+/// file's own module docs and comments discuss the seam by name), so only real
+/// code is inspected.
+fn code_lines_naming(source: &str, needle: &str) -> Vec<String> {
+    source
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| !line.trim_start().starts_with("//"))
+        .filter(|(_, line)| line.contains(needle))
+        .map(|(index, line)| format!("{}: {}", index + 1, line.trim()))
+        .collect()
+}
+
+#[cfg(test)]
+mod oracle_tests {
+    use super::code_lines_naming;
+
+    /// The forbidden-name oracle must SEE a real invocation and IGNORE a comment
+    /// that merely mentions the name, so it can neither pass vacuously nor fail
+    /// on this file's own documentation.
+    #[test]
+    fn code_lines_naming_sees_code_and_ignores_comments() {
+        let needle = concat!("forbidden", "_seam");
+        let source = concat!(
+            "//! docs mention forbidden_seam by name\n",
+            "    // so does an indented comment: forbidden_seam\n",
+            "let clean = other_call();\n",
+            "    store.forbidden_seam();\n"
+        );
+        let found = code_lines_naming(source, needle);
+        assert_eq!(
+            found,
+            vec!["4: store.forbidden_seam();".to_string()],
+            "only the real invocation line is an offender"
+        );
+    }
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 4bd5725..a6d3ccf 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2700,3 +2700,136 @@ at SHA-256 `5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450` an
 evidence bytes are written BEFORE repository formatting and the one authoritative
 `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run
 over these exact final bytes; no final Green is claimed until that gate passes.
+
+## Batch M item 17 acceptance closure — a failed engine open is not cached and the next request recovers (2026-07-26)
+
+Frozen plan item 17 asks for
+`failed_engine_open_is_not_cached_and_next_request_recovers`: one long-lived
+shipped MCP process must take a request whose engine/`Store` open FAILS for a real
+v2 state/artifact reason, survive it, retain nothing from it, and — after the
+namespace is repaired WITHOUT a restart — serve only the repaired graph on the
+next request in that same process.
+
+The acceptance lands as one new query-side test target,
+`crates/codegraph-cli/tests/batch_m_failed_open_recovery.rs`, over the SHIPPED
+binary (`CARGO_BIN_EXE_codegraph`). No production byte changed: M15 already made
+every MCP engine request-scoped and M16 proved the per-request handle release, so
+item 17 is the behavioral proof that the FAILURE path shares that ownership rather
+than a new mechanism.
+
+The staged failure is a genuine v2 inconsistency, never a stub. The served project
+is really indexed by the shipped `codegraph init`; then BOTH fixed state slots are
+removed and nothing else, so the namespace classifies `Missing` while its main
+database and its permanent lock are still present. `Store::open_for_read` refuses
+exactly that through `reject_missing_database_artifacts` with
+`state is missing but a database artifact already exists at <db>`, which the test
+asserts directly against the staged fixture BEFORE any server is involved. No gate
+is weakened, relaxed, or repaired to manufacture the failure.
+
+The failure is deliberately POST-RESOLUTION. Because the current-namespace DB file
+still exists, `roots::probe_root` classifies the project `Indexed` and
+`resolve_project_arg` resolves it, so request 1 fails inside the engine open. The
+test pins that distinction: the request-1 tool error must contain
+`Failed to open project at …` AND the missing-state-with-database diagnostic, and
+must NOT contain `No indexed project`. A resolution miss therefore cannot be
+mistaken for the engine-open failure this item is about. The failure also arrives
+as an `isError` tool result rather than a JSON-RPC transport error, which is the
+evidence the live session survived it.
+
+Determinism comes from protocol frames and fail-closed gates. READY is the arrival
+of request 1's complete JSON-RPC response frame — rmcp writes it only after the
+owned result materialized. The parent then acquires the namespace's EXCLUSIVE
+lease: a shared reader lease retained by the FAILED open makes that acquisition
+fail, so it is the fail-closed proof that the failed open released everything.
+Still under that lease the parent `fs::rename`s the separately built repaired
+database over the live main database file — on native Windows that fails with a
+sharing violation while any process holds an open handle on the destination, which
+is the Windows handle proof for the failure path. Repair is then COMPLETED by the
+protocol-aware `Missing -> Building -> Current` fixture finalizer
+(`codegraph_store::test_support::finalize_current_test_fixture`), and completion is
+observed from published state and artifact shape — status `Current`, a published
+state slot, the preserved permanent lock, a sidecar-free database — never from
+elapsed time. CONTINUE is request 2's frame, written only after all of that. The
+60s deadlines are deadlock guards only; no assertion is satisfied by waiting, by
+mtime, or by process exit, and the server is never restarted.
+
+Startup catch-up is excluded as an explanation for BOTH halves, with runtime
+evidence rather than a caveat. It cannot repair the staged namespace: a dedicated
+test, `catch_up_sync_refuses_missing_state_with_database_without_mutating_bytes`,
+drives the SAME `codegraph_watch::sync_project_once` entry point the catch-up
+thread calls against an identically staged namespace and proves it fails with the
+same state/artifact diagnostic while leaving the database bytes byte-identical, the
+state slots absent, no tombstone created, and the permanent lock intact — a gate,
+not a race. It also cannot invent the repaired rows: following M16's pattern the
+distinguishing sources live under a root-`.gitignore` directory and the exclusion
+is PROVEN in-test with the shipped `codegraph_extract::engine::scan_project`; all
+three supplied files stay present on disk so the cold removal pass cannot delete
+their rows either, and the single scannable neutral file is byte-identical in every
+graph so a catch-up is a proven no-op.
+
+Recovery is additionally proven not to be a silent legacy fallback: the project
+carries a legacy `.codegraph/codegraph.db` holding a TRAP symbol present in no
+other graph, and request 2 must neither surface the trap file nor resolve the trap
+symbol (`No results found`). Request 2 must also render real search results
+(`## Search Results (`) containing the repaired file, and the pre-repair symbol
+must resolve to nothing in the same session — absence observed through a lookup
+that finds nothing, not through a response that merely omits it.
+
+A second test, `in_process_engine_open_failure_leaves_no_cached_state_and_reopens_repaired`,
+pins the same seam in-process: `CodeGraphEngine::open` is the exact call
+`execute_owned` makes per request, so a failed open followed by the same legitimate
+repair must let a LATER open in the SAME process serve the repaired graph with no
+memoized error, lease, or handle in the way. The forbidden-seam oracle from M16 is
+carried over unchanged in spirit (structural, code-lines-only, two-half needle,
+with its own unit test), so the recovery flow provably never depends on
+`close_cached_handles`.
+
+Four negative-control runs establish the assertions are load-bearing (each
+reverted immediately, the file restored to SHA-256
+`263c6a76a3b2412c4434c5e4be9ce08772986d94ad8ead6b0d9d790ec181b756`). Memoizing the
+first failed open per project in `execute_owned` makes request 2 return the cached
+`Failed to open project at … state is missing but a database artifact already
+exists` error and the acceptance fails — this is the exact production regression the
+item forbids, and the test detects it. Holding an extra SHARED lease across the
+repair makes the exclusive acquisition time out with
+`TimedOut { path: …/index.lock }`, so the no-retained-lease proof is real rather
+than incidental. Skipping the protocol-aware republication leaves the namespace
+`Missing` and fails the repair-completion assertion, so recovery genuinely requires
+a legitimate `Current` publication. Leaving the state slots in place fails the
+staging assertion `removing both fixed state slots must classify the namespace
+Missing`, so the fixture cannot silently degrade into a happy-path test.
+
+Local Green on the integrated bytes, with
+`bash scripts/check-workspace-versions.sh` run before every Cargo batch and
+`--locked` on every Cargo command:
+`cargo test --locked -p codegraph-rs --test batch_m_failed_open_recovery` **5/5**,
+`cargo test --locked -p codegraph-rs --test lease_lifetime` **5/5**,
+`cargo test --locked -p codegraph-rs --test batch_m_long_lived_mcp` **3/3**, and
+`cargo test --locked -p codegraph-mcp --test reopen` **3/3**. Workspace all-target
+check and Clippy with `-D warnings` pass. Changed-file LSP diagnostics were
+attempted for the new target and the tool again rejected this required external
+worktree with `LSP file path must be inside request cwd`; locked Cargo diagnostics
+are the honest fallback and this ledger claims no LSP-clean result.
+
+Native Windows/MSVC runtime was NOT executed here and is not claimed — this Linux
+host cannot provide it. M16's explicit `windows-latest` selection and every other
+CI byte are preserved unchanged; item 17 adds no CI wiring, so its Windows
+`MoveFileEx` behavior is documented as unexecuted rather than asserted.
+
+This slice adds no dependency and changes no schema, node-ID formula, extraction or
+golden byte, `UPSTREAM.md`, or `KNOWN_DIFFS.md`; the frozen plan is untouched at
+SHA-256 `5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450` and
+`Cargo.lock` remains required at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. These evidence
+bytes are written BEFORE repository formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run
+over these exact final bytes; no final Green is claimed until that gate passes.
+
+Addendum for exactness: the negative-control restore hash
+`263c6a76a3b2412c4434c5e4be9ce08772986d94ad8ead6b0d9d790ec181b756` is the
+pre-`make fmt` byte state of `batch_m_failed_open_recovery.rs`, which is what each
+control was reverted to. Repository formatting afterwards rewrapped exactly one
+function signature (`build_graph_database`) and nothing else, so the committed
+target hashes
+`7d5ac54647c6bb5a66235a5ca1d8f0a3988d4630078d0db4b891a52e695b2f1f`; the assertions
+the controls exercised are byte-unchanged.

From b71988c001d992b804d3fc5a2e51792967ea77d1 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 22:24:50 +0800
Subject: [PATCH 35/91] feat(config): scope configuration to the addressed
 project

---
 crates/codegraph-cli/src/main.rs              |  99 ++-
 .../global_http_project_scoped_config.rs      | 607 ++++++++++++++++++
 .../codegraph-cli/tests/godot_idfields_cwd.rs |  73 ++-
 .../tests/godot_idfields_determinism.rs       |  51 +-
 crates/codegraph-core/src/config.rs           | 194 +++---
 crates/codegraph-daemon/src/lib.rs            |  26 +-
 crates/codegraph-daemon/tests/async_model.rs  |   3 +-
 .../codegraph-daemon/tests/rmcp_tools_call.rs |   6 +-
 crates/codegraph-extract/src/engine.rs        | 114 +++-
 crates/codegraph-extract/src/ext_config.rs    | 270 ++++----
 crates/codegraph-extract/src/lib.rs           |   5 +-
 .../tests/coverage_ext_config.rs              |  92 ++-
 crates/codegraph-extract/tests/custom_ext.rs  | 119 +++-
 crates/codegraph-mcp/src/engine.rs            |  55 +-
 crates/codegraph-resolve/src/framework.rs     |  73 ++-
 .../codegraph-resolve/src/frameworks/godot.rs |   9 +-
 .../src/frameworks/godot_dsl_config.rs        | 385 +++++------
 .../src/frameworks/godot_resource.rs          |  52 +-
 .../codegraph-resolve/src/frameworks/mod.rs   |   2 +-
 .../src/frameworks/nestjs.rs                  |  43 +-
 .../codegraph-resolve/src/frameworks/react.rs |  37 +-
 .../codegraph-resolve/src/frameworks/vue.rs   |  31 +-
 crates/codegraph-resolve/src/resolver.rs      |  24 +-
 crates/codegraph-resolve/tests/frameworks.rs  |  17 +-
 crates/codegraph-resolve/tests/godot_dsl.rs   |  72 ++-
 .../codegraph-resolve/tests/godot_project.rs  |  19 +-
 .../codegraph-resolve/tests/godot_resource.rs |  33 +-
 crates/codegraph-resolve/tests/godot_scene.rs |  33 +-
 .../codegraph-resolve/tests/godot_script.rs   |  35 +-
 crates/codegraph-watch/src/lib.rs             |   4 +-
 crates/codegraph-watch/src/migrate.rs         |  20 +-
 crates/codegraph-watch/src/policy.rs          |  21 +-
 crates/codegraph-watch/src/sync.rs            | 303 ++++++---
 crates/codegraph-watch/src/watcher.rs         |  67 +-
 34 files changed, 2123 insertions(+), 871 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/global_http_project_scoped_config.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index f7e980e..629d2ad 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -16,11 +16,11 @@ use std::time::{SystemTime, UNIX_EPOCH};
 use anyhow::{Context, Result, anyhow, bail};
 use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
 use clap_complete::{Shell, generate};
-use codegraph_core::config::init_config;
+use codegraph_core::config::Config;
 use codegraph_core::logger::{LoggerConfig, init_logger};
 use codegraph_core::node_id::hash_content;
 use codegraph_core::types::{ExtractionResult, FileRecord, Language, Node, NodeKind};
-use codegraph_extract::{ExtractOptions, detect_language, extract_source};
+use codegraph_extract::{ExtractOptions, detect_language_with, extract_source_with};
 use codegraph_graph::graph::{GodotReach, GraphTraverser};
 use codegraph_graph::query::{SearchOptions, search_nodes};
 use codegraph_mcp::{McpServer, RunUntilAdoption};
@@ -43,8 +43,11 @@ const VERSION: &str = env!("CARGO_PKG_VERSION");
 
 fn main() {
     let cli = Cli::parse();
-    let bootstrap_root = cli.bootstrap_project_root();
-    let config = match init_config(None, &bootstrap_root) {
+    // Process bootstrap has no addressed project yet, so this config is
+    // `APP_CONFIG`-or-defaults ONLY and may configure NOTHING but the logger
+    // below. Every project operation (index, sync, watch, an MCP request) loads
+    // the addressed project's own immutable config from its resolved index root.
+    let config = match Config::load_env_or_default(None) {
         Ok(config) => config,
         Err(err) => {
             eprintln!("CodeGraph config error: {err:#}");
@@ -88,42 +91,6 @@ struct Cli {
     command: Command,
 }
 
-impl Cli {
-    fn bootstrap_project_root(&self) -> PathBuf {
-        let raw = match &self.command {
-            Command::Init { path, .. }
-            | Command::Uninit { path, .. }
-            | Command::Index { path, .. }
-            | Command::Sync { path, .. }
-            | Command::Status { path, .. }
-            | Command::Unlock { path } => path.clone(),
-            Command::Query { path, .. }
-            | Command::Files { path, .. }
-            | Command::Serve { path, .. }
-            | Command::Callers { path, .. }
-            | Command::Callees { path, .. }
-            | Command::Impact { path, .. }
-            | Command::Affected { path, .. }
-            | Command::Check { path, .. }
-            | Command::Audit { path, .. }
-            | Command::Explore { path, .. }
-            | Command::Node { path, .. } => path.clone(),
-            Command::Export { path, .. } => path.clone(),
-            Command::PromptHook { path, .. } => path.clone(),
-            // install/uninstall/skill are not project-scoped — bootstrap from cwd.
-            Command::Install { .. }
-            | Command::Uninstall { .. }
-            | Command::Skill { .. }
-            | Command::Http { .. }
-            | Command::Version
-            | Command::Completions { .. }
-            | Command::SelfUpdate { .. } => None,
-        };
-        let start = absolute_path(raw.unwrap_or_else(|| PathBuf::from(".")));
-        resolve_project_path_optional(&start)
-    }
-}
-
 #[derive(Debug, Subcommand)]
 enum Command {
     // Upstream flags/output: upstream bin/codegraph.ts:420-424, 431-470.
@@ -1685,14 +1652,13 @@ fn cmd_serve(
                 return serve_direct(project, &project_root, no_watch, explicit_path);
             }
             ServeMode::BeDaemon => {
-                let cfg = codegraph_core::config::get_config();
+                // The daemon loads THIS project's own watch config itself, from
+                // the resolved index root, so nothing is passed down here.
                 return codegraph_daemon::run_foreground(
                     &project_root,
                     codegraph_daemon::DaemonOptions {
                         run_mcp: true,
                         host_pid: codegraph_daemon::host_pid_from_env(),
-                        include: cfg.indexing.include.clone(),
-                        exclude: cfg.indexing.exclude.clone(),
                         ..Default::default()
                     },
                 )
@@ -2364,11 +2330,18 @@ fn start_direct_watcher(
     project_root: &Path,
     no_watch: bool,
 ) -> Option<codegraph_watch::ProjectWatcher> {
-    let mut opts = codegraph_watch::WatchOptions::default();
-    opts.no_watch = no_watch;
-    let cfg = codegraph_core::config::get_config();
-    opts.include = cfg.indexing.include.clone();
-    opts.exclude = cfg.indexing.exclude.clone();
+    // Include/exclude, debounce, the enable flag, and extension overrides all come
+    // from THIS project's own config (its resolved index root), so a direct serve
+    // watches exactly the scope its own `index`/`sync` would.
+    let mut opts = match codegraph_watch::watch_options_for_project(project_root) {
+        Ok(opts) => opts,
+        Err(err) => {
+            tracing::warn!(error = %err, "could not load project watch config; watcher disabled");
+            return None;
+        }
+    };
+    // An explicit `--no-watch` still wins over the project's `watch.enabled`.
+    opts.no_watch = opts.no_watch || no_watch;
     opts.on_sync_complete = Some(std::sync::Arc::new(
         |outcome: codegraph_watch::SyncOutcome| {
             tracing::info!(
@@ -3613,15 +3586,16 @@ fn index_project_inner(
     let started = std::time::Instant::now();
     let paths = index_paths(project)?;
     let index_root = paths.current_root().to_path_buf();
-    let config = codegraph_core::config::get_config();
-    let options = ExtractOptions {
-        max_file_size: config.indexing.max_file_size,
-        ignore_dirs: config.indexing.ignore_dirs.clone(),
-        ignore_paths: config.indexing.ignore_paths.clone(),
-        exclude: config.indexing.exclude.clone(),
-        include: config.indexing.include.clone(),
-        parallel: true,
-    };
+    // THIS project's own immutable config + extension overrides, read from its
+    // resolved current index root. Nothing consults a process-global value, a
+    // legacy `.codegraph` root, or the process working directory.
+    let config = Config::load_for_paths(None, &paths)?;
+    let extensions = codegraph_extract::ExtensionOverrides::load_for_paths(&paths);
+    let options = ExtractOptions::for_project(&config, extensions);
+    let framework_context = codegraph_resolve::framework::FrameworkExtractionContext::new(
+        project.to_string_lossy().into_owned(),
+        codegraph_resolve::frameworks::godot_dsl_config::GodotDslConfig::load_for_paths(&paths),
+    );
     if !quiet {
         eprintln!("Scanning files…");
     }
@@ -3774,12 +3748,12 @@ fn index_project_inner(
                                 duration_ms: 0,
                             }
                         } else {
-                            extract_source(relative, &source, None)
+                            extract_source_with(relative, &source, None, &options_ref.extensions)
                         };
                         let file = FileRecord {
                             path: relative.clone(),
                             content_hash: hash_content(&source),
-                            language: detect_language(relative),
+                            language: detect_language_with(relative, &options_ref.extensions),
                             size: metadata.len() as i64,
                             modified_at: modified_millis(&metadata),
                             indexed_at: now_millis(),
@@ -3927,7 +3901,12 @@ fn index_project_inner(
             .into_iter()
             .map(|f| f.path)
             .collect::<Vec<_>>();
-        resolver.extract_and_persist_frameworks(&mut store, &relative_files)?;
+        resolver.extract_and_persist_frameworks_with(
+            &mut store,
+            &relative_files,
+            &framework_context,
+            &options.extensions,
+        )?;
     }
     finish_phase(&pb, "Detected frameworks");
     // Finished from INSIDE the callback on the final chunk so the retained line
diff --git a/crates/codegraph-cli/tests/global_http_project_scoped_config.rs b/crates/codegraph-cli/tests/global_http_project_scoped_config.rs
new file mode 100644
index 0000000..f35c481
--- /dev/null
+++ b/crates/codegraph-cli/tests/global_http_project_scoped_config.rs
@@ -0,0 +1,607 @@
+//! Batch M item 19 — PROJECT-SCOPED v2 configuration, end to end.
+//!
+//! One process must never let one project's configuration reach another, and must
+//! never adopt a legacy `.codegraph/config.toml` / `.codegraph/codegraph.json`.
+//! These targets drive the REAL `codegraph` binary:
+//!
+//! 1. [`global_http_uses_project_scoped_v2_configs`] — the named acceptance
+//!    target. ONE global `serve --http` process (no `--path`, `APP_CONFIG`
+//!    unset) answers requests for two projects whose current-root `config.toml`
+//!    files carry OPPOSING `include`/`exclude`/`max_file_size` settings, plus
+//!    hostile LEGACY configs that must be ignored. It proves per-request scoping
+//!    in both orders, then proves the same for `sync` and for the live watcher.
+//! 2. [`app_config_overrides_both_projects_including_codegraph_dir_collision`] —
+//!    the control: `APP_CONFIG` is INTENTIONALLY process-wide, so it supersedes
+//!    both projects' own configs; and with both projects pointed at the SAME
+//!    absolute `CODEGRAPH_DIR`, their identity-suffixed current roots stay
+//!    distinct, so neither project's index or config collides with the other's.
+#![cfg(unix)]
+
+use std::fs;
+use std::io::{BufRead, BufReader, Read, Write};
+use std::net::{TcpStream, ToSocketAddrs};
+use std::path::{Path, PathBuf};
+use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_store::Store;
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn mini_fixture() -> PathBuf {
+    workspace_root().join("crates/codegraph-bench/fixtures/mini")
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-m19-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    fs::create_dir_all(dst).unwrap();
+    for entry in fs::read_dir(src).unwrap() {
+        let entry = entry.unwrap();
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            fs::copy(&from, &to).unwrap();
+        }
+    }
+}
+
+/// A `mini`-fixture project plus a `.gitignore`d `Tools/` dir, and HOSTILE legacy
+/// configs (`.codegraph/config.toml` + `.codegraph/codegraph.json`) that no
+/// production path may read. The legacy TOML asks for the OPPOSITE of every
+/// project-scoped expectation, so adopting it fails the assertions below.
+fn project_with_hostile_legacy_config(root: &Path, legacy_include: &str) -> PathBuf {
+    copy_tree(&mini_fixture(), root);
+    fs::write(root.join(".gitignore"), "Tools/\n").unwrap();
+    fs::create_dir_all(root.join("Tools")).unwrap();
+    fs::write(
+        root.join("Tools/helper.ts"),
+        "export function toolsHelper() { return 1; }\n",
+    )
+    .unwrap();
+    fs::create_dir_all(root.join(".codegraph")).unwrap();
+    fs::write(
+        root.join(".codegraph/config.toml"),
+        format!(
+            "[app]\nname = \"legacy\"\n\n[indexing]\nmax_file_size = 7\ninclude = [{legacy_include}]\n"
+        ),
+    )
+    .unwrap();
+    fs::write(
+        root.join(".codegraph/codegraph.json"),
+        "{\"extensions\":{\".zz\":\"lua\"}}\n",
+    )
+    .unwrap();
+    root.to_path_buf()
+}
+
+/// Write `contents` to the project's CURRENT-ROOT `config.toml` — the only
+/// project config production reads. Call AFTER `init`, so the current root is the
+/// initialized namespace rather than a hand-made directory.
+fn write_current_config(project: &Path, contents: &str, codegraph_dir: Option<&str>) {
+    let paths = IndexPaths::resolve(project, codegraph_dir).expect("resolve index paths");
+    assert!(
+        paths.current_root().is_dir(),
+        "write the project config after `init` created {}",
+        paths.current_root().display()
+    );
+    fs::write(paths.config_toml(), contents).unwrap();
+}
+
+/// Run the binary with foreground-only env, returning (stdout, stderr, ok).
+fn cli(args: &[&str], envs: &[(&str, &str)]) -> (String, String, bool) {
+    let mut cmd = Command::new(bin());
+    cmd.args(args);
+    cmd.env("CODEGRAPH_NO_DAEMON", "1");
+    cmd.env("CODEGRAPH_NO_WATCH", "1");
+    cmd.env_remove("APP_CONFIG");
+    for (key, value) in envs {
+        cmd.env(key, value);
+    }
+    let output = cmd.output().expect("run codegraph binary");
+    (
+        String::from_utf8_lossy(&output.stdout).into_owned(),
+        String::from_utf8_lossy(&output.stderr).into_owned(),
+        output.status.success(),
+    )
+}
+
+/// The indexed root-relative file paths recorded in the project's v2 database.
+fn indexed_files(project: &Path, codegraph_dir: Option<&str>) -> Vec<String> {
+    let paths = IndexPaths::resolve(project, codegraph_dir).expect("resolve index paths");
+    let store = Store::open(&paths.current_db()).expect("open v2 store");
+    let mut files = store
+        .all_files()
+        .expect("read files")
+        .into_iter()
+        .map(|file| file.path)
+        .collect::<Vec<_>>();
+    files.sort();
+    files
+}
+
+fn free_port() -> u16 {
+    let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+    listener.local_addr().unwrap().port()
+}
+
+fn http_post_mcp(addr: &str, body: &str) -> std::io::Result<String> {
+    let sockaddr = addr.to_socket_addrs()?.next().expect("resolve addr");
+    let mut stream = TcpStream::connect_timeout(&sockaddr, Duration::from_secs(5))?;
+    stream.set_read_timeout(Some(Duration::from_secs(10)))?;
+    let req = format!(
+        "POST /mcp HTTP/1.1\r\nHost: {addr}\r\nContent-Type: application/json\r\nAccept: application/json, text/event-stream\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+        body.len()
+    );
+    stream.write_all(req.as_bytes())?;
+    stream.flush()?;
+    let mut buf = String::new();
+    let _ = stream.read_to_string(&mut buf);
+    Ok(buf)
+}
+
+fn wait_reachable(addr: &str) -> bool {
+    let deadline = Instant::now() + Duration::from_secs(30);
+    let init = r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"m19","version":"0"}}}"#;
+    while Instant::now() < deadline {
+        if let Ok(resp) = http_post_mcp(addr, init)
+            && resp.contains("\"result\"")
+        {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(200));
+    }
+    false
+}
+
+/// One `tools/call` against the GLOBAL HTTP server, addressed by `projectPath`.
+fn http_tool_call(addr: &str, id: u64, tool: &str, arguments: &str) -> String {
+    let body = format!(
+        r#"{{"jsonrpc":"2.0","id":{id},"method":"tools/call","params":{{"name":"{tool}","arguments":{arguments}}}}}"#
+    );
+    http_post_mcp(addr, &body).expect("HTTP tool call")
+}
+
+/// A child process killed + reaped on drop, so no server leaks out of a test.
+struct ChildGuard(Child);
+
+impl Drop for ChildGuard {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+        let _ = self.0.wait();
+    }
+}
+
+/// A live `serve --mcp` child driven over line-delimited JSON-RPC.
+struct ServeProcess {
+    child: Child,
+    stdin: ChildStdin,
+    reader: BufReader<ChildStdout>,
+}
+
+impl ServeProcess {
+    fn spawn(project: &Path) -> Self {
+        let mut child = Command::new(bin())
+            .arg("serve")
+            .arg("--mcp")
+            .arg("--path")
+            .arg(project)
+            .env("CODEGRAPH_NO_DAEMON", "1")
+            // The documented env escape hatch still wins over config, keeping the
+            // watcher reaction fast and deterministic.
+            .env("CODEGRAPH_WATCH_DEBOUNCE_MS", "100")
+            .env_remove("CODEGRAPH_NO_WATCH")
+            .env_remove("APP_CONFIG")
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn serve --mcp");
+        let stdin = child.stdin.take().expect("serve stdin");
+        let stdout = child.stdout.take().expect("serve stdout");
+        Self {
+            child,
+            stdin,
+            reader: BufReader::new(stdout),
+        }
+    }
+
+    fn send(&mut self, line: &str) {
+        self.stdin
+            .write_all(line.as_bytes())
+            .expect("write request");
+        self.stdin.write_all(b"\n").expect("write newline");
+        self.stdin.flush().expect("flush request");
+    }
+
+    fn read_line(&mut self) -> Option<String> {
+        let mut buf = String::new();
+        match self.reader.read_line(&mut buf) {
+            Ok(0) => None,
+            Ok(_) => Some(buf),
+            Err(_) => None,
+        }
+    }
+
+    fn handshake(&mut self) {
+        self.send(
+            r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"m19","version":"0"}}}"#,
+        );
+        self.read_line().expect("initialize response");
+    }
+
+    /// Poll `codegraph_search` for `symbol`, returning whether it was FOUND
+    /// within the budget. The not-found response echoes the query, so the
+    /// explicit sentinel decides presence.
+    fn search_finds_within(&mut self, symbol: &str, budget: Duration) -> bool {
+        let deadline = Instant::now() + budget;
+        let mut id = 100;
+        loop {
+            id += 1;
+            self.send(&format!(
+                r#"{{"jsonrpc":"2.0","id":{id},"method":"tools/call","params":{{"name":"codegraph_search","arguments":{{"query":"{symbol}"}}}}}}"#
+            ));
+            let found = match self.read_line() {
+                Some(line) => line.contains(symbol) && !line.contains("No results found"),
+                None => false,
+            };
+            if found {
+                return true;
+            }
+            if Instant::now() >= deadline {
+                return false;
+            }
+            std::thread::sleep(Duration::from_millis(200));
+        }
+    }
+}
+
+impl Drop for ServeProcess {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+/// ALPHA force-indexes its gitignored `Tools/`, drops the `tools/` python dir,
+/// and caps `max_file_size` far below the fixture's TypeScript sources.
+const ALPHA_CONFIG: &str = "[app]\nname = \"alpha\"\n\n[indexing]\nmax_file_size = 120\ninclude = [\"Tools/\"]\nexclude = [\"tools/\"]\n";
+/// BETA is the mirror image: no `include` (so `Tools/` stays gitignored), keeps
+/// `tools/`, drops `src/math.ts`, and leaves `max_file_size` at the default.
+const BETA_CONFIG: &str = "[app]\nname = \"beta\"\n\n[indexing]\nexclude = [\"src/math.ts\"]\n";
+
+/// Item 19. ONE global HTTP process, `APP_CONFIG` unset, two projects with
+/// opposing current-root configs — plus `sync` and the live watcher.
+#[test]
+fn global_http_uses_project_scoped_v2_configs() {
+    let home = TestDir::new("global-http");
+    let alpha = project_with_hostile_legacy_config(&home.path().join("alpha"), "\"tools/\"");
+    let beta = project_with_hostile_legacy_config(&home.path().join("beta"), "\"Tools/\"");
+
+    // -------------------------------------------------- index and sync ---
+    // `init` publishes each project's v2 namespace; the per-project config then
+    // lands in that namespace. `index --force` must scope each project's SCAN by
+    // its own config, and a subsequent `sync` must scope the same way. The hostile
+    // legacy `.codegraph/config.toml` in each project asks for the other's
+    // `include` and a 7-byte size cap, so adopting it would flip the assertions.
+    let (out, err, ok) = cli(&["init", alpha.to_str().unwrap()], &[]);
+    assert!(ok, "alpha init failed: stdout={out} stderr={err}");
+    let (out, err, ok) = cli(&["init", beta.to_str().unwrap()], &[]);
+    assert!(ok, "beta init failed: stdout={out} stderr={err}");
+    write_current_config(&alpha, ALPHA_CONFIG, None);
+    write_current_config(&beta, BETA_CONFIG, None);
+    let (out, err, ok) = cli(&["index", "--force", alpha.to_str().unwrap()], &[]);
+    assert!(ok, "alpha index failed: stdout={out} stderr={err}");
+    let (out, err, ok) = cli(&["index", "--force", beta.to_str().unwrap()], &[]);
+    assert!(ok, "beta index failed: stdout={out} stderr={err}");
+
+    let alpha_files = indexed_files(&alpha, None);
+    let beta_files = indexed_files(&beta, None);
+    assert!(
+        alpha_files.contains(&"Tools/helper.ts".to_string()),
+        "alpha's own include must force its gitignored Tools/ in: {alpha_files:?}"
+    );
+    assert!(
+        !alpha_files.iter().any(|path| path.starts_with("tools/")),
+        "alpha's own exclude must drop tools/: {alpha_files:?}"
+    );
+    assert!(
+        !beta_files.contains(&"Tools/helper.ts".to_string()),
+        "beta must not inherit alpha's include: {beta_files:?}"
+    );
+    assert!(
+        beta_files.contains(&"tools/greeter.py".to_string()),
+        "beta must not inherit alpha's exclude: {beta_files:?}"
+    );
+    assert!(
+        !beta_files.contains(&"src/math.ts".to_string()),
+        "beta's own exclude must drop src/math.ts: {beta_files:?}"
+    );
+    assert!(
+        alpha_files.contains(&"src/math.ts".to_string()),
+        "alpha must not inherit beta's exclude: {alpha_files:?}"
+    );
+
+    // The SYNC path is scoped the same way: an identical new file under the
+    // gitignored `Tools/` is picked up by alpha (whose config includes it) and
+    // ignored by beta (whose config does not, its legacy config notwithstanding).
+    for project in [&alpha, &beta] {
+        fs::write(
+            project.join("Tools/synced.ts"),
+            "export function syncedMarker() { return 1; }\n",
+        )
+        .unwrap();
+    }
+    let (out, err, ok) = cli(&["sync", alpha.to_str().unwrap()], &[]);
+    assert!(ok, "alpha sync failed: stdout={out} stderr={err}");
+    let (out, err, ok) = cli(&["sync", beta.to_str().unwrap()], &[]);
+    assert!(ok, "beta sync failed: stdout={out} stderr={err}");
+    assert!(
+        indexed_files(&alpha, None).contains(&"Tools/synced.ts".to_string()),
+        "alpha's sync must honor alpha's include"
+    );
+    assert!(
+        !indexed_files(&beta, None).contains(&"Tools/synced.ts".to_string()),
+        "beta's sync must not adopt alpha's (or its legacy config's) include"
+    );
+
+    // --------------------------------------------------- one HTTP process ---
+    // GLOBAL mode: no `--path`, so each tool call carries its own projectPath and
+    // ONE process answers for both projects.
+    let port = free_port();
+    let addr = format!("127.0.0.1:{port}");
+    let registry = home.path().join("http-registry");
+    let child = Command::new(bin())
+        .args(["serve", "--http", "--http-addr", &addr])
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1")
+        .env("CODEGRAPH_HTTP_REGISTRY_DIR", &registry)
+        .env_remove("APP_CONFIG")
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn global serve --http");
+    let _guard = ChildGuard(child);
+    assert!(
+        wait_reachable(&addr),
+        "the global HTTP MCP server never became reachable on {addr}"
+    );
+
+    // Per-project `max_file_size`: alpha's 120-byte cap refuses to serve
+    // `src/app.ts` (185 bytes) as source, while beta's default limit renders it.
+    // Requested in BOTH orders so no ordering or reuse can hide a bleed.
+    let alpha_node = http_tool_call(
+        &addr,
+        11,
+        "codegraph_node",
+        &format!(
+            r#"{{"projectPath":"{}","file":"src/app.ts"}}"#,
+            alpha.display()
+        ),
+    );
+    let beta_node = http_tool_call(
+        &addr,
+        12,
+        "codegraph_node",
+        &format!(
+            r#"{{"projectPath":"{}","file":"src/app.ts"}}"#,
+            beta.display()
+        ),
+    );
+    let alpha_again = http_tool_call(
+        &addr,
+        13,
+        "codegraph_node",
+        &format!(
+            r#"{{"projectPath":"{}","file":"src/app.ts"}}"#,
+            alpha.display()
+        ),
+    );
+    assert!(
+        alpha_node.contains("could not read from disk"),
+        "alpha's own 120-byte max_file_size must refuse src/app.ts: {alpha_node}"
+    );
+    assert!(
+        !beta_node.contains("could not read from disk"),
+        "beta must not inherit alpha's max_file_size: {beta_node}"
+    );
+    assert!(
+        beta_node.contains("export"),
+        "beta must serve src/app.ts source: {beta_node}"
+    );
+    assert!(
+        alpha_again.contains("could not read from disk"),
+        "alpha must keep its own limit after beta was served: {alpha_again}"
+    );
+
+    // The two projects' file sets stay their own inside the SAME process.
+    let alpha_listing = http_tool_call(
+        &addr,
+        21,
+        "codegraph_files",
+        &format!(r#"{{"projectPath":"{}"}}"#, alpha.display()),
+    );
+    let beta_listing = http_tool_call(
+        &addr,
+        22,
+        "codegraph_files",
+        &format!(r#"{{"projectPath":"{}"}}"#, beta.display()),
+    );
+    assert!(
+        alpha_listing.contains("helper.ts") && !alpha_listing.contains("greeter.py"),
+        "alpha's listing must reflect alpha's config: {alpha_listing}"
+    );
+    assert!(
+        beta_listing.contains("greeter.py") && !beta_listing.contains("helper.ts"),
+        "beta's listing must reflect beta's config: {beta_listing}"
+    );
+
+    // ------------------------------------------------------------- watcher ---
+    // The live watcher scopes by the ADDRESSED project's config: a new file under
+    // the gitignored `Tools/` is auto-synced for alpha (which includes it) and
+    // never for beta (which does not) — even though beta's hostile LEGACY config
+    // names `Tools/`.
+    let mut alpha_serve = ServeProcess::spawn(&alpha);
+    alpha_serve.handshake();
+    fs::write(
+        alpha.join("Tools/watched.ts"),
+        "export function alphaWatchedMarker() { return 1; }\n",
+    )
+    .unwrap();
+    assert!(
+        alpha_serve.search_finds_within("alphaWatchedMarker", Duration::from_secs(20)),
+        "alpha's watcher must auto-sync a file its own include covers"
+    );
+    drop(alpha_serve);
+
+    let mut beta_serve = ServeProcess::spawn(&beta);
+    beta_serve.handshake();
+    fs::write(
+        beta.join("Tools/watched.ts"),
+        "export function betaWatchedMarker() { return 1; }\n",
+    )
+    .unwrap();
+    assert!(
+        !beta_serve.search_finds_within("betaWatchedMarker", Duration::from_secs(6)),
+        "beta's watcher must not adopt alpha's (or its legacy config's) include"
+    );
+    drop(beta_serve);
+}
+
+/// The control: `APP_CONFIG` is INTENTIONALLY a process-wide override, so it
+/// supersedes both projects' own current-root configs. The same run also points
+/// both projects at ONE absolute `CODEGRAPH_DIR`: their identity-suffixed current
+/// roots must stay distinct, so the collision attempt cannot merge two projects'
+/// storage or configuration.
+#[test]
+fn app_config_overrides_both_projects_including_codegraph_dir_collision() {
+    let home = TestDir::new("app-config");
+    let shared_dir = home.path().join("shared-index");
+    let shared = shared_dir.to_string_lossy().into_owned();
+    let alpha = project_with_hostile_legacy_config(&home.path().join("alpha"), "\"tools/\"");
+    let beta = project_with_hostile_legacy_config(&home.path().join("beta"), "\"Tools/\"");
+
+    let override_path = home.path().join("process-wide.toml");
+    fs::write(
+        &override_path,
+        "[app]\nname = \"process-wide\"\n\n[indexing]\ninclude = [\"Tools/\"]\n",
+    )
+    .unwrap();
+    let override_arg = override_path.to_string_lossy().into_owned();
+
+    // The identity-suffixed sibling roots must differ even though CODEGRAPH_DIR is
+    // literally the same absolute path for both projects.
+    let alpha_paths = IndexPaths::resolve(&alpha, Some(&shared)).expect("alpha paths");
+    let beta_paths = IndexPaths::resolve(&beta, Some(&shared)).expect("beta paths");
+    assert_ne!(
+        alpha_paths.current_root(),
+        beta_paths.current_root(),
+        "a shared absolute CODEGRAPH_DIR must still yield per-project current roots"
+    );
+    assert_ne!(alpha_paths.current_db(), beta_paths.current_db());
+    assert_ne!(alpha_paths.config_toml(), beta_paths.config_toml());
+
+    // Initialize both namespaces first (so each has a published current root),
+    // write each project's OWN config — which forbids the other's scope and, for
+    // alpha, `Tools/` too — then reindex under the process-wide APP_CONFIG.
+    for project in [&alpha, &beta] {
+        let (out, err, ok) = cli(
+            &["init", project.to_str().unwrap()],
+            &[("CODEGRAPH_DIR", shared.as_str())],
+        );
+        assert!(
+            ok,
+            "init failed for {}: stdout={out} stderr={err}",
+            project.display()
+        );
+    }
+    write_current_config(&alpha, ALPHA_CONFIG, Some(&shared));
+    write_current_config(&beta, BETA_CONFIG, Some(&shared));
+    for project in [&alpha, &beta] {
+        let (out, err, ok) = cli(
+            &["index", "--force", project.to_str().unwrap()],
+            &[
+                ("CODEGRAPH_DIR", shared.as_str()),
+                ("APP_CONFIG", override_arg.as_str()),
+            ],
+        );
+        assert!(
+            ok,
+            "index under APP_CONFIG failed for {}: stdout={out} stderr={err}",
+            project.display()
+        );
+    }
+
+    // APP_CONFIG won for BOTH: each index carries `Tools/helper.ts`, which
+    // alpha's own config allows but beta's forbids.
+    for (label, project) in [("alpha", &alpha), ("beta", &beta)] {
+        let files = indexed_files(project, Some(&shared));
+        assert!(
+            files.contains(&"Tools/helper.ts".to_string()),
+            "APP_CONFIG must override {label}'s own config: {files:?}"
+        );
+        // Storage stayed separate: each project's DB holds only its own tree.
+        assert!(
+            files.contains(&"src/app.ts".to_string()),
+            "{label}'s index must hold its own sources: {files:?}"
+        );
+    }
+    assert!(
+        alpha_paths.current_root().is_dir() && beta_paths.current_root().is_dir(),
+        "both identity-suffixed roots must exist side by side under the shared CODEGRAPH_DIR"
+    );
+
+    // And with APP_CONFIG UNSET the same two projects fall back to their own
+    // configs again — the override is process-wide, not sticky state on disk.
+    let (out, err, ok) = cli(
+        &["index", "--force", beta.to_str().unwrap()],
+        &[("CODEGRAPH_DIR", shared.as_str())],
+    );
+    assert!(ok, "beta reindex failed: stdout={out} stderr={err}");
+    let beta_files = indexed_files(&beta, Some(&shared));
+    assert!(
+        !beta_files.contains(&"Tools/helper.ts".to_string()),
+        "without APP_CONFIG beta must use its own config again: {beta_files:?}"
+    );
+}
diff --git a/crates/codegraph-cli/tests/godot_idfields_cwd.rs b/crates/codegraph-cli/tests/godot_idfields_cwd.rs
index c927492..6fda322 100644
--- a/crates/codegraph-cli/tests/godot_idfields_cwd.rs
+++ b/crates/codegraph-cli/tests/godot_idfields_cwd.rs
@@ -2,19 +2,19 @@
 //! must fire under the REAL `codegraph index` CLI even when the process CWD is
 //! NOT the project root.
 //!
-//! The pipeline (`extract_and_persist_frameworks`) hands the framework resolver
-//! a repo-RELATIVE `.tres` path; the DSL config reader used to resolve that path
-//! against the process CWD, so `$PROJECT/.codegraph/codegraph.json` was only
-//! found when the CLI happened to run with its CWD == the project root. The A3
-//! unit tests masked this by passing ABSOLUTE `.tres` paths. This test drives
-//! the binary from a DIFFERENT temp dir and asserts the `godot:id:*` (idFields)
-//! and the `resourceFields` literal sentinels land in `unresolved_refs` —
-//! proving config lookup now resolves against the project root.
+//! The pipeline (`extract_and_persist_frameworks`) hands the framework resolver a
+//! repo-RELATIVE `.tres` path plus the project's EXPLICITLY loaded DSL config,
+//! read from the addressed project's own index root — so the process CWD cannot
+//! influence which config is used. This test drives the binary from a DIFFERENT
+//! temp dir and asserts the `godot:id:*` (idFields) and `resourceFields` literal
+//! sentinels land in `unresolved_refs`; a companion target asserts a LEGACY
+//! `.codegraph/codegraph.json` is never adopted.
 
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
+use codegraph_core::IndexPaths;
 use codegraph_store::Store;
 
 struct TestDir {
@@ -70,13 +70,19 @@ duration = 5.0
 ";
 
 fn write_godot_project(root: &Path) {
-    fs::create_dir_all(root.join(".codegraph")).unwrap();
-    fs::write(root.join(".codegraph").join("codegraph.json"), DSL_CONFIG).unwrap();
+    fs::create_dir_all(root).unwrap();
     fs::write(root.join("project.godot"), PROJECT_GODOT).unwrap();
     fs::create_dir_all(root.join("data")).unwrap();
     fs::write(root.join("data").join("spell.tres"), SPELL_TRES).unwrap();
 }
 
+/// Write the project's CURRENT-ROOT `codegraph.json` — the only DSL config a
+/// project-scoped run consults. Call after `init` published the namespace.
+fn write_dsl_config(root: &Path) {
+    let paths = IndexPaths::resolve(root, None).expect("resolve index paths");
+    fs::write(paths.extension_config(), DSL_CONFIG).unwrap();
+}
+
 /// Run the binary from `cwd` (a FOREIGN directory) against an absolute project
 /// path. `CODEGRAPH_NO_DAEMON`/`NO_WATCH` keep the run foreground so the test
 /// never blocks on a background daemon.
@@ -95,8 +101,8 @@ fn cli_from(cwd: &Path, args: &[&str]) -> (String, String, bool) {
 }
 
 fn unresolved_ref_names(project: &Path) -> Vec<String> {
-    // Batch M: the index DB moved to the isolated v2 namespace. The opt-in DSL
-    // config (`.codegraph/codegraph.json`) is still read by the ancestor walker.
+    // Batch M: both the index DB and the opt-in DSL config live in the isolated
+    // v2 namespace.
     let db = project.join(".codegraph-v2").join("codegraph.db");
     let store = Store::open(&db).expect("open store");
     store
@@ -124,6 +130,7 @@ fn idfields_dsl_fires_when_cwd_is_not_project_root() {
     let project_str = project.to_string_lossy().into_owned();
     let (out, err, ok) = cli_from(foreign.path(), &["init", &project_str]);
     assert!(ok, "init failed: stdout={out} stderr={err}");
+    write_dsl_config(&project);
     let (out, err, ok) = cli_from(foreign.path(), &["index", "--force", &project_str]);
     assert!(ok, "index --force failed: stdout={out} stderr={err}");
 
@@ -143,13 +150,10 @@ fn idfields_dsl_fires_when_cwd_is_not_project_root() {
 /// DSL config emits ZERO `godot:id:*` sentinels.
 #[test]
 fn no_config_emits_zero_id_sentinels_from_foreign_cwd() {
-    // Given a Godot project with NO `.codegraph/codegraph.json` DSL block,
+    // Given a Godot project with NO DSL config at all,
     let project_dir = TestDir::new("noconfig");
     let project = project_dir.path().join("game");
-    fs::create_dir_all(project.join(".codegraph")).unwrap();
-    fs::write(project.join("project.godot"), PROJECT_GODOT).unwrap();
-    fs::create_dir_all(project.join("data")).unwrap();
-    fs::write(project.join("data").join("spell.tres"), SPELL_TRES).unwrap();
+    write_godot_project(&project);
     let foreign = TestDir::new("noconfig-cwd");
 
     // When indexed from a foreign cwd,
@@ -166,3 +170,38 @@ fn no_config_emits_zero_id_sentinels_from_foreign_cwd() {
         "off-by-default violated: godot:id:* sentinel present without config: {names:?}"
     );
 }
+
+/// A LEGACY `.codegraph/codegraph.json` must NEVER supply the DSL config: with the
+/// same block written only there, the run emits zero sentinels.
+#[test]
+fn legacy_dsl_config_is_never_adopted() {
+    // Given a Godot project whose ONLY DSL config is the legacy one,
+    let project_dir = TestDir::new("legacy");
+    let project = project_dir.path().join("game");
+    write_godot_project(&project);
+    fs::create_dir_all(project.join(".codegraph")).unwrap();
+    fs::write(
+        project.join(".codegraph").join("codegraph.json"),
+        DSL_CONFIG,
+    )
+    .unwrap();
+    let foreign = TestDir::new("legacy-cwd");
+
+    // When indexed,
+    let project_str = project.to_string_lossy().into_owned();
+    let (out, err, ok) = cli_from(foreign.path(), &["init", &project_str]);
+    assert!(ok, "init failed: stdout={out} stderr={err}");
+    let (out, err, ok) = cli_from(foreign.path(), &["index", "--force", &project_str]);
+    assert!(ok, "index --force failed: stdout={out} stderr={err}");
+
+    // Then nothing fired: neither the id sentinel nor the resourceFields literal.
+    let names = unresolved_ref_names(&project);
+    assert!(
+        !names.iter().any(|n| n.starts_with("godot:id:")),
+        "a legacy DSL config must not emit id sentinels: {names:?}"
+    );
+    assert!(
+        !names.iter().any(|n| n == "Fireball"),
+        "a legacy DSL config must not emit resourceFields literals: {names:?}"
+    );
+}
diff --git a/crates/codegraph-cli/tests/godot_idfields_determinism.rs b/crates/codegraph-cli/tests/godot_idfields_determinism.rs
index ee9efaf..1f8039a 100644
--- a/crates/codegraph-cli/tests/godot_idfields_determinism.rs
+++ b/crates/codegraph-cli/tests/godot_idfields_determinism.rs
@@ -5,11 +5,9 @@
 //!
 //! This is the A5 counterpart to `sync_incremental.rs` / `parallel_index.rs`,
 //! but exercises the `.tres` framework-extraction path that emits
-//! `godot:id:<kind>:<value>` sentinels — i.e. it stresses the mtime-cached
-//! `dsl_id_fields` reader + `find_config_path` tree-walk under both the
-//! incremental (`sync`) and full (`index --force`) code paths, and under both
-//! the rayon parallel parse and a single-threaded (`RAYON_NUM_THREADS=1`)
-//! parse.
+//! `godot:id:<kind>:<value>` sentinels — i.e. it stresses the project-scoped DSL
+//! config load under both the incremental (`sync`) and full (`index --force`)
+//! code paths, and under the rayon parallel parse.
 //!
 //! Comparisons use the codegraph-bench canonical oracle (order-independent
 //! edge/ref multisets + `.schema`), so "identical" means content + `.schema`,
@@ -22,6 +20,7 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 
 use codegraph_bench::oracle::{canonicalize_db, diff_canonical};
+use codegraph_core::IndexPaths;
 
 struct TestDir {
     path: PathBuf,
@@ -75,25 +74,25 @@ skill_effect = \"a:b:9015:c:7005:1000\"
 duration = 5.0
 ";
 
-/// Lay down a Godot project (project.godot + a `.tres` + an idFields config)
-/// under `root`.
+/// Lay down a Godot project (project.godot + a `.tres`) under `root`.
 fn write_godot_project(root: &Path) {
-    fs::create_dir_all(root.join(".codegraph")).unwrap();
-    fs::write(
-        root.join(".codegraph").join("codegraph.json"),
-        IDFIELDS_CONFIG,
-    )
-    .unwrap();
+    fs::create_dir_all(root).unwrap();
     fs::write(root.join("project.godot"), PROJECT_GODOT).unwrap();
     fs::create_dir_all(root.join("data")).unwrap();
     fs::write(root.join("data").join("strength.tres"), BUFF_TRES).unwrap();
 }
 
-/// Run the binary with `cwd` as the working directory. The config reader walks
-/// up from each `.tres`'s relative path joined onto cwd, so the project must be
-/// the cwd for the opt-in `idFields` config to be discovered — exactly how a
-/// user runs `codegraph` from inside their project. `CODEGRAPH_NO_DAEMON` keeps
-/// the run foreground so the test never blocks on a background daemon.
+/// Write the project's CURRENT-ROOT `codegraph.json` — the only DSL config a
+/// project-scoped run consults. Call after `init` published the namespace.
+fn write_idfields_config(root: &Path) {
+    let paths = IndexPaths::resolve(root, None).expect("resolve index paths");
+    fs::write(paths.extension_config(), IDFIELDS_CONFIG).unwrap();
+}
+
+/// Run the binary with `cwd` as the working directory — how a user runs
+/// `codegraph` from inside their project. The DSL config is resolved from the
+/// project's own index root, not the cwd. `CODEGRAPH_NO_DAEMON` keeps the run
+/// foreground so the test never blocks on a background daemon.
 fn cli_cwd(cwd: &Path, args: &[&str]) -> (String, String, bool) {
     let mut cmd = Command::new(env!("CARGO_BIN_EXE_codegraph"));
     cmd.current_dir(cwd);
@@ -109,10 +108,8 @@ fn cli_cwd(cwd: &Path, args: &[&str]) -> (String, String, bool) {
 }
 
 fn db_path(project: &Path) -> PathBuf {
-    // Batch M: the index DB moved to the isolated v2 namespace. The opt-in DSL
-    // config (`.codegraph/codegraph.json`) is still read by the ancestor walker
-    // (its project-scoped move is a later Batch M task), so only the DB path
-    // changes here.
+    // Batch M: both the index DB and the opt-in DSL config live in the isolated
+    // v2 namespace.
     project.join(".codegraph-v2").join("codegraph.db")
 }
 
@@ -127,6 +124,9 @@ fn idfields_sync_after_edit_equals_index_force_from_scratch() {
     write_godot_project(&project);
     let (out, err, ok) = cli_cwd(&project, &["init", "."]);
     assert!(ok, "init failed: stdout={out} stderr={err}");
+    write_idfields_config(&project);
+    let (out, err, ok) = cli_cwd(&project, &["index", "--force", "."]);
+    assert!(ok, "configured index failed: stdout={out} stderr={err}");
 
     // When the `.tres` is edited (a new idField line added) and synced,
     let edited = "\
@@ -148,6 +148,7 @@ duration = 9.0
     fs::write(scratch_project.join("data").join("strength.tres"), edited).unwrap();
     let (out, err, ok) = cli_cwd(&scratch_project, &["init", "."]);
     assert!(ok, "scratch init failed: stdout={out} stderr={err}");
+    write_idfields_config(&scratch_project);
     let (out, err, ok) = cli_cwd(&scratch_project, &["index", "--force", "."]);
     assert!(ok, "index --force failed: stdout={out} stderr={err}");
 
@@ -160,8 +161,8 @@ duration = 9.0
 
 /// (ii) Two independent parallel `index --force` runs of the same idFields
 /// Godot project must be canonically identical — proving the rayon-parallel
-/// framework-extraction path (with the mtime-cached config reader shared across
-/// threads) converges on ONE fixed canonical form regardless of thread
+/// framework-extraction path (with the project's config loaded once and shared
+/// immutably across threads) converges on ONE fixed canonical form regardless of thread
 /// scheduling. This mirrors `parallel_index.rs`'s determinism property, applied
 /// to the `godot:id:*` sentinel-emitting path. (A single-threaded run via
 /// `RAYON_NUM_THREADS=1` is deliberately NOT used: the CLI bulk-index pipeline
@@ -176,12 +177,14 @@ fn idfields_parallel_index_is_deterministic_across_runs() {
     write_godot_project(&first_project);
     let (out, err, ok) = cli_cwd(&first_project, &["init", "."]);
     assert!(ok, "first init failed: stdout={out} stderr={err}");
+    write_idfields_config(&first_project);
 
     let second = TestDir::new("parallel-b");
     let second_project = second.path().join("game");
     write_godot_project(&second_project);
     let (out, err, ok) = cli_cwd(&second_project, &["init", "."]);
     assert!(ok, "second init failed: stdout={out} stderr={err}");
+    write_idfields_config(&second_project);
 
     // When each is independently indexed with the default rayon parallelism,
     let (out, err, ok) = cli_cwd(&first_project, &["index", "--force", "."]);
diff --git a/crates/codegraph-core/src/config.rs b/crates/codegraph-core/src/config.rs
index 0fc5821..b61654e 100644
--- a/crates/codegraph-core/src/config.rs
+++ b/crates/codegraph-core/src/config.rs
@@ -16,16 +16,16 @@
 //! - watch.enabled: true
 //! - watch.debounce_ms: 2000
 //!
-//! The process-global [`init_config`] / [`get_config`] API remains temporarily for
-//! transitional bootstrap callers. New library code must use
-//! [`Config::load_for_paths`] and pass the returned [`Arc`] through project-scoped
-//! operations instead of consulting that singleton.
+//! There is NO process-global config. Every project-scoped operation loads its own
+//! immutable [`Config`] with [`Config::load_for_paths`] and passes the returned
+//! [`Arc`] down; process bootstrap (which has no addressed project yet) uses
+//! [`Config::load_env_or_default`], whose result may only configure the logger.
 
 use crate::IndexPaths;
 use anyhow::{Context, Result};
 use serde::Deserialize;
 use std::path::{Path, PathBuf};
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 /// Top-level configuration.
 #[derive(Debug, Clone, Deserialize)]
@@ -296,73 +296,28 @@ impl Config {
         Ok(Arc::new(config))
     }
 
-    /// Transitional legacy discovery with a clear precedence:
-    ///   1. explicit `cli_path` (passed in directly)
-    ///   2. `APP_CONFIG` env var
-    ///   3. `./.codegraph/config.toml` (current working directory)
-    ///   4. `<project_root>/.codegraph/config.toml` (if provided)
+    /// Load the PROCESS-BOOTSTRAP config, before any project is addressed.
     ///
-    /// If no file is found, returns all defaults. New project-scoped callers
-    /// should use [`Config::load_for_paths`]; this compatibility path retains the
-    /// old `.codegraph` and CWD behavior only until downstream callers migrate.
-    pub fn discover(cli_path: Option<&Path>, project_root: &Path) -> Result<Self> {
-        if let Some(p) = cli_path {
-            return Self::from_path(p);
-        }
-        if let Ok(p) = std::env::var("APP_CONFIG") {
-            return Self::from_path(p);
-        }
-
-        // Try .codegraph/config.toml relative to project root
-        let project_config = project_root.join(".codegraph").join("config.toml");
-        if project_config.exists() {
-            return Self::from_path(&project_config);
+    /// Precedence is exactly the project-independent prefix of
+    /// [`Config::load_for_paths`]: an explicit `cli_path`, then the process-wide
+    /// `APP_CONFIG` override, then all defaults. It never reads a project root,
+    /// a legacy `.codegraph/config.toml`, or the process working directory.
+    ///
+    /// The result may ONLY configure process-wide bootstrap concerns (the logger
+    /// level). It is never the configuration source for a project operation — a
+    /// global HTTP server, sync, watcher, or extraction pass loads the addressed
+    /// project's own config through [`Config::load_for_paths`].
+    pub fn load_env_or_default(cli_path: Option<&Path>) -> Result<Arc<Self>> {
+        if let Some(path) = cli_path {
+            return Self::from_path(path).map(Arc::new);
         }
-
-        // Try ./.codegraph/config.toml (CWD)
-        let cwd_config = PathBuf::from(".codegraph/config.toml");
-        if cwd_config.exists() {
-            return Self::from_path(&cwd_config);
+        if let Some(path) = std::env::var_os("APP_CONFIG") {
+            return Self::from_path(PathBuf::from(path)).map(Arc::new);
         }
-
-        // No file found — return all defaults
-        Ok(Self::default())
+        Ok(Arc::new(Self::default()))
     }
 }
 
-static CONFIG: OnceLock<Config> = OnceLock::new();
-
-/// Initialize the transitional global config once, early in `main`.
-///
-/// This exists so unmigrated bootstrap callers continue to compile. New
-/// project-scoped operations must use [`Config::load_for_paths`] instead.
-pub fn init_config(cli_path: Option<&Path>, project_root: &Path) -> Result<&'static Config> {
-    let cfg = Config::discover(cli_path, project_root)?;
-    CONFIG
-        .set(cfg)
-        .map_err(|_| anyhow::anyhow!("config already initialized"))?;
-    Ok(CONFIG.get().expect("just set"))
-}
-
-/// Borrow the global config only if `init_config` has already run.
-///
-/// Non-panicking counterpart of [`get_config`], for library code that must stay
-/// alive on a path where no binary initialized the global config (for example a
-/// watcher thread that escalates to a full migration). Callers fall back to the
-/// documented defaults instead of aborting the process.
-#[must_use]
-pub fn try_get_config() -> Option<&'static Config> {
-    CONFIG.get()
-}
-
-/// Borrow the global config after `init_config` has run.
-/// Panics if not initialized; for library use, prefer init_config().
-pub fn get_config() -> &'static Config {
-    CONFIG
-        .get()
-        .expect("config not initialized; call init_config() first")
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -500,8 +455,7 @@ max_file_size = 2097152
     #[test]
     fn test_missing_file_returns_defaults() {
         let _env = AppConfigEnvGuard::unset();
-        let cfg = Config::discover(None, Path::new("/tmp/nonexistent"))
-            .expect("should not error on missing file");
+        let cfg = Config::load_env_or_default(None).expect("should not error on missing file");
         assert_eq!(cfg.app.log_level, "info");
         assert_eq!(cfg.indexing.max_file_size, 1048576);
         assert!(cfg.watch.enabled);
@@ -553,12 +507,12 @@ max_file_size = 2097152
     }
 
     #[test]
-    fn discover_prefers_explicit_cli_path() {
+    fn load_env_or_default_prefers_explicit_cli_path() {
         let dir = temp_dir("cli-path");
         let path = dir.join("explicit.toml");
         std::fs::write(&path, "[app]\nname = \"explicit\"\nlog_level = \"error\"\n").unwrap();
 
-        let cfg = Config::discover(Some(&path), Path::new("/tmp/ignored")).expect("discover");
+        let cfg = Config::load_env_or_default(Some(&path)).expect("bootstrap config");
         assert_eq!(cfg.app.name, "explicit");
         assert_eq!(cfg.app.log_level, "error");
 
@@ -566,22 +520,64 @@ max_file_size = 2097152
     }
 
     #[test]
-    fn discover_reads_project_root_codegraph_config() {
-        let _env = AppConfigEnvGuard::unset();
-        let project = temp_dir("project-root");
-        let cfg_dir = project.join(".codegraph");
-        std::fs::create_dir_all(&cfg_dir).unwrap();
+    fn load_env_or_default_honors_app_config_then_falls_back_to_defaults() {
+        let dir = temp_dir("bootstrap-env");
+        let path = dir.join("env.toml");
+        std::fs::write(&path, "[app]\nname = \"env\"\nlog_level = \"trace\"\n").unwrap();
+        {
+            let _env = AppConfigEnvGuard::set(Some(&path));
+            let cfg = Config::load_env_or_default(None).expect("bootstrap config");
+            assert_eq!(cfg.app.name, "env");
+            assert_eq!(cfg.app.log_level, "trace");
+        }
+        {
+            let _env = AppConfigEnvGuard::unset();
+            let cfg = Config::load_env_or_default(None).expect("bootstrap config");
+            assert_eq!(cfg.app.log_level, default_log_level());
+        }
+
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// Bootstrap must never adopt a project or CWD legacy `.codegraph/config.toml`:
+    /// with `APP_CONFIG` unset it is defaults-only, so it can never become the
+    /// configuration source for a later per-project operation.
+    #[test]
+    fn load_env_or_default_ignores_legacy_project_and_cwd_configs() {
+        const CHILD_MARKER: &str = "CODEGRAPH_CONFIG_BOOTSTRAP_CHILD";
+
+        if std::env::var_os(CHILD_MARKER).is_some() {
+            let cfg = Config::load_env_or_default(None).unwrap();
+            assert_eq!(cfg.app.name, "codegraph");
+            assert_eq!(cfg.app.log_level, default_log_level());
+            return;
+        }
+
+        let outer = temp_dir("bootstrap-no-legacy");
+        std::fs::create_dir_all(outer.join(".codegraph")).unwrap();
         std::fs::write(
-            cfg_dir.join("config.toml"),
-            "[app]\nname = \"rooted\"\nlog_level = \"debug\"\n",
+            outer.join(".codegraph/config.toml"),
+            "[app]\nname = \"legacy-cwd\"\nlog_level = \"error\"\n",
         )
         .unwrap();
 
-        let cfg = Config::discover(None, &project).expect("discover project config");
-        assert_eq!(cfg.app.name, "rooted");
-        assert_eq!(cfg.app.log_level, "debug");
+        let output = std::process::Command::new(std::env::current_exe().unwrap())
+            .arg("--exact")
+            .arg("config::tests::load_env_or_default_ignores_legacy_project_and_cwd_configs")
+            .arg("--nocapture")
+            .current_dir(&outer)
+            .env(CHILD_MARKER, "1")
+            .env_remove("APP_CONFIG")
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "child failed\nstdout:\n{}\nstderr:\n{}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
 
-        let _ = std::fs::remove_dir_all(&project);
+        let _ = std::fs::remove_dir_all(outer);
     }
 
     fn project_paths(label: &str) -> (PathBuf, IndexPaths) {
@@ -838,31 +834,23 @@ ignore_paths = ["custom/gen*"]
         let cfg: Config = toml::from_str(with_override).expect("should parse");
         assert_eq!(cfg.indexing.ignore_paths, vec!["custom/gen*"]);
     }
+    /// Two loads of the SAME project return independent immutable values, so no
+    /// caller can observe (or mutate) a shared process-wide config instance.
     #[test]
-    fn init_and_get_config_share_the_global_singleton() {
+    fn repeated_loads_are_independent_immutable_values() {
         let _env = AppConfigEnvGuard::unset();
-        let dir = std::env::temp_dir().join(format!(
-            "codegraph-config-init-{}-{}",
-            std::process::id(),
-            std::time::SystemTime::now()
-                .duration_since(std::time::UNIX_EPOCH)
-                .unwrap()
-                .as_nanos()
-        ));
-        let cg = dir.join(".codegraph");
-        std::fs::create_dir_all(&cg).unwrap();
-        std::fs::write(
-            cg.join("config.toml"),
-            "[app]\nname = \"global-singleton\"\n",
-        )
-        .unwrap();
-        let first = init_config(None, &dir).expect("first init succeeds");
-        assert_eq!(first.app.name, "global-singleton");
-        assert_eq!(get_config().app.name, "global-singleton");
+        let (project, paths) = project_paths("no-singleton");
+        write_current_config(&paths, "[app]\nname = \"scoped\"\n");
+
+        let first = Config::load_for_paths(None, &paths).unwrap();
+        let second = Config::load_for_paths(None, &paths).unwrap();
         assert!(
-            init_config(None, &dir).is_err(),
-            "a second init must fail (already initialized)"
+            !Arc::ptr_eq(&first, &second),
+            "load_for_paths must not hand back a cached/shared instance"
         );
-        let _ = std::fs::remove_dir_all(&dir);
+        assert_eq!(first.app.name, "scoped");
+        assert_eq!(second.app.name, "scoped");
+
+        let _ = std::fs::remove_dir_all(project);
     }
 }
diff --git a/crates/codegraph-daemon/src/lib.rs b/crates/codegraph-daemon/src/lib.rs
index 6829f22..2ee6473 100644
--- a/crates/codegraph-daemon/src/lib.rs
+++ b/crates/codegraph-daemon/src/lib.rs
@@ -166,11 +166,6 @@ pub struct DaemonOptions {
     /// project (N client inotify sets collapse to 1). Honors
     /// `watch_disabled_reason` (e.g. `CODEGRAPH_NO_WATCH=1`).
     pub watch: bool,
-    /// `config.toml` `include`/`exclude` path patterns (#1063), passed through
-    /// to the shared `ProjectWatcher` so its scope matches the scan's. The CLI
-    /// (which owns the config singleton) populates these; empty = pre-#1063.
-    pub include: Vec<String>,
-    pub exclude: Vec<String>,
 }
 
 impl Default for DaemonOptions {
@@ -181,8 +176,6 @@ impl Default for DaemonOptions {
             watchdog_interval: DEFAULT_WATCHDOG_INTERVAL,
             run_mcp: true,
             watch: true,
-            include: Vec::new(),
-            exclude: Vec::new(),
         }
     }
 }
@@ -560,10 +553,21 @@ fn start_project_watcher(
     options: &DaemonOptions,
 ) -> Option<codegraph_watch::ProjectWatcher> {
     let counter = Arc::new(AtomicUsize::new(0));
-    let mut watch_options = codegraph_watch::WatchOptions::default();
-    watch_options.no_watch = !options.watch;
-    watch_options.include = options.include.clone();
-    watch_options.exclude = options.exclude.clone();
+    // The watcher's scope comes from THIS project's own config (include/exclude,
+    // debounce, enable flag, extension overrides), loaded from its resolved index
+    // root — never from a process-global value or from whichever project the
+    // launcher happened to start in. A config that cannot be read is reported and
+    // the daemon keeps serving without a watcher rather than watching the wrong
+    // scope.
+    let mut watch_options = match codegraph_watch::watch_options_for_project(project_root) {
+        Ok(watch_options) => watch_options,
+        Err(err) => {
+            warn!(error = %err, "daemon could not load project watch config");
+            return None;
+        }
+    };
+    // An explicit `--no-watch` (or `CODEGRAPH_NO_WATCH`) still wins over config.
+    watch_options.no_watch = watch_options.no_watch || !options.watch;
     watch_options.on_sync_complete =
         Some(Arc::new(move |outcome: codegraph_watch::SyncOutcome| {
             let n = counter.fetch_add(1, Ordering::SeqCst) + 1;
diff --git a/crates/codegraph-daemon/tests/async_model.rs b/crates/codegraph-daemon/tests/async_model.rs
index f0e8d29..30e9d95 100644
--- a/crates/codegraph-daemon/tests/async_model.rs
+++ b/crates/codegraph-daemon/tests/async_model.rs
@@ -97,7 +97,8 @@ fn handshake(stream: &mut Stream, id: i64) {
 }
 
 fn start_daemon(project: &Path) -> DaemonHandle {
-    let _ = codegraph_core::config::init_config(None, project);
+    // No process-global config to initialize: every project-scoped operation
+    // loads the addressed project's own immutable config on demand.
     let options = DaemonOptions {
         host_pid: None,
         watchdog_interval: Duration::from_millis(10),
diff --git a/crates/codegraph-daemon/tests/rmcp_tools_call.rs b/crates/codegraph-daemon/tests/rmcp_tools_call.rs
index 9b6d4a8..4675eae 100644
--- a/crates/codegraph-daemon/tests/rmcp_tools_call.rs
+++ b/crates/codegraph-daemon/tests/rmcp_tools_call.rs
@@ -91,10 +91,8 @@ fn real_client_tools_call_through_daemon_session_returns_result() {
     // golden mini db into the temp project's `.codegraph/`.
     let project = temp_indexed_project("rmcp-toolscall");
 
-    // In-process daemon must replicate the binary's `init_config` startup
-    // (main.rs) or tool execution panics on the uninitialized global config.
-    let _ = codegraph_core::config::init_config(None, &project);
-
+    // No process-global config to initialize: tool execution loads the addressed
+    // project's own config (or its documented defaults) per request.
     let options = DaemonOptions {
         host_pid: None,
         watchdog_interval: Duration::from_millis(10),
diff --git a/crates/codegraph-extract/src/engine.rs b/crates/codegraph-extract/src/engine.rs
index 7961451..b0aba8d 100644
--- a/crates/codegraph-extract/src/engine.rs
+++ b/crates/codegraph-extract/src/engine.rs
@@ -5,7 +5,7 @@
 //! `tree-sitter.ts:4350-4425` maps to source dispatch.
 
 use anyhow::{Context, Result};
-use codegraph_core::config::IndexingConfig;
+use codegraph_core::config::{Config, IndexingConfig};
 use codegraph_core::node_id::hash_content;
 use codegraph_core::types::{ExtractionResult, Language};
 use rayon::prelude::*;
@@ -13,10 +13,11 @@ use regex::Regex;
 use std::collections::HashSet;
 use std::fs;
 use std::path::{Path, PathBuf};
-use std::sync::OnceLock;
+use std::sync::{Arc, OnceLock};
 use std::time::Instant;
 use tree_sitter::Parser;
 
+use crate::ext_config::ExtensionOverrides;
 use crate::lang::spec_for_language;
 use crate::walker::TreeSitterWalker;
 
@@ -28,6 +29,12 @@ pub struct ExtractOptions {
     pub exclude: Vec<String>,
     pub include: Vec<String>,
     pub parallel: bool,
+    /// The addressed project's custom extension→language overrides, loaded from
+    /// ITS current-root `codegraph.json` ([`ExtensionOverrides::load_for_paths`]).
+    /// Empty by default, so a project that declares none behaves exactly as
+    /// before. Passed explicitly instead of discovered, so two projects handled
+    /// by one process can never see each other's overrides.
+    pub extensions: Arc<ExtensionOverrides>,
 }
 
 impl Default for ExtractOptions {
@@ -40,6 +47,25 @@ impl Default for ExtractOptions {
             exclude: indexing.exclude,
             include: indexing.include,
             parallel: true,
+            extensions: ExtensionOverrides::empty(),
+        }
+    }
+}
+
+impl ExtractOptions {
+    /// Build the scan/extract options for ONE project from its own immutable
+    /// [`Config`] and extension overrides. This is the only shape production
+    /// callers use; nothing here consults a process-global value.
+    #[must_use]
+    pub fn for_project(config: &Config, extensions: Arc<ExtensionOverrides>) -> Self {
+        Self {
+            max_file_size: config.indexing.max_file_size,
+            ignore_dirs: config.indexing.ignore_dirs.clone(),
+            ignore_paths: config.indexing.ignore_paths.clone(),
+            exclude: config.indexing.exclude.clone(),
+            include: config.indexing.include.clone(),
+            parallel: true,
+            extensions,
         }
     }
 }
@@ -96,7 +122,25 @@ pub fn builtin_language_for_ext(ext: &str) -> Option<Language> {
     Some(language)
 }
 
+/// Built-in language detection with NO project extension overrides.
+///
+/// Use this only where no project is addressed (a bare path classification).
+/// Every pipeline path that indexes or syncs a project calls
+/// [`detect_language_with`] with that project's own overrides.
 pub fn detect_language(file_path: impl AsRef<Path>) -> Language {
+    detect_language_with(file_path, &ExtensionOverrides::default())
+}
+
+/// Detect `file_path`'s language, consulting `overrides` for extensions the
+/// built-in table and the embedded pre-pass leave unclaimed.
+///
+/// Golden safety: the override is consulted ONLY for extensions unclaimed by
+/// both the built-in match and the embedded pre-pass (both checked first), so
+/// empty overrides are byte-identical to the pre-override behavior.
+pub fn detect_language_with(
+    file_path: impl AsRef<Path>,
+    overrides: &ExtensionOverrides,
+) -> Language {
     let path = file_path.as_ref();
     let normalized = normalize_path(path);
     if let Some(language) = crate::embedded::detect_embedded_language(&normalized) {
@@ -114,10 +158,7 @@ pub fn detect_language(file_path: impl AsRef<Path>) -> Language {
     if let Some(language) = builtin_language_for_ext(&ext) {
         return language;
     }
-    // Golden safety: the override is consulted ONLY for extensions unclaimed by
-    // both the built-in match and the embedded pre-pass (both already checked
-    // above). Absent codegraph.json => no override => exact current behavior.
-    if let Some(language) = crate::ext_config::override_language_for(path, &ext) {
+    if let Some(language) = overrides.language_for(&ext) {
         return language;
     }
     Language::Unknown
@@ -156,13 +197,27 @@ fn prefix_8k(source: &str) -> &str {
     }
 }
 
+/// Extract `source` with NO project extension overrides. Equivalent to
+/// [`extract_source_with`] with empty overrides; used where `language` is already
+/// known (embedded delegation) or no project is addressed.
 pub fn extract_source(
     file_path: &str,
     source: &str,
     language: Option<Language>,
+) -> ExtractionResult {
+    extract_source_with(file_path, source, language, &ExtensionOverrides::default())
+}
+
+/// Extract `source`, resolving an absent `language` through the addressed
+/// project's own extension `overrides`.
+pub fn extract_source_with(
+    file_path: &str,
+    source: &str,
+    language: Option<Language>,
+    overrides: &ExtensionOverrides,
 ) -> ExtractionResult {
     let start = Instant::now();
-    let mut language = language.unwrap_or_else(|| detect_language(file_path));
+    let mut language = language.unwrap_or_else(|| detect_language_with(file_path, overrides));
     if language == Language::C
         && Path::new(file_path)
             .extension()
@@ -235,16 +290,30 @@ pub fn extract_source(
         .extract(start.elapsed().as_millis() as i64)
 }
 
+/// Extract one file under the DEFAULT options (no project config). Kept for
+/// callers that address no project; project pipelines use
+/// [`extract_file_with_options`] so the addressed project's `max_file_size` and
+/// extension overrides apply.
 pub fn extract_file(
     root: impl AsRef<Path>,
     relative_path: impl AsRef<Path>,
+) -> Result<ExtractionResult> {
+    extract_file_with_options(root, relative_path, &ExtractOptions::default())
+}
+
+/// Extract one file under ONE project's own `options` (size limit + extension
+/// overrides), so a per-project `max_file_size` and custom extension map apply
+/// to the incremental path exactly as they do to a full scan.
+pub fn extract_file_with_options(
+    root: impl AsRef<Path>,
+    relative_path: impl AsRef<Path>,
+    options: &ExtractOptions,
 ) -> Result<ExtractionResult> {
     let root = root.as_ref();
     let relative_path = normalize_path(relative_path.as_ref());
     let full_path = root.join(&relative_path);
     let metadata = fs::metadata(&full_path)
         .with_context(|| format!("stat source file {}", full_path.display()))?;
-    let options = ExtractOptions::default();
     if metadata.len() > options.max_file_size {
         return Ok(size_skip_result(
             &relative_path,
@@ -255,7 +324,12 @@ pub fn extract_file(
     let source = fs::read_to_string(&full_path)
         .with_context(|| format!("read source file {}", full_path.display()))?;
     let _content_hash = hash_content(&source);
-    Ok(extract_source(&relative_path, &source, None))
+    Ok(extract_source_with(
+        &relative_path,
+        &source,
+        None,
+        &options.extensions,
+    ))
 }
 
 pub fn extract_project(
@@ -278,7 +352,12 @@ pub fn extract_project(
         let source = fs::read_to_string(&full)
             .with_context(|| format!("read source file {}", full.display()))?;
         let _content_hash = hash_content(&source);
-        Ok(extract_source(relative, &source, None))
+        Ok(extract_source_with(
+            relative,
+            &source,
+            None,
+            &options.extensions,
+        ))
     };
 
     let mut results = if options.parallel {
@@ -318,12 +397,14 @@ pub fn scan_project(root: &Path, options: &ExtractOptions) -> Result<Vec<String>
         &reserved_roots,
         &pattern_sets,
         &include,
+        &options.extensions,
         &mut files,
     )?;
     files.sort();
     Ok(files)
 }
 
+#[allow(clippy::too_many_arguments)]
 fn scan_dir(
     root: &Path,
     dir: &Path,
@@ -331,6 +412,7 @@ fn scan_dir(
     reserved_roots: &std::collections::BTreeSet<PathBuf>,
     pattern_sets: &[&[String]],
     include: &IncludeSet,
+    overrides: &ExtensionOverrides,
     files: &mut Vec<String>,
 ) -> Result<()> {
     let entries = fs::read_dir(dir).with_context(|| format!("read dir {}", dir.display()))?;
@@ -366,9 +448,10 @@ fn scan_dir(
                 reserved_roots,
                 pattern_sets,
                 include,
+                overrides,
                 files,
             )?;
-        } else if file_type.is_file() && is_extractable_source_path(&relative) {
+        } else if file_type.is_file() && is_extractable_source_path(&relative, overrides) {
             // Post-model include decision: a model-ignored file is force-included
             // iff it matches `include` and is NOT overridden by an explicit
             // `exclude` (checked inside `IncludeSet::forces`). Built-in dir skips
@@ -566,8 +649,8 @@ fn include_file_matches(relative: &str, pattern: &str) -> bool {
     pattern_matches(relative, pattern)
 }
 
-fn is_extractable_source_path(relative: &str) -> bool {
-    let language = detect_language(relative);
+fn is_extractable_source_path(relative: &str, overrides: &ExtensionOverrides) -> bool {
+    let language = detect_language_with(relative, overrides);
     language != Language::Unknown
         && (crate::lang::spec_for_language(language).is_some()
             || crate::embedded::is_embedded_source_path(relative)
@@ -980,7 +1063,10 @@ mod tests {
             Language::Unknown
         );
         assert!(
-            !is_extractable_source_path("Scripts/effect_manager.gd.uid"),
+            !is_extractable_source_path(
+                "Scripts/effect_manager.gd.uid",
+                &ExtensionOverrides::default()
+            ),
             ".gd.uid sidecar must never be scanned into a file record"
         );
     }
diff --git a/crates/codegraph-extract/src/ext_config.rs b/crates/codegraph-extract/src/ext_config.rs
index 6d13e2e..707ab25 100644
--- a/crates/codegraph-extract/src/ext_config.rs
+++ b/crates/codegraph-extract/src/ext_config.rs
@@ -1,134 +1,118 @@
-//! Reader for `.codegraph/codegraph.json` custom extension overrides:
+//! Reader for the PROJECT-SCOPED `codegraph.json` extension overrides:
 //! `{"extensions": {".x": "lua"}}`. Keys normalized (dot stripped, lowercased);
-//! languages parse via `Language` serde names (unknown skipped). The parsed map
-//! is mtime-cached per config-file path; "absent" is cached too, so a project
-//! with no codegraph.json pays no repeated I/O.
+//! languages parse via `Language` serde names (unknown skipped).
+//!
+//! The file read is ALWAYS the caller-supplied current-root
+//! [`IndexPaths::extension_config`](codegraph_core::IndexPaths::extension_config)
+//! path: nothing here walks the directory tree, consults the process working
+//! directory, or reads a legacy `.codegraph/codegraph.json`. The parsed result is
+//! an immutable [`ExtensionOverrides`] value that the caller threads through
+//! [`crate::ExtractOptions`], so two projects served by ONE process cannot see
+//! each other's overrides and no cache can go stale.
+//!
+//! Absence and malformed content stay tolerant (empty overrides, logged), which
+//! is the documented opt-in contract: a project with no `codegraph.json` behaves
+//! byte-identically to a build without the feature.
 
+use codegraph_core::IndexPaths;
 use codegraph_core::types::Language;
 use serde::Deserialize;
-use std::collections::HashMap;
-use std::path::{Path, PathBuf};
-use std::sync::{Arc, Mutex, OnceLock};
-use std::time::SystemTime;
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::sync::Arc;
 
 #[derive(Debug, Deserialize)]
 struct CodegraphJson {
     #[serde(default)]
-    extensions: HashMap<String, String>,
+    extensions: BTreeMap<String, String>,
 }
 
-type ExtMap = HashMap<String, Language>;
-
-#[derive(Clone)]
-enum CacheEntry {
-    Absent,
-    Present { mtime: SystemTime, map: Arc<ExtMap> },
-}
-
-fn cache() -> &'static Mutex<HashMap<PathBuf, CacheEntry>> {
-    static CACHE: OnceLock<Mutex<HashMap<PathBuf, CacheEntry>>> = OnceLock::new();
-    CACHE.get_or_init(|| Mutex::new(HashMap::new()))
-}
-
-/// Override language for `ext` (lowercased, no dot), resolving the nearest
-/// `.codegraph/codegraph.json` walking up from `path`. `None` when no config is
-/// reachable, parse failed, or the extension is unmapped.
-pub fn override_language_for(path: &Path, ext: &str) -> Option<Language> {
-    let config_path = find_config_path(path)?;
-    let map = load_cached(&config_path)?;
-    map.get(ext).copied()
+/// One project's parsed extension overrides: lowercased dot-free extension →
+/// language. Empty when the project declares none.
+///
+/// Deterministic: the backing map is ordered, and the value is immutable once
+/// built, so every consumer of the same `Arc` observes identical bytes.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub struct ExtensionOverrides {
+    map: BTreeMap<String, Language>,
 }
 
-fn find_config_path(file_path: &Path) -> Option<PathBuf> {
-    let start = if file_path.is_absolute() {
-        file_path.parent().map(Path::to_path_buf)
-    } else {
-        std::env::current_dir()
-            .ok()
-            .map(|cwd| cwd.join(file_path))
-            .and_then(|abs| abs.parent().map(Path::to_path_buf))
-    }?;
-    let mut dir: Option<&Path> = Some(start.as_path());
-    while let Some(current) = dir {
-        let candidate = current.join(".codegraph").join("codegraph.json");
-        if candidate.is_file() {
-            return Some(candidate);
-        }
-        dir = current.parent();
+impl ExtensionOverrides {
+    /// No overrides — the zero-config default.
+    #[must_use]
+    pub fn empty() -> Arc<Self> {
+        Arc::new(Self::default())
     }
-    None
-}
-
-fn load_cached(config_path: &Path) -> Option<Arc<ExtMap>> {
-    let current_mtime = std::fs::metadata(config_path)
-        .and_then(|m| m.modified())
-        .ok();
-    let mut guard = cache().lock().unwrap_or_else(|p| p.into_inner());
 
-    if let Some(entry) = guard.get(config_path) {
-        match (entry, current_mtime) {
-            (CacheEntry::Present { mtime, map }, Some(now)) if *mtime == now => {
-                return Some(Arc::clone(map));
-            }
-            (CacheEntry::Absent, None) => return None,
-            _ => {}
-        }
+    /// Load the overrides declared by ONE project's current index root.
+    ///
+    /// Reads exactly `paths.extension_config()`. A missing file yields empty
+    /// overrides; an unreadable or malformed file is tolerated as empty and
+    /// logged, matching the opt-in contract.
+    #[must_use]
+    pub fn load_for_paths(paths: &IndexPaths) -> Arc<Self> {
+        Self::load_from_file(&paths.extension_config())
     }
 
-    let Some(mtime) = current_mtime else {
-        guard.insert(config_path.to_path_buf(), CacheEntry::Absent);
-        return None;
-    };
-
-    let map = Arc::new(parse_config(config_path));
-    guard.insert(
-        config_path.to_path_buf(),
-        CacheEntry::Present {
-            mtime,
-            map: Arc::clone(&map),
-        },
-    );
-    Some(map)
-}
-
-fn parse_config(config_path: &Path) -> ExtMap {
-    let Ok(contents) = std::fs::read_to_string(config_path) else {
-        return ExtMap::new();
-    };
-    let parsed: CodegraphJson = match serde_json::from_str(&contents) {
-        Ok(parsed) => parsed,
-        Err(error) => {
-            tracing::warn!(
-                target: "codegraph_extract::ext_config",
-                path = %config_path.display(),
-                %error,
-                "ignoring malformed .codegraph/codegraph.json"
-            );
-            return ExtMap::new();
-        }
-    };
+    /// Load overrides from an explicit `codegraph.json` path. Exposed so a
+    /// caller that already resolved the file (or a test fixture) can supply it
+    /// directly; the tolerance rules are identical to [`Self::load_for_paths`].
+    #[must_use]
+    pub fn load_from_file(config_path: &Path) -> Arc<Self> {
+        let Ok(contents) = std::fs::read_to_string(config_path) else {
+            return Self::empty();
+        };
+        Arc::new(Self::parse(&contents, config_path))
+    }
 
-    let mut map = ExtMap::new();
-    for (raw_ext, raw_lang) in parsed.extensions {
-        let ext = normalize_ext(&raw_ext);
-        if ext.is_empty() {
-            continue;
-        }
-        match parse_language(&raw_lang) {
-            Some(language) => {
-                map.insert(ext, language);
-            }
-            None => {
+    fn parse(contents: &str, config_path: &Path) -> Self {
+        let parsed: CodegraphJson = match serde_json::from_str(contents) {
+            Ok(parsed) => parsed,
+            Err(error) => {
                 tracing::warn!(
                     target: "codegraph_extract::ext_config",
-                    extension = %raw_ext,
-                    language = %raw_lang,
-                    "ignoring unknown language in codegraph.json extensions"
+                    path = %config_path.display(),
+                    %error,
+                    "ignoring malformed codegraph.json"
                 );
+                return Self::default();
+            }
+        };
+
+        let mut map = BTreeMap::new();
+        for (raw_ext, raw_lang) in parsed.extensions {
+            let ext = normalize_ext(&raw_ext);
+            if ext.is_empty() {
+                continue;
+            }
+            match parse_language(&raw_lang) {
+                Some(language) => {
+                    map.insert(ext, language);
+                }
+                None => {
+                    tracing::warn!(
+                        target: "codegraph_extract::ext_config",
+                        extension = %raw_ext,
+                        language = %raw_lang,
+                        "ignoring unknown language in codegraph.json extensions"
+                    );
+                }
             }
         }
+        Self { map }
+    }
+
+    /// `true` when the project declared no usable override.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.map.is_empty()
+    }
+
+    /// The override language for `ext` (lowercased, no leading dot), if any.
+    #[must_use]
+    pub fn language_for(&self, ext: &str) -> Option<Language> {
+        self.map.get(ext).copied()
     }
-    map
 }
 
 fn normalize_ext(raw: &str) -> String {
@@ -143,3 +127,73 @@ fn parse_language(raw: &str) -> Option<Language> {
     }
     Some(language)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn overrides(json: &str) -> ExtensionOverrides {
+        ExtensionOverrides::parse(json, Path::new("codegraph.json"))
+    }
+
+    #[test]
+    fn parses_normalized_keys_and_known_languages() {
+        let parsed = overrides(r#"{"extensions":{".MyExt":"lua","X":"go"}}"#);
+        assert_eq!(parsed.language_for("myext"), Some(Language::Lua));
+        assert_eq!(parsed.language_for("x"), Some(Language::Go));
+        assert!(!parsed.is_empty());
+    }
+
+    #[test]
+    fn skips_unknown_languages_and_empty_keys() {
+        let parsed = overrides(r#"{"extensions":{".foo":"klingon",".":"lua","  ":"go"}}"#);
+        assert_eq!(parsed.language_for("foo"), None);
+        assert!(parsed.is_empty());
+    }
+
+    #[test]
+    fn malformed_json_yields_empty_overrides() {
+        assert!(overrides("{ not json ").is_empty());
+    }
+
+    #[test]
+    fn missing_file_yields_empty_overrides() {
+        let missing = std::env::temp_dir().join(format!(
+            "codegraph-ext-missing-{}-{}/codegraph.json",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        assert!(ExtensionOverrides::load_from_file(&missing).is_empty());
+    }
+
+    /// The reader consults the caller's current-root path only: a legacy
+    /// `.codegraph/codegraph.json` next to it is never adopted.
+    #[test]
+    fn load_for_paths_reads_only_the_current_root_config() {
+        let project = std::env::temp_dir().join(format!(
+            "codegraph-ext-scoped-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(project.join(".codegraph")).unwrap();
+        std::fs::write(
+            project.join(".codegraph/codegraph.json"),
+            r#"{"extensions":{".zz":"go"}}"#,
+        )
+        .unwrap();
+        let paths = IndexPaths::resolve(&project, None).expect("resolve paths");
+        std::fs::create_dir_all(paths.current_root()).unwrap();
+        std::fs::write(paths.extension_config(), r#"{"extensions":{".zz":"lua"}}"#).unwrap();
+
+        let loaded = ExtensionOverrides::load_for_paths(&paths);
+        assert_eq!(loaded.language_for("zz"), Some(Language::Lua));
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
+}
diff --git a/crates/codegraph-extract/src/lib.rs b/crates/codegraph-extract/src/lib.rs
index 5fb9982..143f5ea 100644
--- a/crates/codegraph-extract/src/lib.rs
+++ b/crates/codegraph-extract/src/lib.rs
@@ -17,6 +17,7 @@ pub mod spec;
 pub mod walker;
 
 pub use engine::{
-    ExtractOptions, detect_language, extract_file, extract_project, extract_source,
-    include_exclude_pattern_matches,
+    ExtractOptions, detect_language, detect_language_with, extract_file, extract_file_with_options,
+    extract_project, extract_source, extract_source_with, include_exclude_pattern_matches,
 };
+pub use ext_config::ExtensionOverrides;
diff --git a/crates/codegraph-extract/tests/coverage_ext_config.rs b/crates/codegraph-extract/tests/coverage_ext_config.rs
index e01a9bf..d344233 100644
--- a/crates/codegraph-extract/tests/coverage_ext_config.rs
+++ b/crates/codegraph-extract/tests/coverage_ext_config.rs
@@ -1,10 +1,12 @@
-//! Coverage for the `.codegraph/codegraph.json` custom extension-override
-//! reader (`ext_config.rs`) driven through the public `detect_language` API.
+//! Coverage for the PROJECT-SCOPED `codegraph.json` extension-override reader
+//! (`ext_config.rs`) driven through its public API plus `detect_language_with`.
 //! Exercises: successful override, unknown-language skip, malformed-JSON
-//! tolerance, and the absent-config fast path. TEST-ONLY: no production change.
+//! tolerance, the absent-config fast path, and the built-in skip-list.
+//! TEST-ONLY: no production change.
 
+use codegraph_core::IndexPaths;
 use codegraph_core::types::Language;
-use codegraph_extract::detect_language;
+use codegraph_extract::{ExtensionOverrides, detect_language, detect_language_with};
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicU32, Ordering};
@@ -22,26 +24,30 @@ fn unique_project(tag: &str) -> PathBuf {
     dir
 }
 
-fn write_config(root: &Path, contents: &str) {
-    let dir = root.join(".codegraph");
-    fs::create_dir_all(&dir).expect("create .codegraph");
-    fs::write(dir.join("codegraph.json"), contents).expect("write codegraph.json");
+/// Write the project's CURRENT-ROOT `codegraph.json` and load it the way the
+/// pipeline does — explicitly, from the resolved index paths.
+fn load_overrides(project: &Path, contents: &str) -> std::sync::Arc<ExtensionOverrides> {
+    let paths = IndexPaths::resolve(project, None).expect("resolve index paths");
+    fs::create_dir_all(paths.current_root()).expect("create current root");
+    fs::write(paths.extension_config(), contents).expect("write codegraph.json");
+    ExtensionOverrides::load_for_paths(&paths)
 }
 
 #[test]
 fn override_maps_custom_extension_to_a_known_language() {
     let project = unique_project("known");
-    write_config(
+    let overrides = load_overrides(
         &project,
         r#"{ "extensions": { ".blade": "php", "X": "lua" } }"#,
     );
 
     // A custom extension unmapped by the built-in table resolves via the config.
-    let blade = project.join("views/home.blade");
-    assert_eq!(detect_language(&blade), Language::Php);
+    assert_eq!(
+        detect_language_with("views/home.blade", &overrides),
+        Language::Php
+    );
     // Keys are dot-stripped and lowercased before matching.
-    let x = project.join("script.x");
-    assert_eq!(detect_language(&x), Language::Lua);
+    assert_eq!(detect_language_with("script.x", &overrides), Language::Lua);
 
     fs::remove_dir_all(&project).ok();
 }
@@ -49,10 +55,12 @@ fn override_maps_custom_extension_to_a_known_language() {
 #[test]
 fn override_ignores_unknown_language_names() {
     let project = unique_project("unknown_lang");
-    write_config(&project, r#"{ "extensions": { ".foo": "klingon" } }"#);
+    let overrides = load_overrides(&project, r#"{ "extensions": { ".foo": "klingon" } }"#);
 
-    let foo = project.join("thing.foo");
-    assert_eq!(detect_language(&foo), Language::Unknown);
+    assert_eq!(
+        detect_language_with("thing.foo", &overrides),
+        Language::Unknown
+    );
 
     fs::remove_dir_all(&project).ok();
 }
@@ -60,10 +68,13 @@ fn override_ignores_unknown_language_names() {
 #[test]
 fn malformed_config_is_tolerated_and_yields_no_override() {
     let project = unique_project("malformed");
-    write_config(&project, "{ this is not valid json ");
+    let overrides = load_overrides(&project, "{ this is not valid json ");
 
-    let bar = project.join("thing.bar");
-    assert_eq!(detect_language(&bar), Language::Unknown);
+    assert!(overrides.is_empty());
+    assert_eq!(
+        detect_language_with("thing.bar", &overrides),
+        Language::Unknown
+    );
 
     fs::remove_dir_all(&project).ok();
 }
@@ -73,10 +84,12 @@ fn builtin_extension_never_consults_the_override() {
     let project = unique_project("builtin_wins");
     // Even if the config tries to remap `.rs`, the built-in table wins because
     // the override is consulted only for extensions the built-ins do not claim.
-    write_config(&project, r#"{ "extensions": { ".rs": "python" } }"#);
+    let overrides = load_overrides(&project, r#"{ "extensions": { ".rs": "python" } }"#);
 
-    let rs = project.join("src/lib.rs");
-    assert_eq!(detect_language(&rs), Language::Rust);
+    assert_eq!(
+        detect_language_with("src/lib.rs", &overrides),
+        Language::Rust
+    );
 
     fs::remove_dir_all(&project).ok();
 }
@@ -84,8 +97,39 @@ fn builtin_extension_never_consults_the_override() {
 #[test]
 fn absent_config_leaves_custom_extension_unknown() {
     let project = unique_project("absent");
-    let baz = project.join("thing.baz");
-    assert_eq!(detect_language(&baz), Language::Unknown);
+    let paths = IndexPaths::resolve(&project, None).expect("resolve index paths");
+    let overrides = ExtensionOverrides::load_for_paths(&paths);
+
+    assert!(overrides.is_empty());
+    assert_eq!(
+        detect_language_with("thing.baz", &overrides),
+        Language::Unknown
+    );
+    // The override-free entry point agrees.
+    assert_eq!(detect_language("thing.baz"), Language::Unknown);
+
+    fs::remove_dir_all(&project).ok();
+}
+
+/// A LEGACY `.codegraph/codegraph.json` is never consulted: only the project's
+/// current-root config can supply an override.
+#[test]
+fn legacy_codegraph_json_is_never_read() {
+    let project = unique_project("legacy");
+    fs::create_dir_all(project.join(".codegraph")).unwrap();
+    fs::write(
+        project.join(".codegraph/codegraph.json"),
+        r#"{ "extensions": { ".legacyext": "lua" } }"#,
+    )
+    .unwrap();
+    let paths = IndexPaths::resolve(&project, None).expect("resolve index paths");
+
+    let overrides = ExtensionOverrides::load_for_paths(&paths);
+    assert!(overrides.is_empty(), "a legacy config must not be adopted");
+    assert_eq!(
+        detect_language_with("plugin.legacyext", &overrides),
+        Language::Unknown
+    );
 
     fs::remove_dir_all(&project).ok();
 }
diff --git a/crates/codegraph-extract/tests/custom_ext.rs b/crates/codegraph-extract/tests/custom_ext.rs
index 595a01b..9ca9c87 100644
--- a/crates/codegraph-extract/tests/custom_ext.rs
+++ b/crates/codegraph-extract/tests/custom_ext.rs
@@ -1,16 +1,23 @@
-//! T11: custom file-extension -> language via `.codegraph/codegraph.json`.
+//! T11: custom file-extension -> language via the project's CURRENT-ROOT
+//! `codegraph.json` (`IndexPaths::extension_config`).
 //!
 //! Golden-safety contract: the override may ONLY add a language for an
 //! extension that has NO built-in match arm AND NO embedded mapping. A
 //! hostile attempt to re-map a real golden extension (`.ts`, `.py`) MUST be
 //! ignored, so the byte-stable golden oracle is never perturbed.
+//!
+//! The overrides are loaded EXPLICITLY from the project's resolved index paths
+//! and passed into `detect_language_with`, exactly as the pipeline threads them
+//! through `ExtractOptions` — no directory walk, no process-CWD lookup, no cache.
 
+use codegraph_core::IndexPaths;
 use codegraph_core::types::Language;
-use codegraph_extract::detect_language;
+use codegraph_extract::{ExtensionOverrides, detect_language, detect_language_with};
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 use std::sync::atomic::{AtomicU32, Ordering};
-use std::time::{Duration, SystemTime};
+use std::time::SystemTime;
 
 /// A unique temp project directory per call (no external `tempfile` dep).
 fn unique_project(tag: &str) -> PathBuf {
@@ -28,10 +35,17 @@ fn unique_project(tag: &str) -> PathBuf {
     dir
 }
 
+/// Write the project's current-root `codegraph.json` (the only config consulted).
 fn write_codegraph_json(project: &Path, contents: &str) {
-    let cg = project.join(".codegraph");
-    fs::create_dir_all(&cg).expect("create .codegraph");
-    fs::write(cg.join("codegraph.json"), contents).expect("write codegraph.json");
+    let paths = IndexPaths::resolve(project, None).expect("resolve index paths");
+    fs::create_dir_all(paths.current_root()).expect("create current root");
+    fs::write(paths.extension_config(), contents).expect("write codegraph.json");
+}
+
+/// Load the project's overrides the way the pipeline does.
+fn overrides_for(project: &Path) -> Arc<ExtensionOverrides> {
+    let paths = IndexPaths::resolve(project, None).expect("resolve index paths");
+    ExtensionOverrides::load_for_paths(&paths)
 }
 
 /// (a) A custom extension with NO built-in/embedded mapping maps to the
@@ -43,7 +57,10 @@ fn custom_ext_maps_unknown_extension() {
     let file = project.join("foo.myext");
     fs::write(&file, "-- lua").unwrap();
 
-    assert_eq!(detect_language(&file), Language::Lua);
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&project)),
+        Language::Lua
+    );
 
     fs::remove_dir_all(&project).ok();
 }
@@ -53,10 +70,14 @@ fn custom_ext_maps_unknown_extension() {
 #[test]
 fn custom_ext_absent_config_is_unknown() {
     let project = unique_project("b");
-    // No .codegraph/codegraph.json at all.
+    // No current-root codegraph.json at all.
     let file = project.join("foo.myext");
     fs::write(&file, "whatever").unwrap();
 
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&project)),
+        Language::Unknown
+    );
     assert_eq!(detect_language(&file), Language::Unknown);
 
     fs::remove_dir_all(&project).ok();
@@ -71,6 +92,7 @@ fn custom_ext_hostile_remap_is_ignored_for_builtins() {
         &project,
         r#"{"extensions": {".ts": "lua", ".py": "go", ".rs": "python", ".go": "ruby"}}"#,
     );
+    let overrides = overrides_for(&project);
     let ts = project.join("x.ts");
     let py = project.join("a.py");
     let rs = project.join("lib.rs");
@@ -81,17 +103,25 @@ fn custom_ext_hostile_remap_is_ignored_for_builtins() {
     fs::write(&go, "package main").unwrap();
 
     assert_eq!(
-        detect_language(&ts),
+        detect_language_with(&ts, &overrides),
         Language::TypeScript,
         ".ts must stay TypeScript"
     );
     assert_eq!(
-        detect_language(&py),
+        detect_language_with(&py, &overrides),
         Language::Python,
         ".py must stay Python"
     );
-    assert_eq!(detect_language(&rs), Language::Rust, ".rs must stay Rust");
-    assert_eq!(detect_language(&go), Language::Go, ".go must stay Go");
+    assert_eq!(
+        detect_language_with(&rs, &overrides),
+        Language::Rust,
+        ".rs must stay Rust"
+    );
+    assert_eq!(
+        detect_language_with(&go, &overrides),
+        Language::Go,
+        ".go must stay Go"
+    );
 
     fs::remove_dir_all(&project).ok();
 }
@@ -102,18 +132,19 @@ fn custom_ext_hostile_remap_is_ignored_for_builtins() {
 fn custom_ext_hostile_remap_is_ignored_for_embedded() {
     let project = unique_project("emb");
     write_codegraph_json(&project, r#"{"extensions": {".vue": "lua", ".xml": "go"}}"#);
+    let overrides = overrides_for(&project);
     let vue = project.join("widget.vue");
     let xml = project.join("mapper.xml");
     fs::write(&vue, "<template></template>").unwrap();
     fs::write(&xml, "<x/>").unwrap();
 
     assert_eq!(
-        detect_language(&vue),
+        detect_language_with(&vue, &overrides),
         Language::Vue,
         ".vue stays Vue (embedded)"
     );
     assert_eq!(
-        detect_language(&xml),
+        detect_language_with(&xml, &overrides),
         Language::Xml,
         ".xml stays Xml (embedded)"
     );
@@ -121,25 +152,28 @@ fn custom_ext_hostile_remap_is_ignored_for_embedded() {
     fs::remove_dir_all(&project).ok();
 }
 
-/// (d) ADVERSARIAL — mtime recache: changing codegraph.json (new mtime) is
-/// picked up on the next detect_language call.
+/// (d) ADVERSARIAL — no cache to go stale: rewriting `codegraph.json` and
+/// reloading picks up the change immediately, with no mtime dependence (so a
+/// same-second edit is honored too).
 #[test]
-fn custom_ext_mtime_recache_picks_up_changes() {
+fn custom_ext_reload_picks_up_changes_immediately() {
     let project = unique_project("d");
     write_codegraph_json(&project, r#"{"extensions": {".zz": "lua"}}"#);
     let file = project.join("foo.zz");
     fs::write(&file, "x").unwrap();
 
-    assert_eq!(detect_language(&file), Language::Lua);
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&project)),
+        Language::Lua
+    );
 
-    // Ensure the mtime advances enough to be observable across filesystems.
-    std::thread::sleep(Duration::from_millis(1100));
+    // No sleep: the reader never caches, so the very next load sees the change.
     write_codegraph_json(&project, r#"{"extensions": {".zz": "go"}}"#);
 
     assert_eq!(
-        detect_language(&file),
+        detect_language_with(&file, &overrides_for(&project)),
         Language::Go,
-        "cache must re-read after mtime change"
+        "an explicit reload must observe the new config"
     );
 
     fs::remove_dir_all(&project).ok();
@@ -156,7 +190,10 @@ fn custom_ext_malformed_config_is_ignored() {
     fs::write(&file, "x").unwrap();
 
     // No panic; unmapped extension -> Unknown.
-    assert_eq!(detect_language(&file), Language::Unknown);
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&project)),
+        Language::Unknown
+    );
 
     // Unknown language string is skipped (warning), other valid entries still apply.
     let project2 = unique_project("e2");
@@ -164,17 +201,18 @@ fn custom_ext_malformed_config_is_ignored() {
         &project2,
         r#"{"extensions": {".aa": "not_a_language", ".bb": "lua"}}"#,
     );
+    let overrides2 = overrides_for(&project2);
     let aa = project2.join("f.aa");
     let bb = project2.join("f.bb");
     fs::write(&aa, "x").unwrap();
     fs::write(&bb, "x").unwrap();
     assert_eq!(
-        detect_language(&aa),
+        detect_language_with(&aa, &overrides2),
         Language::Unknown,
         "unknown lang skipped"
     );
     assert_eq!(
-        detect_language(&bb),
+        detect_language_with(&bb, &overrides2),
         Language::Lua,
         "valid entry still applies"
     );
@@ -182,3 +220,34 @@ fn custom_ext_malformed_config_is_ignored() {
     fs::remove_dir_all(&project).ok();
     fs::remove_dir_all(&project2).ok();
 }
+
+/// A LEGACY `.codegraph/codegraph.json` never supplies an override, and neither
+/// does another project's config.
+#[test]
+fn custom_ext_ignores_legacy_and_other_projects() {
+    let project = unique_project("legacy");
+    let other = unique_project("other");
+    fs::create_dir_all(project.join(".codegraph")).unwrap();
+    fs::write(
+        project.join(".codegraph/codegraph.json"),
+        r#"{"extensions": {".myext": "lua"}}"#,
+    )
+    .unwrap();
+    write_codegraph_json(&other, r#"{"extensions": {".myext": "go"}}"#);
+    let file = project.join("foo.myext");
+    fs::write(&file, "x").unwrap();
+
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&project)),
+        Language::Unknown,
+        "neither the legacy config nor another project's may apply"
+    );
+    assert_eq!(
+        detect_language_with(&file, &overrides_for(&other)),
+        Language::Go,
+        "the other project's own config applies to its own operations"
+    );
+
+    fs::remove_dir_all(&project).ok();
+    fs::remove_dir_all(&other).ok();
+}
diff --git a/crates/codegraph-mcp/src/engine.rs b/crates/codegraph-mcp/src/engine.rs
index 1c9b3be..2bd0173 100644
--- a/crates/codegraph-mcp/src/engine.rs
+++ b/crates/codegraph-mcp/src/engine.rs
@@ -9,8 +9,10 @@
 use std::collections::{HashMap, HashSet};
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 use std::time::{Duration, Instant};
 
+use codegraph_core::config::Config;
 use codegraph_core::types::{EdgeKind, FileRecord, Node, NodeKind};
 use codegraph_graph::graph::{GodotReach, GraphTraverser, NodeEdge};
 use codegraph_graph::query::{SearchOptions, search_nodes};
@@ -65,6 +67,11 @@ const SIG_EDGE_KINDS: [EdgeKind; 3] = [EdgeKind::References, EdgeKind::TypeOf, E
 pub struct CodeGraphEngine {
     store: Store,
     project_root: PathBuf,
+    /// The ADDRESSED project's own immutable config, loaded per request from its
+    /// resolved current index root. A server that answers for many projects (a
+    /// global HTTP process) therefore honors each project's own settings, and
+    /// nothing here reads a process-global value or a legacy `.codegraph` config.
+    config: Arc<Config>,
 }
 
 impl CodeGraphEngine {
@@ -80,14 +87,37 @@ impl CodeGraphEngine {
             project_root,
             std::env::var("CODEGRAPH_DIR").ok().as_deref(),
         )?;
+        let config = Config::load_for_paths(None, &paths)?;
         let store =
             Store::open_for_read(&paths, Instant::now() + Self::READ_LEASE_TIMEOUT, || false)?;
         Ok(Self {
             store,
             project_root: project_root.to_path_buf(),
+            config,
         })
     }
 
+    /// This project's own immutable configuration for the current request.
+    pub fn config(&self) -> &Config {
+        &self.config
+    }
+
+    /// Read an indexed file's on-disk source, refusing anything larger than THIS
+    /// project's `indexing.max_file_size`.
+    ///
+    /// Extraction skips a file over that limit, so its symbols are not in the
+    /// graph; serving its full text through a graph tool would contradict the
+    /// project's own size policy. `None` therefore means "unreadable or beyond
+    /// this project's limit", and every rendering path treats it exactly as it
+    /// already treats an unreadable file.
+    fn read_project_source(&self, abs: &Path) -> Option<String> {
+        let metadata = fs::metadata(abs).ok()?;
+        if metadata.len() > self.config.indexing.max_file_size {
+            return None;
+        }
+        fs::read_to_string(abs).ok()
+    }
+
     fn project_name_tokens(&self) -> HashSet<String> {
         HashSet::new()
     }
@@ -575,9 +605,9 @@ impl CodeGraphEngine {
         }
 
         let abs = self.project_root.join(&file_path);
-        let content = match fs::read_to_string(&abs) {
-            Ok(c) => c,
-            Err(_) => {
+        let content = match self.read_project_source(&abs) {
+            Some(c) => c,
+            None => {
                 let mut out = vec![
                     format!(
                         "**{file_path}** — could not read from disk (it may have moved since indexing). {dep_summary}"
@@ -740,9 +770,9 @@ impl CodeGraphEngine {
                 continue;
             }
             let abs = self.project_root.join(file_path);
-            let content = match fs::read_to_string(&abs) {
-                Ok(c) => c,
-                Err(_) => continue,
+            let content = match self.read_project_source(&abs) {
+                Some(c) => c,
+                None => continue,
             };
             let file_lines: Vec<&str> = content.split('\n').collect();
             let lang = subgraph.file_language(file_path);
@@ -1534,9 +1564,9 @@ impl CodeGraphEngine {
             }
             seen_node.insert(node.id.as_str());
             let abs = self.project_root.join(&node.file_path);
-            let content = match fs::read_to_string(&abs) {
-                Ok(c) => c,
-                Err(_) => continue,
+            let content = match self.read_project_source(&abs) {
+                Some(c) => c,
+                None => continue,
             };
             let file_lines: Vec<&str> = content.split('\n').collect();
             let start_idx = ((node.start_line - 1).max(0) as usize).min(file_lines.len());
@@ -1748,9 +1778,9 @@ impl CodeGraphEngine {
     /// out of the on-disk file (1-based inclusive).
     fn get_code(&self, node: &Node) -> anyhow::Result<Option<String>> {
         let abs = self.project_root.join(&node.file_path);
-        let content = match fs::read_to_string(&abs) {
-            Ok(c) => c,
-            Err(_) => return Ok(None),
+        let content = match self.read_project_source(&abs) {
+            Some(c) => c,
+            None => return Ok(None),
         };
         let lines: Vec<&str> = content.split('\n').collect();
         let start_idx = (node.start_line - 1).max(0) as usize;
@@ -2673,6 +2703,7 @@ mod tests {
         CodeGraphEngine {
             store,
             project_root: base,
+            config: Arc::new(Config::default()),
         }
     }
 
diff --git a/crates/codegraph-resolve/src/framework.rs b/crates/codegraph-resolve/src/framework.rs
index 9d4c59f..1da0059 100644
--- a/crates/codegraph-resolve/src/framework.rs
+++ b/crates/codegraph-resolve/src/framework.rs
@@ -23,8 +23,57 @@
 //! On a project where none are detected the orchestrator holds an empty list, so
 //! behavior is identical to the upstream with zero `FrameworkResolver`s detected.
 
+use crate::frameworks::godot_dsl_config::GodotDslConfig;
 use crate::types::{FrameworkResolverExtractionResult, RefView, ResolutionContext, ResolvedRef};
 use codegraph_core::types::Language;
+use std::sync::Arc;
+
+/// The per-project inputs a [`FrameworkResolver::extract`] pass may need beyond
+/// the file itself: the absolute project root, and the project's explicitly
+/// loaded framework configuration.
+///
+/// Project configuration is PASSED IN, never discovered: the pipeline loads it
+/// once from the addressed project's resolved current index root
+/// (`<current_root>/codegraph.json`) and hands the same immutable value to every
+/// file's extraction. No resolver walks the directory tree, reads a legacy
+/// `.codegraph/codegraph.json`, or caches config across projects, so one process
+/// serving several projects can never mix their configuration.
+#[derive(Debug, Clone)]
+pub struct FrameworkExtractionContext {
+    project_root: String,
+    godot_dsl: Arc<GodotDslConfig>,
+}
+
+impl FrameworkExtractionContext {
+    /// Build a context for `project_root` with the project's Godot DSL config.
+    #[must_use]
+    pub fn new(project_root: impl Into<String>, godot_dsl: Arc<GodotDslConfig>) -> Self {
+        Self {
+            project_root: project_root.into(),
+            godot_dsl,
+        }
+    }
+
+    /// Build a context for `project_root` with NO project configuration — the
+    /// off-by-default case (and what a caller that addresses no project uses).
+    #[must_use]
+    pub fn without_config(project_root: impl Into<String>) -> Self {
+        Self::new(project_root, GodotDslConfig::empty())
+    }
+
+    /// The absolute project root being indexed (may be empty for a caller that
+    /// supplies absolute file paths).
+    #[must_use]
+    pub fn project_root(&self) -> &str {
+        &self.project_root
+    }
+
+    /// The project's opt-in Godot DSL configuration (empty when it declares none).
+    #[must_use]
+    pub fn godot_dsl(&self) -> &GodotDslConfig {
+        &self.godot_dsl
+    }
+}
 
 /// A framework-specific resolution strategy (EXTENSION POINT).
 ///
@@ -64,18 +113,16 @@ pub trait FrameworkResolver: Sync {
     /// per-file extraction.
     ///
     /// `file_path` is the repo-RELATIVE path that MUST be used for all node /
-    /// reference attribution (preserving golden byte-stability). `project_root`
-    /// is the absolute project root the pipeline is indexing; resolvers that
-    /// read a per-project `.codegraph/codegraph.json` (e.g. Godot's opt-in DSL
-    /// config) MUST resolve that config against `project_root.join(file_path)`
-    /// rather than the process CWD — otherwise the config is only found when the
-    /// CLI happens to run with its CWD == the project root. Resolvers that need
-    /// no project config simply ignore `project_root`.
+    /// reference attribution (preserving golden byte-stability). `context`
+    /// carries the absolute project root plus the project's EXPLICITLY loaded
+    /// configuration (see [`FrameworkExtractionContext`]); a resolver that needs
+    /// per-project config reads it from there instead of discovering a file,
+    /// and one that needs none simply ignores it.
     fn extract(
         &self,
         _file_path: &str,
         _content: &str,
-        _project_root: &str,
+        _context: &FrameworkExtractionContext,
     ) -> Option<FrameworkResolverExtractionResult> {
         None
     }
@@ -196,7 +243,15 @@ mod tests {
     #[test]
     fn extract_default_is_none() {
         // The default `extract` returns None (no per-file extraction).
-        assert!(BareResolver.extract("a.ts", "content", "/root").is_none());
+        assert!(
+            BareResolver
+                .extract(
+                    "a.ts",
+                    "content",
+                    &FrameworkExtractionContext::without_config("/root")
+                )
+                .is_none()
+        );
     }
 
     #[test]
diff --git a/crates/codegraph-resolve/src/frameworks/godot.rs b/crates/codegraph-resolve/src/frameworks/godot.rs
index b2782f7..7dcd628 100644
--- a/crates/codegraph-resolve/src/frameworks/godot.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot.rs
@@ -237,8 +237,9 @@ impl FrameworkResolver for GodotResolver {
         &self,
         file_path: &str,
         content: &str,
-        project_root: &str,
+        context: &crate::framework::FrameworkExtractionContext,
     ) -> Option<FrameworkResolverExtractionResult> {
+        let project_root = context.project_root();
         if godot_project::is_project_godot(file_path) {
             return Some(godot_project::parse_project_godot(
                 file_path,
@@ -250,7 +251,11 @@ impl FrameworkResolver for GodotResolver {
             return Some(godot_scene::parse_tscn(file_path, content));
         }
         if godot_resource::is_tres(file_path) {
-            return Some(godot_resource::parse_tres(file_path, content, project_root));
+            return Some(godot_resource::parse_tres(
+                file_path,
+                content,
+                context.godot_dsl(),
+            ));
         }
         if godot_script::is_gdscript(file_path) {
             let mut result = godot_script::parse_gdscript_dynamics(file_path, content);
diff --git a/crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs b/crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs
index ceff110..993b6e6 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_dsl_config.rs
@@ -1,6 +1,7 @@
-//! OPT-IN DSL config reader for Godot `.tres` resource fields (L5 / T9).
+//! OPT-IN DSL config for Godot `.tres` resource fields (L5 / T9).
 //!
-//! Reads an OPTIONAL, OFF-by-default block from `.codegraph/codegraph.json`:
+//! Reads an OPTIONAL, OFF-by-default block from ONE project's current-root
+//! `codegraph.json` ([`IndexPaths::extension_config`]):
 //!
 //! ```jsonc
 //! { "godot": { "dsl": { "resourceFields": ["skill_effect", "effect_on"] } } }
@@ -25,30 +26,27 @@
 //! } } } }
 //! ```
 //!
-//! Same off-by-default + tolerant-parse + mtime-cache discipline as
-//! `resourceFields`. All field names / kinds / separators / segment indices are
-//! project-supplied; nothing is hardcoded. See [`dsl_id_fields`] and
-//! [`super::godot_resource`]'s `dsl_id_targets`.
+//! # Explicit, project-scoped, cache-free
 //!
-//! # Mirrors `codegraph_extract::ext_config`
+//! The config is loaded ONCE per operation from the addressed project's resolved
+//! current root and threaded into extraction as an immutable
+//! [`GodotDslConfig`]. Nothing here walks up the directory tree, consults the
+//! process working directory, reads a legacy `.codegraph/codegraph.json`, or
+//! caches across calls — so two projects handled by one process can never see
+//! each other's DSL fields and no mtime cache can go stale.
 //!
-//! The reading strategy is intentionally identical to the existing
-//! `.codegraph/codegraph.json` extension-override reader: walk up the directory
-//! tree from the file being parsed to find the nearest config, parse it with
-//! `serde` using `#[serde(default)]` at every level (so any missing key yields
-//! the empty list), tolerate a malformed file (logged + ignored, never panics),
-//! and mtime-cache the parsed result per config-file path — caching "absent"
-//! too, so a project with no `godot.dsl` block pays no repeated I/O.
+//! Parsing stays tolerant (`#[serde(default)]` at every level, a malformed file
+//! yielding the empty config), preserving the documented opt-in contract.
 
+use codegraph_core::IndexPaths;
 use serde::Deserialize;
-use std::collections::{BTreeMap, HashMap};
-use std::path::{Path, PathBuf};
-use std::sync::{Arc, Mutex, OnceLock};
-use std::time::SystemTime;
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::sync::Arc;
 
-/// Top-level `.codegraph/codegraph.json` shape — only the `godot` key matters
-/// here; other keys (e.g. `extensions`) are ignored. `#[serde(default)]` makes a
-/// file with no `godot` key parse to an empty config.
+/// Top-level `codegraph.json` shape — only the `godot` key matters here; other
+/// keys (e.g. `extensions`) are ignored. `#[serde(default)]` makes a file with no
+/// `godot` key parse to an empty config.
 #[derive(Debug, Default, Deserialize)]
 struct CodegraphJson {
     #[serde(default)]
@@ -59,13 +57,12 @@ struct CodegraphJson {
 #[derive(Debug, Default, Deserialize)]
 struct GodotConfig {
     #[serde(default)]
-    dsl: GodotDslConfig,
+    dsl: GodotDslConfigFile,
 }
 
-/// The `godot.dsl` block. `resourceFields` lists the `.tres` `[resource]`
-/// property names that should emit a reference edge from their value.
+/// The raw `godot.dsl` block as it appears on disk.
 #[derive(Debug, Default, Deserialize)]
-struct GodotDslConfig {
+struct GodotDslConfigFile {
     #[serde(default, rename = "resourceFields")]
     resource_fields: Vec<String>,
     #[serde(default, rename = "idFields")]
@@ -77,7 +74,7 @@ struct GodotDslConfig {
 ///
 /// `separator` + `id_segments` together select compound parts; with neither, the
 /// whole quote-stripped value is the single ID. All fields are project-supplied.
-#[derive(Debug, Default, Clone, Deserialize)]
+#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize)]
 pub struct IdFieldSpec {
     #[serde(default)]
     pub kind: String,
@@ -87,211 +84,167 @@ pub struct IdFieldSpec {
     pub id_segments: Option<Vec<usize>>,
 }
 
-/// The cached, parsed DSL field list for one config-file path.
-type DslFields = Vec<String>;
-
-#[derive(Clone)]
-enum CacheEntry {
-    Absent,
-    Present {
-        mtime: SystemTime,
-        fields: Arc<DslFields>,
-    },
-}
-
-fn cache() -> &'static Mutex<HashMap<PathBuf, CacheEntry>> {
-    static CACHE: OnceLock<Mutex<HashMap<PathBuf, CacheEntry>>> = OnceLock::new();
-    CACHE.get_or_init(|| Mutex::new(HashMap::new()))
+/// One project's parsed, immutable Godot DSL configuration: the `resourceFields`
+/// list and the `idFields` spec map. Both empty for a project that declares none
+/// (the off-by-default case).
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub struct GodotDslConfig {
+    resource_fields: Vec<String>,
+    id_fields: BTreeMap<String, IdFieldSpec>,
 }
 
-/// The configured DSL resource-field names for the `.tres` at `path`, resolving
-/// the nearest `.codegraph/codegraph.json` walking up from `path`. Returns an
-/// EMPTY list when no config is reachable, the file is malformed, or no
-/// `godot.dsl.resourceFields` block is present — i.e. the off-by-default case
-/// yields no DSL behavior.
-pub(crate) fn dsl_resource_fields(path: &Path) -> Arc<DslFields> {
-    let Some(config_path) = find_config_path(path) else {
-        return Arc::new(Vec::new());
-    };
-    load_cached(&config_path)
-}
+impl GodotDslConfig {
+    /// The empty config — no DSL resource fields, no ID fields.
+    #[must_use]
+    pub fn empty() -> Arc<Self> {
+        Arc::new(Self::default())
+    }
 
-/// Walk up from `path` to the nearest `.codegraph/codegraph.json`. The starting
-/// directory is the file's own parent. `path` is expected to be ABSOLUTE — the
-/// pipeline resolves the `.tres` against the project root before calling
-/// (`godot_resource::config_lookup_path`), and the unit tests pass absolute
-/// paths. A relative `path` is still tolerated (joined onto the CWD, matching
-/// `ext_config::find_config_path`), but the pipeline never relies on that CWD
-/// join: doing so silently mislocated the config whenever the CLI ran with its
-/// CWD != the project root, which is the bug this resolution was hardened
-/// against.
-fn find_config_path(file_path: &Path) -> Option<PathBuf> {
-    let start = if file_path.is_absolute() {
-        file_path.parent().map(Path::to_path_buf)
-    } else {
-        std::env::current_dir()
-            .ok()
-            .map(|cwd| cwd.join(file_path))
-            .and_then(|abs| abs.parent().map(Path::to_path_buf))
-    }?;
-    let mut dir: Option<&Path> = Some(start.as_path());
-    while let Some(current) = dir {
-        let candidate = current.join(".codegraph").join("codegraph.json");
-        if candidate.is_file() {
-            return Some(candidate);
-        }
-        dir = current.parent();
+    /// Load the DSL config declared by ONE project's current index root
+    /// (`<current_root>/codegraph.json`). A missing, unreadable, or malformed
+    /// file yields the empty config.
+    #[must_use]
+    pub fn load_for_paths(paths: &IndexPaths) -> Arc<Self> {
+        Self::load_from_file(&paths.extension_config())
     }
-    None
-}
 
-/// Return the cached DSL field list for `config_path`, re-parsing when the
-/// file's mtime changed. Mirrors `ext_config::load_cached`; "absent" (unreadable
-/// file) is cached as an empty list so it is not re-read.
-fn load_cached(config_path: &Path) -> Arc<DslFields> {
-    let current_mtime = std::fs::metadata(config_path)
-        .and_then(|m| m.modified())
-        .ok();
-    let mut guard = cache().lock().unwrap_or_else(|p| p.into_inner());
+    /// Load from an explicit `codegraph.json` path, with the same tolerance as
+    /// [`Self::load_for_paths`].
+    #[must_use]
+    pub fn load_from_file(config_path: &Path) -> Arc<Self> {
+        let Ok(contents) = std::fs::read_to_string(config_path) else {
+            return Self::empty();
+        };
+        Arc::new(Self::parse(&contents))
+    }
 
-    if let Some(entry) = guard.get(config_path) {
-        match (entry, current_mtime) {
-            (CacheEntry::Present { mtime, fields }, Some(now)) if *mtime == now => {
-                return Arc::clone(fields);
-            }
-            (CacheEntry::Absent, None) => return Arc::new(Vec::new()),
-            _ => {}
+    /// Parse the `godot.dsl` block out of `contents`, tolerating any parse
+    /// failure as the empty config. Field names are trimmed; empty names are
+    /// dropped, and an `idFields` entry needs a non-empty key AND kind.
+    #[must_use]
+    pub fn parse(contents: &str) -> Self {
+        // A malformed config is swallowed silently (not logged):
+        // `codegraph-resolve` has no logging dependency, and the no-new-dep
+        // posture forbids adding one.
+        let Ok(parsed) = serde_json::from_str::<CodegraphJson>(contents) else {
+            return Self::default();
+        };
+        let resource_fields = parsed
+            .godot
+            .dsl
+            .resource_fields
+            .into_iter()
+            .map(|field| field.trim().to_string())
+            .filter(|field| !field.is_empty())
+            .collect();
+        let id_fields = parsed
+            .godot
+            .dsl
+            .id_fields
+            .into_iter()
+            .map(|(key, spec)| (key.trim().to_string(), spec))
+            .filter(|(key, spec)| !key.is_empty() && !spec.kind.trim().is_empty())
+            .collect();
+        Self {
+            resource_fields,
+            id_fields,
         }
     }
 
-    let Some(mtime) = current_mtime else {
-        guard.insert(config_path.to_path_buf(), CacheEntry::Absent);
-        return Arc::new(Vec::new());
-    };
-
-    let fields = Arc::new(parse_config(config_path));
-    guard.insert(
-        config_path.to_path_buf(),
-        CacheEntry::Present {
-            mtime,
-            fields: Arc::clone(&fields),
-        },
-    );
-    fields
-}
-
-/// Parse `godot.dsl.resourceFields` out of the config file, tolerating any
-/// read/parse failure as an empty list (logged). Field names are trimmed; empty
-/// names are dropped. Mirrors `ext_config::parse_config`'s tolerance.
-fn parse_config(config_path: &Path) -> DslFields {
-    let Ok(contents) = std::fs::read_to_string(config_path) else {
-        return Vec::new();
-    };
-    // Malformed config is swallowed silently (not logged): `codegraph-resolve`
-    // has no logging dependency, and the no-new-dep posture forbids adding one.
-    let Ok(parsed) = serde_json::from_str::<CodegraphJson>(&contents) else {
-        return Vec::new();
-    };
-
-    parsed
-        .godot
-        .dsl
-        .resource_fields
-        .into_iter()
-        .map(|f| f.trim().to_string())
-        .filter(|f| !f.is_empty())
-        .collect()
-}
-
-// ---------------------------------------------------------------------------
-// `idFields` reader — a second, independent opt-in block (PR2). Same shape as
-// the `resourceFields` reader above: tree-walk find_config_path + mtime cache +
-// tolerant parse + "absent" caching, kept separate so `resourceFields` behavior
-// is provably untouched.
-// ---------------------------------------------------------------------------
-
-/// The cached, parsed `idFields` spec map for one config-file path.
-type IdFields = BTreeMap<String, IdFieldSpec>;
-
-#[derive(Clone)]
-enum IdCacheEntry {
-    Absent,
-    Present {
-        mtime: SystemTime,
-        fields: Arc<IdFields>,
-    },
-}
+    /// `true` when the project declared neither `resourceFields` nor `idFields`.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.resource_fields.is_empty() && self.id_fields.is_empty()
+    }
 
-fn id_cache() -> &'static Mutex<HashMap<PathBuf, IdCacheEntry>> {
-    static CACHE: OnceLock<Mutex<HashMap<PathBuf, IdCacheEntry>>> = OnceLock::new();
-    CACHE.get_or_init(|| Mutex::new(HashMap::new()))
-}
+    /// The configured `.tres` `[resource]` property names whose value becomes a
+    /// reference target, in declaration order.
+    #[must_use]
+    pub fn resource_fields(&self) -> &[String] {
+        &self.resource_fields
+    }
 
-/// The configured `idFields` spec map for the `.tres` at `path`, resolving the
-/// nearest `.codegraph/codegraph.json` walking up from `path`. Returns an EMPTY
-/// map when no config is reachable, the file is malformed, or no
-/// `godot.dsl.idFields` block is present — the off-by-default case yields no ID
-/// behavior.
-pub(crate) fn dsl_id_fields(path: &Path) -> Arc<IdFields> {
-    let Some(config_path) = find_config_path(path) else {
-        return Arc::new(BTreeMap::new());
-    };
-    load_cached_id(&config_path)
+    /// The configured `idFields` spec map, keyed by property name.
+    #[must_use]
+    pub fn id_fields(&self) -> &BTreeMap<String, IdFieldSpec> {
+        &self.id_fields
+    }
 }
 
-/// Return the cached `idFields` map for `config_path`, re-parsing when the
-/// file's mtime changed. Mirrors [`load_cached`]; "absent" is cached as an empty
-/// map so it is not re-read.
-fn load_cached_id(config_path: &Path) -> Arc<IdFields> {
-    let current_mtime = std::fs::metadata(config_path)
-        .and_then(|m| m.modified())
-        .ok();
-    let mut guard = id_cache().lock().unwrap_or_else(|p| p.into_inner());
-
-    if let Some(entry) = guard.get(config_path) {
-        match (entry, current_mtime) {
-            (IdCacheEntry::Present { mtime, fields }, Some(now)) if *mtime == now => {
-                return Arc::clone(fields);
-            }
-            (IdCacheEntry::Absent, None) => return Arc::new(BTreeMap::new()),
-            _ => {}
-        }
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_resource_and_id_fields() {
+        let config = GodotDslConfig::parse(
+            r#"{"godot":{"dsl":{"resourceFields":[" skill_effect ",""],
+               "idFields":{"buff_id":{"kind":"buff"},
+                           " skill ":{"kind":"skill","separator":":","idSegments":[0,2]},
+                           "bad":{"kind":"  "}}}}}"#,
+        );
+        assert_eq!(config.resource_fields(), ["skill_effect"]);
+        let ids = config.id_fields();
+        assert_eq!(ids.len(), 2, "empty-kind entries are dropped: {ids:?}");
+        assert_eq!(ids["buff_id"].kind, "buff");
+        assert_eq!(ids["skill"].separator.as_deref(), Some(":"));
+        assert_eq!(ids["skill"].id_segments.as_deref(), Some([0, 2].as_slice()));
     }
 
-    let Some(mtime) = current_mtime else {
-        guard.insert(config_path.to_path_buf(), IdCacheEntry::Absent);
-        return Arc::new(BTreeMap::new());
-    };
-
-    let fields = Arc::new(parse_id_config(config_path));
-    guard.insert(
-        config_path.to_path_buf(),
-        IdCacheEntry::Present {
-            mtime,
-            fields: Arc::clone(&fields),
-        },
-    );
-    fields
-}
+    #[test]
+    fn absent_block_and_malformed_json_are_empty() {
+        assert!(GodotDslConfig::parse(r#"{"extensions":{".zz":"lua"}}"#).is_empty());
+        assert!(GodotDslConfig::parse("{ not json ").is_empty());
+        assert!(GodotDslConfig::default().is_empty());
+    }
 
-/// Parse `godot.dsl.idFields` out of the config file, tolerating any read/parse
-/// failure as an empty map. Entry keys are trimmed; entries with an empty key or
-/// empty `kind` are dropped (a sentinel needs a non-empty key + kind). Mirrors
-/// [`parse_config`]'s tolerance.
-fn parse_id_config(config_path: &Path) -> IdFields {
-    let Ok(contents) = std::fs::read_to_string(config_path) else {
-        return BTreeMap::new();
-    };
-    let Ok(parsed) = serde_json::from_str::<CodegraphJson>(&contents) else {
-        return BTreeMap::new();
-    };
+    /// The reader consults ONLY the current-root config path; a legacy
+    /// `.codegraph/codegraph.json` beside it is never adopted.
+    #[test]
+    fn load_for_paths_reads_only_the_current_root_config() {
+        let project = std::env::temp_dir().join(format!(
+            "codegraph-godot-dsl-scoped-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(project.join(".codegraph")).unwrap();
+        std::fs::write(
+            project.join(".codegraph/codegraph.json"),
+            r#"{"godot":{"dsl":{"resourceFields":["legacy_field"]}}}"#,
+        )
+        .unwrap();
+        let paths = IndexPaths::resolve(&project, None).expect("resolve paths");
+        std::fs::create_dir_all(paths.current_root()).unwrap();
+        std::fs::write(
+            paths.extension_config(),
+            r#"{"godot":{"dsl":{"resourceFields":["current_field"]}}}"#,
+        )
+        .unwrap();
+
+        let config = GodotDslConfig::load_for_paths(&paths);
+        assert_eq!(config.resource_fields(), ["current_field"]);
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
 
-    parsed
-        .godot
-        .dsl
-        .id_fields
-        .into_iter()
-        .map(|(k, spec)| (k.trim().to_string(), spec))
-        .filter(|(k, spec)| !k.is_empty() && !spec.kind.trim().is_empty())
-        .collect()
+    #[test]
+    fn missing_current_root_config_is_empty() {
+        let project = std::env::temp_dir().join(format!(
+            "codegraph-godot-dsl-absent-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&project).unwrap();
+        let paths = IndexPaths::resolve(&project, None).expect("resolve paths");
+
+        assert!(GodotDslConfig::load_for_paths(&paths).is_empty());
+
+        let _ = std::fs::remove_dir_all(&project);
+    }
 }
diff --git a/crates/codegraph-resolve/src/frameworks/godot_resource.rs b/crates/codegraph-resolve/src/frameworks/godot_resource.rs
index b604b1e..64d3fed 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_resource.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_resource.rs
@@ -63,14 +63,13 @@
 //! (only the text `.tres`).
 
 use std::collections::{BTreeMap, HashMap};
-use std::path::{Path, PathBuf};
 
 use codegraph_core::node_id::generate_node_id;
 use codegraph_core::types::{EdgeKind, Language, Node, NodeKind, ReferenceSubkind};
 
 use super::framework_node;
 use super::godot_common::{map_res_path, quoted_strings, strip_quotes};
-use super::godot_dsl_config::{IdFieldSpec, dsl_id_fields, dsl_resource_fields};
+use super::godot_dsl_config::{GodotDslConfig, IdFieldSpec};
 use crate::types::{FrameworkResolverExtractionResult, RefView};
 
 /// The marker-node name used when a `.tres` has no `[gd_resource type="..."]`.
@@ -86,21 +85,6 @@ pub(crate) fn is_tres(file_path: &str) -> bool {
         .is_some_and(|base| base.ends_with(".tres"))
 }
 
-/// The path the DSL config reader walks up from. An absolute `file_path` is used
-/// as-is (test callers pass absolute paths; `find_config_path` walks from its
-/// parent). A relative `file_path` (the pipeline's repo-relative path) is joined
-/// onto `project_root` so the walk starts at the file's real on-disk location —
-/// independent of the process CWD. An empty `project_root` falls back to the
-/// `file_path` verbatim (the pre-fix behavior, for callers that supply none).
-fn config_lookup_path(file_path: &str, project_root: &str) -> PathBuf {
-    let p = Path::new(file_path);
-    if p.is_absolute() || project_root.is_empty() {
-        p.to_path_buf()
-    } else {
-        Path::new(project_root).join(file_path)
-    }
-}
-
 /// Parse a `.tres` resource into a resource marker node + its script/resource
 /// references.
 ///
@@ -111,31 +95,25 @@ fn config_lookup_path(file_path: &str, project_root: &str) -> PathBuf {
 pub(crate) fn parse_tres(
     file_path: &str,
     content: &str,
-    project_root: &str,
+    dsl: &GodotDslConfig,
 ) -> FrameworkResolverExtractionResult {
     let mut nodes: Vec<Node> = Vec::new();
     let mut references: Vec<RefView> = Vec::new();
 
-    // The DSL config is resolved against the project root, NOT `file_path`'s
-    // CWD-relative join: the pipeline passes a repo-RELATIVE `file_path` (used
-    // verbatim for golden-stable node/ref attribution below), so config lookup
-    // walks up from the file's ABSOLUTE location (`project_root` + `file_path`).
-    // A `file_path` that is already absolute is used as-is. This keeps
-    // attribution relative while letting `find_config_path` find the project's
-    // `.codegraph/codegraph.json` regardless of the process CWD.
-    let config_lookup_path = config_lookup_path(file_path, project_root);
-
     // OPT-IN DSL fields (T9): the `godot.dsl.resourceFields` list from the
-    // nearest `.codegraph/codegraph.json` (empty when absent — the off-by-default
-    // case, so zero DSL behavior). A `key = value` line whose key is in this list
-    // emits a reference to its value (string literal → the literal text).
-    let dsl_fields = dsl_resource_fields(&config_lookup_path);
-
-    // OPT-IN ID fields (PR2): the `godot.dsl.idFields` spec map from the same
-    // nearest config (empty when absent — off-by-default). A `key = value` line
+    // addressed project's EXPLICITLY loaded current-root `codegraph.json` (empty
+    // when it declares none — the off-by-default case, so zero DSL behavior). A
+    // `key = value` line whose key is in this list emits a reference to its value
+    // (string literal → the literal text). The config arrives as a parameter, so
+    // `file_path` stays purely an attribution path and no directory walk or
+    // process-CWD lookup can mislocate it.
+    let dsl_fields = dsl.resource_fields();
+
+    // OPT-IN ID fields (PR2): the `godot.dsl.idFields` spec map from the SAME
+    // project config (empty when absent — off-by-default). A `key = value` line
     // whose key is a spec key emits one `godot:id:<kind>:<value>` sentinel per
     // selected segment. Independent of `dsl_fields`: a line may match both.
-    let id_fields = dsl_id_fields(&config_lookup_path);
+    let id_fields = dsl.id_fields();
 
     // In-file ext_resource lookup: id → repo-relative path. Built top-down as
     // the file is scanned (Godot declares ext_resources before `[resource]`),
@@ -189,7 +167,7 @@ pub(crate) fn parse_tres(
         // values fall through to the opt-in DSL check.
         let target = match resolve_ext_resource(value, &ext_resources) {
             Some(resolved) => Some(resolved),
-            None => dsl_literal_target(key, value, &dsl_fields),
+            None => dsl_literal_target(key, value, dsl_fields),
         };
         if let Some(target) = target {
             let from = marker_id(&mut marker, &mut nodes, file_path, line_no, &resource_type);
@@ -198,7 +176,7 @@ pub(crate) fn parse_tres(
         // The opt-in PR2 ID edges: one `godot:id:<kind>:<value>` sentinel per
         // configured segment, emitted AFTER the standard edge so a line that
         // matches both keeps source-line order. Empty when `id_fields` is empty.
-        for sentinel in dsl_id_targets(key, value, &id_fields) {
+        for sentinel in dsl_id_targets(key, value, id_fields) {
             let from = marker_id(&mut marker, &mut nodes, file_path, line_no, &resource_type);
             references.push(reference(from, sentinel, line_no, file_path));
         }
diff --git a/crates/codegraph-resolve/src/frameworks/mod.rs b/crates/codegraph-resolve/src/frameworks/mod.rs
index 8108367..4e71be0 100644
--- a/crates/codegraph-resolve/src/frameworks/mod.rs
+++ b/crates/codegraph-resolve/src/frameworks/mod.rs
@@ -12,7 +12,7 @@
 
 pub mod godot;
 pub(crate) mod godot_common;
-pub(crate) mod godot_dsl_config;
+pub mod godot_dsl_config;
 pub(crate) mod godot_project;
 pub(crate) mod godot_resource;
 pub(crate) mod godot_scene;
diff --git a/crates/codegraph-resolve/src/frameworks/nestjs.rs b/crates/codegraph-resolve/src/frameworks/nestjs.rs
index c61dd4e..53a0b1a 100644
--- a/crates/codegraph-resolve/src/frameworks/nestjs.rs
+++ b/crates/codegraph-resolve/src/frameworks/nestjs.rs
@@ -103,7 +103,7 @@ impl FrameworkResolver for NestjsResolver {
         &self,
         file_path: &str,
         content: &str,
-        _project_root: &str,
+        _context: &crate::framework::FrameworkExtractionContext,
     ) -> Option<FrameworkResolverExtractionResult> {
         if !nestjs_file_ext_regex().is_match(file_path) {
             return Some(FrameworkResolverExtractionResult::default());
@@ -1046,6 +1046,11 @@ fn module_file_regex() -> &'static Regex {
 
 #[cfg(test)]
 mod tests {
+    /// Extraction context for a resolver that needs no project config.
+    fn test_extraction_context() -> crate::framework::FrameworkExtractionContext {
+        crate::framework::FrameworkExtractionContext::without_config("")
+    }
+
     use super::*;
     use crate::types::ImportMapping;
     use std::collections::HashMap;
@@ -1357,7 +1362,7 @@ mod tests {
     #[test]
     fn extract_non_nest_extension_returns_default() {
         let result = NestjsResolver
-            .extract("src/styles.css", "body{}", "")
+            .extract("src/styles.css", "body{}", &test_extraction_context())
             .expect("extract");
         assert!(result.nodes.is_empty() && result.references.is_empty());
     }
@@ -1366,7 +1371,7 @@ mod tests {
     fn extract_graphql_query_inside_resolver() {
         let content = "@Resolver()\nclass UsersResolver {\n  @Query()\n  users() {}\n}";
         let result = NestjsResolver
-            .extract("src/users.resolver.ts", content, "")
+            .extract("src/users.resolver.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1381,7 +1386,7 @@ mod tests {
         // @Query not inside an @Resolver class -> ignored.
         let content = "class Plain {\n  @Query()\n  q() {}\n}";
         let result = NestjsResolver
-            .extract("src/x.resolver.ts", content, "")
+            .extract("src/x.resolver.ts", content, &test_extraction_context())
             .expect("extract");
         assert!(!result.nodes.iter().any(|n| n.kind == NodeKind::Route));
     }
@@ -1390,7 +1395,7 @@ mod tests {
     fn extract_microservice_message_and_event_patterns() {
         let content = "class H {\n  @MessagePattern('cmd')\n  handle() {}\n  @EventPattern('evt')\n  onEvt() {}\n}";
         let result = NestjsResolver
-            .extract("src/h.controller.ts", content, "")
+            .extract("src/h.controller.ts", content, &test_extraction_context())
             .expect("extract");
         let names: Vec<&str> = result
             .nodes
@@ -1413,7 +1418,7 @@ mod tests {
         // No string arg -> the handler name is used as the path.
         let content = "class H {\n  @MessagePattern()\n  doThing() {}\n}";
         let result = NestjsResolver
-            .extract("src/h.controller.ts", content, "")
+            .extract("src/h.controller.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1427,7 +1432,7 @@ mod tests {
     fn extract_websocket_handler_with_gateway_namespace() {
         let content = "@WebSocketGateway({ namespace: 'chat' })\nclass ChatGw {\n  @SubscribeMessage('msg')\n  onMsg() {}\n}";
         let result = NestjsResolver
-            .extract("src/chat.gateway.ts", content, "")
+            .extract("src/chat.gateway.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1447,7 +1452,7 @@ mod tests {
     fn extract_websocket_without_namespace_uses_event() {
         let content = "class Gw {\n  @SubscribeMessage('ping')\n  onPing() {}\n}";
         let result = NestjsResolver
-            .extract("src/x.gateway.ts", content, "")
+            .extract("src/x.gateway.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1462,7 +1467,7 @@ mod tests {
         // @Get outside any controller class -> prefix is empty.
         let content = "@Get('bare')\nfunction f() {}";
         let result = NestjsResolver
-            .extract("src/x.controller.ts", content, "")
+            .extract("src/x.controller.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1638,7 +1643,11 @@ mod tests {
         // A `.controller.js` routes through the JavaScript comment-strip branch.
         let content = "@Controller('items')\nclass ItemsController {\n  @Get()\n  list() {}\n}";
         let result = NestjsResolver
-            .extract("src/items.controller.js", content, "")
+            .extract(
+                "src/items.controller.js",
+                content,
+                &test_extraction_context(),
+            )
             .expect("extract");
         let route = result
             .nodes
@@ -1654,7 +1663,11 @@ mod tests {
         // `@Controller({ path: 'admin' })` prefix joins onto the method path.
         let content = "@Controller({ path: 'admin' })\nclass AdminController {\n  @Get('users')\n  list() {}\n}";
         let result = NestjsResolver
-            .extract("src/admin.controller.ts", content, "")
+            .extract(
+                "src/admin.controller.ts",
+                content,
+                &test_extraction_context(),
+            )
             .expect("extract");
         let route = result
             .nodes
@@ -1670,7 +1683,7 @@ mod tests {
         // the explicit `name` field, not the handler.
         let content = "@Resolver()\nclass R {\n  @Query({ name: 'allUsers' })\n  fetch() {}\n}";
         let result = NestjsResolver
-            .extract("src/r.resolver.ts", content, "")
+            .extract("src/r.resolver.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1685,7 +1698,7 @@ mod tests {
         // `@Mutation('doThing')` inside a resolver names by the leading string.
         let content = "@Resolver()\nclass R {\n  @Mutation('doThing')\n  run() {}\n}";
         let result = NestjsResolver
-            .extract("src/r.resolver.ts", content, "")
+            .extract("src/r.resolver.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1700,7 +1713,7 @@ mod tests {
         // `@EventPattern()` with no string arg → path is the handler name.
         let content = "class H {\n  @EventPattern()\n  onEvt() {}\n}";
         let result = NestjsResolver
-            .extract("src/h.controller.ts", content, "")
+            .extract("src/h.controller.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1716,7 +1729,7 @@ mod tests {
         // name → empty event, empty namespace → "WS ".
         let content = "class Gw {\n  @SubscribeMessage()\n}";
         let result = NestjsResolver
-            .extract("src/x.gateway.ts", content, "")
+            .extract("src/x.gateway.ts", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
diff --git a/crates/codegraph-resolve/src/frameworks/react.rs b/crates/codegraph-resolve/src/frameworks/react.rs
index 7131a3e..10f1f70 100644
--- a/crates/codegraph-resolve/src/frameworks/react.rs
+++ b/crates/codegraph-resolve/src/frameworks/react.rs
@@ -78,7 +78,7 @@ impl FrameworkResolver for ReactResolver {
         &self,
         file_path: &str,
         content: &str,
-        _project_root: &str,
+        _context: &crate::framework::FrameworkExtractionContext,
     ) -> Option<FrameworkResolverExtractionResult> {
         let mut nodes = Vec::new();
         let mut references = Vec::new();
@@ -651,6 +651,11 @@ fn page_ext_strip_regex() -> &'static Regex {
 
 #[cfg(test)]
 mod tests {
+    /// Extraction context for a resolver that needs no project config.
+    fn test_extraction_context() -> crate::framework::FrameworkExtractionContext {
+        crate::framework::FrameworkExtractionContext::without_config("")
+    }
+
     use super::*;
     use crate::types::ImportMapping;
     use codegraph_core::types::Node;
@@ -1030,7 +1035,7 @@ mod tests {
     fn extract_arrow_component_with_jsx() {
         let content = "export const Card = () => { return <div/>; };";
         let result = ReactResolver
-            .extract("src/Card.jsx", content, "")
+            .extract("src/Card.jsx", content, &test_extraction_context())
             .expect("extract");
         assert!(
             result
@@ -1048,7 +1053,7 @@ mod tests {
         content.push('é');
 
         let result = ReactResolver
-            .extract("src/Card.tsx", &content, "")
+            .extract("src/Card.tsx", &content, &test_extraction_context())
             .expect("extract");
 
         assert!(
@@ -1064,7 +1069,7 @@ mod tests {
         // A PascalCase function that returns no JSX must NOT be a component node.
         let content = "export function Helper() { return 42; }";
         let result = ReactResolver
-            .extract("src/Helper.tsx", content, "")
+            .extract("src/Helper.tsx", content, &test_extraction_context())
             .expect("extract");
         assert!(!result.nodes.iter().any(|n| n.kind == NodeKind::Component));
     }
@@ -1074,7 +1079,7 @@ mod tests {
         let content =
             "const Fancy = React.forwardRef(() => <div/>);\nconst Wrapped = memo(() => <span/>);";
         let result = ReactResolver
-            .extract("src/W.tsx", content, "")
+            .extract("src/W.tsx", content, &test_extraction_context())
             .expect("extract");
         let names: Vec<&str> = result
             .nodes
@@ -1090,7 +1095,7 @@ mod tests {
     fn extract_custom_hook_node() {
         let content = "export function useCounter() { return 0; }";
         let result = ReactResolver
-            .extract("src/useCounter.ts", content, "")
+            .extract("src/useCounter.ts", content, &test_extraction_context())
             .expect("extract");
         let hook = result
             .nodes
@@ -1106,7 +1111,7 @@ mod tests {
     fn extract_hook_js_language_for_plain_js() {
         let content = "const useX = () => 1;";
         let result = ReactResolver
-            .extract("src/useX.js", content, "")
+            .extract("src/useX.js", content, &test_extraction_context())
             .expect("extract");
         let hook = result
             .nodes
@@ -1121,7 +1126,7 @@ mod tests {
         // <Route ... element={<Home/>}/> uses the element attr branch.
         let content = "<Route path=\"/x\" element={<Home/>}/>";
         let result = ReactResolver
-            .extract("src/App.tsx", content, "")
+            .extract("src/App.tsx", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1139,7 +1144,7 @@ mod tests {
         content.push('é');
 
         let result = ReactResolver
-            .extract("src/App.tsx", &content, "")
+            .extract("src/App.tsx", &content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1155,7 +1160,7 @@ mod tests {
     fn extract_route_without_path_is_skipped() {
         let content = "<Route element={<Home/>}/>";
         let result = ReactResolver
-            .extract("src/App.tsx", content, "")
+            .extract("src/App.tsx", content, &test_extraction_context())
             .expect("extract");
         assert!(!result.nodes.iter().any(|n| n.kind == NodeKind::Route));
     }
@@ -1165,7 +1170,7 @@ mod tests {
         let content =
             "const r = createBrowserRouter([\n  { path: '/dash', element: <Dashboard/> },\n]);";
         let result = ReactResolver
-            .extract("src/routes.tsx", content, "")
+            .extract("src/routes.tsx", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1191,7 +1196,7 @@ mod tests {
         content.push('é');
 
         let result = ReactResolver
-            .extract("src/routes.tsx", &content, "")
+            .extract("src/routes.tsx", &content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1207,7 +1212,7 @@ mod tests {
     fn extract_data_router_empty_path_becomes_root() {
         let content = "createBrowserRouter([{ path: '', Component: Index }]);";
         let result = ReactResolver
-            .extract("src/routes.tsx", content, "")
+            .extract("src/routes.tsx", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1221,7 +1226,7 @@ mod tests {
     fn extract_data_router_path_without_component_skipped() {
         let content = "createBrowserRouter([{ path: '/only' }]);";
         let result = ReactResolver
-            .extract("src/routes.tsx", content, "")
+            .extract("src/routes.tsx", content, &test_extraction_context())
             .expect("extract");
         assert!(!result.nodes.iter().any(|n| n.kind == NodeKind::Route));
     }
@@ -1230,7 +1235,7 @@ mod tests {
     fn extract_nextjs_app_page_route() {
         let content = "export default function Page() { return <div/>; }";
         let result = ReactResolver
-            .extract("app/blog/page.tsx", content, "")
+            .extract("app/blog/page.tsx", content, &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -1244,7 +1249,7 @@ mod tests {
     fn extract_nextjs_without_export_default_no_route() {
         let content = "export function NotDefault() { return <div/>; }";
         let result = ReactResolver
-            .extract("pages/x.tsx", content, "")
+            .extract("pages/x.tsx", content, &test_extraction_context())
             .expect("extract");
         assert!(!result.nodes.iter().any(|n| n.kind == NodeKind::Route));
     }
diff --git a/crates/codegraph-resolve/src/frameworks/vue.rs b/crates/codegraph-resolve/src/frameworks/vue.rs
index 5fa1599..e411082 100644
--- a/crates/codegraph-resolve/src/frameworks/vue.rs
+++ b/crates/codegraph-resolve/src/frameworks/vue.rs
@@ -134,7 +134,7 @@ impl FrameworkResolver for VueResolver {
         &self,
         file_path: &str,
         _content: &str,
-        _project_root: &str,
+        _context: &crate::framework::FrameworkExtractionContext,
     ) -> Option<FrameworkResolverExtractionResult> {
         let mut nodes = Vec::new();
         let normalized = file_path.replace('\\', "/");
@@ -382,6 +382,11 @@ fn param_regex() -> &'static Regex {
 
 #[cfg(test)]
 mod tests {
+    /// Extraction context for a resolver that needs no project config.
+    fn test_extraction_context() -> crate::framework::FrameworkExtractionContext {
+        crate::framework::FrameworkExtractionContext::without_config("")
+    }
+
     use super::*;
     use crate::types::ImportMapping;
     use codegraph_core::types::Node;
@@ -675,7 +680,7 @@ mod tests {
     #[test]
     fn extract_nuxt_catch_all_route() {
         let result = VueResolver
-            .extract("app/pages/[...slug].vue", "", "")
+            .extract("app/pages/[...slug].vue", "", &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -688,7 +693,7 @@ mod tests {
     #[test]
     fn extract_nuxt_optional_param_route() {
         let result = VueResolver
-            .extract("app/pages/[[maybe]].vue", "", "")
+            .extract("app/pages/[[maybe]].vue", "", &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -702,7 +707,7 @@ mod tests {
     fn extract_nuxt_nested_index_route_strips_index() {
         // `pages/users/index.vue` -> after_pages "users/index" -> strip /index -> "/users".
         let result = VueResolver
-            .extract("app/pages/users/index.vue", "", "")
+            .extract("app/pages/users/index.vue", "", &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -717,7 +722,11 @@ mod tests {
         // The matcher keys on a leading-slash "/server/api/", so the file needs a
         // parent segment (app/server/api/...).
         let result = VueResolver
-            .extract("app/server/api/users/index.ts", "", "")
+            .extract(
+                "app/server/api/users/index.ts",
+                "",
+                &test_extraction_context(),
+            )
             .expect("extract");
         let route = result
             .nodes
@@ -732,7 +741,7 @@ mod tests {
     fn extract_middleware_node() {
         // Leading-slash "/middleware/" match requires a parent segment.
         let result = VueResolver
-            .extract("app/middleware/auth.ts", "", "")
+            .extract("app/middleware/auth.ts", "", &test_extraction_context())
             .expect("extract");
         let mw = result
             .nodes
@@ -746,7 +755,7 @@ mod tests {
     #[test]
     fn extract_non_route_file_yields_no_nodes() {
         let result = VueResolver
-            .extract("src/plain.ts", "", "")
+            .extract("src/plain.ts", "", &test_extraction_context())
             .expect("extract");
         assert!(result.nodes.is_empty());
     }
@@ -755,7 +764,7 @@ mod tests {
     fn extract_backslash_paths_normalized() {
         // Windows-style separators normalize so /pages/ still matches.
         let result = VueResolver
-            .extract("app\\pages\\about.vue", "", "")
+            .extract("app\\pages\\about.vue", "", &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
@@ -847,7 +856,7 @@ mod tests {
         // A `.vue` file under server/api and under middleware exercises the
         // Language::Vue arm of both extract branches.
         let api = VueResolver
-            .extract("app/server/api/ping.vue", "", "")
+            .extract("app/server/api/ping.vue", "", &test_extraction_context())
             .expect("extract");
         let api_route = api
             .nodes
@@ -858,7 +867,7 @@ mod tests {
         assert_eq!(api_route.language, Language::Vue);
 
         let mw = VueResolver
-            .extract("app/middleware/guard.vue", "", "")
+            .extract("app/middleware/guard.vue", "", &test_extraction_context())
             .expect("extract");
         let mw_node = mw
             .nodes
@@ -874,7 +883,7 @@ mod tests {
         // `pages/index.vue` → after_pages "index"; strip_suffix("/index") does
         // not match (no leading segment), so the route is "/index".
         let result = VueResolver
-            .extract("app/pages/index.vue", "", "")
+            .extract("app/pages/index.vue", "", &test_extraction_context())
             .expect("extract");
         let route = result
             .nodes
diff --git a/crates/codegraph-resolve/src/resolver.rs b/crates/codegraph-resolve/src/resolver.rs
index 0fb1392..2181e3b 100644
--- a/crates/codegraph-resolve/src/resolver.rs
+++ b/crates/codegraph-resolve/src/resolver.rs
@@ -799,6 +799,26 @@ impl ReferenceResolver {
         &self,
         store: &mut Store,
         relative_files: &[String],
+    ) -> anyhow::Result<()> {
+        self.extract_and_persist_frameworks_with(
+            store,
+            relative_files,
+            &crate::framework::FrameworkExtractionContext::without_config(&self.project_root),
+            &codegraph_extract::ext_config::ExtensionOverrides::default(),
+        )
+    }
+
+    /// Like [`Self::extract_and_persist_frameworks`] but driven by the addressed
+    /// project's EXPLICITLY loaded configuration: `context` carries its framework
+    /// config (Godot DSL fields) and `extensions` its custom extension→language
+    /// overrides, so language gating and framework extraction both reflect that
+    /// one project and never another's.
+    pub fn extract_and_persist_frameworks_with(
+        &self,
+        store: &mut Store,
+        relative_files: &[String],
+        context: &crate::framework::FrameworkExtractionContext,
+        extensions: &codegraph_extract::ext_config::ExtensionOverrides,
     ) -> anyhow::Result<()> {
         if self.framework_resolver_extensions.is_empty() {
             return Ok(());
@@ -806,7 +826,7 @@ impl ReferenceResolver {
         let mut nodes: Vec<Node> = Vec::new();
         let mut refs: Vec<UnresolvedRef> = Vec::new();
         for relative in relative_files {
-            let language = codegraph_extract::detect_language(relative);
+            let language = codegraph_extract::detect_language_with(relative, extensions);
             let Some(content) =
                 std::fs::read_to_string(std::path::Path::new(&self.project_root).join(relative))
                     .ok()
@@ -817,7 +837,7 @@ impl ReferenceResolver {
                 if !applies_to_language(resolver.as_ref(), language) {
                     continue;
                 }
-                if let Some(result) = resolver.extract(relative, &content, &self.project_root) {
+                if let Some(result) = resolver.extract(relative, &content, context) {
                     nodes.extend(result.nodes);
                     for reference in result.references {
                         refs.push(ref_view_to_unresolved(&reference));
diff --git a/crates/codegraph-resolve/tests/frameworks.rs b/crates/codegraph-resolve/tests/frameworks.rs
index d332abe..ed5b220 100644
--- a/crates/codegraph-resolve/tests/frameworks.rs
+++ b/crates/codegraph-resolve/tests/frameworks.rs
@@ -11,6 +11,11 @@ use codegraph_resolve::framework::FrameworkResolver;
 use codegraph_resolve::frameworks::{detect_frameworks, godot, nestjs, react, vue};
 use codegraph_resolve::types::{ImportMapping, RefView, ResolutionContext, ResolvedBy};
 
+/// Extraction context for a resolver call that needs no project configuration.
+fn no_project_config() -> codegraph_resolve::framework::FrameworkExtractionContext {
+    codegraph_resolve::framework::FrameworkExtractionContext::without_config("")
+}
+
 /// A self-contained, in-memory [`ResolutionContext`] for resolver tests.
 #[derive(Default)]
 struct MockContext {
@@ -254,7 +259,7 @@ fn react_extract_emits_nextjs_page_route() {
         .extract(
             "pages/about.tsx",
             "export default function About() { return <div/>; }",
-            "",
+            &no_project_config(),
         )
         .expect("extract result");
     let route = result
@@ -270,7 +275,7 @@ fn react_extract_component_and_route_reference() {
     let content =
         "export function Home() { return <Layout/>; }\n<Route path=\"/home\" component={Home}/>";
     let result = react::ReactResolver
-        .extract("src/Home.tsx", content, "")
+        .extract("src/Home.tsx", content, &no_project_config())
         .expect("extract result");
     assert!(
         result
@@ -354,7 +359,7 @@ fn vue_extract_emits_nuxt_page_route() {
     // the upstream extract keys on `/pages/` (with leading slash), so the route file
     // must sit under a parent dir (vue.ts:198).
     let result = vue::VueResolver
-        .extract("app/pages/users/[id].vue", "", "")
+        .extract("app/pages/users/[id].vue", "", &no_project_config())
         .expect("extract result");
     let route = result
         .nodes
@@ -411,7 +416,11 @@ fn nestjs_resolves_service_provider_preferring_convention() {
 fn nestjs_extract_http_route_joins_controller_prefix() {
     let content = "@Controller('users')\nclass UsersController {\n  @Get(':id')\n  findOne() {}\n}";
     let result = nestjs::NestjsResolver
-        .extract("src/users/users.controller.ts", content, "")
+        .extract(
+            "src/users/users.controller.ts",
+            content,
+            &no_project_config(),
+        )
         .expect("extract result");
     let route = result
         .nodes
diff --git a/crates/codegraph-resolve/tests/godot_dsl.rs b/crates/codegraph-resolve/tests/godot_dsl.rs
index 5adb4f4..11050b0 100644
--- a/crates/codegraph-resolve/tests/godot_dsl.rs
+++ b/crates/codegraph-resolve/tests/godot_dsl.rs
@@ -1,23 +1,27 @@
 //! L5 Godot static-analysis tests: OPTIONAL, config-gated DSL resource-field
 //! reference edges (T9 of godot-static-analysis).
 //!
-//! The DSL hook is OFF by default. It fires ONLY when a `.codegraph/codegraph.json`
-//! up the directory tree from the `.tres` declares
+//! The DSL hook is OFF by default. It fires ONLY when the addressed project's own
+//! current-root `codegraph.json` (`IndexPaths::extension_config`) declares
 //! `godot.dsl.resourceFields = [...]`. Each listed `[resource]` property name `F`
 //! then makes its `F = <value>` line emit a [`EdgeKind::References`] edge from the
 //! resource marker to the value (a string literal → the literal text; an
 //! `ExtResource("id")` handle → the resolved repo-relative path, via the same
 //! id-table T5 uses for `script`/property bindings).
 //!
-//! These tests build a temp project dir (config + `.tres`) and drive the public
-//! [`FrameworkResolver::extract`] entry point with the ABSOLUTE `.tres` path, so
-//! the config reader can walk up to the config exactly as the pipeline does.
+//! These tests write the config into the project's resolved v2 root, load it
+//! EXPLICITLY through [`GodotDslConfig::load_for_paths`], and drive the public
+//! [`FrameworkResolver::extract`] entry point with that config in the extraction
+//! context — exactly as the pipeline does. No legacy `.codegraph/codegraph.json`
+//! is written, because it is no longer consulted.
 
 use std::path::{Path, PathBuf};
 
+use codegraph_core::IndexPaths;
 use codegraph_core::types::EdgeKind;
-use codegraph_resolve::framework::FrameworkResolver;
+use codegraph_resolve::framework::{FrameworkExtractionContext, FrameworkResolver};
 use codegraph_resolve::frameworks::godot::GodotResolver;
+use codegraph_resolve::frameworks::godot_dsl_config::GodotDslConfig;
 use codegraph_resolve::types::FrameworkResolverExtractionResult;
 
 /// A fresh, uniquely-named temp project directory.
@@ -34,15 +38,24 @@ fn unique_dir(slug: &str) -> PathBuf {
     dir
 }
 
-/// Write `.codegraph/codegraph.json` with the given JSON contents under `root`.
+/// Write the project's CURRENT-ROOT `codegraph.json` — the only config the DSL
+/// reader consults.
 fn write_config(root: &Path, json: &str) {
-    let cfg_dir = root.join(".codegraph");
-    std::fs::create_dir_all(&cfg_dir).expect("mkdir .codegraph");
-    std::fs::write(cfg_dir.join("codegraph.json"), json).expect("write codegraph.json");
+    let paths = IndexPaths::resolve(root, None).expect("resolve index paths");
+    std::fs::create_dir_all(paths.current_root()).expect("mkdir current root");
+    std::fs::write(paths.extension_config(), json).expect("write codegraph.json");
 }
 
-/// Write `rel` under `root` and return its ABSOLUTE path as a `/`-joined string
-/// (the config reader walks up from this path).
+/// The extraction context for `root`, carrying its EXPLICITLY loaded DSL config.
+fn project_config(root: &Path) -> FrameworkExtractionContext {
+    let paths = IndexPaths::resolve(root, None).expect("resolve index paths");
+    FrameworkExtractionContext::new(
+        root.to_string_lossy().into_owned(),
+        GodotDslConfig::load_for_paths(&paths),
+    )
+}
+
+/// Write `rel` under `root` and return its ABSOLUTE path as a `/`-joined string.
 fn write_tres(root: &Path, rel: &str, content: &str) -> String {
     let abs = root.join(rel);
     if let Some(parent) = abs.parent() {
@@ -52,10 +65,11 @@ fn write_tres(root: &Path, rel: &str, content: &str) -> String {
     abs.to_string_lossy().into_owned()
 }
 
-/// Extract a `.tres` at `abs_path` (panics if the resolver returned `None`).
-fn extract(abs_path: &str, content: &str) -> FrameworkResolverExtractionResult {
+/// Extract a `.tres` under `root`'s own loaded DSL config (panics if the resolver
+/// returned `None`).
+fn extract_in(root: &Path, abs_path: &str, content: &str) -> FrameworkResolverExtractionResult {
     GodotResolver
-        .extract(abs_path, content, "")
+        .extract(abs_path, content, &project_config(root))
         .expect(".tres must produce Some(result)")
 }
 
@@ -79,7 +93,7 @@ fn with_dsl_config_string_field_emits_reference_to_literal_value() {
     let tres = write_tres(&root, "data/strength.tres", SKILL_TRES);
 
     // When extracting the `.tres` that has `skill_effect = "Fireball"`,
-    let result = extract(&tres, SKILL_TRES);
+    let result = extract_in(&root, &tres, SKILL_TRES);
 
     // Then a reference edge to the literal value `Fireball` is emitted.
     let dsl_ref = result
@@ -114,7 +128,7 @@ fn without_dsl_config_same_tres_emits_no_dsl_edge() {
     let tres = write_tres(&root, "data/strength.tres", SKILL_TRES);
 
     // When extracting the SAME `.tres`,
-    let result = extract(&tres, SKILL_TRES);
+    let result = extract_in(&root, &tres, SKILL_TRES);
 
     // Then ZERO DSL edges are emitted — `skill_effect = "Fireball"` produces no
     // reference, because the config is the only trigger.
@@ -147,7 +161,7 @@ fn dsl_config_present_but_other_fields_listed_emits_no_edge() {
     let tres = write_tres(&root, "data/strength.tres", SKILL_TRES);
 
     // When extracting a `.tres` whose only DSL-shaped line is `skill_effect`,
-    let result = extract(&tres, SKILL_TRES);
+    let result = extract_in(&root, &tres, SKILL_TRES);
 
     // Then no DSL edge fires — the field list is honored exactly.
     assert!(
@@ -179,7 +193,7 @@ skill_effect = ExtResource(\"1\")
     let tres = write_tres(&root, "data/mage.tres", content);
 
     // When extracting,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then the DSL edge resolves the ExtResource id to the repo-relative path
     // (res:// stripped), exactly like T5's script/property bindings.
@@ -201,7 +215,7 @@ fn malformed_config_is_ignored_no_panic_no_dsl_edge() {
     let tres = write_tres(&root, "data/strength.tres", SKILL_TRES);
 
     // When extracting (must not panic),
-    let result = extract(&tres, SKILL_TRES);
+    let result = extract_in(&root, &tres, SKILL_TRES);
 
     // Then the malformed config is ignored — no DSL edge, as if absent.
     assert!(
@@ -231,8 +245,8 @@ effect_on = \"Enemy\"
     let tres = write_tres(&root, "data/spell.tres", content);
 
     // When extracting twice,
-    let a = extract(&tres, content);
-    let b = extract(&tres, content);
+    let a = extract_in(&root, &tres, content);
+    let b = extract_in(&root, &tres, content);
 
     // Then the parser-controlled fields (ids/names/kinds/targets/order) match.
     let nodes_a: Vec<(&str, &str)> = a
@@ -315,7 +329,7 @@ buff_id = 7005
     let tres = write_tres(&root, "data/strength.tres", content);
 
     // When extracting a `.tres` with a bare integer `buff_id = 7005`,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then exactly one `godot:id:buff:7005` sentinel is emitted, anchored on the
     // resource marker with EdgeKind::References.
@@ -349,7 +363,7 @@ skill_effect = \"a:b:9015:c:7005:1000\"
     let tres = write_tres(&root, "data/mage.tres", content);
 
     // When extracting the compound value,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then EXACTLY the 0-based segments 2 and 4 (9015, 7005) become sentinels —
     // not the whole string, not segment 5 (1000).
@@ -376,7 +390,7 @@ skill_effect = \"a:b:9015:c:7005:1000\"
     let tres = write_tres(&root, "data/strength.tres", content);
 
     // When extracting a `.tres` full of ID-shaped lines,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then ZERO id sentinels are emitted — the config is the only trigger, so a
     // non-configured project behaves byte-identically to pre-PR2.
@@ -412,7 +426,7 @@ duration = 5.0
     let tres = write_tres(&root, "data/strength.tres", content);
 
     // When extracting a `.tres` with no matching key,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then no sentinel fires — the spec map is matched by exact key.
     assert!(
@@ -441,7 +455,7 @@ pair = \"100:200\"
     let tres = write_tres(&root, "data/oob.tres", content);
 
     // When extracting a value with only two segments,
-    let result = extract(&tres, content);
+    let result = extract_in(&root, &tres, content);
 
     // Then the in-range segment yields a sentinel and the out-of-range index is
     // silently skipped (no panic, no error, no empty sentinel).
@@ -472,8 +486,8 @@ skill_effect = \"9015:c:7005\"
     let tres = write_tres(&root, "data/spell.tres", content);
 
     // When extracting twice,
-    let a = extract(&tres, content);
-    let b = extract(&tres, content);
+    let a = extract_in(&root, &tres, content);
+    let b = extract_in(&root, &tres, content);
 
     // Then the sentinel set, order, and edge sources are byte-stable, and follow
     // SOURCE-LINE order (buff_id line before skill_effect line), not config order.
diff --git a/crates/codegraph-resolve/tests/godot_project.rs b/crates/codegraph-resolve/tests/godot_project.rs
index ec46634..371d851 100644
--- a/crates/codegraph-resolve/tests/godot_project.rs
+++ b/crates/codegraph-resolve/tests/godot_project.rs
@@ -10,11 +10,16 @@ use codegraph_resolve::framework::FrameworkResolver;
 use codegraph_resolve::frameworks::godot::GodotResolver;
 use codegraph_resolve::types::FrameworkResolverExtractionResult;
 
+/// Extraction context for a resolver call that needs no project configuration.
+fn no_project_config() -> codegraph_resolve::framework::FrameworkExtractionContext {
+    codegraph_resolve::framework::FrameworkExtractionContext::without_config("")
+}
+
 /// Run `extract()` and unwrap the result (panics if the resolver returned
 /// `None`, which for `project.godot` is itself a failure).
 fn extract(path: &str, content: &str) -> FrameworkResolverExtractionResult {
     GodotResolver
-        .extract(path, content, "")
+        .extract(path, content, &no_project_config())
         .expect("project.godot must produce Some(result)")
 }
 
@@ -349,15 +354,19 @@ fn extract_returns_none_for_non_project_godot_file() {
     // project parser.
     assert!(
         GodotResolver
-            .extract("foo.gd", "extends Node\n", "")
+            .extract("foo.gd", "extends Node\n", &no_project_config())
             .is_some()
     );
     // A genuinely unclaimed file → None.
-    assert!(GodotResolver.extract("README.md", "# hi\n", "").is_none());
+    assert!(
+        GodotResolver
+            .extract("README.md", "# hi\n", &no_project_config())
+            .is_none()
+    );
     // A .tres routes to T5's resource parser (Some, not this project parser).
     assert!(
         GodotResolver
-            .extract("data/item.tres", "[gd_resource]\n", "")
+            .extract("data/item.tres", "[gd_resource]\n", &no_project_config())
             .is_some()
     );
     // A nested path whose basename IS project.godot still dispatches.
@@ -366,7 +375,7 @@ fn extract_returns_none_for_non_project_godot_file() {
             .extract(
                 "sub/dir/project.godot",
                 "[autoload]\nX=\"res://x.gd\"\n",
-                ""
+                &no_project_config()
             )
             .is_some()
     );
diff --git a/crates/codegraph-resolve/tests/godot_resource.rs b/crates/codegraph-resolve/tests/godot_resource.rs
index 9f747d6..bd3a366 100644
--- a/crates/codegraph-resolve/tests/godot_resource.rs
+++ b/crates/codegraph-resolve/tests/godot_resource.rs
@@ -12,11 +12,16 @@ use codegraph_resolve::framework::FrameworkResolver;
 use codegraph_resolve::frameworks::godot::GodotResolver;
 use codegraph_resolve::types::FrameworkResolverExtractionResult;
 
+/// Extraction context for a resolver call that needs no project configuration.
+fn no_project_config() -> codegraph_resolve::framework::FrameworkExtractionContext {
+    codegraph_resolve::framework::FrameworkExtractionContext::without_config("")
+}
+
 /// Run `extract()` and unwrap the result (panics if the resolver returned
 /// `None`, which for a `.tres` is itself a failure).
 fn extract(path: &str, content: &str) -> FrameworkResolverExtractionResult {
     GodotResolver
-        .extract(path, content, "")
+        .extract(path, content, &no_project_config())
         .expect(".tres must produce Some(result)")
 }
 
@@ -236,32 +241,48 @@ fn extract_routes_tres_to_t5_and_others_correctly() {
     // A .tres dispatches to T5 (Some).
     assert!(
         GodotResolver
-            .extract("data/item.tres", "[gd_resource format=3]\n", "")
+            .extract(
+                "data/item.tres",
+                "[gd_resource format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // A nested path whose extension is .tres still dispatches.
     assert!(
         GodotResolver
-            .extract("a/b/c/Deep.tres", "[gd_resource format=3]\n", "")
+            .extract(
+                "a/b/c/Deep.tres",
+                "[gd_resource format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
 
     // A .gd file now routes to T6's GDScript dynamic parser (Some).
     assert!(
         GodotResolver
-            .extract("player.gd", "extends Node\n", "")
+            .extract("player.gd", "extends Node\n", &no_project_config())
             .is_some()
     );
     // A .tscn routes to T4 (Some, via the scene parser, not this one).
     assert!(
         GodotResolver
-            .extract("scenes/Main.tscn", "[gd_scene format=3]\n", "")
+            .extract(
+                "scenes/Main.tscn",
+                "[gd_scene format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // project.godot routes to T3 (Some, via the project parser).
     assert!(
         GodotResolver
-            .extract("project.godot", "[autoload]\nX=\"res://x.gd\"\n", "")
+            .extract(
+                "project.godot",
+                "[autoload]\nX=\"res://x.gd\"\n",
+                &no_project_config()
+            )
             .is_some()
     );
 }
diff --git a/crates/codegraph-resolve/tests/godot_scene.rs b/crates/codegraph-resolve/tests/godot_scene.rs
index d747473..dbc0b9e 100644
--- a/crates/codegraph-resolve/tests/godot_scene.rs
+++ b/crates/codegraph-resolve/tests/godot_scene.rs
@@ -11,11 +11,16 @@ use codegraph_resolve::framework::FrameworkResolver;
 use codegraph_resolve::frameworks::godot::GodotResolver;
 use codegraph_resolve::types::FrameworkResolverExtractionResult;
 
+/// Extraction context for a resolver call that needs no project configuration.
+fn no_project_config() -> codegraph_resolve::framework::FrameworkExtractionContext {
+    codegraph_resolve::framework::FrameworkExtractionContext::without_config("")
+}
+
 /// Run `extract()` and unwrap the result (panics if the resolver returned
 /// `None`, which for a `.tscn` is itself a failure).
 fn extract(path: &str, content: &str) -> FrameworkResolverExtractionResult {
     GodotResolver
-        .extract(path, content, "")
+        .extract(path, content, &no_project_config())
         .expect(".tscn must produce Some(result)")
 }
 
@@ -296,33 +301,49 @@ fn extract_routes_only_tscn_not_gd_or_tres() {
     // A .tscn dispatches to T4.
     assert!(
         GodotResolver
-            .extract("scenes/Main.tscn", "[gd_scene format=3]\n", "")
+            .extract(
+                "scenes/Main.tscn",
+                "[gd_scene format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // A nested path whose extension is .tscn still dispatches.
     assert!(
         GodotResolver
-            .extract("a/b/c/Deep.tscn", "[gd_scene format=3]\n", "")
+            .extract(
+                "a/b/c/Deep.tscn",
+                "[gd_scene format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
 
     // A .gd file now routes to T6's GDScript dynamic parser (Some).
     assert!(
         GodotResolver
-            .extract("player.gd", "extends Node\n", "")
+            .extract("player.gd", "extends Node\n", &no_project_config())
             .is_some()
     );
     // A .tres routes to T5's resource parser (Some, via that parser, not this).
     assert!(
         GodotResolver
-            .extract("data/item.tres", "[gd_resource format=3]\n", "")
+            .extract(
+                "data/item.tres",
+                "[gd_resource format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // project.godot still routes to T3 (not this parser) — it returns Some, but
     // via the project parser, so it is NOT None.
     assert!(
         GodotResolver
-            .extract("project.godot", "[autoload]\nX=\"res://x.gd\"\n", "")
+            .extract(
+                "project.godot",
+                "[autoload]\nX=\"res://x.gd\"\n",
+                &no_project_config()
+            )
             .is_some()
     );
 }
diff --git a/crates/codegraph-resolve/tests/godot_script.rs b/crates/codegraph-resolve/tests/godot_script.rs
index 7db58bb..b3b8e45 100644
--- a/crates/codegraph-resolve/tests/godot_script.rs
+++ b/crates/codegraph-resolve/tests/godot_script.rs
@@ -15,11 +15,16 @@ use codegraph_resolve::frameworks::godot::GodotResolver;
 use codegraph_resolve::frameworks::godot_script::{AUTOLOAD_CALL_PREFIX, DYNAMIC_PREFIX};
 use codegraph_resolve::types::{FrameworkResolverExtractionResult, RefView};
 
+/// Extraction context for a resolver call that needs no project configuration.
+fn no_project_config() -> codegraph_resolve::framework::FrameworkExtractionContext {
+    codegraph_resolve::framework::FrameworkExtractionContext::without_config("")
+}
+
 /// Run `extract()` and unwrap the result (panics if the resolver returned
 /// `None`, which for a `.gd` is itself a failure).
 fn extract(path: &str, content: &str) -> FrameworkResolverExtractionResult {
     GodotResolver
-        .extract(path, content, "")
+        .extract(path, content, &no_project_config())
         .expect(".gd must produce Some(result)")
 }
 
@@ -425,36 +430,52 @@ fn extract_routes_gd_to_t6_and_others_correctly() {
     // A .gd dispatches to T6 (Some).
     assert!(
         GodotResolver
-            .extract("player.gd", "extends Node\n", "")
+            .extract("player.gd", "extends Node\n", &no_project_config())
             .is_some()
     );
     // A nested path whose extension is .gd still dispatches.
     assert!(
         GodotResolver
-            .extract("a/b/c/Deep.gd", "extends Node\n", "")
+            .extract("a/b/c/Deep.gd", "extends Node\n", &no_project_config())
             .is_some()
     );
 
     // A .tscn routes to T4 (Some, via the scene parser).
     assert!(
         GodotResolver
-            .extract("scenes/Main.tscn", "[gd_scene format=3]\n", "")
+            .extract(
+                "scenes/Main.tscn",
+                "[gd_scene format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // A .tres routes to T5 (Some, via the resource parser).
     assert!(
         GodotResolver
-            .extract("data/item.tres", "[gd_resource format=3]\n", "")
+            .extract(
+                "data/item.tres",
+                "[gd_resource format=3]\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // project.godot routes to T3 (Some, via the project parser).
     assert!(
         GodotResolver
-            .extract("project.godot", "[autoload]\nX=\"res://x.gd\"\n", "")
+            .extract(
+                "project.godot",
+                "[autoload]\nX=\"res://x.gd\"\n",
+                &no_project_config()
+            )
             .is_some()
     );
     // A non-Godot file the resolver doesn't claim → None.
-    assert!(GodotResolver.extract("README.md", "# hi\n", "").is_none());
+    assert!(
+        GodotResolver
+            .extract("README.md", "# hi\n", &no_project_config())
+            .is_none()
+    );
 }
 
 #[test]
diff --git a/crates/codegraph-watch/src/lib.rs b/crates/codegraph-watch/src/lib.rs
index 5854f35..d13ab5f 100644
--- a/crates/codegraph-watch/src/lib.rs
+++ b/crates/codegraph-watch/src/lib.rs
@@ -15,7 +15,9 @@ pub use policy::{
 pub use sync::{
     SyncOutcome, sync_changed_paths, sync_project_once, sync_project_once_with_progress,
 };
-pub use watcher::{PendingFile, ProjectWatcher, WatchOptions, start_serve_watcher};
+pub use watcher::{
+    PendingFile, ProjectWatcher, WatchOptions, start_serve_watcher, watch_options_for_project,
+};
 pub use worktree::{
     WorktreeIndexMismatch, detect_worktree_index_mismatch, git_worktree_root,
     worktree_mismatch_notice, worktree_mismatch_warning,
diff --git a/crates/codegraph-watch/src/migrate.rs b/crates/codegraph-watch/src/migrate.rs
index 1af4978..e45efc8 100644
--- a/crates/codegraph-watch/src/migrate.rs
+++ b/crates/codegraph-watch/src/migrate.rs
@@ -36,11 +36,11 @@ use anyhow::{Context, Result};
 use codegraph_core::IndexPaths;
 use codegraph_core::node_id::hash_content;
 use codegraph_core::types::{Edge, FileRecord, Node, UnresolvedRef};
-use codegraph_extract::{ExtractOptions, detect_language, extract_source};
+use codegraph_extract::{detect_language_with, extract_source_with};
 use codegraph_resolve::ReferenceResolver;
 use codegraph_store::StoreWriteAuthorization;
 
-use crate::sync::{SyncOutcome, modified_millis, now_millis};
+use crate::sync::{ProjectScope, SyncOutcome, modified_millis, now_millis};
 
 /// Batch sizes and the resolver batch, matching the CLI full-index constants so a
 /// migrated index is byte-equal to `index --force`.
@@ -63,10 +63,13 @@ pub(crate) fn migrate_project(
     project_root: &Path,
     paths: &IndexPaths,
     authorization: StoreWriteAuthorization,
-    options: &ExtractOptions,
+    scope: &ProjectScope,
     started: Instant,
     mut on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
+    // The addressed project's own scan/extract options and framework config; the
+    // migration never consults a process-global value.
+    let options = &scope.options;
     // `scan_project` returns a SORTED list, and every downstream pass keeps that
     // order, so no HashSet iteration order can reach the database or the outcome.
     let candidates = codegraph_extract::engine::scan_project(project_root, options)?;
@@ -108,12 +111,12 @@ pub(crate) fn migrate_project(
                 duration_ms: 0,
             }
         } else {
-            extract_source(relative, &source, None)
+            extract_source_with(relative, &source, None, &options.extensions)
         };
         let file = FileRecord {
             path: relative.clone(),
             content_hash: hash_content(&source),
-            language: detect_language(relative),
+            language: detect_language_with(relative, &options.extensions),
             size: metadata.len() as i64,
             modified_at: modified_millis(&metadata),
             indexed_at: now_millis(),
@@ -174,7 +177,12 @@ pub(crate) fn migrate_project(
             .into_iter()
             .map(|file| file.path)
             .collect::<Vec<_>>();
-        resolver.extract_and_persist_frameworks(rebuild.store_mut(), &relative_files)?;
+        resolver.extract_and_persist_frameworks_with(
+            rebuild.store_mut(),
+            &relative_files,
+            &scope.framework,
+            &options.extensions,
+        )?;
     }
     resolver.resolve_and_persist_batched(rebuild.store_mut(), RESOLVE_BATCH_ROWS)?;
     resolver.run_post_extract(rebuild.store_mut())?;
diff --git a/crates/codegraph-watch/src/policy.rs b/crates/codegraph-watch/src/policy.rs
index 03f7211..25537cf 100644
--- a/crates/codegraph-watch/src/policy.rs
+++ b/crates/codegraph-watch/src/policy.rs
@@ -1,7 +1,8 @@
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 
-use codegraph_extract::detect_language;
+use codegraph_extract::{ExtensionOverrides, detect_language_with};
 
 pub const CODEGRAPH_NO_WATCH: &str = "CODEGRAPH_NO_WATCH";
 
@@ -85,6 +86,10 @@ pub struct WatchPolicy {
     builtin_rule_count: usize,
     include: Vec<String>,
     exclude: Vec<String>,
+    /// The addressed project's custom extension→language overrides, so a file the
+    /// project declared as source is HANDLED by the watcher exactly as the scan
+    /// indexes it. Empty by default (built-in detection only).
+    extensions: Arc<ExtensionOverrides>,
 }
 
 impl WatchPolicy {
@@ -136,9 +141,20 @@ impl WatchPolicy {
             builtin_rule_count,
             include: include.to_vec(),
             exclude: exclude.to_vec(),
+            extensions: ExtensionOverrides::empty(),
         }
     }
 
+    /// Adopt the addressed project's extension overrides, so
+    /// [`should_handle_file`](Self::should_handle_file) treats a project-declared
+    /// custom extension as source. Without this the policy uses built-in
+    /// detection only, which is the zero-config behavior.
+    #[must_use]
+    pub fn with_extension_overrides(mut self, extensions: Arc<ExtensionOverrides>) -> Self {
+        self.extensions = extensions;
+        self
+    }
+
     pub fn normalize_relative(&self, path: impl AsRef<Path>) -> Option<String> {
         let path = path.as_ref();
         let relative = if path.is_absolute() {
@@ -156,7 +172,8 @@ impl WatchPolicy {
     pub fn should_handle_file(&self, relative: &str) -> bool {
         !self.is_always_ignored(relative)
             && !self.is_ignored(relative, false)
-            && detect_language(relative) != codegraph_core::types::Language::Unknown
+            && detect_language_with(relative, &self.extensions)
+                != codegraph_core::types::Language::Unknown
     }
 
     pub fn allows_file_path(&self, relative: &str) -> bool {
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index c860ba5..55ba12c 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -1,14 +1,20 @@
 use std::collections::HashSet;
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use anyhow::{Context, Result, bail};
 use codegraph_core::IndexPaths;
+use codegraph_core::config::Config;
 use codegraph_core::node_id::hash_content;
 use codegraph_core::types::FileRecord;
-use codegraph_extract::{ExtractOptions, detect_language, extract_file};
+use codegraph_extract::{
+    ExtensionOverrides, ExtractOptions, detect_language_with, extract_file_with_options,
+};
 use codegraph_resolve::ReferenceResolver;
+use codegraph_resolve::framework::FrameworkExtractionContext;
+use codegraph_resolve::frameworks::godot_dsl_config::GodotDslConfig;
 use codegraph_store::{IndexLease, Store, StoreWriteOpen, StoreWritePurpose};
 
 use crate::policy::WatchPolicy;
@@ -43,15 +49,23 @@ pub fn sync_project_once(project_root: impl AsRef<Path>) -> Result<SyncOutcome>
 
 /// Whole-project sync using watcher-owned path patterns while preserving every
 /// other scan option from the normal sync path.
+///
+/// The watcher owns `include`/`exclude` because it derived them from the SAME
+/// project config when it started; every other option (size limit, ignore sets,
+/// extension overrides, framework config) is loaded here from the addressed
+/// project, so a watcher-triggered full sync scans exactly what a direct sync of
+/// that project scans.
 pub(crate) fn sync_project_once_with_patterns(
     project_root: impl AsRef<Path>,
     include: &[String],
     exclude: &[String],
 ) -> Result<SyncOutcome> {
-    let mut options = scan_options();
-    options.include = include.to_vec();
-    options.exclude = exclude.to_vec();
-    sync_project_once_with_options(project_root.as_ref(), options, |_, _| {})
+    let project_root = project_root.as_ref();
+    let paths = index_paths(project_root)?;
+    let mut scope = ProjectScope::load(project_root, &paths)?;
+    scope.options.include = include.to_vec();
+    scope.options.exclude = exclude.to_vec();
+    sync_project_once_with_scope(project_root, &paths, &scope, |_, _| {})
 }
 
 /// Like [`sync_project_once`] but invokes `on_progress(done, total)` after each
@@ -62,28 +76,31 @@ pub fn sync_project_once_with_progress(
     project_root: impl AsRef<Path>,
     on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
-    let options = scan_options();
-    sync_project_once_with_options(project_root.as_ref(), options, on_progress)
+    let project_root = project_root.as_ref();
+    let paths = index_paths(project_root)?;
+    let scope = ProjectScope::load(project_root, &paths)?;
+    sync_project_once_with_scope(project_root, &paths, &scope, on_progress)
 }
 
-fn sync_project_once_with_options(
+fn sync_project_once_with_scope(
     project_root: &Path,
-    options: ExtractOptions,
+    paths: &IndexPaths,
+    scope: &ProjectScope,
     mut on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
+    let options = &scope.options;
     let include = options.include.clone();
     let exclude = options.exclude.clone();
     let started = Instant::now();
-    let paths = index_paths(project_root)?;
 
     // CLASSIFY BEFORE MUTATING A ROW (frozen plan lines 557-565). The gate takes
     // the ONE outer exclusive lease, classifies under it, and either hands back
     // the incremental writer for a corroborated Current namespace or the
     // lease-retaining authorization that escalates to a forced full migration.
     // Future/Corrupt/unauthorized-Uninitialized fail here, before any byte moves.
-    match open_sync_writer(&paths)? {
+    match open_sync_writer(paths)? {
         SyncWriter::Incremental(mut store) => {
-            let mut candidates = codegraph_extract::engine::scan_project(project_root, &options)?;
+            let mut candidates = codegraph_extract::engine::scan_project(project_root, options)?;
             // Cold CLI sync has no watcher event list, so deletions are found by
             // diffing tracked files against scan_project's on-disk set; absent
             // paths flow through sync_one's delete branch (upstream removal pass,
@@ -105,6 +122,7 @@ fn sync_project_once_with_options(
                 &mut store,
                 project_root,
                 candidates,
+                scope,
                 &include,
                 &exclude,
                 started,
@@ -115,29 +133,40 @@ fn sync_project_once_with_options(
         }
         SyncWriter::MigrationRequired(authorization) => crate::migrate::migrate_project(
             project_root,
-            &paths,
+            paths,
             authorization,
-            &options,
+            scope,
             started,
             &mut on_progress,
         ),
     }
 }
 
-/// The scan/extract options one sync uses. The global config is the source of
-/// truth when a binary initialized it; a library caller that never did (a bare
-/// watcher thread) falls back to the documented defaults instead of panicking.
-fn scan_options() -> ExtractOptions {
-    let Some(config) = codegraph_core::config::try_get_config() else {
-        return ExtractOptions::default();
-    };
-    ExtractOptions {
-        max_file_size: config.indexing.max_file_size,
-        ignore_dirs: config.indexing.ignore_dirs.clone(),
-        ignore_paths: config.indexing.ignore_paths.clone(),
-        exclude: config.indexing.exclude.clone(),
-        include: config.indexing.include.clone(),
-        parallel: true,
+/// One project's immutable configuration for ONE sync operation.
+///
+/// Loaded from the addressed project's resolved [`IndexPaths`] — its current-root
+/// `config.toml` (scan/extract options) and current-root `codegraph.json`
+/// (extension overrides + Godot DSL fields). Nothing here reads a process-global
+/// value, a legacy `.codegraph` root, or the process working directory, so a
+/// watcher, a direct sync, and a startup catch-up on different projects inside one
+/// process each operate under their own settings.
+pub(crate) struct ProjectScope {
+    pub(crate) options: ExtractOptions,
+    pub(crate) framework: FrameworkExtractionContext,
+}
+
+impl ProjectScope {
+    pub(crate) fn load(project_root: &Path, paths: &IndexPaths) -> Result<Self> {
+        let config = Config::load_for_paths(None, paths)?;
+        let extensions = ExtensionOverrides::load_for_paths(paths);
+        let framework = FrameworkExtractionContext::new(
+            project_root.to_string_lossy().into_owned(),
+            GodotDslConfig::load_for_paths(paths),
+        );
+        Ok(Self {
+            options: ExtractOptions::for_project(&config, extensions),
+            framework,
+        })
     }
 }
 
@@ -214,6 +243,14 @@ pub fn sync_changed_paths_with_patterns(
         );
     }
 
+    // The addressed project's own immutable config drives extraction and any
+    // migration escalation; the caller-supplied `include`/`exclude` (the watcher's
+    // own patterns, derived from this same project config) override those two
+    // fields so watcher scope and scan scope stay identical.
+    let mut scope = ProjectScope::load(project_root, &paths)?;
+    scope.options.include = include.to_vec();
+    scope.options.exclude = exclude.to_vec();
+
     // Same classify-before-mutate gate as the cold full sync: a Current namespace
     // stays incremental, while Missing/Outdated/recoverable Building escalate to a
     // forced migration under the SAME retained exclusive lease.
@@ -223,6 +260,7 @@ pub fn sync_changed_paths_with_patterns(
                 &mut store,
                 project_root,
                 changed,
+                &scope,
                 include,
                 exclude,
                 started,
@@ -231,21 +269,14 @@ pub fn sync_changed_paths_with_patterns(
             store.finish_current_mutation()?;
             Ok(outcome)
         }
-        SyncWriter::MigrationRequired(authorization) => {
-            let options = ExtractOptions {
-                include: include.to_vec(),
-                exclude: exclude.to_vec(),
-                ..scan_options()
-            };
-            crate::migrate::migrate_project(
-                project_root,
-                &paths,
-                authorization,
-                &options,
-                started,
-                |_, _| {},
-            )
-        }
+        SyncWriter::MigrationRequired(authorization) => crate::migrate::migrate_project(
+            project_root,
+            &paths,
+            authorization,
+            &scope,
+            started,
+            |_, _| {},
+        ),
     }
 }
 
@@ -254,12 +285,14 @@ fn sync_paths_with_store(
     store: &mut Store,
     project_root: &Path,
     paths: impl IntoIterator<Item = impl AsRef<Path>>,
+    scope: &ProjectScope,
     include: &[String],
     exclude: &[String],
     started: std::time::Instant,
     mut on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
-    let policy = WatchPolicy::with_config(project_root, include, exclude);
+    let policy = WatchPolicy::with_config(project_root, include, exclude)
+        .with_extension_overrides(Arc::clone(&scope.options.extensions));
     let mut outcome = SyncOutcome::default();
     let mut changed = false;
     let mut seen = HashSet::new();
@@ -290,6 +323,7 @@ fn sync_paths_with_store(
             project_root,
             store,
             &relative,
+            scope,
             &mut outcome,
             &mut dependents,
             &mut changed_names,
@@ -310,6 +344,7 @@ fn sync_paths_with_store(
         refresh_dependent_refs(
             project_root,
             store,
+            scope,
             &dependents,
             &reindexed,
             &mut changed_names,
@@ -332,7 +367,12 @@ fn sync_paths_with_store(
         // nodes/refs were dropped on re-extraction (upstream tree-sitter.ts:4796-4819).
         if resolver.has_framework_resolvers() {
             let reindexed_files: Vec<String> = reindexed.iter().cloned().collect();
-            resolver.extract_and_persist_frameworks(store, &reindexed_files)?;
+            resolver.extract_and_persist_frameworks_with(
+                store,
+                &reindexed_files,
+                &scope.framework,
+                &scope.options.extensions,
+            )?;
         }
         resolver.resolve_incremental_and_persist(store, &scope_files, &changed_names)?;
         // Cross-file framework finalization on every sync (upstream index.ts:464).
@@ -377,6 +417,7 @@ fn sync_paths_with_store(
 fn refresh_dependent_refs(
     project_root: &Path,
     store: &mut Store,
+    scope: &ProjectScope,
     dependents: &HashSet<String>,
     already_reindexed: &HashSet<String>,
     changed_names: &mut HashSet<String>,
@@ -388,7 +429,7 @@ fn refresh_dependent_refs(
         if !project_root.join(relative).exists() {
             continue;
         }
-        let result = extract_file(project_root, relative)?;
+        let result = extract_file_with_options(project_root, relative, &scope.options)?;
         let node_ids = result
             .nodes
             .iter()
@@ -445,10 +486,12 @@ pub(crate) fn default_db_path(project_root: &Path) -> Result<PathBuf> {
     .current_db())
 }
 
+#[allow(clippy::too_many_arguments)]
 fn sync_one(
     project_root: &Path,
     store: &mut Store,
     relative: &str,
+    scope: &ProjectScope,
     outcome: &mut SyncOutcome,
     dependents: &mut HashSet<String>,
     changed_names: &mut HashSet<String>,
@@ -500,7 +543,7 @@ fn sync_one(
     for dependent in store.dependent_file_paths(relative)? {
         dependents.insert(dependent);
     }
-    reextract_into_store(project_root, store, relative, changed_names)?;
+    reextract_into_store(project_root, store, relative, scope, changed_names)?;
     outcome.files_reindexed += 1;
     Ok(true)
 }
@@ -509,12 +552,13 @@ fn reextract_into_store(
     project_root: &Path,
     store: &mut Store,
     relative: &str,
+    scope: &ProjectScope,
     changed_names: &mut HashSet<String>,
 ) -> Result<()> {
     let full = project_root.join(relative);
     let source = fs::read_to_string(&full).with_context(|| format!("read {}", full.display()))?;
     let metadata = fs::metadata(&full).with_context(|| format!("stat {}", full.display()))?;
-    let result = extract_file(project_root, relative)?;
+    let result = extract_file_with_options(project_root, relative, &scope.options)?;
     let node_ids = result
         .nodes
         .iter()
@@ -528,7 +572,7 @@ fn reextract_into_store(
     let file = FileRecord {
         path: relative.to_string(),
         content_hash: hash_content(&source),
-        language: detect_language(relative),
+        language: detect_language_with(relative, &scope.options.extensions),
         size: metadata.len() as i64,
         modified_at: modified_millis(&metadata),
         indexed_at: now_millis(),
@@ -846,19 +890,12 @@ pub(crate) mod tests {
         assert_eq!(outcome.changed_paths, vec!["src/helper.ts".to_string()]);
     }
 
-    /// `sync_project_once` reads the global config; initialize it once (the
-    /// global `OnceLock` tolerates a repeat set as an ignorable error).
-    fn ensure_config(project_root: &Path) {
-        let _ = codegraph_core::config::init_config(None, project_root);
-    }
-
     #[test]
     fn framework_sweep_does_not_grow_unresolved_refs_across_heal_cycles() {
         // Given: an indexed Godot project (autoload + signal-handler refs produce
         // framework `unresolved_refs`), with the #1187 marker set so every sync
         // triggers the orphan sweep.
         let dir = TestDir::new("watch-godot-sweep");
-        ensure_config(dir.path());
         fs::create_dir_all(dir.path().join(".codegraph")).unwrap();
         fs::write(
             dir.path().join("project.godot"),
@@ -906,7 +943,6 @@ pub(crate) mod tests {
     fn sync_project_once_scans_and_removes_absent_tracked_files() {
         // Given: a project with two source files indexed via a full scan.
         let dir = TestDir::new("watch-once");
-        ensure_config(dir.path());
         fs::create_dir_all(dir.path().join("src")).unwrap();
         fs::create_dir_all(dir.path().join(".codegraph")).unwrap();
         fs::write(
@@ -940,7 +976,6 @@ pub(crate) mod tests {
     fn sync_project_once_with_progress_reports_monotonic_progress() {
         // Given: a project with a couple of source files.
         let dir = TestDir::new("watch-progress");
-        ensure_config(dir.path());
         fs::create_dir_all(dir.path().join("src")).unwrap();
         fs::create_dir_all(dir.path().join(".codegraph")).unwrap();
         fs::write(
@@ -1106,19 +1141,27 @@ pub(crate) mod tests {
         );
     }
 
+    /// Write this project's CURRENT-ROOT `config.toml` — the only config a sync
+    /// consults.
+    fn write_project_config(project_root: &Path, contents: &str) {
+        let paths = index_paths(project_root).expect("resolve project paths");
+        fs::create_dir_all(paths.current_root()).unwrap();
+        fs::write(paths.config_toml(), contents).unwrap();
+    }
+
     #[test]
     fn sync_project_once_indexes_gitignored_dir_named_in_include() {
         // #1063: a gitignored first-party dir named in `[indexing] include` is
-        // indexed on a full `codegraph sync` (sync_project_once reads the config
-        // and threads include into both the scan and the WatchPolicy gate).
+        // indexed on a full `codegraph sync`. The config is THIS project's own
+        // current-root `config.toml`, loaded per operation, so the assertion is
+        // unconditional — no process-global singleton can hold another project's
+        // settings.
         let dir = TestDir::new("watch-once-include");
-        fs::create_dir_all(dir.path().join(".codegraph")).unwrap();
         fs::write(dir.path().join(".gitignore"), "Tools/\n").unwrap();
-        fs::write(
-            dir.path().join(".codegraph/config.toml"),
+        write_project_config(
+            dir.path(),
             "[app]\nname = \"p\"\n\n[indexing]\ninclude = [\"Tools/\"]\n",
-        )
-        .unwrap();
+        );
         fs::create_dir_all(dir.path().join("src")).unwrap();
         fs::create_dir_all(dir.path().join("Tools")).unwrap();
         fs::write(
@@ -1131,26 +1174,117 @@ pub(crate) mod tests {
             "export function help() { return 2; }\n",
         )
         .unwrap();
-        // The config OnceLock is process-global; point it at THIS project (a
-        // repeat set is an ignorable error, but then it may hold another test's
-        // path). Guard: only assert when our config actually took effect.
-        let cfg = codegraph_core::config::init_config(None, dir.path());
-        if cfg
-            .map(|c| c.indexing.include.iter().any(|p| p == "Tools/"))
-            .unwrap_or(false)
-        {
-            let outcome = sync_project_once(dir.path()).unwrap();
-            assert!(
-                outcome
-                    .changed_paths
-                    .contains(&"Tools/helper.ts".to_string())
-            );
-            let store = Store::open(&default_db_path(dir.path()).unwrap()).unwrap();
-            assert!(
-                store.file_by_path("Tools/helper.ts").unwrap().is_some(),
-                "gitignored Tools/ named in include must be indexed on sync"
-            );
+
+        let outcome = sync_project_once(dir.path()).unwrap();
+        assert!(
+            outcome
+                .changed_paths
+                .contains(&"Tools/helper.ts".to_string())
+        );
+        let store = Store::open(&default_db_path(dir.path()).unwrap()).unwrap();
+        assert!(
+            store.file_by_path("Tools/helper.ts").unwrap().is_some(),
+            "gitignored Tools/ named in include must be indexed on sync"
+        );
+    }
+
+    /// A LEGACY `.codegraph/config.toml` must never influence a sync: with the
+    /// same `include` written only there, the gitignored dir stays unindexed.
+    #[test]
+    fn sync_project_once_ignores_a_legacy_project_config() {
+        let dir = TestDir::new("watch-once-legacy-config");
+        fs::write(dir.path().join(".gitignore"), "Tools/\n").unwrap();
+        fs::create_dir_all(dir.path().join(".codegraph")).unwrap();
+        fs::write(
+            dir.path().join(".codegraph/config.toml"),
+            "[app]\nname = \"legacy\"\n\n[indexing]\ninclude = [\"Tools/\"]\n",
+        )
+        .unwrap();
+        fs::create_dir_all(dir.path().join("Tools")).unwrap();
+        fs::write(
+            dir.path().join("Tools/helper.ts"),
+            "export function help() { return 2; }\n",
+        )
+        .unwrap();
+
+        let outcome = sync_project_once(dir.path()).unwrap();
+        assert!(
+            !outcome
+                .changed_paths
+                .contains(&"Tools/helper.ts".to_string()),
+            "a legacy .codegraph/config.toml must not re-include a gitignored dir: {outcome:?}"
+        );
+    }
+
+    /// Two projects synced by ONE process use their OWN current-root configs:
+    /// only the project whose config names `Tools/` indexes its gitignored dir.
+    #[test]
+    fn two_projects_in_one_process_use_their_own_configs() {
+        let alpha = TestDir::new("watch-scope-alpha");
+        let beta = TestDir::new("watch-scope-beta");
+        for project in [alpha.path(), beta.path()] {
+            fs::write(project.join(".gitignore"), "Tools/\n").unwrap();
+            fs::create_dir_all(project.join("Tools")).unwrap();
+            fs::write(
+                project.join("Tools/helper.ts"),
+                "export function help() { return 2; }\n",
+            )
+            .unwrap();
         }
+        write_project_config(
+            alpha.path(),
+            "[app]\nname = \"alpha\"\n\n[indexing]\ninclude = [\"Tools/\"]\n",
+        );
+        write_project_config(beta.path(), "[app]\nname = \"beta\"\n");
+
+        let alpha_outcome = sync_project_once(alpha.path()).unwrap();
+        let beta_outcome = sync_project_once(beta.path()).unwrap();
+        assert!(
+            alpha_outcome
+                .changed_paths
+                .contains(&"Tools/helper.ts".to_string()),
+            "alpha's own include must apply: {alpha_outcome:?}"
+        );
+        assert!(
+            !beta_outcome
+                .changed_paths
+                .contains(&"Tools/helper.ts".to_string()),
+            "beta must not inherit alpha's include: {beta_outcome:?}"
+        );
+    }
+
+    /// A project-declared custom extension is indexed by a sync AND handled by
+    /// the incremental path, proving the current-root `codegraph.json` overrides
+    /// reach both scan and watcher gating.
+    #[test]
+    fn project_extension_overrides_reach_scan_and_incremental_sync() {
+        let dir = TestDir::new("watch-ext-override");
+        let paths = index_paths(dir.path()).expect("resolve project paths");
+        fs::create_dir_all(paths.current_root()).unwrap();
+        fs::write(
+            paths.extension_config(),
+            "{\"extensions\":{\".myext\":\"lua\"}}",
+        )
+        .unwrap();
+        fs::write(dir.path().join("plugin.myext"), "local x = 1\n").unwrap();
+
+        let full = sync_project_once(dir.path()).unwrap();
+        assert!(
+            full.changed_paths.contains(&"plugin.myext".to_string()),
+            "a project-declared extension must be indexed: {full:?}"
+        );
+
+        fs::write(dir.path().join("plugin.myext"), "local x = 2\n").unwrap();
+        let incremental = sync_changed_paths(
+            dir.path(),
+            default_db_path(dir.path()).unwrap(),
+            ["plugin.myext"],
+        )
+        .unwrap();
+        assert_eq!(
+            incremental.files_reindexed, 1,
+            "the incremental path must handle it too: {incremental:?}"
+        );
     }
 
     #[test]
@@ -1267,7 +1401,6 @@ pub(crate) mod tests {
         // Given: two indexed files, one of which is then deleted, over a
         // namespace marked Outdated.
         let dir = TestDir::new("watch-outdated-full");
-        ensure_config(dir.path());
         fs::create_dir_all(dir.path().join("src")).unwrap();
         fs::write(
             dir.path().join("src/alpha.ts"),
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index 1c4eb9c..ad9fe02 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -12,6 +12,10 @@ use anyhow::Result;
 use notify::event::{EventKind, RemoveKind};
 use notify::{Event, RecommendedWatcher, RecursiveMode, Watcher};
 
+use codegraph_core::IndexPaths;
+use codegraph_core::config::Config;
+use codegraph_extract::ExtensionOverrides;
+
 use crate::policy::{WatchPolicy, watch_disabled_reason};
 use crate::sync::{
     SyncOutcome, default_db_path, sync_changed_paths_with_patterns, sync_project_once_with_patterns,
@@ -296,11 +300,15 @@ pub struct WatchOptions {
     /// Called for a non-degrading watch/sync error (e.g. inotify watch-count
     /// exhaustion). May fire more than once; the watcher keeps running.
     pub on_sync_error: Option<NoticeCallback>,
-    /// `codegraph.json`/`config.toml` `include`/`exclude` path patterns (#1063).
-    /// Threaded into the [`WatchPolicy`] and the default incremental-sync fn so
-    /// the watcher's scope matches the scan's. Empty = pre-#1063 behavior.
+    /// The addressed project's `config.toml` `include`/`exclude` path patterns
+    /// (#1063). Threaded into the [`WatchPolicy`] and the default incremental-sync
+    /// fn so the watcher's scope matches the scan's. Empty = pre-#1063 behavior.
     pub include: Vec<String>,
     pub exclude: Vec<String>,
+    /// The addressed project's custom extension→language overrides (its
+    /// current-root `codegraph.json`), so the watcher HANDLES a file the project
+    /// declared as source. Empty = built-in detection only.
+    pub extensions: Arc<ExtensionOverrides>,
     sync_fn: Option<SyncFn>,
     /// Override for the whole-project sync a removed directory escalates to.
     /// Defaults to [`crate::sync::sync_project_once`]; tests inject a counter.
@@ -321,12 +329,35 @@ impl Default for WatchOptions {
             on_sync_error: None,
             include: Vec::new(),
             exclude: Vec::new(),
+            extensions: ExtensionOverrides::empty(),
             sync_fn: None,
             full_sync_fn: None,
         }
     }
 }
 
+impl WatchOptions {
+    /// Build watch options from ONE project's immutable [`Config`] and its own
+    /// extension overrides.
+    ///
+    /// `include`/`exclude` and the debounce window come from that project, and
+    /// `watch.enabled = false` disables watching for it — so two projects served
+    /// by one process can watch different scopes (or one not at all). An explicit
+    /// `CODEGRAPH_WATCH_DEBOUNCE_MS` still wins, keeping the documented env escape
+    /// hatch authoritative over config.
+    #[must_use]
+    pub fn for_project(config: &Config, extensions: Arc<ExtensionOverrides>) -> Self {
+        Self {
+            debounce: debounce_from_env_or(config.watch.debounce_ms),
+            no_watch: !config.watch.enabled,
+            include: config.indexing.include.clone(),
+            exclude: config.indexing.exclude.clone(),
+            extensions,
+            ..Self::default()
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PendingFile {
     pub path: String,
@@ -348,13 +379,31 @@ pub fn start_serve_watcher(
     ProjectWatcher::start(project_root, options)
 }
 
+/// Build [`WatchOptions`] from the ADDRESSED project's own immutable config.
+///
+/// Loads `<current_root>/config.toml` and `<current_root>/codegraph.json` through
+/// the resolved [`IndexPaths`], so a caller that serves several projects in one
+/// process (a shared daemon, a global HTTP server) gives each watcher that
+/// project's include/exclude, debounce, enable flag, and extension overrides —
+/// never another project's and never a process-global value.
+pub fn watch_options_for_project(project_root: impl AsRef<Path>) -> Result<WatchOptions> {
+    let paths = IndexPaths::resolve(
+        project_root.as_ref(),
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )?;
+    let config = Config::load_for_paths(None, &paths)?;
+    let extensions = ExtensionOverrides::load_for_paths(&paths);
+    Ok(WatchOptions::for_project(&config, extensions))
+}
+
 impl ProjectWatcher {
     pub fn start(project_root: impl AsRef<Path>, options: WatchOptions) -> Result<Option<Self>> {
         let project_root = project_root.as_ref().to_path_buf();
         if watch_disabled_reason(&project_root, options.no_watch).is_some() {
             return Ok(None);
         }
-        let policy = WatchPolicy::with_config(&project_root, &options.include, &options.exclude);
+        let policy = WatchPolicy::with_config(&project_root, &options.include, &options.exclude)
+            .with_extension_overrides(Arc::clone(&options.extensions));
         let db_path = match options.db_path.clone() {
             Some(db) => db,
             None => default_db_path(&project_root)?,
@@ -950,10 +999,17 @@ fn maybe_deleted_source(relative: &str) -> bool {
 }
 
 fn debounce_from_env() -> Duration {
+    debounce_from_env_or(2_000)
+}
+
+/// The debounce window: `CODEGRAPH_WATCH_DEBOUNCE_MS` when set (the documented
+/// env escape hatch), else `fallback_ms` (a project's `watch.debounce_ms`, or the
+/// upstream 2000ms default). Always clamped to [100ms, 60s].
+fn debounce_from_env_or(fallback_ms: u64) -> Duration {
     let millis = std::env::var("CODEGRAPH_WATCH_DEBOUNCE_MS")
         .ok()
         .and_then(|raw| raw.parse::<u64>().ok())
-        .unwrap_or(2_000)
+        .unwrap_or(fallback_ms)
         .clamp(100, 60_000);
     Duration::from_millis(millis)
 }
@@ -1043,7 +1099,6 @@ mod tests {
         // full-project sync — the only pass that discovers every absent tracked
         // descendant — instead of an incremental path-scoped sync.
         let dir = crate::sync::tests::TestDir::new("watch-deleted-dir");
-        let _ = codegraph_core::config::init_config(None, dir.path());
         fs::write(dir.path().join(".gitignore"), "Tools/\n").unwrap();
         fs::create_dir_all(dir.path().join("Tools/feature")).unwrap();
         fs::create_dir_all(dir.path().join("src")).unwrap();

From 91024153ca3f29a6acc4275ddef732057492802f Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Sun, 26 Jul 2026 22:25:13 +0800
Subject: [PATCH 36/91] docs(upstream-sync): record project-scoped config
 evidence

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 145 ++++++++++++++++++++++
 1 file changed, 145 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index a6d3ccf..569c1e2 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2833,3 +2833,148 @@ function signature (`build_graph_database`) and nothing else, so the committed
 target hashes
 `7d5ac54647c6bb5a66235a5ca1d8f0a3988d4630078d0db4b891a52e695b2f1f`; the assertions
 the controls exercised are byte-unchanged.
+
+## Batch M item 19 acceptance closure — global HTTP uses project-scoped v2 configs (2026-07-26)
+
+`global_http_uses_project_scoped_v2_configs` is now proven end to end, and the
+process-global configuration singleton is GONE from the codebase. M19's core
+prerequisite (`Config::load_for_paths`, commit `496afa2`) only added the API; this
+slice migrates every production consumer onto it, so configuration is an immutable
+`Arc<Config>` derived from the addressed project's resolved `IndexPaths` and threaded
+explicitly through the operation that uses it.
+
+What replaced the singleton. `codegraph-core::config` keeps exactly two loaders:
+`Config::load_for_paths` (project-scoped: explicit CLI path → `APP_CONFIG` →
+`IndexPaths::config_toml` → defaults) and the new `Config::load_env_or_default`
+(process bootstrap: explicit path → `APP_CONFIG` → defaults, and nothing else).
+`init_config`, `get_config`, `try_get_config`, `Config::discover`, and the `OnceLock`
+are deleted, so no code path can consult a project or CWD legacy
+`.codegraph/config.toml` and none can share one project's settings with another. The
+CLI's `main` now loads the bootstrap config for ONE purpose — the logger level — and
+`Cli::bootstrap_project_root` (which existed only to feed the singleton a project) is
+removed with it. A residual audit over `crates/` finds zero occurrences of
+`get_config`, `try_get_config`, `init_config`, or `Config::discover`.
+
+Extension overrides and the Godot DSL are now explicit values, not discoveries.
+`codegraph-extract::ext_config` becomes an immutable `ExtensionOverrides` loaded from
+`IndexPaths::extension_config`; the ancestor `.codegraph/codegraph.json` tree-walk,
+its process-CWD join, and its mtime cache are all deleted. The value rides
+`ExtractOptions.extensions` (built by the new `ExtractOptions::for_project`) into
+`scan_project`, `extract_project`, the new `extract_file_with_options`, and the new
+`detect_language_with` / `extract_source_with`; `detect_language` and `extract_file`
+remain as the override-free entry points for callers that address no project.
+`codegraph-resolve::frameworks::godot_dsl_config` becomes an immutable
+`GodotDslConfig` (`resourceFields` + `idFields`) loaded the same way, its two
+mtime caches and its own tree-walk deleted, and it reaches `.tres` parsing through a
+new `FrameworkExtractionContext` (project root + config) that replaces the bare
+`project_root: &str` parameter of `FrameworkResolver::extract`. Tolerance is
+preserved exactly: a missing, unreadable, or malformed `codegraph.json` still yields
+empty overrides / an empty DSL config, so an unconfigured project behaves
+byte-identically. Because nothing is cached, an edited config is observed on the next
+load with no mtime dependence — `custom_ext_reload_picks_up_changes_immediately`
+replaces the old sleep-based mtime-recache test and needs no sleep at all.
+
+Sync, watcher, and daemon. `codegraph-watch::sync` gains a per-operation
+`ProjectScope` (the project's `ExtractOptions` + its `FrameworkExtractionContext`),
+loaded once from the addressed `IndexPaths` at the top of every entry point —
+`sync_project_once`, `sync_project_once_with_progress`,
+`sync_project_once_with_patterns` (the watcher's removed-directory escalation),
+`sync_changed_paths`, and `sync_changed_paths_with_patterns` — and threaded into the
+scan, `extract_file_with_options`, `detect_language_with`, the framework pass, and
+`migrate_project`. The transitional `scan_options()` that read the singleton is gone.
+`WatchPolicy` now carries the project's overrides (`with_extension_overrides`) so
+`should_handle_file` agrees with the scan on a project-declared custom extension, and
+the new `WatchOptions::for_project` / `watch_options_for_project` derive
+include/exclude, debounce, and the enable flag from that project's own config (an
+explicit `CODEGRAPH_WATCH_DEBOUNCE_MS` and `--no-watch`/`CODEGRAPH_NO_WATCH` still
+win, so the documented escape hatches stay authoritative). `DaemonOptions.include` /
+`.exclude` are deleted: the daemon loads the project's watch config itself, so a
+daemon can no longer inherit whichever project its launcher started in. Startup
+catch-up is untouched and still runs; it simply goes through the same per-project
+load.
+
+MCP. `CodeGraphEngine` holds the addressed project's `Arc<Config>`, loaded per
+request beside the request-scoped store (M15's ownership model is unchanged), and its
+four on-disk source reads go through one `read_project_source` that refuses a file
+larger than THAT project's `indexing.max_file_size`. This is what makes the
+acceptance observable over HTTP: extraction already skips an oversized file, so
+serving its full text through a graph tool would contradict the project's own policy;
+the refusal reuses the existing unreadable-file rendering, so no new output shape is
+introduced.
+
+Behavioral Red (recorded before implementation, at the real public surface — the
+core API already existed, so an API-absence or compile failure would not qualify).
+Against clean `73833fa` with only the new acceptance target added,
+`cargo test --locked -p codegraph-rs --test global_http_project_scoped_config` fails
+2/2. The project-scoping half fails with
+`alpha's own include must force its gitignored Tools/ in: ["src/app.ts", "src/math.ts", "tools/greeter.py"]`
+— the process-global singleton, bootstrapped from whatever root the CLI resolved,
+never applied alpha's own current-root `include`. The `APP_CONFIG` control fails with
+`without APP_CONFIG beta must use its own config again: ["Tools/helper.ts", "src/app.ts", "src/math.ts", "tools/greeter.py"]`.
+A third, isolated Red run (temporary target, deleted afterwards) drove the ONE global
+HTTP process against clean HEAD and failed with
+`alpha's own 120-byte max_file_size must refuse src/app.ts` while the response body
+carried all ten lines of `src/app.ts` — the direct proof that one HTTP process served
+project A under a configuration A never declared.
+
+Green. `cargo test --locked -p codegraph-rs --test global_http_project_scoped_config`
+**2/2**. The acceptance target proves, in ONE process with `APP_CONFIG` unset and
+hostile LEGACY `.codegraph/config.toml` + `.codegraph/codegraph.json` planted in BOTH
+projects (each asking for the other's `include` and a 7-byte size cap): index and
+sync scope each project by its own config in both directions; the single global
+`serve --http` (no `--path`) honors alpha's 120-byte `max_file_size` and beta's
+default for the SAME `src/app.ts` — requested alpha → beta → alpha, so neither
+ordering nor reuse can hide a bleed; each project's `codegraph_files` listing carries
+only its own tree; and the live watcher auto-syncs a new `Tools/` file for alpha
+while never adopting it for beta. The control
+`app_config_overrides_both_projects_including_codegraph_dir_collision` proves
+`APP_CONFIG` INTENTIONALLY supersedes both projects' own configs, that pointing both
+projects at ONE absolute `CODEGRAPH_DIR` still yields distinct identity-suffixed
+current roots (root, DB, and `config.toml` all differ, both roots exist side by
+side), and that with `APP_CONFIG` unset again each project falls back to its own
+config — the override is process-wide, not sticky state on disk.
+
+Affected-package Green, with `bash scripts/check-workspace-versions.sh` before every
+Cargo batch and `--locked` on every Cargo command: `codegraph-core` **66**,
+`codegraph-extract` **all suites green** (349 unit + 17 integration suites, including
+the rewritten `custom_ext` 7/7 and `coverage_ext_config` 6/6), `codegraph-resolve`
+**642 unit + 12 integration suites**, `codegraph-watch` **98 unit + 2 integration**,
+`codegraph-mcp` **256 unit + integration suites green**, `codegraph-daemon` **all
+suites green**, and `codegraph-rs` **612 tests, 0 failures** across every target.
+Workspace `cargo check --locked --workspace --all-targets` and
+`cargo clippy --locked --workspace --all-targets -- -D warnings` pass.
+
+Existing coverage was migrated, never weakened. `custom_ext`,
+`coverage_ext_config`, `godot_dsl`, `godot_idfields_cwd`, and
+`godot_idfields_determinism` now write the config where production reads it (the
+project's current root) and load it explicitly; each gained a NEW negative control
+proving a legacy `.codegraph/codegraph.json` is never adopted
+(`legacy_codegraph_json_is_never_read`, `custom_ext_ignores_legacy_and_other_projects`,
+`legacy_dsl_config_is_never_adopted`). `codegraph-watch` gained
+`sync_project_once_ignores_a_legacy_project_config`,
+`two_projects_in_one_process_use_their_own_configs`, and
+`project_extension_overrides_reach_scan_and_incremental_sync`; the pre-existing
+`sync_project_once_indexes_gitignored_dir_named_in_include` lost its
+singleton-dependent `if` guard and now asserts unconditionally. The two daemon tests
+that replicated the binary's `init_config` startup no longer need to. No test was
+deleted, skipped, or weakened to pass.
+
+Determinism and caching. No path-keyed cache was introduced: every consumer loads an
+immutable per-operation value, which is why the two deleted mtime caches needed no
+replacement and why the golden byte-stability suite is unaffected (goldens,
+node-ID formula, schema, and extraction semantics are all untouched, and the
+`codegraph-bench` equivalence oracle passes as part of the workspace run).
+
+Limitations, stated honestly. Changed-file LSP diagnostics were attempted and the
+tool again rejected this required external worktree with
+`LSP file path must be inside request cwd`; locked Cargo check/Clippy/tests are the
+fallback and this ledger claims no LSP-clean result. Native Windows/MSVC runtime was
+NOT executed and is not claimed. This slice adds no dependency and changes no schema,
+node-ID formula, extraction or golden byte, `UPSTREAM.md`, or `KNOWN_DIFFS.md`; the
+frozen plan is untouched at SHA-256
+`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450` and `Cargo.lock`
+remains required at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. These evidence
+bytes are written BEFORE repository formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run over
+these exact final bytes; no final Green is claimed until that gate passes.

From df86a5a3699117a13bcbbe3c1856fe76039f0d93 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Mon, 27 Jul 2026 13:35:18 +0800
Subject: [PATCH 37/91] feat(daemon): drain the daemon under uninit through an
 owner-bound control frame

---
 crates/codegraph-cli/src/main.rs              | 127 +++-
 .../tests/batch_m_daemon_uninit_lifecycle.rs  | 568 ++++++++++++++++++
 .../tests/cold_start_handshake.rs             |   8 +-
 crates/codegraph-cli/tests/daemon_idle.rs     |   6 +-
 .../tests/daemon_single_watcher.rs            |   8 +-
 crates/codegraph-cli/tests/daemon_spawn.rs    |  11 +-
 crates/codegraph-cli/tests/daemon_sweep.rs    |   6 +-
 crates/codegraph-cli/tests/lease_lifetime.rs  |  40 +-
 crates/codegraph-cli/tests/proxy_e2e.rs       |   2 +-
 crates/codegraph-daemon/Cargo.toml            |   2 +
 crates/codegraph-daemon/src/control.rs        | 390 ++++++++++++
 crates/codegraph-daemon/src/lib.rs            | 306 ++++++++--
 crates/codegraph-daemon/src/lock.rs           | 170 +++++-
 crates/codegraph-daemon/src/paths.rs          | 239 ++++++--
 crates/codegraph-daemon/src/session.rs        | 225 ++++++-
 crates/codegraph-daemon/src/spawn.rs          |  19 +-
 crates/codegraph-daemon/src/transport.rs      |   3 +-
 .../tests/control_shutdown.rs                 | 308 ++++++++++
 crates/codegraph-daemon/tests/lifecycle.rs    |  24 +-
 crates/codegraph-daemon/tests/regressions.rs  |  23 +-
 crates/codegraph-daemon/tests/rmcp_reap.rs    |   4 +-
 crates/codegraph-daemon/tests/stale_socket.rs |  57 +-
 crates/codegraph-store/src/lib.rs             |   2 +-
 crates/codegraph-store/src/uninit.rs          | 148 ++++-
 crates/codegraph-watch/src/lib.rs             |   3 +-
 crates/codegraph-watch/src/sync.rs            |  98 ++-
 crates/codegraph-watch/src/watcher.rs         | 183 +++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 160 +++++
 28 files changed, 2898 insertions(+), 242 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
 create mode 100644 crates/codegraph-daemon/src/control.rs
 create mode 100644 crates/codegraph-daemon/tests/control_shutdown.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 629d2ad..00ddeab 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1142,10 +1142,19 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
         bail!("refusing to delete .codegraph without --force");
     }
     let paths = index_paths(&project)?;
-    let outcome = codegraph_store::uninit_index(
+    // The drain runs INSIDE uninit's retained exclusive lease, after both durable
+    // markers publish and before any runtime child is removed. It sends the
+    // versioned, project-identity-bound shutdown control frame — which bypasses
+    // data-request lease acquisition, the only way it can be answered while this
+    // command holds the namespace exclusively — and waits for the daemon's
+    // post-drain ACK. No pid is ever signalled: an unresponsive daemon makes uninit
+    // fail closed with the namespace left recoverable `Uninitialized`.
+    let identity = paths.project_identity().to_string();
+    let outcome = codegraph_store::uninit_index_with_drain(
         &paths,
         std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
         || false,
+        || drain_project_daemon(&project, &identity),
     )?;
     println!("Removed CodeGraph from {}", project.display());
     if outcome.legacy_index_present {
@@ -1154,6 +1163,63 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
     Ok(())
 }
 
+/// Daemon-startup gate (frozen plan lines 590-592, 603-604).
+///
+/// ONE bounded shared acquisition validates everything: `Store::open_for_read`
+/// acquires the shared `IndexLease` and, under it, corroborates the FULL `Current`
+/// contract — both owner-bound state slots (so `Future`, `Corrupt`, `Building`,
+/// `Uninitialized`, `Outdated`, and an owner mismatch are all refused), tombstone
+/// absence, database presence, sidecar-freedom, and the exact extraction stamp
+/// read from the checkpointed main-file bytes. Slot phase alone would let a
+/// `Current` slot with a deleted database or a stale stamp publish a rendezvous.
+///
+/// The returned `Store` OWNS that same lease, so retaining it across pid/socket
+/// publication requires no second acquisition: there is no nested lock and no
+/// window between validation and publication for another writer to reclassify.
+fn authorize_daemon_startup(project_root: &Path) -> Result<codegraph_daemon::StartupAuthorization> {
+    let paths = index_paths(project_root)?;
+    match Store::open_for_read(
+        &paths,
+        std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
+        || false,
+    ) {
+        Ok(store) => Ok(Box::new(store)),
+        Err(error) => {
+            // Re-read the observed markers for the operator-facing message only.
+            // The refusal itself is already decided by the gate above.
+            let status = Store::extraction_status(&paths);
+            let tombstone = if paths.tombstone().exists() {
+                "present"
+            } else {
+                "absent"
+            };
+            bail!(
+                "refusing to start a daemon for {}: {error}; index state is {status} and its \
+                 uninitialized tombstone is {tombstone}. No daemon pid, socket, or log was \
+                 published. Run `codegraph init` to rebuild.",
+                project_root.display()
+            )
+        }
+    }
+}
+
+/// Ask this project's daemon (if any) to stop accepting, cancel its watcher lease
+/// loops, drain, remove its own pid/socket, and ACK. `Err(detail)` is the
+/// fail-closed signal; the pid is only ever reported, never signalled.
+fn drain_project_daemon(project: &Path, project_identity: &str) -> Result<(), String> {
+    match codegraph_daemon::request_daemon_shutdown(project, project_identity) {
+        Ok(codegraph_daemon::ShutdownOutcome::NoDaemon) => Ok(()),
+        Ok(codegraph_daemon::ShutdownOutcome::Drained { pid }) => {
+            tracing::info!(pid, "daemon drained and removed its own rendezvous");
+            Ok(())
+        }
+        Ok(codegraph_daemon::ShutdownOutcome::Unresponsive { pid, detail }) => Err(format!(
+            "daemon {pid} did not acknowledge the shutdown control frame ({detail})"
+        )),
+        Err(error) => Err(format!("could not reach this project's daemon: {error:#}")),
+    }
+}
+
 fn cmd_index(path: Option<PathBuf>, force: bool, quiet: bool, verbose: bool) -> Result<()> {
     // Index is the one ordinary CLI surface allowed to retry an authenticated
     // interrupted Building rebuild. Resolve state slots as well as a DB artifact
@@ -1247,9 +1313,9 @@ fn cmd_status(path: Option<PathBuf>, json_output: bool) -> Result<()> {
         .collect::<Vec<_>>();
     let legacy_index_present = !legacy_index_paths.is_empty();
     let daemon_running = daemon_already_running(&project);
-    let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project);
-    let daemon_socket_path = codegraph_daemon::recorded_socket_path(&project);
-    let daemon_log_path = codegraph_daemon::daemon_log_path(&project);
+    let daemon_pid_path = codegraph_daemon::daemon_pid_path(&project)?;
+    let daemon_socket_path = codegraph_daemon::recorded_socket_path(&project)?;
+    let daemon_log_path = codegraph_daemon::daemon_log_path(&project)?;
     let status_open = Store::open_for_status(
         &resolved,
         std::time::Instant::now() + STATUS_LEASE_TIMEOUT,
@@ -1569,6 +1635,25 @@ fn effective_log_level(config_level: &str) -> String {
     config_level.to_string()
 }
 
+/// The project's rendezvous identities for one debug line, or the fail-closed
+/// diagnostic when the configured index root is unsafe. Debug output must never
+/// reconstruct a path the resolver refused.
+fn describe_rendezvous(project_root: &Path) -> String {
+    match (
+        codegraph_daemon::daemon_pid_path(project_root),
+        codegraph_daemon::recorded_socket_path(project_root),
+    ) {
+        (Ok(pid_path), Ok(socket_path)) => {
+            format!(
+                "pid={} socket={}",
+                pid_path.display(),
+                socket_path.display()
+            )
+        }
+        (Err(error), _) | (_, Err(error)) => format!("(unresolved: {error})"),
+    }
+}
+
 fn emit_serve_startup_debug(
     project_root: &Path,
     explicit_path: bool,
@@ -1653,14 +1738,19 @@ fn cmd_serve(
             }
             ServeMode::BeDaemon => {
                 // The daemon loads THIS project's own watch config itself, from
-                // the resolved index root, so nothing is passed down here.
-                return codegraph_daemon::run_foreground(
+                // the resolved index root, so nothing is passed down here. The
+                // startup gate below validates state/owner/tombstone under a
+                // bounded SHARED index lease and RETAINS it across pid/socket
+                // publication, so a concurrent `uninit --force` cannot interleave.
+                let gate = |root: &Path| authorize_daemon_startup(root);
+                return codegraph_daemon::run_foreground_gated(
                     &project_root,
                     codegraph_daemon::DaemonOptions {
                         run_mcp: true,
                         host_pid: codegraph_daemon::host_pid_from_env(),
                         ..Default::default()
                     },
+                    Some(&gate),
                 )
                 .context("running as detached MCP daemon");
             }
@@ -2246,12 +2336,12 @@ fn start_daemon_for_adopted_root(project_root: &Path, no_watch: bool) -> Option<
         return None;
     }
     if daemon_already_running(project_root) {
+        let socket_path = codegraph_daemon::recorded_socket_path(project_root).ok()?;
         tracing::debug!(
-            pid_path = %codegraph_daemon::daemon_pid_path(project_root).display(),
-            socket_path = %codegraph_daemon::recorded_socket_path(project_root).display(),
+            socket_path = %socket_path.display(),
             "adopted-root: attaching to existing daemon"
         );
-        return Some(codegraph_daemon::recorded_socket_path(project_root));
+        return Some(socket_path);
     }
     let Ok(exe) = std::env::current_exe() else {
         return None;
@@ -2263,12 +2353,11 @@ fn start_daemon_for_adopted_root(project_root: &Path, no_watch: bool) -> Option<
                 project = %project_root.display(),
                 "started shared daemon for adopted project root"
             );
+            let socket_path = codegraph_daemon::recorded_socket_path(project_root).ok()?;
             tracing::debug!(
-                pid_path = %codegraph_daemon::daemon_pid_path(project_root).display(),
-                socket_path = %codegraph_daemon::recorded_socket_path(project_root).display(),
+                socket_path = %socket_path.display(),
                 "adopted-root: spawned new daemon"
             );
-            let socket_path = codegraph_daemon::recorded_socket_path(project_root);
             socket_path.exists().then_some(socket_path)
         }
         Err(err) => {
@@ -2419,8 +2508,7 @@ fn serve_spawn_or_proxy(
     explicit_path: bool,
 ) -> Result<()> {
     tracing::debug!(
-        pid_path = %codegraph_daemon::daemon_pid_path(project_root).display(),
-        socket_path = %codegraph_daemon::recorded_socket_path(project_root).display(),
+        rendezvous = %describe_rendezvous(project_root),
         "serve_spawn_or_proxy: begin"
     );
     match cold_start_action(daemon_already_running(project_root)) {
@@ -2452,7 +2540,7 @@ fn serve_spawn_or_proxy(
 /// proxy semantics: `run_proxy` answers `initialize`/`tools/list` locally and
 /// forwards tool calls; its fd half-close / ppid-watchdog teardown is untouched.
 fn proxy_to_running_daemon(project_root: &Path) -> Option<Result<()>> {
-    let socket_path = codegraph_daemon::recorded_socket_path(project_root);
+    let socket_path = codegraph_daemon::recorded_socket_path(project_root).ok()?;
     if !socket_path.exists() {
         tracing::debug!("proxy_to_running_daemon: daemon socket missing; falling back to direct");
         heal_stale_daemon_if_dead(project_root);
@@ -2516,7 +2604,9 @@ fn heal_stale_daemon_if_dead(project_root: &Path) {
 }
 
 fn daemon_already_running(project_root: &Path) -> bool {
-    let pid_path = codegraph_daemon::daemon_pid_path(project_root);
+    let Ok(pid_path) = codegraph_daemon::daemon_pid_path(project_root) else {
+        return false;
+    };
     let Ok(raw) = fs::read_to_string(&pid_path) else {
         return false;
     };
@@ -2531,7 +2621,8 @@ fn poll_for_daemon_socket(project_root: &Path) {
         // Re-read the lock each tick: the daemon rewrites the recorded socket to
         // its bind-fallback choice during startup, so the path can change while
         // we poll (D-Daemon-b).
-        if codegraph_daemon::recorded_socket_path(project_root).exists() {
+        if codegraph_daemon::recorded_socket_path(project_root).is_ok_and(|socket| socket.exists())
+        {
             return;
         }
         std::thread::sleep(DAEMON_SOCKET_POLL_INTERVAL);
@@ -2781,7 +2872,7 @@ mod serve_mode_tests {
 
 fn cmd_unlock(path: Option<PathBuf>) -> Result<()> {
     let project = resolve_required_project(path)?;
-    let daemon_lock = codegraph_daemon::daemon_pid_path(&project);
+    let daemon_lock = codegraph_daemon::daemon_pid_path(&project)?;
     let daemon_removed = daemon_lock.exists() && codegraph_daemon::unlock_project(&project);
     let lock = codegraph_dir(&project)?.join("codegraph.lock");
     if !lock.exists() && !daemon_removed {
diff --git a/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
new file mode 100644
index 0000000..972343d
--- /dev/null
+++ b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
@@ -0,0 +1,568 @@
+//! Batch M item 20 — daemon rendezvous lifecycle under `uninit --force`.
+//!
+//! Frozen plan `upstream-v1.5-portable-fixes.md` lines 590-612 and 787-793:
+//!
+//! * daemon startup takes a bounded SHARED index lease across state/owner/
+//!   tombstone validation AND pid/socket publication, so a concurrent start that
+//!   blocks on `uninit`'s exclusive lease observes the authoritative
+//!   `uninitialized` state slot and the tombstone (published in that order)
+//!   BEFORE it could publish any rendezvous artifact — and therefore publishes
+//!   none;
+//! * `uninit --force` acquires exclusive first, reclassifies, publishes the
+//!   `uninitialized` slot, publishes/ensures the tombstone, and only then sends a
+//!   versioned, project-identity-bound shutdown control frame that BYPASSES
+//!   data-request lease acquisition. The daemon stops accepting, cancels queued/
+//!   running watcher lease loops, drains, removes its owned pid/socket, and ACKs;
+//!   only then does uninit remove the remaining v2 runtime children while still
+//!   holding the same exclusive lease;
+//! * an unresponsive daemon is fail-closed: NO pid is killed, the already
+//!   published durable markers stay, and the namespace classifies recoverable
+//!   `Uninitialized` (never `Corrupt`), continuable by a repeated
+//!   `uninit --force`.
+//!
+//! Determinism. Ordering evidence never comes from a sleep: the concurrent-start
+//! test publishes both durable markers while it still holds the exclusive lease,
+//! and the competing daemon start is stopped at the store's test-only
+//! post-acquisition SHARED-lease barrier, so the "did it publish anything?"
+//! snapshot is taken at an exact checkpoint. The drain tests assert process exit
+//! status and on-disk artifacts, with wall-clock only as a finite upper bound.
+
+use std::fs;
+use std::io::{Read, Write};
+use std::net::{SocketAddr, TcpListener, TcpStream};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, Output, Stdio};
+use std::sync::mpsc::{self, Receiver};
+use std::thread;
+use std::time::{Duration, Instant};
+
+use codegraph_core::IndexPaths;
+use codegraph_daemon::{DaemonLockInfo, encode_lock_info, is_process_alive};
+use codegraph_store::{
+    ExtractionStatus, IndexLease, StatePhase, Store, classify, publish_index_state,
+};
+
+/// Store test-hook barrier envs (compiled into `CARGO_BIN_EXE_codegraph` only
+/// for this package's test builds, never the shipped binary).
+const BARRIER_ADDR: &str = "CODEGRAPH_TEST_LEASE_BARRIER_ADDR";
+const BARRIER_MODE: &str = "CODEGRAPH_TEST_LEASE_BARRIER_MODE";
+
+const WAIT: Duration = Duration::from_secs(20);
+const LEASE_WAIT: Duration = Duration::from_secs(30);
+const TOMBSTONE_BYTES: &[u8] = b"uninitialized\n";
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli lives under crates/")
+        .to_path_buf()
+}
+
+fn copy_tree(source: &Path, target: &Path) {
+    fs::create_dir_all(target).expect("create fixture target");
+    for entry in fs::read_dir(source).expect("read fixture source") {
+        let entry = entry.expect("fixture entry");
+        let destination = target.join(entry.file_name());
+        if entry.path().is_dir() {
+            copy_tree(&entry.path(), &destination);
+        } else {
+            fs::copy(entry.path(), destination).expect("copy fixture file");
+        }
+    }
+}
+
+struct TestProject(PathBuf);
+
+impl TestProject {
+    /// A real `codegraph init` of the mini fixture: a genuinely `Current` v2
+    /// namespace with its permanent lock, both state slots, and a database.
+    fn indexed(label: &str) -> Self {
+        let root = std::env::temp_dir().join(format!(
+            "codegraph-m20-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system clock after epoch")
+                .as_nanos()
+        ));
+        let project = root.join("mini");
+        copy_tree(
+            &workspace_root().join("crates/codegraph-bench/fixtures/mini"),
+            &project,
+        );
+        let output = Command::new(bin())
+            .args(["init", project.to_str().expect("utf-8 project path")])
+            .output()
+            .expect("run codegraph init");
+        assert!(
+            output.status.success(),
+            "init failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        Self(project)
+    }
+
+    fn path(&self) -> &Path {
+        &self.0
+    }
+
+    fn paths(&self) -> IndexPaths {
+        IndexPaths::resolve(&self.0, None).expect("resolve v2 index paths")
+    }
+}
+
+impl Drop for TestProject {
+    fn drop(&mut self) {
+        if let Some(parent) = self.0.parent() {
+            let _ = fs::remove_dir_all(parent);
+        }
+    }
+}
+
+/// Every rendezvous artifact path a daemon could publish: the authoritative v2
+/// identities plus the LEGACY `.codegraph` spellings, so "published nothing"
+/// cannot pass merely because the daemon wrote somewhere else.
+fn rendezvous_candidates(project: &Path, paths: &IndexPaths) -> Vec<PathBuf> {
+    let legacy = project.join(".codegraph");
+    vec![
+        paths.daemon_pid(),
+        paths.daemon_socket(),
+        paths.daemon_log(),
+        legacy.join("daemon.pid"),
+        legacy.join("daemon.sock"),
+        legacy.join("daemon.log"),
+    ]
+}
+
+fn assert_no_rendezvous(project: &Path, paths: &IndexPaths, when: &str) {
+    for candidate in rendezvous_candidates(project, paths) {
+        assert!(
+            fs::symlink_metadata(&candidate).is_err(),
+            "{when}: no daemon rendezvous artifact may exist at {}",
+            candidate.display()
+        );
+    }
+}
+
+/// Deterministic post-acquisition lease barrier: the child stops immediately
+/// after its lease is granted and corroborated, acknowledges arrival on this
+/// listener, and resumes only when released.
+struct LeaseBarrier {
+    address: SocketAddr,
+    arrived: Receiver<(u8, TcpStream)>,
+}
+
+impl LeaseBarrier {
+    fn start() -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind lease barrier listener");
+        let address = listener.local_addr().expect("lease barrier address");
+        let (tx, arrived) = mpsc::channel();
+        thread::spawn(move || {
+            for stream in listener.incoming() {
+                let Ok(mut stream) = stream else { return };
+                let mut marker = [0_u8; 1];
+                if stream.read_exact(&mut marker).is_err() {
+                    return;
+                }
+                if marker[0] == b'C' {
+                    return;
+                }
+                if tx.send((marker[0], stream)).is_err() {
+                    return;
+                }
+            }
+        });
+        Self { address, arrived }
+    }
+
+    fn configure(&self, command: &mut Command, mode: &str) {
+        command
+            .env(BARRIER_ADDR, self.address.to_string())
+            .env(BARRIER_MODE, mode);
+    }
+
+    fn wait(&self, expected: u8) -> TcpStream {
+        match self.arrived.recv_timeout(WAIT) {
+            Ok((actual, stream)) => {
+                assert_eq!(actual, expected, "wrong lease mode reached the barrier");
+                stream
+            }
+            Err(error) => {
+                if let Ok(mut cancel) = TcpStream::connect(self.address) {
+                    let _ = cancel.write_all(b"C");
+                }
+                panic!("lease barrier was not reached before its finite deadline: {error}");
+            }
+        }
+    }
+
+    fn release(mut stream: TcpStream) {
+        stream.write_all(b"R").expect("release the barriered child");
+    }
+}
+
+struct ChildGuard(Option<Child>);
+
+impl ChildGuard {
+    fn new(child: Child) -> Self {
+        Self(Some(child))
+    }
+
+    fn child_mut(&mut self) -> &mut Child {
+        self.0.as_mut().expect("child still owned")
+    }
+
+    /// Wait for exit within a finite bound. The bound is an upper limit only —
+    /// no assertion depends on how long the child took.
+    fn wait_bounded(&mut self, label: &str) -> std::process::ExitStatus {
+        let deadline = Instant::now() + WAIT;
+        loop {
+            match self.child_mut().try_wait().expect("poll child status") {
+                Some(status) => return status,
+                None if Instant::now() < deadline => thread::sleep(Duration::from_millis(20)),
+                None => {
+                    let _ = self.child_mut().kill();
+                    panic!("{label} did not exit within {WAIT:?}");
+                }
+            }
+        }
+    }
+
+    fn finish(mut self, label: &str) -> Output {
+        let status = self.wait_bounded(label);
+        let mut child = self.0.take().expect("child still owned");
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        if let Some(pipe) = child.stdout.as_mut() {
+            let _ = pipe.read_to_end(&mut stdout);
+        }
+        if let Some(pipe) = child.stderr.as_mut() {
+            let _ = pipe.read_to_end(&mut stderr);
+        }
+        // `wait_bounded` already reaped the child through `try_wait`; std caches
+        // that status, so this second wait cannot block and simply proves to the
+        // reader (and to clippy) that no child is left unreaped.
+        let _ = child.wait();
+        Output {
+            status,
+            stdout,
+            stderr,
+        }
+    }
+}
+
+impl Drop for ChildGuard {
+    fn drop(&mut self) {
+        if let Some(child) = self.0.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+/// Spawn the daemon process the way production does when it IS the daemon:
+/// `CODEGRAPH_DAEMON_INTERNAL=1 codegraph serve --mcp --path <project>`.
+fn daemon_command(project: &Path) -> Command {
+    let mut command = Command::new(bin());
+    command
+        .args(["serve", "--mcp", "--path"])
+        .arg(project)
+        .env(codegraph_daemon::CODEGRAPH_DAEMON_INTERNAL, "1")
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    command
+}
+
+fn uninit_force(project: &Path) -> Output {
+    Command::new(bin())
+        .args(["uninit", "--force"])
+        .arg(project)
+        .output()
+        .expect("run codegraph uninit --force")
+}
+
+/// A live process this test owns, used ONLY as the pid recorded in an
+/// unresponsive daemon's rendezvous record: the "no PID kill" assertion needs a
+/// real live pid that production must leave running.
+fn spawn_live_placeholder() -> Child {
+    #[cfg(unix)]
+    let mut command = {
+        let mut command = Command::new("/bin/sleep");
+        command.arg("120");
+        command
+    };
+    #[cfg(windows)]
+    let mut command = {
+        let mut command = Command::new("cmd");
+        command.args(["/C", "ping -n 120 127.0.0.1 > NUL"]);
+        command
+    };
+    command
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn the live placeholder owner process")
+}
+
+fn write_owner_record(paths: &IndexPaths, pid: u32) {
+    let info = DaemonLockInfo {
+        pid,
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        socket_path: paths.daemon_socket(),
+        started_at: 1,
+    };
+    fs::write(
+        paths.daemon_pid(),
+        encode_lock_info(&info).expect("encode owner record"),
+    )
+    .expect("write daemon owner record");
+}
+
+fn assert_recoverable_uninitialized(paths: &IndexPaths, when: &str) {
+    let classification = classify(paths);
+    assert_eq!(
+        classification.status(),
+        &ExtractionStatus::Uninitialized,
+        "{when}: the namespace must classify recoverable Uninitialized, not Corrupt"
+    );
+    assert_eq!(
+        Store::extraction_status(paths),
+        ExtractionStatus::Uninitialized,
+        "{when}: the visible status must agree"
+    );
+    assert!(
+        paths.tombstone().is_file(),
+        "{when}: the tombstone must remain published"
+    );
+    assert!(
+        paths.permanent_lock().is_file(),
+        "{when}: the permanent index.lock is never removed"
+    );
+    assert!(
+        paths.state_slots().iter().all(|slot| slot.is_file()),
+        "{when}: both state slots survive"
+    );
+}
+
+/// Whether a recorded rendezvous name is bound. On Unix the socket IS a
+/// filesystem path; on Windows it is a bare namespaced pipe name (the daemon's
+/// `GenericNamespaced` identity), which has no filesystem existence, so the
+/// published owner record is the only observable there.
+fn recorded_rendezvous_is_bound(socket: &Path) -> bool {
+    #[cfg(unix)]
+    {
+        socket.exists()
+    }
+    #[cfg(not(unix))]
+    {
+        !socket.as_os_str().is_empty()
+    }
+}
+
+fn wait_for_owner_record(paths: &IndexPaths) -> u32 {
+    let deadline = Instant::now() + WAIT;
+    while Instant::now() < deadline {
+        if let Ok(raw) = fs::read_to_string(paths.daemon_pid())
+            && let Some(info) = codegraph_daemon::decode_lock_info(&raw)
+            && info.pid > 0
+            && recorded_rendezvous_is_bound(&info.socket_path)
+        {
+            return info.pid;
+        }
+        thread::sleep(Duration::from_millis(25));
+    }
+    panic!(
+        "the daemon never published its v2 rendezvous at {}",
+        paths.daemon_pid().display()
+    );
+}
+
+#[test]
+fn daemon_start_during_uninit_observes_uninitialized_and_tombstone_before_publish() {
+    let project = TestProject::indexed("concurrent-start");
+    let paths = project.paths();
+    assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+    assert_no_rendezvous(project.path(), &paths, "before any daemon start");
+
+    let barrier = LeaseBarrier::start();
+
+    // The competing daemon start can only observe the namespace AFTER this
+    // exclusive lease is released, so everything published below is ordered
+    // before its first observation without any timing assumption.
+    let uninit_lease =
+        IndexLease::acquire_exclusive_existing(&paths, Instant::now() + LEASE_WAIT, || false)
+            .expect("uninit acquires the exclusive lease first");
+
+    let mut command = daemon_command(project.path());
+    barrier.configure(&mut command, "shared");
+    let daemon = ChildGuard::new(command.spawn().expect("spawn the competing daemon start"));
+
+    // The authoritative durable markers, in the protocol order: the
+    // `uninitialized` state slot first, then the tombstone.
+    publish_index_state(&paths, &uninit_lease, StatePhase::Uninitialized)
+        .expect("publish the authoritative uninitialized slot");
+    assert_eq!(
+        Store::extraction_status(&paths),
+        ExtractionStatus::Uninitialized
+    );
+    fs::write(paths.tombstone(), TOMBSTONE_BYTES).expect("publish the tombstone");
+    assert_no_rendezvous(
+        project.path(),
+        &paths,
+        "while uninit still holds the exclusive lease",
+    );
+
+    drop(uninit_lease);
+
+    // Deterministic checkpoint: the child has just been granted its startup
+    // SHARED lease. Nothing may have been published at or before this point.
+    let released = barrier.wait(b'S');
+    assert_no_rendezvous(
+        project.path(),
+        &paths,
+        "at the daemon's own startup shared-lease checkpoint",
+    );
+    LeaseBarrier::release(released);
+
+    let output = daemon.finish("the competing daemon start");
+    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
+    assert!(
+        !output.status.success(),
+        "a daemon start must refuse an uninitialized namespace; stderr: {stderr}"
+    );
+    assert!(
+        stderr.contains("uninitialized"),
+        "the refusal must name the observed uninitialized state: {stderr}"
+    );
+    assert!(
+        stderr.contains("tombstone"),
+        "the refusal must name the observed tombstone: {stderr}"
+    );
+    assert_no_rendezvous(
+        project.path(),
+        &paths,
+        "after the refused daemon start exited",
+    );
+    assert_recoverable_uninitialized(&paths, "after the refused daemon start");
+}
+
+#[test]
+fn uninit_shutdown_control_drains_without_pid_kill() {
+    let project = TestProject::indexed("shutdown-drain");
+    let paths = project.paths();
+
+    let mut daemon = ChildGuard::new(
+        daemon_command(project.path())
+            .spawn()
+            .expect("spawn daemon"),
+    );
+    let daemon_pid = wait_for_owner_record(&paths);
+    assert!(
+        is_process_alive(daemon_pid),
+        "the published owner pid must be live before uninit runs"
+    );
+
+    // `uninit --force` holds the ONE exclusive lease for its whole lifecycle, so
+    // a shutdown control frame that took a data-request shared lease could never
+    // complete: this command succeeding IS the bypass evidence.
+    let output = uninit_force(project.path());
+    assert!(
+        output.status.success(),
+        "uninit --force must drain the live daemon and complete; stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+
+    let status = daemon.wait_bounded("the drained daemon");
+    assert_eq!(
+        status.code(),
+        Some(0),
+        "the daemon must exit gracefully after ACKing its drain"
+    );
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt as _;
+        assert_eq!(
+            status.signal(),
+            None,
+            "no PID may be signalled: the daemon exits on its own control frame"
+        );
+    }
+
+    assert!(
+        fs::symlink_metadata(paths.daemon_pid()).is_err(),
+        "the daemon removes its own pid record before ACKing"
+    );
+    assert!(
+        fs::symlink_metadata(paths.daemon_socket()).is_err(),
+        "the daemon removes its own socket before ACKing"
+    );
+    assert!(
+        !paths.current_db().is_file(),
+        "uninit removes the v2 database after the ACK, under the same lease"
+    );
+    assert_recoverable_uninitialized(&paths, "after a drained uninit");
+}
+
+#[test]
+fn unresponsive_daemon_leaves_recoverable_uninitialized_without_kill() {
+    let project = TestProject::indexed("unresponsive");
+    let paths = project.paths();
+
+    // A live owner pid with an unreachable rendezvous socket: the daemon can
+    // never ACK, so uninit must fail closed.
+    let mut placeholder = spawn_live_placeholder();
+    let owner_pid = placeholder.id();
+    write_owner_record(&paths, owner_pid);
+    assert!(fs::symlink_metadata(paths.daemon_socket()).is_err());
+
+    let output = uninit_force(project.path());
+    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
+    assert!(
+        !output.status.success(),
+        "an unresponsive daemon must make uninit fail closed; stderr: {stderr}"
+    );
+    assert!(
+        stderr.contains("daemon"),
+        "the incomplete-uninit error must name the undrained daemon: {stderr}"
+    );
+
+    assert!(
+        is_process_alive(owner_pid),
+        "no PID is killed: the recorded owner process must still be running"
+    );
+    assert_recoverable_uninitialized(&paths, "after a fail-closed uninit");
+    assert!(
+        paths.current_db().is_file(),
+        "the fail-closed pass must NOT remove runtime children"
+    );
+    assert!(
+        paths.daemon_pid().is_file(),
+        "the undrained owner record is preserved for the continuation"
+    );
+
+    // Continuation: once the owner is gone, a repeated `uninit --force` resumes
+    // the same cleanup idempotently under a fresh lease and reclassification.
+    let _ = placeholder.kill();
+    let _ = placeholder.wait();
+    let deadline = Instant::now() + WAIT;
+    while is_process_alive(owner_pid) && Instant::now() < deadline {
+        thread::sleep(Duration::from_millis(20));
+    }
+
+    let retry = uninit_force(project.path());
+    assert!(
+        retry.status.success(),
+        "a repeated uninit --force must resume cleanup; stderr: {}",
+        String::from_utf8_lossy(&retry.stderr)
+    );
+    assert!(!paths.current_db().is_file());
+    assert!(fs::symlink_metadata(paths.daemon_pid()).is_err());
+    assert_recoverable_uninitialized(&paths, "after the uninit continuation");
+}
diff --git a/crates/codegraph-cli/tests/cold_start_handshake.rs b/crates/codegraph-cli/tests/cold_start_handshake.rs
index 7cca3b0..fc510bb 100644
--- a/crates/codegraph-cli/tests/cold_start_handshake.rs
+++ b/crates/codegraph-cli/tests/cold_start_handshake.rs
@@ -190,11 +190,11 @@ impl Drop for ServeProcess {
     }
 }
 
-/// Read the live daemon pid recorded under `<project>/.codegraph/daemon.pid`, if
-/// any. The cold path fire-and-forget spawns this daemon; we reap it in teardown
-/// so no orphan `codegraph` daemon process survives the test.
+/// Read the live daemon pid recorded in the project's v2 rendezvous, if any. The
+/// cold path fire-and-forget spawns this daemon; we reap it in teardown so no
+/// orphan `codegraph` daemon process survives the test.
 fn recorded_daemon_pid(project: &Path) -> Option<u32> {
-    let pid_path = codegraph_daemon::daemon_pid_path(project);
+    let pid_path = codegraph_daemon::daemon_pid_path(project).ok()?;
     let raw = fs::read_to_string(&pid_path).ok()?;
     codegraph_daemon::decode_lock_info(&raw)
         .filter(|info| info.pid > 0)
diff --git a/crates/codegraph-cli/tests/daemon_idle.rs b/crates/codegraph-cli/tests/daemon_idle.rs
index a5d42db..95b2d7d 100644
--- a/crates/codegraph-cli/tests/daemon_idle.rs
+++ b/crates/codegraph-cli/tests/daemon_idle.rs
@@ -2,7 +2,7 @@
 //!
 //! The daemon lives in a SEPARATE detached process, so we assert lifecycle via
 //! pid liveness (`is_process_alive`) at timed checkpoints, not via stdout (it is
-//! detached + logs to `.codegraph/daemon.log`). With a multi-second
+//! detached + logs to its v2 `daemon.log`). With a multi-second
 //! `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` the daemon should LINGER while a client is
 //! connected and shortly after the LAST client disconnects, then EXIT once the
 //! idle window elapses with zero clients. De-flake by polling pid liveness
@@ -179,7 +179,7 @@ fn wait_until_gone(pid: u32, timeout: Duration) -> bool {
 #[test]
 fn daemon_idle_exits_after_last_client() {
     let (_dir, project) = indexed_project("exits");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_idle_daemon(&project, "2000");
     let pid = poll_for_daemon_pid(&socket, Duration::from_millis(3000))
@@ -226,7 +226,7 @@ fn daemon_idle_exits_after_last_client() {
 #[test]
 fn daemon_stays_alive_with_active_client() {
     let (_dir, project) = indexed_project("active");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_idle_daemon(&project, "500");
     let pid = poll_for_daemon_pid(&socket, Duration::from_millis(3000))
diff --git a/crates/codegraph-cli/tests/daemon_single_watcher.rs b/crates/codegraph-cli/tests/daemon_single_watcher.rs
index d4b5e66..51b0588 100644
--- a/crates/codegraph-cli/tests/daemon_single_watcher.rs
+++ b/crates/codegraph-cli/tests/daemon_single_watcher.rs
@@ -3,7 +3,7 @@
 //!
 //! The watcher lives in a SEPARATE detached process, so an in-process
 //! `watcher_count()` hook is unreachable. We assert BEHAVIORALLY via the
-//! observable single-sync signal the daemon writes to `.codegraph/daemon.log`
+//! observable single-sync signal the daemon writes to its v2 `daemon.log`
 //! (its stdout/stderr is redirected there by the T2 detached spawn):
 //! `watcher sync #{n}: {files} file(s)`. Exactly ONE such line for a single
 //! change proves one watcher fired once, not N (one per connected client).
@@ -178,7 +178,7 @@ fn wait_until_gone(pid: u32, timeout: Duration) -> bool {
 }
 
 fn daemon_log(project: &Path) -> PathBuf {
-    project.join(".codegraph").join("daemon.log")
+    codegraph_daemon::daemon_log_path(project).expect("resolve the v2 rendezvous log path")
 }
 
 /// Read the daemon.log and count the watcher sync lines.
@@ -224,7 +224,7 @@ fn poll_for_sync_lines(log: &Path, timeout: Duration) -> usize {
 #[test]
 fn daemon_single_watcher_fires_once() {
     let (_dir, project) = indexed_project("fires-once");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
     let log = daemon_log(&project);
 
     let pid = {
@@ -296,7 +296,7 @@ fn daemon_single_watcher_fires_once() {
 #[test]
 fn daemon_no_watch_does_not_autosync() {
     let (_dir, project) = indexed_project("no-watch");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
     let log = daemon_log(&project);
 
     let pid = {
diff --git a/crates/codegraph-cli/tests/daemon_spawn.rs b/crates/codegraph-cli/tests/daemon_spawn.rs
index 4923d45..a71a39f 100644
--- a/crates/codegraph-cli/tests/daemon_spawn.rs
+++ b/crates/codegraph-cli/tests/daemon_spawn.rs
@@ -156,8 +156,9 @@ fn wait_until_gone(pid: u32, timeout: Duration) -> bool {
 #[test]
 fn spawn_detached_daemon_listens_and_survives() {
     let (_dir, project) = indexed_project("survive");
-    let socket = daemon_socket_path(&project);
-    let log = project.join(".codegraph").join("daemon.log");
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
+    let log =
+        codegraph_daemon::daemon_log_path(&project).expect("resolve the v2 rendezvous log path");
 
     // Spawn the detached daemon. The helper must RETURN without waiting.
     spawn_detached_daemon(&bin(), &project, false).expect("spawn_detached_daemon");
@@ -199,7 +200,7 @@ fn spawn_detached_daemon_listens_and_survives() {
 #[test]
 fn spawn_detached_daemon_twice_no_stale_deadlock() {
     let (_dir, project) = indexed_project("twice");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_detached_daemon(&bin(), &project, false).expect("first spawn");
     let pid1 = poll_for_daemon_pid(&socket, Duration::from_millis(2000)).expect("first daemon pid");
@@ -215,7 +216,9 @@ fn spawn_detached_daemon_twice_no_stale_deadlock() {
     // A zombie's lock cannot be cleared by signal-0 liveness, so remove the
     // stale pid/socket directly (the test owns this temp project) to prove the
     // respawn path comes up cleanly rather than deadlocking on a stale lock.
-    let _ = fs::remove_file(codegraph_daemon::daemon_pid_path(&project));
+    let _ = fs::remove_file(
+        codegraph_daemon::daemon_pid_path(&project).expect("resolve the v2 rendezvous pid path"),
+    );
     let _ = fs::remove_file(&socket);
 
     // Second spawn must come up cleanly (reuse-or-respawn), not deadlock.
diff --git a/crates/codegraph-cli/tests/daemon_sweep.rs b/crates/codegraph-cli/tests/daemon_sweep.rs
index f72e783..8899079 100644
--- a/crates/codegraph-cli/tests/daemon_sweep.rs
+++ b/crates/codegraph-cli/tests/daemon_sweep.rs
@@ -7,7 +7,7 @@
 //! keeps being served. With `CODEGRAPH_DAEMON_CLIENT_SWEEP_MS=200` the sweep
 //! fires fast; we poll pid liveness / daemon exit against a clear deadline.
 //!
-//! The daemon is detached + logs to `.codegraph/daemon.log`, so lifecycle is
+//! The daemon is detached + logs to its v2 `daemon.log`, so lifecycle is
 //! asserted via the daemon pid (idle-exit once no live clients remain) — exactly
 //! the observable surface `daemon_idle.rs` uses.
 
@@ -203,7 +203,7 @@ fn spawn_throwaway_child() -> Child {
 #[test]
 fn dead_client_is_swept_and_daemon_idle_exits() {
     let (_dir, project) = indexed_project("dead");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_sweep_daemon(&project);
     let daemon_pid = poll_for_daemon_pid(&socket, Duration::from_millis(3000))
@@ -249,7 +249,7 @@ fn dead_client_is_swept_and_daemon_idle_exits() {
 #[test]
 fn client_without_hello_is_never_swept() {
     let (_dir, project) = indexed_project("nohello");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_sweep_daemon(&project);
     let daemon_pid = poll_for_daemon_pid(&socket, Duration::from_millis(3000))
diff --git a/crates/codegraph-cli/tests/lease_lifetime.rs b/crates/codegraph-cli/tests/lease_lifetime.rs
index 9e3ad0c..1de7bdd 100644
--- a/crates/codegraph-cli/tests/lease_lifetime.rs
+++ b/crates/codegraph-cli/tests/lease_lifetime.rs
@@ -102,16 +102,28 @@ impl LeaseBarrier {
         let listener = TcpListener::bind("127.0.0.1:0").expect("bind lease barrier");
         let address = listener.local_addr().expect("lease barrier address");
         let (arrived_tx, arrived_rx) = mpsc::channel();
+        // Accept EVERY arrival, not just the first: one process can reach the
+        // barrier more than once (a daemon takes a startup shared lease, then a
+        // separate per-request shared lease), and each arrival must be releasable
+        // in order rather than silently dropped.
         std::thread::spawn(move || {
-            let Ok((mut stream, _)) = listener.accept() else {
-                return;
-            };
-            let _ = stream.set_read_timeout(Some(WAIT));
-            let mut marker = [0_u8; 1];
-            if stream.read_exact(&mut marker).is_ok() {
+            for stream in listener.incoming() {
+                let Ok(mut stream) = stream else {
+                    return;
+                };
+                let _ = stream.set_read_timeout(Some(WAIT));
+                let mut marker = [0_u8; 1];
+                if stream.read_exact(&mut marker).is_err() {
+                    return;
+                }
+                if marker[0] == b'C' {
+                    return;
+                }
                 // The receiver can be gone during failure cleanup. That is not a
                 // listener-thread failure and must not add a secondary panic.
-                let _ = arrived_tx.send((marker[0], stream));
+                if arrived_tx.send((marker[0], stream)).is_err() {
+                    return;
+                }
             }
         });
         Self {
@@ -317,7 +329,8 @@ fn send_http_tool_call(stream: &mut TcpStream, address: SocketAddr, project: &Pa
 fn wait_for_daemon(project: &Path) {
     let deadline = Instant::now() + WAIT;
     loop {
-        let socket = codegraph_daemon::recorded_socket_path(project);
+        let socket = codegraph_daemon::recorded_socket_path(project)
+            .expect("resolve the recorded v2 rendezvous socket");
         if codegraph_daemon::attach_to_daemon(&socket).is_ok() {
             return;
         }
@@ -765,11 +778,20 @@ fn reader_lease_spans_stamp_check_through_last_row() {
             .stderr(Stdio::piped());
         barrier.configure(&mut daemon_command, "shared");
         let mut daemon = ChildGuard::new(daemon_command.spawn().expect("spawn daemon reader"));
+        // The daemon's STARTUP shared lease (state/owner/tombstone validation held
+        // across pid/socket publication) reaches the same barrier first. Release it
+        // so the rendezvous can be published; the next arrival is the per-request
+        // lease this test is about, which proves the two acquisitions are distinct.
+        let mut startup_release = barrier.wait(b'S');
+        startup_release
+            .write_all(b"R")
+            .expect("release the daemon startup lease");
         wait_for_daemon(project.path());
 
         let output = Arc::new(Mutex::new(Vec::new()));
         let sink = SharedSink(Arc::clone(&output));
-        let socket = codegraph_daemon::recorded_socket_path(project.path());
+        let socket = codegraph_daemon::recorded_socket_path(project.path())
+            .expect("resolve the recorded v2 rendezvous socket");
         let frames = mcp_frames(project.path());
         let (done_tx, done_rx) = mpsc::channel();
         std::thread::spawn(move || {
diff --git a/crates/codegraph-cli/tests/proxy_e2e.rs b/crates/codegraph-cli/tests/proxy_e2e.rs
index 63ccab4..a4b4120 100644
--- a/crates/codegraph-cli/tests/proxy_e2e.rs
+++ b/crates/codegraph-cli/tests/proxy_e2e.rs
@@ -206,7 +206,7 @@ fn run_proxy_oneshot(
 #[test]
 fn proxy_local_handshake_and_forwarded_tool_call() {
     let (_dir, project) = indexed_project("handshake");
-    let socket = daemon_socket_path(&project);
+    let socket = daemon_socket_path(&project).expect("resolve the v2 rendezvous socket identity");
 
     spawn_detached_daemon(&bin(), &project, false).expect("spawn detached daemon");
     let pid =
diff --git a/crates/codegraph-daemon/Cargo.toml b/crates/codegraph-daemon/Cargo.toml
index 3d8aee3..92132ad 100644
--- a/crates/codegraph-daemon/Cargo.toml
+++ b/crates/codegraph-daemon/Cargo.toml
@@ -22,6 +22,7 @@ tracing = { workspace = true }
 time = { workspace = true }
 # Cross-platform IPC (local socket on unix, named pipe on windows)
 interprocess = { workspace = true }
+codegraph-core = { path = "../codegraph-core" }
 codegraph-mcp = { path = "../codegraph-mcp" }
 codegraph-watch = { path = "../codegraph-watch" }
 tokio = { version = "1", features = [
@@ -30,6 +31,7 @@ tokio = { version = "1", features = [
     "net",
     "time",
     "macros",
+    "sync",
 ] }
 
 # Unix process introspection (getppid, signal-0 liveness) + socket half-close
diff --git a/crates/codegraph-daemon/src/control.rs b/crates/codegraph-daemon/src/control.rs
new file mode 100644
index 0000000..fc3b87b
--- /dev/null
+++ b/crates/codegraph-daemon/src/control.rs
@@ -0,0 +1,390 @@
+//! Versioned, project-identity-bound daemon CONTROL frames.
+//!
+//! Frozen plan lines 593-612. `uninit --force` holds the ONE outer exclusive
+//! index lease for its whole lifecycle, so the frame that asks a live daemon to
+//! shut down must NOT travel the ordinary data-request path — an ordinary request
+//! takes its own SHARED lease and would deadlock against that exclusive holder.
+//!
+//! This module owns both ends of that narrow channel:
+//!
+//! * the wire form — a versioned JSON line carrying the FULL physical project
+//!   identity, so a frame can never drain a daemon serving another project;
+//! * [`request_daemon_shutdown`], the caller side used by `uninit`, which
+//!   connects to the daemon's recorded rendezvous, sends the frame, and waits a
+//!   bounded time for the ACK the daemon writes only AFTER it has stopped
+//!   accepting, cancelled its watcher lease loops, drained, and removed its own
+//!   pid/socket. No PID is ever signalled: an unresponsive daemon returns
+//!   [`ShutdownOutcome::Unresponsive`] and the caller fails closed.
+
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::sync::mpsc;
+use std::time::Duration;
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+use crate::transport::{Rendezvous, connect};
+
+/// Wire version of the control protocol. A daemon refuses any other value rather
+/// than guessing a peer's semantics.
+pub const CONTROL_PROTOCOL: u8 = 1;
+
+/// The only control action this version defines.
+const SHUTDOWN_ACTION: &str = "shutdown";
+
+/// Bounded wall-clock budget for the whole send-and-ACK exchange.
+const SHUTDOWN_ACK_TIMEOUT: Duration = Duration::from_secs(10);
+/// Slack added to the caller-side wait so a daemon that answers right at its own
+/// drain budget is still read, while the wait stays finite everywhere.
+const SHUTDOWN_WAIT_MARGIN: Duration = Duration::from_secs(5);
+
+/// A control frame sent on a fresh rendezvous connection, BEFORE any JSON-RPC.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ControlFrame {
+    /// Discriminator that separates a control frame from a client hello and from
+    /// a JSON-RPC request.
+    pub codegraph_control: u8,
+    /// The requested action.
+    pub action: String,
+    /// The FULL lowercase SHA-256 physical project identity the sender addresses.
+    pub project_identity: String,
+}
+
+impl ControlFrame {
+    #[must_use]
+    pub fn shutdown(project_identity: &str) -> Self {
+        Self {
+            codegraph_control: CONTROL_PROTOCOL,
+            action: SHUTDOWN_ACTION.to_string(),
+            project_identity: project_identity.to_string(),
+        }
+    }
+
+    /// Whether this frame is a shutdown request this build understands, bound to
+    /// `project_identity`. A version, action, or identity mismatch is refused.
+    #[must_use]
+    pub fn authorizes_shutdown_of(&self, project_identity: &str) -> bool {
+        self.codegraph_control == CONTROL_PROTOCOL
+            && self.action == SHUTDOWN_ACTION
+            && self.project_identity == project_identity
+    }
+}
+
+/// The daemon's reply, written only after the drain completed.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ControlAck {
+    pub codegraph_control: u8,
+    pub action: String,
+    /// `true` only when the daemon fully drained and removed its own rendezvous.
+    pub drained: bool,
+}
+
+impl ControlAck {
+    #[must_use]
+    pub fn drained() -> Self {
+        Self::for_drain(true)
+    }
+
+    /// The ack for a completed (`true`) or INCOMPLETE (`false`) drain. An
+    /// incomplete drain must never be reported as success: the caller treats it as
+    /// unresponsive and fails closed.
+    #[must_use]
+    pub fn for_drain(drained: bool) -> Self {
+        Self {
+            codegraph_control: CONTROL_PROTOCOL,
+            action: SHUTDOWN_ACTION.to_string(),
+            drained,
+        }
+    }
+
+    #[must_use]
+    pub fn accepted(&self) -> bool {
+        self.codegraph_control == CONTROL_PROTOCOL && self.action == SHUTDOWN_ACTION && self.drained
+    }
+}
+
+/// Parse one already-read line as a control frame. Anything else is `None`, and
+/// the caller must treat the bytes as ordinary session input.
+///
+/// EVERY line that deserializes as a `ControlFrame` — including
+/// `codegraph_control: 0` and any future version — is recognized here, so it is
+/// routed to explicit authorization and refused. Rejecting a foreign version at
+/// parse time instead would push those bytes into the JSON-RPC executor, which is
+/// exactly the data path a control frame must never reach.
+#[must_use]
+pub fn parse_control_frame(line: &str) -> Option<ControlFrame> {
+    let trimmed = line.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    serde_json::from_str::<ControlFrame>(trimmed).ok()
+}
+
+/// Serialize a frame as one newline-terminated wire line.
+#[must_use]
+pub fn encode_control_line<T: Serialize>(value: &T) -> String {
+    format!(
+        "{}\n",
+        serde_json::to_string(value).unwrap_or_else(|_| String::from("{}"))
+    )
+}
+
+/// What the shutdown exchange established.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ShutdownOutcome {
+    /// No live owner: nothing to drain.
+    NoDaemon,
+    /// The daemon ACKed after draining and removing its own pid/socket.
+    Drained { pid: u32 },
+    /// A live owner was recorded but never ACKed within the bounded budget. The
+    /// caller MUST fail closed; the pid is reported, never signalled.
+    Unresponsive { pid: u32, detail: String },
+}
+
+/// Ask the daemon recorded for `project_root` to shut down, and wait a bounded
+/// time for its post-drain ACK.
+///
+/// `project_identity` is the full physical identity from `IndexPaths`, so the
+/// frame authorizes draining ONLY the daemon serving this exact namespace.
+pub fn request_daemon_shutdown(
+    project_root: &Path,
+    project_identity: &str,
+) -> Result<ShutdownOutcome> {
+    let pid_path = crate::paths::daemon_pid_path(project_root)?;
+    let Some(info) = std::fs::read_to_string(&pid_path)
+        .ok()
+        .and_then(|raw| crate::lock::decode_lock_info(&raw))
+        .filter(|info| info.pid > 0)
+    else {
+        return Ok(ShutdownOutcome::NoDaemon);
+    };
+    if !crate::process::is_process_alive(info.pid) {
+        return Ok(ShutdownOutcome::NoDaemon);
+    }
+    let socket_path = if info.socket_path.as_os_str().is_empty() {
+        crate::paths::daemon_socket_path(project_root)?
+    } else {
+        info.socket_path.clone()
+    };
+
+    match bounded_exchange_shutdown(socket_path, project_identity.to_string()) {
+        Ok(()) => Ok(ShutdownOutcome::Drained { pid: info.pid }),
+        Err(detail) => Ok(ShutdownOutcome::Unresponsive {
+            pid: info.pid,
+            detail,
+        }),
+    }
+}
+
+/// Run the exchange on a worker thread and wait for it with a monotonic channel
+/// deadline.
+///
+/// The per-socket send/recv timeouts `interprocess` exposes are Unix-only, so a
+/// wedged Windows named pipe would otherwise block forever. Bounding the WAIT
+/// itself (not the socket) is finite on every supported platform; the abandoned
+/// worker owns only its own connection and never touches index bytes.
+fn bounded_exchange_shutdown(socket_path: PathBuf, project_identity: String) -> Result<(), String> {
+    let (tx, rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        let result =
+            exchange_shutdown(&socket_path, &project_identity).map_err(|e| format!("{e:#}"));
+        let _ = tx.send(result);
+    });
+    match rx.recv_timeout(SHUTDOWN_ACK_TIMEOUT + SHUTDOWN_WAIT_MARGIN) {
+        Ok(result) => result,
+        Err(mpsc::RecvTimeoutError::Timeout) => Err(format!(
+            "no drain acknowledgement within {:?}",
+            SHUTDOWN_ACK_TIMEOUT + SHUTDOWN_WAIT_MARGIN
+        )),
+        Err(mpsc::RecvTimeoutError::Disconnected) => {
+            Err("the shutdown exchange ended without a result".to_string())
+        }
+    }
+}
+
+fn exchange_shutdown(socket_path: &Path, project_identity: &str) -> Result<()> {
+    let rendezvous = Rendezvous::from_socket_path(socket_path);
+    let stream = connect(&rendezvous)
+        .with_context(|| format!("connecting to daemon socket {}", socket_path.display()))?;
+    #[cfg(unix)]
+    {
+        use interprocess::local_socket::traits::Stream as _;
+        stream
+            .set_recv_timeout(Some(SHUTDOWN_ACK_TIMEOUT))
+            .context("bounding the daemon shutdown ACK wait")?;
+        stream
+            .set_send_timeout(Some(SHUTDOWN_ACK_TIMEOUT))
+            .context("bounding the daemon shutdown send")?;
+    }
+
+    // The daemon writes its versioned hello on accept; consume that line first so
+    // the ACK read below cannot mistake it for the reply.
+    let mut reader = BufReader::new(&stream);
+    let mut hello = String::new();
+    reader
+        .read_line(&mut hello)
+        .context("reading the daemon hello before sending a control frame")?;
+
+    let frame = ControlFrame::shutdown(project_identity);
+    (&stream)
+        .write_all(encode_control_line(&frame).as_bytes())
+        .context("sending the shutdown control frame")?;
+    (&stream).flush().context("flushing the control frame")?;
+
+    let mut ack_line = String::new();
+    reader
+        .read_line(&mut ack_line)
+        .context("waiting for the daemon drain ACK")?;
+    let ack: ControlAck = serde_json::from_str(ack_line.trim())
+        .with_context(|| format!("decoding the daemon drain ACK {:?}", ack_line.trim()))?;
+    anyhow::ensure!(
+        ack.accepted(),
+        "daemon reported an incomplete drain (drained={})",
+        ack.drained
+    );
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const IDENTITY: &str = "a1b2c3";
+
+    #[test]
+    fn shutdown_frame_round_trips_and_binds_the_project_identity() {
+        let frame = ControlFrame::shutdown(IDENTITY);
+        let line = encode_control_line(&frame);
+        assert!(line.ends_with('\n'));
+        let parsed = parse_control_frame(&line).expect("a control frame parses");
+        assert_eq!(parsed, frame);
+        assert!(parsed.authorizes_shutdown_of(IDENTITY));
+        assert!(
+            !parsed.authorizes_shutdown_of("another-project"),
+            "a frame must never authorize draining another project's daemon"
+        );
+    }
+
+    #[test]
+    fn a_client_hello_or_jsonrpc_line_is_not_a_control_frame() {
+        assert!(parse_control_frame("").is_none());
+        assert!(parse_control_frame("   \n").is_none());
+        assert!(parse_control_frame("{\"hostPid\":4242}").is_none());
+        assert!(parse_control_frame("{\"jsonrpc\":\"2.0\",\"id\":1}").is_none());
+        assert!(parse_control_frame("not json").is_none());
+    }
+
+    #[test]
+    fn a_foreign_protocol_version_is_never_authorized() {
+        for version in [0, CONTROL_PROTOCOL + 1, u8::MAX] {
+            let frame = ControlFrame {
+                codegraph_control: version,
+                action: SHUTDOWN_ACTION.to_string(),
+                project_identity: IDENTITY.to_string(),
+            };
+            // Recognized as a control frame (so it is refused explicitly) and
+            // never authorized.
+            let parsed = parse_control_frame(&encode_control_line(&frame))
+                .expect("every control-shaped line is recognized, not routed to JSON-RPC");
+            assert_eq!(parsed.codegraph_control, version);
+            assert!(!parsed.authorizes_shutdown_of(IDENTITY));
+        }
+        let frame = ControlFrame {
+            codegraph_control: CONTROL_PROTOCOL + 1,
+            action: SHUTDOWN_ACTION.to_string(),
+            project_identity: IDENTITY.to_string(),
+        };
+        assert!(!frame.authorizes_shutdown_of(IDENTITY));
+        let other_action = ControlFrame {
+            codegraph_control: CONTROL_PROTOCOL,
+            action: "reindex".to_string(),
+            project_identity: IDENTITY.to_string(),
+        };
+        assert!(!other_action.authorizes_shutdown_of(IDENTITY));
+    }
+
+    #[test]
+    fn only_a_drained_matching_ack_is_accepted() {
+        assert!(ControlAck::drained().accepted());
+        assert!(ControlAck::for_drain(true).accepted());
+        let undrained = ControlAck::for_drain(false);
+        assert!(
+            !undrained.accepted(),
+            "an incomplete drain must never be accepted as success"
+        );
+        assert_eq!(
+            undrained,
+            ControlAck {
+                codegraph_control: CONTROL_PROTOCOL,
+                action: SHUTDOWN_ACTION.to_string(),
+                drained: false,
+            }
+        );
+        let wrong_version = ControlAck {
+            codegraph_control: CONTROL_PROTOCOL + 1,
+            action: SHUTDOWN_ACTION.to_string(),
+            drained: true,
+        };
+        assert!(!wrong_version.accepted());
+    }
+
+    #[test]
+    fn no_recorded_owner_means_there_is_nothing_to_drain() {
+        let project = std::env::temp_dir().join(format!(
+            "cg-control-none-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&project).unwrap();
+        let outcome = request_daemon_shutdown(&project, IDENTITY).expect("probe an idle project");
+        assert_eq!(outcome, ShutdownOutcome::NoDaemon);
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn a_live_owner_with_an_unreachable_socket_is_unresponsive_and_unsignalled() {
+        let project = std::env::temp_dir().join(format!(
+            "cg-control-unresponsive-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&project).unwrap();
+        let project = project.canonicalize().unwrap();
+        let paths = crate::paths::index_paths(&project).expect("resolve v2 paths");
+        std::fs::create_dir_all(paths.current_root()).unwrap();
+        // This process is the live "owner": a real live pid whose rendezvous
+        // socket was never bound.
+        let info = crate::lock::DaemonLockInfo {
+            pid: std::process::id(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            socket_path: paths.daemon_socket(),
+            started_at: 1,
+        };
+        std::fs::write(
+            paths.daemon_pid(),
+            crate::lock::encode_lock_info(&info).unwrap(),
+        )
+        .unwrap();
+
+        let outcome =
+            request_daemon_shutdown(&project, IDENTITY).expect("an unreachable socket is data");
+        match outcome {
+            ShutdownOutcome::Unresponsive { pid, .. } => assert_eq!(pid, std::process::id()),
+            other => panic!("expected an unresponsive outcome, got {other:?}"),
+        }
+        assert!(
+            crate::process::is_process_alive(std::process::id()),
+            "the recorded owner is never signalled"
+        );
+        let _ = std::fs::remove_dir_all(&project);
+    }
+}
diff --git a/crates/codegraph-daemon/src/lib.rs b/crates/codegraph-daemon/src/lib.rs
index 2ee6473..5efb68d 100644
--- a/crates/codegraph-daemon/src/lib.rs
+++ b/crates/codegraph-daemon/src/lib.rs
@@ -5,6 +5,7 @@
 //! watchdogs, graceful shutdown, and stale-lock recovery. It deliberately does
 //! not implement task-25 file watching.
 
+pub mod control;
 pub mod http_registry;
 mod lock;
 mod paths;
@@ -22,6 +23,10 @@ use std::thread::{self, JoinHandle};
 use std::time::Duration;
 
 use anyhow::{Context, Result, bail};
+pub use control::{
+    CONTROL_PROTOCOL, ControlAck, ControlFrame, ShutdownOutcome, parse_control_frame,
+    request_daemon_shutdown,
+};
 pub use lock::{
     AcquireResult, DaemonLockInfo, clear_stale_daemon_lock, clear_stale_daemon_socket,
     decode_lock_info, encode_lock_info, recorded_socket_path, try_acquire_daemon_lock,
@@ -37,14 +42,20 @@ pub use session::{SessionRegistry, read_daemon_hello, run_session_recv};
 pub use spawn::{CODEGRAPH_HTTP_DETACH_INTERNAL, spawn_detached_daemon, spawn_detached_http};
 use tracing::{debug, info, warn};
 
-use crate::lock::{cleanup_owned_lock, rewrite_lock_socket_path};
-use crate::paths::codegraph_dir;
-use crate::session::serve_session_async;
+use crate::lock::{cleanup_owned_rendezvous, rewrite_lock_socket_path};
+use crate::session::{ControlHandle, ShutdownRequest, serve_session_async};
 use crate::transport::{AsyncListener, Rendezvous, bind_tokio, connect};
 
 const DEFAULT_WATCHDOG_INTERVAL: Duration = Duration::from_millis(500);
 const ACCEPT_POLL_INTERVAL: Duration = Duration::from_millis(250);
 
+/// Bounded budget for the post-control-frame drain: cancelled watcher/catch-up
+/// lease loops must exit and active sessions must close before the daemon removes
+/// its own rendezvous and ACKs. Exceeding it is reported and the daemon still
+/// tears its own rendezvous down, so the caller never has to signal a pid.
+const DRAIN_TIMEOUT: Duration = Duration::from_secs(10);
+const DRAIN_POLL_INTERVAL: Duration = Duration::from_millis(10);
+
 /// Env var name: when set to `"1"`, the process re-invoked by the launcher IS
 /// the detached daemon and must listen+serve, never re-spawn.
 pub const CODEGRAPH_DAEMON_INTERNAL: &str = "CODEGRAPH_DAEMON_INTERNAL";
@@ -166,6 +177,12 @@ pub struct DaemonOptions {
     /// project (N client inotify sets collapse to 1). Honors
     /// `watch_disabled_reason` (e.g. `CODEGRAPH_NO_WATCH=1`).
     pub watch: bool,
+    /// Bounded budget for the post-shutdown drain: how long the daemon waits for
+    /// its cancelled watcher/catch-up lease loops and its actively-closed data
+    /// sessions to finish before reporting an INCOMPLETE drain. Exceeding it never
+    /// acknowledges success, so the caller fails closed. Defaults to
+    /// [`DRAIN_TIMEOUT`].
+    pub drain_budget: Duration,
 }
 
 impl Default for DaemonOptions {
@@ -176,10 +193,26 @@ impl Default for DaemonOptions {
             watchdog_interval: DEFAULT_WATCHDOG_INTERVAL,
             run_mcp: true,
             watch: true,
+            drain_budget: DRAIN_TIMEOUT,
         }
     }
 }
 
+/// The capability a startup gate returns and the daemon RETAINS across
+/// pid/socket publication (frozen plan lines 590-592: startup takes a shared
+/// index lease across state/owner/tombstone validation AND publication, and
+/// releases it only afterwards).
+///
+/// It is opaque here on purpose: the gate lives in the crate that owns the index
+/// state protocol, so this crate cannot reclassify a namespace itself or reach a
+/// store API behind the gate's back.
+pub type StartupAuthorization = Box<dyn std::any::Any + Send>;
+
+/// A startup gate: validate `project_root`'s namespace and return the capability
+/// to retain until the rendezvous is published. `Err` refuses the start, and the
+/// daemon then publishes NOTHING.
+pub type StartupGate<'a> = &'a (dyn Fn(&Path) -> Result<StartupAuthorization> + Sync);
+
 #[derive(Debug)]
 pub enum StartOrAttach {
     Started(DaemonHandle),
@@ -245,14 +278,41 @@ impl Drop for DaemonHandle {
 pub fn start_or_attach(
     project_root: impl AsRef<Path>,
     options: DaemonOptions,
+) -> Result<StartOrAttach> {
+    start_or_attach_gated(project_root, options, None)
+}
+
+/// [`start_or_attach`] with the caller-supplied startup gate.
+///
+/// The gate runs BEFORE the pid record is claimed and its returned capability is
+/// held until the socket is bound and the chosen rendezvous persisted, so a
+/// concurrent `uninit --force` can never interleave its own exclusive-lease work
+/// between validation and publication. A refused gate publishes nothing at all.
+pub fn start_or_attach_gated(
+    project_root: impl AsRef<Path>,
+    options: DaemonOptions,
+    gate: Option<StartupGate<'_>>,
 ) -> Result<StartOrAttach> {
     let project_root = project_root.as_ref().to_path_buf();
+    let authorization = match gate {
+        Some(gate) => Some(gate(&project_root)?),
+        None => None,
+    };
     match try_acquire_daemon_lock(&project_root)? {
         AcquireResult::Acquired { pid_path, info } => {
-            let handle = start_with_lock(project_root, pid_path, info.socket_path, options)?;
+            let handle = start_with_lock(
+                project_root,
+                pid_path,
+                info.socket_path,
+                options,
+                authorization,
+            )?;
             Ok(StartOrAttach::Started(handle))
         }
         AcquireResult::Taken { existing, pid_path } => {
+            // Nothing will be published on this path, so release the startup
+            // capability before any recursion re-acquires it.
+            drop(authorization);
             if let Some(info) = existing {
                 if let Ok(client) = attach_to_daemon(&info.socket_path) {
                     return Ok(StartOrAttach::Attached(client));
@@ -260,7 +320,7 @@ pub fn start_or_attach(
                 if !clear_stale_daemon_lock(&pid_path, Some(info.pid)) {
                     bail!("daemon already running for this project (pid {})", info.pid);
                 }
-                return start_or_attach(project_root, options);
+                return start_or_attach_gated(project_root, options, gate);
             }
             if !clear_stale_daemon_lock(&pid_path, None) {
                 bail!(
@@ -268,13 +328,22 @@ pub fn start_or_attach(
                     pid_path.display()
                 );
             }
-            start_or_attach(project_root, options)
+            start_or_attach_gated(project_root, options, gate)
         }
     }
 }
 
 pub fn run_foreground(project_root: impl AsRef<Path>, options: DaemonOptions) -> Result<()> {
-    match start_or_attach(project_root, options)? {
+    run_foreground_gated(project_root, options, None)
+}
+
+/// [`run_foreground`] under a startup gate; see [`start_or_attach_gated`].
+pub fn run_foreground_gated(
+    project_root: impl AsRef<Path>,
+    options: DaemonOptions,
+    gate: Option<StartupGate<'_>>,
+) -> Result<()> {
+    match start_or_attach_gated(project_root, options, gate)? {
         StartOrAttach::Started(handle) => handle.wait(),
         StartOrAttach::Attached(client) => {
             bail!("daemon already running at {}", client.socket_path.display())
@@ -298,9 +367,14 @@ fn start_with_lock(
     pid_path: PathBuf,
     socket_path: PathBuf,
     options: DaemonOptions,
+    authorization: Option<StartupAuthorization>,
 ) -> Result<DaemonHandle> {
-    fs::create_dir_all(codegraph_dir(&project_root))
-        .with_context(|| format!("creating {}", codegraph_dir(&project_root).display()))?;
+    let rendezvous_dir = paths::rendezvous_dir(&project_root)?;
+    fs::create_dir_all(&rendezvous_dir)
+        .with_context(|| format!("creating {}", rendezvous_dir.display()))?;
+    let project_identity = paths::index_paths(&project_root)?
+        .project_identity()
+        .to_string();
 
     // The async interprocess Listener must be created inside a tokio runtime
     // context, so build the runtime here and bind within it. The runtime is
@@ -317,6 +391,9 @@ fn start_with_lock(
     if let Err(err) = rewrite_lock_socket_path(&pid_path, &socket_path) {
         debug!(error = %err, "could not persist chosen daemon socket into lock");
     }
+    // The rendezvous is published; the startup capability is released here, and
+    // every later data request takes its own shared lease.
+    drop(authorization);
     let registry = SessionRegistry::default();
     let shutdown = Arc::new(AtomicBool::new(false));
     let thread_registry = registry.clone();
@@ -329,6 +406,7 @@ fn start_with_lock(
         runtime.block_on(run_accept_loop_async(
             listener,
             thread_project,
+            project_identity,
             thread_socket,
             thread_pid_path,
             thread_registry,
@@ -349,19 +427,19 @@ fn start_with_lock(
 /// remaining unix fallback candidates (`f83a1ec`). On non-unix there is a single
 /// namespaced pipe name, so the chain is just `[preferred]`.
 #[cfg(unix)]
-fn socket_candidate_chain(project_root: &Path, preferred: PathBuf) -> Vec<PathBuf> {
+fn socket_candidate_chain(project_root: &Path, preferred: PathBuf) -> Result<Vec<PathBuf>> {
     let mut candidates = vec![preferred];
-    for candidate in paths::daemon_socket_candidates(project_root) {
+    for candidate in paths::daemon_socket_candidates(project_root)? {
         if !candidates.contains(&candidate) {
             candidates.push(candidate);
         }
     }
-    candidates
+    Ok(candidates)
 }
 
 #[cfg(not(unix))]
-fn socket_candidate_chain(_project_root: &Path, preferred: PathBuf) -> Vec<PathBuf> {
-    vec![preferred]
+fn socket_candidate_chain(_project_root: &Path, preferred: PathBuf) -> Result<Vec<PathBuf>> {
+    Ok(vec![preferred])
 }
 
 /// Bind the daemon listener, falling through the deterministic socket-candidate
@@ -371,7 +449,7 @@ fn socket_candidate_chain(_project_root: &Path, preferred: PathBuf) -> Vec<PathB
 /// socket that actually bound. Errors only when EVERY candidate fails. Must be
 /// called inside a tokio runtime context (the async listener requires it).
 fn bind_with_fallback(project_root: &Path, preferred: PathBuf) -> Result<(AsyncListener, PathBuf)> {
-    let candidates = socket_candidate_chain(project_root, preferred);
+    let candidates = socket_candidate_chain(project_root, preferred)?;
 
     let mut last_err = None;
     for socket_path in candidates {
@@ -406,6 +484,7 @@ fn bind_with_fallback(project_root: &Path, preferred: PathBuf) -> Result<(AsyncL
 async fn run_accept_loop_async(
     listener: AsyncListener,
     project_root: PathBuf,
+    project_identity: String,
     socket_path: PathBuf,
     pid_path: PathBuf,
     registry: SessionRegistry,
@@ -430,12 +509,24 @@ async fn run_accept_loop_async(
     let mut first_connection_seen = false;
     info!(project = %project_root.display(), socket = %socket_path.display(), "daemon started");
 
+    // ONE cooperative cancellation shared by the watcher's lease loops and the
+    // startup catch-up, so a shutdown control frame can refuse queued loops and
+    // interrupt a running one instead of waiting out its lease budget.
+    let lease_loops = codegraph_watch::SyncCancellation::new();
+
     // ONE shared watcher per daemon process. Bound to a local so
     // its `Drop` stops the watch thread on shutdown. NEVER move this into
     // the session task: per-connection would spawn N watchers.
-    let _watcher = start_project_watcher(&project_root, &options);
+    let watcher = start_project_watcher(&project_root, &options, &lease_loops);
 
-    let _catch_up_done = spawn_catch_up(&project_root);
+    let _catch_up_done = spawn_catch_up(&project_root, &lease_loops);
+
+    // The control channel is separate from the request path by construction: a
+    // session that reads a control frame never builds an engine and never takes a
+    // data-request shared lease.
+    let (control_tx, mut control_rx) = tokio::sync::mpsc::unbounded_channel::<ShutdownRequest>();
+    let control = ControlHandle::new(&project_identity, control_tx);
+    let mut pending_shutdown: Option<ShutdownRequest> = None;
 
     // Tick cadence for lifecycle checks: the client-sweep interval clamped to a
     // responsive ceiling so idle-exit / supervision loss are observed promptly
@@ -457,6 +548,7 @@ async fn run_accept_loop_async(
                     let session_socket = socket_display.clone();
                     let session_registry = registry.clone();
                     let run_mcp = options.run_mcp;
+                    let session_control = control.clone();
                     tokio::spawn(async move {
                         if let Err(err) = serve_session_async(
                             stream,
@@ -464,6 +556,7 @@ async fn run_accept_loop_async(
                             session_socket,
                             session_registry,
                             run_mcp,
+                            Some(session_control),
                         )
                         .await
                         {
@@ -475,6 +568,11 @@ async fn run_accept_loop_async(
                     break Some(anyhow::Error::new(err).context("accepting daemon connection"));
                 }
             },
+            Some(request) = control_rx.recv() => {
+                info!(project = %project_root.display(), "daemon shutting down on control frame");
+                pending_shutdown = Some(request);
+                break None;
+            }
             _ = ticker.tick() => {
                 let state = SupervisionState {
                     original_ppid,
@@ -516,10 +614,52 @@ async fn run_accept_loop_async(
         }
     };
 
-    cleanup_owned_lock(&pid_path, std::process::id());
-    #[cfg(unix)]
-    if let Some(stale) = Rendezvous::from_socket_path(&socket_path).cleanup_path() {
-        let _ = fs::remove_file(stale);
+    // Accepting has stopped (the loop exited and `listener` is dropped below with
+    // this scope). Drain in the plan's order: signal the watcher and cancel every
+    // queued/running lease loop, actively close every data session, wait for both
+    // to finish within the bounded budget, remove the rendezvous this process owns,
+    // and only then answer with the ACTUAL drain result.
+    //
+    // `begin_shutdown` deliberately does NOT join: a running sync can hold the
+    // event-loop thread for a whole extraction pass, so joining here would block
+    // past the budget and make the "incomplete drain" answer unreachable.
+    lease_loops.cancel();
+    if let Some(watcher) = &watcher {
+        watcher.begin_shutdown();
+    }
+    registry.close_all_sessions();
+    let watcher_done = {
+        let watcher = watcher.as_ref();
+        move || watcher.is_none_or(codegraph_watch::ProjectWatcher::is_finished)
+    };
+    let drained = drain_watcher_loops_and_sessions(
+        watcher_done,
+        &lease_loops,
+        &registry,
+        options.drain_budget,
+    )
+    .await;
+    // Past the deadline the watcher thread is already cancelled and exits on its
+    // own; detach it so no destructor re-introduces an unbounded join AFTER the
+    // incomplete result was computed.
+    match watcher {
+        Some(watcher) if drained => watcher.stop(),
+        Some(watcher) => watcher.detach(),
+        None => {}
+    }
+    cleanup_owned_rendezvous(&pid_path, &socket_path, std::process::id());
+    if let Some(request) = pending_shutdown {
+        if !drained {
+            warn!(
+                "daemon drain exceeded its bounded budget; reporting an INCOMPLETE drain so the \
+                 caller fails closed"
+            );
+        }
+        // The reply is written by the session task, which still owns its socket;
+        // wait for it so this runtime is not torn down mid-write.
+        if request.ack.send(drained).is_ok() {
+            let _ = tokio::time::timeout(DRAIN_TIMEOUT, request.done).await;
+        }
     }
     info!(project = %project_root.display(), "daemon stopped");
     match stop_reason {
@@ -528,6 +668,29 @@ async fn run_accept_loop_async(
     }
 }
 
+/// Wait for the watcher's event loop to finish, every cancellation-aware lease
+/// loop to exit, and every active session to close — all bounded by `budget` and
+/// observed by POLLING, never by a blocking join. Returns whether all three
+/// reached completion; `false` is reported to the caller as an INCOMPLETE drain
+/// and never acknowledged as success.
+async fn drain_watcher_loops_and_sessions(
+    watcher_done: impl Fn() -> bool,
+    lease_loops: &codegraph_watch::SyncCancellation,
+    registry: &SessionRegistry,
+    budget: Duration,
+) -> bool {
+    let deadline = tokio::time::Instant::now() + budget;
+    loop {
+        if watcher_done() && lease_loops.active_syncs() == 0 && registry.active_count() == 0 {
+            return true;
+        }
+        if tokio::time::Instant::now() >= deadline {
+            return false;
+        }
+        tokio::time::sleep(DRAIN_POLL_INTERVAL).await;
+    }
+}
+
 fn sweep_dead_clients(registry: &SessionRegistry) {
     for id in registry.dead_session_ids(is_process_alive) {
         debug!(session = id, "sweeping session whose host pid is dead");
@@ -551,6 +714,7 @@ fn backstop_should_exit(registry: &SessionRegistry, is_alive: impl Fn(u32) -> bo
 fn start_project_watcher(
     project_root: &Path,
     options: &DaemonOptions,
+    lease_loops: &codegraph_watch::SyncCancellation,
 ) -> Option<codegraph_watch::ProjectWatcher> {
     let counter = Arc::new(AtomicUsize::new(0));
     // The watcher's scope comes from THIS project's own config (include/exclude,
@@ -568,6 +732,7 @@ fn start_project_watcher(
     };
     // An explicit `--no-watch` (or `CODEGRAPH_NO_WATCH`) still wins over config.
     watch_options.no_watch = watch_options.no_watch || !options.watch;
+    watch_options = watch_options.with_cancellation(lease_loops.clone());
     watch_options.on_sync_complete =
         Some(Arc::new(move |outcome: codegraph_watch::SyncOutcome| {
             let n = counter.fetch_add(1, Ordering::SeqCst) + 1;
@@ -624,12 +789,16 @@ fn changed_paths_tail(paths: &[String]) -> String {
 /// daemon was down (#905). Returns an `Arc<AtomicBool>` flipped `true` on
 /// completion. Runs on a detached `std::thread`; the accept loop is never
 /// blocked on it, so the first client's first tool call does not wait.
-fn spawn_catch_up(project_root: &Path) -> Arc<AtomicBool> {
+fn spawn_catch_up(
+    project_root: &Path,
+    lease_loops: &codegraph_watch::SyncCancellation,
+) -> Arc<AtomicBool> {
     let done = Arc::new(AtomicBool::new(false));
     let thread_done = Arc::clone(&done);
     let root = project_root.to_path_buf();
+    let cancel = lease_loops.clone();
     thread::spawn(move || {
-        match codegraph_watch::sync_project_once(&root) {
+        match codegraph_watch::sync_project_once_cancellable(&root, &cancel) {
             Ok(outcome) => {
                 let changed = outcome.files_reindexed + outcome.files_removed;
                 if changed > 0 {
@@ -717,11 +886,65 @@ mod tests {
         let options = DaemonOptions::default();
         assert!(options.run_mcp);
         assert!(options.watch);
+        assert_eq!(options.drain_budget, DRAIN_TIMEOUT);
         assert_eq!(options.parent_pid, None);
         assert_eq!(options.host_pid, None);
         assert_eq!(options.watchdog_interval, DEFAULT_WATCHDOG_INTERVAL);
     }
 
+    #[tokio::test]
+    async fn drain_reports_completion_only_when_loops_and_sessions_reach_zero() {
+        let lease_loops = codegraph_watch::SyncCancellation::new();
+        let registry = SessionRegistry::default();
+        // Nothing outstanding: the drain completes.
+        assert!(
+            drain_watcher_loops_and_sessions(
+                || true,
+                &lease_loops,
+                &registry,
+                Duration::from_millis(50)
+            )
+            .await
+        );
+
+        // A still-open session keeps the drain INCOMPLETE, which is what must
+        // travel to the caller as a refusal instead of a success acknowledgement.
+        let session = registry.start_session();
+        assert!(
+            !drain_watcher_loops_and_sessions(
+                || true,
+                &lease_loops,
+                &registry,
+                Duration::from_millis(50)
+            )
+            .await,
+            "an outstanding session must report an incomplete drain"
+        );
+        drop(session);
+        assert!(
+            drain_watcher_loops_and_sessions(
+                || true,
+                &lease_loops,
+                &registry,
+                Duration::from_millis(50)
+            )
+            .await
+        );
+
+        // An unfinished watcher ALONE also keeps the drain incomplete, and the wait
+        // returns at its deadline instead of joining the event-loop thread.
+        assert!(
+            !drain_watcher_loops_and_sessions(
+                || false,
+                &lease_loops,
+                &registry,
+                Duration::from_millis(50)
+            )
+            .await,
+            "an unfinished watcher event loop must report an incomplete drain"
+        );
+    }
+
     #[test]
     fn backstop_exits_only_when_no_client_is_provably_alive() {
         let registry = SessionRegistry::default();
@@ -782,14 +1005,15 @@ mod tests {
     #[cfg(unix)]
     #[test]
     fn socket_candidate_chain_puts_preferred_first_and_dedups() {
-        let root = Path::new("/tmp/cg-candidate-chain");
-        let preferred = daemon_socket_path(root);
-        let chain = socket_candidate_chain(root, preferred.clone());
+        let root = temp_root("candidate-chain");
+        let preferred = socket_path_of(&root);
+        let chain = socket_candidate_chain(&root, preferred.clone()).expect("resolve candidates");
         assert_eq!(chain[0], preferred);
         let mut deduped = chain.clone();
         deduped.sort();
         deduped.dedup();
         assert_eq!(deduped.len(), chain.len());
+        let _ = fs::remove_dir_all(&root);
     }
 
     fn temp_root(label: &str) -> PathBuf {
@@ -802,7 +1026,19 @@ mod tests {
                 .as_nanos()
         ));
         fs::create_dir_all(&root).unwrap();
-        root
+        root.canonicalize().unwrap()
+    }
+
+    fn pid_path_of(root: &Path) -> PathBuf {
+        daemon_pid_path(root).expect("resolve the v2 rendezvous pid path")
+    }
+
+    fn socket_path_of(root: &Path) -> PathBuf {
+        daemon_socket_path(root).expect("resolve the v2 rendezvous socket identity")
+    }
+
+    fn create_rendezvous_dir(root: &Path) {
+        fs::create_dir_all(paths::rendezvous_dir(root).expect("resolve rendezvous dir")).unwrap();
     }
 
     fn quiet_options() -> DaemonOptions {
@@ -895,16 +1131,16 @@ mod tests {
     #[test]
     fn start_or_attach_clears_a_stale_lock_with_a_dead_pid_and_restarts() {
         let root = temp_root("stale-dead");
-        fs::create_dir_all(paths::codegraph_dir(&root)).unwrap();
+        create_rendezvous_dir(&root);
         let mut dead_pid = 999_999u32;
         while is_process_alive(dead_pid) {
             dead_pid -= 1;
         }
-        let pid_path = daemon_pid_path(&root);
+        let pid_path = pid_path_of(&root);
         let stale = DaemonLockInfo {
             pid: dead_pid,
             version: env!("CARGO_PKG_VERSION").to_string(),
-            socket_path: daemon_socket_path(&root),
+            socket_path: socket_path_of(&root),
             started_at: 1,
         };
         fs::write(&pid_path, encode_lock_info(&stale).unwrap()).unwrap();
@@ -922,8 +1158,8 @@ mod tests {
     #[test]
     fn start_or_attach_clears_a_garbage_lock_without_info_and_restarts() {
         let root = temp_root("stale-garbage");
-        fs::create_dir_all(paths::codegraph_dir(&root)).unwrap();
-        let pid_path = daemon_pid_path(&root);
+        create_rendezvous_dir(&root);
+        let pid_path = pid_path_of(&root);
         fs::write(&pid_path, b"not-json-at-all").unwrap();
 
         let started = start_or_attach(&root, quiet_options())
@@ -938,8 +1174,8 @@ mod tests {
     #[tokio::test]
     async fn bind_with_fallback_binds_the_preferred_socket_first() {
         let root = temp_root("bind-fallback");
-        fs::create_dir_all(paths::codegraph_dir(&root)).unwrap();
-        let preferred = daemon_socket_path(&root);
+        create_rendezvous_dir(&root);
+        let preferred = socket_path_of(&root);
         let (_listener, bound) =
             bind_with_fallback(&root, preferred.clone()).expect("preferred socket must bind");
         assert_eq!(bound, preferred, "the preferred candidate binds first");
@@ -953,7 +1189,7 @@ mod tests {
     #[test]
     fn attach_to_a_dead_socket_path_errors() {
         let root = temp_root("attach-dead");
-        let socket = daemon_socket_path(&root);
+        let socket = socket_path_of(&root);
         let err = attach_to_daemon(&socket).expect_err("attaching to an unbound socket must fail");
         assert!(
             err.to_string().contains("connecting to daemon socket"),
diff --git a/crates/codegraph-daemon/src/lock.rs b/crates/codegraph-daemon/src/lock.rs
index ec0de1c..c390663 100644
--- a/crates/codegraph-daemon/src/lock.rs
+++ b/crates/codegraph-daemon/src/lock.rs
@@ -7,8 +7,9 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
+use tracing::debug;
 
-use crate::paths::{codegraph_dir, daemon_pid_path, daemon_socket_path};
+use crate::paths::{daemon_pid_path, daemon_socket_path, rendezvous_dir};
 use crate::process::is_process_alive;
 
 const EMPTY_RETRY_DELAY: Duration = Duration::from_millis(20);
@@ -59,14 +60,14 @@ pub fn decode_lock_info(raw: &str) -> Option<DaemonLockInfo> {
 }
 
 pub fn try_acquire_daemon_lock(project_root: &Path) -> Result<AcquireResult> {
-    let pid_path = daemon_pid_path(project_root);
-    fs::create_dir_all(codegraph_dir(project_root))
-        .with_context(|| format!("creating {}", codegraph_dir(project_root).display()))?;
+    let pid_path = daemon_pid_path(project_root)?;
+    let dir = rendezvous_dir(project_root)?;
+    fs::create_dir_all(&dir).with_context(|| format!("creating {}", dir.display()))?;
 
     let info = DaemonLockInfo {
         pid: process::id(),
         version: env!("CARGO_PKG_VERSION").to_string(),
-        socket_path: daemon_socket_path(project_root),
+        socket_path: daemon_socket_path(project_root)?,
         started_at: now_millis(),
     };
 
@@ -144,9 +145,12 @@ pub fn clear_stale_daemon_lock(pid_path: &Path, expected_dead_pid: Option<u32>)
     fs::remove_file(pid_path).is_ok()
 }
 
+/// Clear a stale daemon lock for `project_root`. An unresolvable index root is
+/// reported as "not cleared" rather than reconstructing a rendezvous path.
 pub fn unlock_project(project_root: &Path) -> bool {
-    let pid_path = daemon_pid_path(project_root);
-    clear_stale_daemon_lock(&pid_path, None)
+    daemon_pid_path(project_root)
+        .map(|pid_path| clear_stale_daemon_lock(&pid_path, None))
+        .unwrap_or(false)
 }
 
 /// Self-heal a project's stale daemon artifacts after a failed attach (Fix A):
@@ -159,8 +163,12 @@ pub fn unlock_project(project_root: &Path) -> bool {
 /// Returns `true` once the stale lock is cleared; socket removal is best-effort
 /// (a missing socket is already the desired end state).
 pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
-    let pid_path = daemon_pid_path(project_root);
-    let socket_path = recorded_socket_path(project_root);
+    let Ok(pid_path) = daemon_pid_path(project_root) else {
+        return false;
+    };
+    let Ok(socket_path) = recorded_socket_path(project_root) else {
+        return false;
+    };
     // Liveness gate: only proceed once the owning pid is proven dead/absent.
     if !clear_stale_daemon_lock(&pid_path, None) {
         return false;
@@ -169,11 +177,12 @@ pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
     true
 }
 
-pub(crate) fn cleanup_owned_lock(pid_path: &Path, pid: u32) {
+pub(crate) fn cleanup_owned_lock(pid_path: &Path, pid: u32) -> bool {
     let owned = read_lock_info_tolerant(pid_path).is_some_and(|info| info.pid == pid);
     if owned {
         let _ = fs::remove_file(pid_path);
     }
+    owned
 }
 
 enum ReadOutcome {
@@ -218,12 +227,44 @@ fn read_lock_info_tolerant(pid_path: &Path) -> Option<DaemonLockInfo> {
 /// recorded socket (a legacy plain-pid lock). Reading the recorded path — not
 /// recomputing — is what lets a client attach to a daemon that bound a fallback
 /// candidate (e.g. the tmpdir socket on an ExFAT project dir).
-pub fn recorded_socket_path(project_root: &Path) -> PathBuf {
-    let pid_path = daemon_pid_path(project_root);
-    read_lock_info_tolerant(&pid_path)
+pub fn recorded_socket_path(project_root: &Path) -> Result<PathBuf> {
+    let pid_path = daemon_pid_path(project_root)?;
+    match read_lock_info_tolerant(&pid_path)
         .map(|info| info.socket_path)
         .filter(|socket| !socket.as_os_str().is_empty())
-        .unwrap_or_else(|| daemon_socket_path(project_root))
+    {
+        Some(recorded) => Ok(recorded),
+        None => daemon_socket_path(project_root),
+    }
+}
+
+/// Remove the rendezvous artifacts this daemon process itself published: its
+/// owner-bound pid record and, on Unix, its bound socket file.
+///
+/// Socket removal is CONDITIONAL on the pid record still naming this process. If
+/// the record was already replaced by a new owner (its own claim published a new
+/// record and rebound the same socket path), unlinking the socket here would strip
+/// the LIVE daemon's rendezvous while its record still advertises it, leaving
+/// every client unable to attach. In that case both the replacement record and its
+/// socket are preserved and this reports `false`. The permanent index lock is
+/// never named here.
+pub(crate) fn cleanup_owned_rendezvous(pid_path: &Path, socket_path: &Path, pid: u32) -> bool {
+    let owned = cleanup_owned_lock(pid_path, pid);
+    if !owned {
+        debug!(
+            pid_path = %pid_path.display(),
+            "daemon rendezvous is owned by another process; leaving its record and socket intact"
+        );
+        return false;
+    }
+    #[cfg(unix)]
+    if let Some(stale) = crate::transport::Rendezvous::from_socket_path(socket_path).cleanup_path()
+    {
+        let _ = fs::remove_file(stale);
+    }
+    #[cfg(not(unix))]
+    let _ = socket_path;
+    true
 }
 
 fn now_millis() -> u128 {
@@ -248,11 +289,7 @@ mod tests {
     fn rewrite_socket_path_updates_recorded_socket_and_keeps_pid() {
         // Given an acquired lock recording the default socket, rewriting the
         // recorded socket to a fallback path is what the client later reads.
-        let base = std::env::temp_dir().join(format!(
-            "cg-lock-rewrite-{}-{}",
-            process::id(),
-            now_millis()
-        ));
+        let base = temp_base("rewrite");
         let AcquireResult::Acquired { pid_path, info } =
             try_acquire_daemon_lock(&base).expect("acquire lock")
         else {
@@ -271,12 +308,30 @@ mod tests {
         let _ = fs::remove_dir_all(&base);
     }
 
+    /// A real, existing project directory. `IndexPaths` derives the physical
+    /// project identity from the filesystem object, so the project must exist
+    /// before any rendezvous path resolves.
     fn temp_base(label: &str) -> PathBuf {
-        std::env::temp_dir().join(format!(
+        let base = std::env::temp_dir().join(format!(
             "cg-lock-{label}-{}-{}",
             process::id(),
             now_millis()
-        ))
+        ));
+        fs::create_dir_all(&base).unwrap();
+        base.canonicalize().unwrap()
+    }
+
+    fn pid_path_of(base: &Path) -> PathBuf {
+        daemon_pid_path(base).expect("resolve the v2 rendezvous pid path")
+    }
+
+    fn socket_path_of(base: &Path) -> PathBuf {
+        daemon_socket_path(base).expect("resolve the v2 rendezvous socket identity")
+    }
+
+    fn create_rendezvous_dir(base: &Path) {
+        let dir = rendezvous_dir(base).expect("resolve the v2 rendezvous dir");
+        fs::create_dir_all(dir).unwrap();
     }
 
     #[test]
@@ -303,7 +358,7 @@ mod tests {
     #[test]
     fn clear_stale_lock_returns_true_when_missing() {
         let base = temp_base("clear-missing");
-        let pid_path = daemon_pid_path(&base);
+        let pid_path = pid_path_of(&base);
         assert!(clear_stale_daemon_lock(&pid_path, None));
     }
 
@@ -326,8 +381,8 @@ mod tests {
     #[test]
     fn clear_stale_lock_removes_a_dead_pid_lock() {
         let base = temp_base("clear-dead");
-        fs::create_dir_all(codegraph_dir(&base)).unwrap();
-        let pid_path = daemon_pid_path(&base);
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
         let dead = DaemonLockInfo {
             pid: 4_000_000_000,
             version: "1.0.0".to_string(),
@@ -343,8 +398,8 @@ mod tests {
     #[test]
     fn clear_stale_lock_refuses_when_expected_pid_mismatches() {
         let base = temp_base("clear-mismatch");
-        fs::create_dir_all(codegraph_dir(&base)).unwrap();
-        let pid_path = daemon_pid_path(&base);
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
         let dead = DaemonLockInfo {
             pid: 4_000_000_000,
             version: "1.0.0".to_string(),
@@ -362,8 +417,8 @@ mod tests {
     #[test]
     fn unlock_project_clears_a_dead_lock() {
         let base = temp_base("unlock");
-        fs::create_dir_all(codegraph_dir(&base)).unwrap();
-        let pid_path = daemon_pid_path(&base);
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
         let dead = DaemonLockInfo {
             pid: 4_000_000_000,
             version: "1.0.0".to_string(),
@@ -378,7 +433,11 @@ mod tests {
     #[test]
     fn recorded_socket_path_falls_back_to_default_when_lock_absent() {
         let base = temp_base("recorded-absent");
-        assert_eq!(recorded_socket_path(&base), daemon_socket_path(&base));
+        assert_eq!(
+            recorded_socket_path(&base).expect("resolve recorded socket"),
+            socket_path_of(&base)
+        );
+        let _ = fs::remove_dir_all(&base);
     }
 
     #[test]
@@ -391,7 +450,10 @@ mod tests {
         };
         let recorded = std::env::temp_dir().join("cg-recorded.sock");
         rewrite_lock_socket_path(&pid_path, &recorded).unwrap();
-        assert_eq!(recorded_socket_path(&base), recorded);
+        assert_eq!(
+            recorded_socket_path(&base).expect("resolve recorded socket"),
+            recorded
+        );
         let _ = fs::remove_dir_all(&base);
     }
 
@@ -412,12 +474,54 @@ mod tests {
         let _ = fs::remove_dir_all(&base);
     }
 
+    #[test]
+    fn cleanup_owned_rendezvous_preserves_a_replacement_owners_record_and_socket() {
+        let base = temp_base("cleanup-replaced");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        // A NEW owner already replaced the record and rebound the same socket.
+        let replacement = DaemonLockInfo {
+            pid: process::id(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            socket_path: socket.clone(),
+            started_at: 2,
+        };
+        fs::write(&pid_path, encode_lock_info(&replacement).unwrap()).unwrap();
+        fs::write(&socket, b"").unwrap();
+
+        // The DEPARTING daemon (a different pid) must strip neither artifact.
+        let mut departing = 4_000_000_000u32;
+        while departing == process::id() {
+            departing -= 1;
+        }
+        assert!(
+            !cleanup_owned_rendezvous(&pid_path, &socket, departing),
+            "an owner mismatch must report that nothing was cleaned"
+        );
+        assert!(
+            pid_path.exists(),
+            "the replacement owner's record must survive"
+        );
+        assert!(
+            socket.exists(),
+            "the replacement owner's socket must survive"
+        );
+
+        // The true owner cleans both.
+        assert!(cleanup_owned_rendezvous(&pid_path, &socket, process::id()));
+        assert!(!pid_path.exists());
+        #[cfg(unix)]
+        assert!(!socket.exists());
+        let _ = fs::remove_dir_all(&base);
+    }
+
     #[test]
     fn clear_stale_daemon_socket_removes_lock_and_socket_when_dead() {
         let base = temp_base("socket-dead");
-        fs::create_dir_all(codegraph_dir(&base)).unwrap();
-        let pid_path = daemon_pid_path(&base);
-        let socket = daemon_socket_path(&base);
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
         let dead = DaemonLockInfo {
             pid: 4_000_000_000,
             version: "1.0.0".to_string(),
diff --git a/crates/codegraph-daemon/src/paths.rs b/crates/codegraph-daemon/src/paths.rs
index 143ce64..0696f6f 100644
--- a/crates/codegraph-daemon/src/paths.rs
+++ b/crates/codegraph-daemon/src/paths.rs
@@ -1,124 +1,235 @@
-#[cfg(unix)]
-use std::env;
+//! Daemon rendezvous paths, derived from the ONE `IndexPaths` authority.
+//!
+//! Frozen plan lines 590-592: current daemon paths use the centralized current
+//! root and the v2 socket identity. Nothing here reconstructs a `.codegraph*`
+//! path: every value comes from [`IndexPaths::resolve`], which fails closed on an
+//! unsafe/aliased/overlapping configured root, so each accessor is fallible.
+
 use std::path::{Path, PathBuf};
 
+use anyhow::Result;
+use codegraph_core::IndexPaths;
 use sha2::{Digest, Sha256};
 
 #[cfg(unix)]
 const POSIX_SOCKET_PATH_LIMIT: usize = 100;
 
-pub(crate) fn codegraph_dir(project_root: &Path) -> PathBuf {
-    project_root.join(".codegraph")
+/// The v2 rendezvous discriminator carried by the out-of-root socket identities
+/// (the POSIX tmpdir fallback and the Windows namespaced pipe), so a current
+/// daemon can never collide with a legacy `v0.40.4` rendezvous name.
+const V2_RENDEZVOUS_PREFIX: &str = "codegraph-v2-";
+
+/// Resolve the project's index paths, honoring `CODEGRAPH_DIR`.
+pub(crate) fn index_paths(project_root: &Path) -> Result<IndexPaths> {
+    Ok(IndexPaths::resolve(
+        project_root,
+        std::env::var("CODEGRAPH_DIR").ok().as_deref(),
+    )?)
 }
 
-pub fn daemon_pid_path(project_root: &Path) -> PathBuf {
-    codegraph_dir(project_root).join("daemon.pid")
+/// The rendezvous directory: the resolved current index root.
+pub(crate) fn rendezvous_dir(project_root: &Path) -> Result<PathBuf> {
+    Ok(index_paths(project_root)?.current_root().to_path_buf())
+}
+
+pub fn daemon_pid_path(project_root: &Path) -> Result<PathBuf> {
+    Ok(index_paths(project_root)?.daemon_pid())
 }
 
 /// Path of the appended log file the detached daemon's stdout+stderr are
-/// redirected to (`.codegraph/daemon.log`).
-pub fn daemon_log_path(project_root: &Path) -> PathBuf {
-    codegraph_dir(project_root).join("daemon.log")
+/// redirected to.
+pub fn daemon_log_path(project_root: &Path) -> Result<PathBuf> {
+    Ok(index_paths(project_root)?.daemon_log())
 }
 
 #[cfg(unix)]
-pub fn daemon_socket_path(project_root: &Path) -> PathBuf {
-    let in_project = codegraph_dir(project_root).join("daemon.sock");
-    if in_project.as_os_str().len() <= POSIX_SOCKET_PATH_LIMIT {
-        return in_project;
+pub fn daemon_socket_path(project_root: &Path) -> Result<PathBuf> {
+    Ok(socket_identity(&index_paths(project_root)?))
+}
+
+#[cfg(unix)]
+fn socket_identity(paths: &IndexPaths) -> PathBuf {
+    let in_root = paths.daemon_socket();
+    if in_root.as_os_str().len() <= POSIX_SOCKET_PATH_LIMIT {
+        return in_root;
     }
-    env::temp_dir().join(format!("codegraph-{}.sock", project_hash(project_root)))
+    tmp_socket(paths)
+}
+
+#[cfg(unix)]
+fn tmp_socket(paths: &IndexPaths) -> PathBuf {
+    std::env::temp_dir().join(format!(
+        "{V2_RENDEZVOUS_PREFIX}{}.sock",
+        rendezvous_name(paths)
+    ))
 }
 
 /// Ordered, deterministic socket-bind candidates for `project_root`
-/// (`f83a1ec`). Candidate #1 is the project-dir socket (when its path fits the
-/// POSIX limit); candidate #2 is the hashed-tmpdir socket. On filesystems that
-/// reject `bind()` for an AF_UNIX socket (ExFAT/FAT, some network mounts, WSL
-/// DrvFs), the daemon falls through to the next candidate. The list is
-/// deduplicated and never empty: when the project path is too long for #1, the
-/// tmpdir socket IS candidate #1 (matching `daemon_socket_path`).
+/// (`f83a1ec`). Candidate #1 is the in-root socket (when its path fits the POSIX
+/// limit); candidate #2 is the hashed-tmpdir socket. On filesystems that reject
+/// `bind()` for an AF_UNIX socket (ExFAT/FAT, some network mounts, WSL DrvFs),
+/// the daemon falls through to the next candidate. The list is deduplicated and
+/// never empty: when the in-root path is too long for #1, the tmpdir socket IS
+/// candidate #1 (matching [`daemon_socket_path`]).
 #[cfg(unix)]
-pub fn daemon_socket_candidates(project_root: &Path) -> Vec<PathBuf> {
-    let in_project = codegraph_dir(project_root).join("daemon.sock");
-    let tmp = env::temp_dir().join(format!("codegraph-{}.sock", project_hash(project_root)));
-    if in_project.as_os_str().len() <= POSIX_SOCKET_PATH_LIMIT && in_project != tmp {
-        vec![in_project, tmp]
-    } else {
-        vec![tmp]
-    }
+pub fn daemon_socket_candidates(project_root: &Path) -> Result<Vec<PathBuf>> {
+    let paths = index_paths(project_root)?;
+    let in_root = paths.daemon_socket();
+    let tmp = tmp_socket(&paths);
+    Ok(
+        if in_root.as_os_str().len() <= POSIX_SOCKET_PATH_LIMIT && in_root != tmp {
+            vec![in_root, tmp]
+        } else {
+            vec![tmp]
+        },
+    )
 }
 
 // Windows has no filesystem socket: the rendezvous is a BARE namespaced name.
 // interprocess `GenericNamespaced` prepends `\\.\pipe\` itself, so storing the
 // prefix here would double it (Locked decision #8/#9).
 #[cfg(windows)]
-pub fn daemon_socket_path(project_root: &Path) -> PathBuf {
-    PathBuf::from(format!("codegraph-{}", project_hash(project_root)))
+pub fn daemon_socket_path(project_root: &Path) -> Result<PathBuf> {
+    let paths = index_paths(project_root)?;
+    Ok(PathBuf::from(format!(
+        "{V2_RENDEZVOUS_PREFIX}{}",
+        rendezvous_name(&paths)
+    )))
 }
 
-fn project_hash(project_root: &Path) -> String {
-    let resolved = project_root
-        .canonicalize()
-        .unwrap_or_else(|_| project_root.to_path_buf());
+/// The 16-hex-character discriminated name used by the OUT-OF-ROOT rendezvous
+/// identities (the POSIX tmpdir fallback and the Windows namespaced pipe).
+///
+/// It is `sha256(V2_RENDEZVOUS_PREFIX || projectIdentity)` truncated, NOT a
+/// prefix of the identity itself: the legacy `v0.40.4` name is
+/// `sha256(<project path>)[..16]`, and mixing in this version's own domain
+/// separator makes the two provably distinct names for the same project even if
+/// a future identity scheme ever coincided with a path hash. The authoritative
+/// owner binding always carries the FULL identity; this value only has to be a
+/// stable, collision-resistant NAME.
+fn rendezvous_name(paths: &IndexPaths) -> String {
     let mut hasher = Sha256::new();
-    hasher.update(resolved.to_string_lossy().as_bytes());
-    let hex = format!("{:x}", hasher.finalize());
-    hex[..16].to_string()
+    hasher.update(V2_RENDEZVOUS_PREFIX.as_bytes());
+    hasher.update(paths.project_identity().as_bytes());
+    let digest = hasher.finalize();
+    let mut out = String::with_capacity(16);
+    for byte in digest.iter().take(8) {
+        out.push_str(&format!("{byte:02x}"));
+    }
+    out
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    #[cfg(unix)]
+    fn temp_project(label: &str) -> PathBuf {
+        let path = std::env::temp_dir().join(format!(
+            "cg-daemon-paths-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        path.canonicalize().unwrap()
+    }
+
     #[test]
-    fn socket_path_uses_project_dir_for_short_paths() {
-        let root = PathBuf::from("/tmp/cg-short");
-        assert_eq!(
-            daemon_socket_path(&root),
-            root.join(".codegraph/daemon.sock")
+    fn rendezvous_paths_come_from_the_resolved_current_root() {
+        let project = temp_project("current-root");
+        let paths = index_paths(&project).unwrap();
+        assert_eq!(daemon_pid_path(&project).unwrap(), paths.daemon_pid());
+        assert_eq!(daemon_log_path(&project).unwrap(), paths.daemon_log());
+        assert_eq!(rendezvous_dir(&project).unwrap(), paths.current_root());
+        assert!(
+            paths
+                .current_root()
+                .starts_with(project.join(".codegraph-v2")),
+            "the default rendezvous dir is the v2 current root: {}",
+            paths.current_root().display()
         );
+        let _ = std::fs::remove_dir_all(&project);
+    }
+
+    #[test]
+    fn rendezvous_paths_fail_closed_for_an_unresolvable_project() {
+        // No `CODEGRAPH_DIR` mutation: that variable is process-global and this
+        // crate's unit tests share one binary, so an env-mutating test would race
+        // every other rendezvous resolution. An absent project is an equally
+        // authoritative fail-closed input, because `IndexPaths` derives the
+        // PHYSICAL project identity and cannot invent one for a path that does
+        // not exist.
+        let missing = std::env::temp_dir().join(format!(
+            "cg-daemon-paths-absent-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        assert!(daemon_pid_path(&missing).is_err());
+        assert!(daemon_log_path(&missing).is_err());
+        assert!(daemon_socket_path(&missing).is_err());
+        assert!(rendezvous_dir(&missing).is_err());
+        #[cfg(unix)]
+        assert!(daemon_socket_candidates(&missing).is_err());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn socket_path_uses_the_current_root_for_short_paths() {
+        let project = temp_project("short");
+        let paths = index_paths(&project).unwrap();
+        assert_eq!(daemon_socket_path(&project).unwrap(), paths.daemon_socket());
+        let _ = std::fs::remove_dir_all(&project);
     }
 
     #[cfg(unix)]
     #[test]
-    fn candidate_chain_starts_with_project_socket_then_tmpdir() {
-        // Given a short project path, candidate #1 is the project-dir socket and
-        // candidate #2 is the hashed-tmpdir socket (the bind-fallback target).
-        let root = PathBuf::from("/tmp/cg-short");
-        let candidates = daemon_socket_candidates(&root);
+    fn candidate_chain_starts_with_the_in_root_socket_then_tmpdir() {
+        let project = temp_project("chain");
+        let paths = index_paths(&project).unwrap();
+        let candidates = daemon_socket_candidates(&project).unwrap();
         assert_eq!(candidates.len(), 2);
-        assert_eq!(candidates[0], root.join(".codegraph/daemon.sock"));
-        assert!(candidates[1].starts_with(env::temp_dir()));
+        assert_eq!(candidates[0], paths.daemon_socket());
+        assert!(candidates[1].starts_with(std::env::temp_dir()));
         assert!(
             candidates[1]
                 .file_name()
-                .and_then(|n| n.to_str())
-                .is_some_and(|n| n.starts_with("codegraph-") && n.ends_with(".sock"))
+                .and_then(|name| name.to_str())
+                .is_some_and(
+                    |name| name.starts_with(V2_RENDEZVOUS_PREFIX) && name.ends_with(".sock")
+                ),
+            "the tmpdir fallback carries the v2 discriminator: {:?}",
+            candidates[1]
         );
-        // The default socket path equals candidate #1.
-        assert_eq!(daemon_socket_path(&root), candidates[0]);
+        assert_eq!(daemon_socket_path(&project).unwrap(), candidates[0]);
+        let _ = std::fs::remove_dir_all(&project);
     }
 
     #[cfg(unix)]
     #[test]
     fn candidate_chain_collapses_to_tmpdir_for_long_paths() {
-        // Given a project path too long for an AF_UNIX socket, the only candidate
-        // is the hashed-tmpdir socket (so the chain is never empty).
-        let long = PathBuf::from(format!("/tmp/{}", "x".repeat(120)));
-        let candidates = daemon_socket_candidates(&long);
+        let base = temp_project("long");
+        let project = base.join("x".repeat(120));
+        std::fs::create_dir_all(&project).unwrap();
+        let candidates = daemon_socket_candidates(&project).unwrap();
         assert_eq!(candidates.len(), 1);
-        assert!(candidates[0].starts_with(env::temp_dir()));
-        assert_eq!(daemon_socket_path(&long), candidates[0]);
+        assert!(candidates[0].starts_with(std::env::temp_dir()));
+        assert_eq!(daemon_socket_path(&project).unwrap(), candidates[0]);
+        let _ = std::fs::remove_dir_all(&base);
     }
 
     #[cfg(windows)]
     #[test]
-    fn socket_path_is_a_bare_namespaced_name() {
-        let root = PathBuf::from(r"C:\tmp\cg-short");
-        let name = daemon_socket_path(&root);
+    fn socket_path_is_a_bare_namespaced_v2_name() {
+        let project = temp_project("windows-name");
+        let name = daemon_socket_path(&project).unwrap();
         let name = name.to_string_lossy();
-        assert!(name.starts_with("codegraph-"));
+        assert!(name.starts_with(V2_RENDEZVOUS_PREFIX));
         assert!(!name.contains(r"\\.\pipe\"));
+        let _ = std::fs::remove_dir_all(&project);
     }
 }
diff --git a/crates/codegraph-daemon/src/session.rs b/crates/codegraph-daemon/src/session.rs
index b36b4b0..f4707a5 100644
--- a/crates/codegraph-daemon/src/session.rs
+++ b/crates/codegraph-daemon/src/session.rs
@@ -11,7 +11,9 @@ use interprocess::local_socket::traits::Stream as _;
 use interprocess::local_socket::traits::tokio::Stream as _;
 use serde::{Deserialize, Serialize};
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tracing::debug;
 
+use crate::control::{ControlAck, ControlFrame, encode_control_line, parse_control_frame};
 use crate::transport::{AsyncStream, Stream};
 
 /// Max milliseconds the PROXY waits for the daemon's one-line versioned hello
@@ -73,6 +75,11 @@ pub struct SessionRegistry {
     sessions: Arc<Mutex<HashMap<u64, SessionEntry>>>,
     next_id: Arc<AtomicU64>,
     last_active: Arc<Mutex<Instant>>,
+    /// Cross-platform "stop serving" signal for EVERY data session. A `watch`
+    /// channel (not a raw-fd shutdown, which exists only on Unix) is what lets the
+    /// control-frame drain actively close long-lived rmcp sessions on Windows too;
+    /// its retained value also refuses a session that connects after the signal.
+    closing: Arc<tokio::sync::watch::Sender<bool>>,
 }
 
 impl std::fmt::Debug for SessionRegistry {
@@ -89,6 +96,7 @@ impl Default for SessionRegistry {
             sessions: Arc::new(Mutex::new(HashMap::new())),
             next_id: Arc::new(AtomicU64::new(1)),
             last_active: Arc::new(Mutex::new(Instant::now())),
+            closing: Arc::new(tokio::sync::watch::channel(false).0),
         }
     }
 }
@@ -183,6 +191,41 @@ impl SessionRegistry {
             .any(|entry| matches!(entry.pid, Some(pid) if is_alive(pid)))
     }
 
+    /// Signal every data session — current and future — to stop serving. Each
+    /// session races its serve loop against this signal, so its transport is
+    /// dropped and its socket closed on every platform. Idempotent.
+    pub(crate) fn close_all_sessions(&self) {
+        // `send_replace`, not `send`: `send` FAILS (and stores nothing) when no
+        // receiver exists yet, which would let a session accepted after the signal
+        // start serving. `send_replace` always updates the retained value.
+        self.closing.send_replace(true);
+        #[cfg(unix)]
+        {
+            // Additionally force EOF on the recorded recv fds: a session blocked in
+            // a read that has not yet reached an await point observes the close
+            // immediately rather than at its next poll.
+            let ids = self
+                .sessions
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .keys()
+                .copied()
+                .collect::<Vec<_>>();
+            for id in ids {
+                self.shutdown_session(id);
+            }
+        }
+    }
+
+    /// Whether [`close_all_sessions`](Self::close_all_sessions) has fired.
+    pub(crate) fn is_closing(&self) -> bool {
+        *self.closing.borrow()
+    }
+
+    fn closing_signal(&self) -> tokio::sync::watch::Receiver<bool> {
+        self.closing.subscribe()
+    }
+
     /// Force a dead session's reader to EOF by half-closing the read direction
     /// of its socket. The session thread, blocked in the rmcp serve loop, then sees
     /// EOF, returns, and drops its [`SessionGuard`] (which removes the entry +
@@ -249,6 +292,44 @@ impl Drop for SessionGuard {
     }
 }
 
+/// One accepted control-frame shutdown, handed from a session task to the accept
+/// loop. `ack` is signalled by the accept loop AFTER it has stopped accepting,
+/// cancelled its watcher lease loops, drained, and removed its own rendezvous;
+/// the session then writes the wire ACK and reports completion through `done` so
+/// the loop never tears its runtime down mid-write.
+pub(crate) struct ShutdownRequest {
+    /// Carries the DRAIN RESULT, not merely a wake: `false` means the bounded
+    /// drain did not complete, and the session must then answer with an UNDRAINED
+    /// ack so `uninit --force` fails closed instead of deleting children behind a
+    /// daemon that still holds work.
+    pub(crate) ack: tokio::sync::oneshot::Sender<bool>,
+    pub(crate) done: tokio::sync::oneshot::Receiver<()>,
+}
+
+/// The session-side capability for the control channel: the FULL project identity
+/// a frame must name, plus the sender the accept loop listens on.
+#[derive(Clone)]
+pub(crate) struct ControlHandle {
+    identity: Arc<str>,
+    tx: tokio::sync::mpsc::UnboundedSender<ShutdownRequest>,
+}
+
+impl ControlHandle {
+    pub(crate) fn new(
+        identity: &str,
+        tx: tokio::sync::mpsc::UnboundedSender<ShutdownRequest>,
+    ) -> Self {
+        Self {
+            identity: Arc::from(identity),
+            tx,
+        }
+    }
+
+    fn authorizes(&self, frame: &ControlFrame) -> bool {
+        frame.authorizes_shutdown_of(&self.identity)
+    }
+}
+
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DaemonHello<'a> {
@@ -276,6 +357,7 @@ pub(crate) async fn serve_session_async(
     socket_path: String,
     registry: SessionRegistry,
     run_mcp: bool,
+    control: Option<ControlHandle>,
 ) -> Result<()> {
     let guard = registry.start_session();
     let session_id = guard.session_id();
@@ -302,12 +384,39 @@ pub(crate) async fn serve_session_async(
     send.write_all(hello_line.as_bytes()).await?;
     send.flush().await?;
 
-    if !run_mcp {
+    if !run_mcp && control.is_none() {
         return Ok(());
     }
 
-    let (first, recv) = read_first_line_bounded_async(recv, MAX_HELLO_LINE_BYTES + 1).await;
+    // The first-line read parks until the peer speaks, so it must observe the
+    // registry's closing signal too — otherwise a connected-but-silent client would
+    // keep the session count nonzero for the whole drain budget on platforms with
+    // no raw-fd half-close.
+    if registry.is_closing() {
+        return Ok(());
+    }
+    let mut closing = registry.closing_signal();
+    // Mark the current value seen so `changed()` awaits the NEXT edge.
+    let _ = closing.borrow_and_update();
+    let (first, recv) = tokio::select! {
+        read = read_first_line_bounded_async(recv, MAX_HELLO_LINE_BYTES + 1) => read,
+        _ = closing.changed() => {
+            debug!("daemon session closed by shutdown drain before its first frame");
+            return Ok(());
+        }
+    };
     let line = String::from_utf8_lossy(&first);
+
+    // A CONTROL frame never reaches the request executor, so it never takes a
+    // data-request shared index lease — that is what lets it be answered while
+    // `uninit --force` holds the namespace's exclusive lease.
+    if let Some(frame) = parse_control_frame(&line) {
+        drop(guard);
+        return serve_control_frame(send, &frame, control.as_ref()).await;
+    }
+    if !run_mcp {
+        return Ok(());
+    }
     let pid = parse_client_hello_line(&line);
     if let Some(pid) = pid {
         registry.set_pid(session_id, pid);
@@ -319,10 +428,78 @@ pub(crate) async fn serve_session_async(
     let put_back: Vec<u8> = if pid.is_some() { Vec::new() } else { first };
     let chained = AsyncReadExt::chain(Cursor::new(put_back), recv);
     let transport = tokio::io::join(chained, send);
-    codegraph_mcp::rmcp_session::serve_session_rmcp_async(transport, project_root).await?;
+    // Race the session against the registry's closing signal so a shutdown
+    // control frame ACTIVELY ends this session (dropping the transport closes the
+    // socket) instead of waiting for the client to disconnect.
+    tokio::select! {
+        served = codegraph_mcp::rmcp_session::serve_session_rmcp_async(transport, project_root) => {
+            served?;
+        }
+        _ = closing.changed() => {
+            debug!("daemon session closed by shutdown drain");
+        }
+    }
     Ok(())
 }
 
+/// Answer one control frame on its own connection.
+///
+/// An unauthorized frame (foreign protocol version, unknown action, or another
+/// project's identity) is refused with an undrained ACK and changes nothing. An
+/// authorized frame hands the request to the accept loop, waits for the loop's
+/// post-drain signal, writes the ACK, and reports completion.
+async fn serve_control_frame(
+    mut send: crate::transport::AsyncSendHalf,
+    frame: &ControlFrame,
+    control: Option<&ControlHandle>,
+) -> Result<()> {
+    let Some(control) = control.filter(|control| control.authorizes(frame)) else {
+        send.write_all(refusal_line(frame).as_bytes()).await?;
+        send.flush().await?;
+        return Ok(());
+    };
+
+    let (ack_tx, ack_rx) = tokio::sync::oneshot::channel();
+    let (done_tx, done_rx) = tokio::sync::oneshot::channel();
+    if control
+        .tx
+        .send(ShutdownRequest {
+            ack: ack_tx,
+            done: done_rx,
+        })
+        .is_err()
+    {
+        anyhow::bail!("daemon accept loop is gone; shutdown control frame cannot be served");
+    }
+    let drained = ack_rx
+        .await
+        .map_err(|_| anyhow::anyhow!("daemon drain ended without acknowledging shutdown"))?;
+    // An incomplete drain answers with `drained: false`, which the caller treats as
+    // unresponsive and therefore fail-closed. A success ack is emitted ONLY when
+    // every session and lease loop actually finished.
+    send.write_all(shutdown_reply_line(drained).as_bytes())
+        .await?;
+    send.flush().await?;
+    let _ = done_tx.send(());
+    Ok(())
+}
+
+/// The wire reply for a completed (`true`) or INCOMPLETE (`false`) drain.
+fn shutdown_reply_line(drained: bool) -> String {
+    encode_control_line(&ControlAck::for_drain(drained))
+}
+
+/// The wire reply for an UNAUTHORIZED control frame: never drained, and the
+/// frame's own action is echoed so the caller can see what was refused. Nothing
+/// is mutated and no shutdown is scheduled.
+fn refusal_line(frame: &ControlFrame) -> String {
+    encode_control_line(&ControlAck {
+        codegraph_control: crate::control::CONTROL_PROTOCOL,
+        action: frame.action.clone(),
+        drained: false,
+    })
+}
+
 /// Async analog of [`read_first_line_bounded`]: read from `recv` up to and
 /// including the first `\n`, or `max` bytes, whichever comes first. Returns the
 /// raw bytes read plus the (unconsumed) recv half so the caller can chain the
@@ -563,6 +740,48 @@ mod tests {
         drop((no_pid, dead, alive));
     }
 
+    #[test]
+    fn shutdown_reply_reports_the_drain_result_and_a_refusal_is_never_drained() {
+        let completed: ControlAck =
+            serde_json::from_str(shutdown_reply_line(true).trim()).expect("ack json");
+        assert!(
+            completed.accepted(),
+            "a completed drain acknowledges success"
+        );
+
+        let incomplete: ControlAck =
+            serde_json::from_str(shutdown_reply_line(false).trim()).expect("ack json");
+        assert!(
+            !incomplete.accepted(),
+            "an incomplete drain must NOT be acknowledged as success"
+        );
+
+        let foreign = ControlFrame::shutdown("another-project");
+        let refusal: ControlAck =
+            serde_json::from_str(refusal_line(&foreign).trim()).expect("refusal json");
+        assert!(!refusal.accepted());
+        assert_eq!(refusal.action, foreign.action);
+    }
+
+    #[test]
+    fn close_all_sessions_is_observable_and_idempotent() {
+        let registry = SessionRegistry::default();
+        assert!(!registry.is_closing());
+        let guard = registry.start_session();
+        registry.close_all_sessions();
+        assert!(
+            registry.is_closing(),
+            "the closing signal must be observable by every session"
+        );
+        // Idempotent: a second call is a no-op and a session that connects AFTER
+        // the signal still observes it.
+        registry.close_all_sessions();
+        assert!(registry.is_closing());
+        let late = registry.start_session();
+        assert!(registry.is_closing());
+        drop((guard, late));
+    }
+
     #[test]
     fn session_registry_millis_since_active_advances_over_time() {
         let registry = SessionRegistry::default();
diff --git a/crates/codegraph-daemon/src/spawn.rs b/crates/codegraph-daemon/src/spawn.rs
index 96d74f0..ba6c5ff 100644
--- a/crates/codegraph-daemon/src/spawn.rs
+++ b/crates/codegraph-daemon/src/spawn.rs
@@ -35,6 +35,9 @@ const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
 /// file watcher, exactly as if the flag had been inherited — but without any
 /// global-env mutation in the parent.
 pub fn spawn_detached_daemon(exe: &Path, root: &Path, no_watch: bool) -> Result<()> {
+    // Resolved once, fail-closed: the log target must be the project's own v2
+    // rendezvous log, never a reconstructed path.
+    let log_path = daemon_log_path(root)?;
     let mut command = Command::new(exe);
     command
         .arg("serve")
@@ -43,8 +46,8 @@ pub fn spawn_detached_daemon(exe: &Path, root: &Path, no_watch: bool) -> Result<
         .arg(root)
         .env(CODEGRAPH_DAEMON_INTERNAL, "1")
         .stdin(Stdio::null())
-        .stdout(log_target(root))
-        .stderr(log_target(root));
+        .stdout(log_target(&log_path))
+        .stderr(log_target(&log_path));
     if no_watch {
         command.env(CODEGRAPH_NO_WATCH, "1");
     }
@@ -60,13 +63,11 @@ pub fn spawn_detached_daemon(exe: &Path, root: &Path, no_watch: bool) -> Result<
     Ok(())
 }
 
-fn log_target(root: &Path) -> Stdio {
-    let path = daemon_log_path(root);
-    // The rendezvous dir (`.codegraph`) is created by the daemon's lock layer in
-    // the CHILD, but this log redirect is set up in the PARENT before spawn. The
-    // current index namespace is the sibling `.codegraph-v2`, so `.codegraph`
-    // may not exist yet — create the log's parent here so the redirect lands in
-    // a file instead of silently falling back to a null sink.
+/// The rendezvous dir is created by the daemon's lock layer in the CHILD, but
+/// this log redirect is set up in the PARENT before spawn, so the parent creates
+/// the log's parent directory here — otherwise the redirect silently falls back
+/// to a null sink and the child's stderr is lost.
+fn log_target(path: &Path) -> Stdio {
     if let Some(parent) = path.parent() {
         let _ = std::fs::create_dir_all(parent);
     }
diff --git a/crates/codegraph-daemon/src/transport.rs b/crates/codegraph-daemon/src/transport.rs
index 8fef060..e46dd2d 100644
--- a/crates/codegraph-daemon/src/transport.rs
+++ b/crates/codegraph-daemon/src/transport.rs
@@ -29,7 +29,8 @@ pub use interprocess::local_socket::{SendHalf, Stream};
 /// yields `AsyncStream`s whose split halves are `AsyncRead`/`AsyncWrite`, and on
 /// unix expose `AsFd` for the force-close reap handle.
 pub use interprocess::local_socket::tokio::{
-    Listener as AsyncListener, RecvHalf as AsyncRecvHalf, Stream as AsyncStream,
+    Listener as AsyncListener, RecvHalf as AsyncRecvHalf, SendHalf as AsyncSendHalf,
+    Stream as AsyncStream,
 };
 
 /// Resolved rendezvous address for a project daemon. On unix `socket_path` is
diff --git a/crates/codegraph-daemon/tests/control_shutdown.rs b/crates/codegraph-daemon/tests/control_shutdown.rs
new file mode 100644
index 0000000..4b40ecb
--- /dev/null
+++ b/crates/codegraph-daemon/tests/control_shutdown.rs
@@ -0,0 +1,308 @@
+//! Batch M item 20 — the daemon side of the `uninit --force` shutdown control
+//! channel.
+//!
+//! The CLI acceptance tests in `codegraph-rs` drive whole processes. These tests
+//! pin the daemon-local guarantees that acceptance cannot observe from outside:
+//!
+//! 1. an authorized control frame ACTIVELY closes a long-lived data session (the
+//!    client's socket reaches EOF) and only then acknowledges the drain;
+//! 2. an UNAUTHORIZED frame (foreign project identity) is answered
+//!    `drained: false`, mutates nothing, and leaves the daemon serving;
+//! 3. an outstanding session at an exhausted drain budget is answered
+//!    `drained: false` on the wire — the daemon never reports success it did not
+//!    achieve;
+//! 4. the caller maps an incomplete-drain reply to
+//!    [`ShutdownOutcome::Unresponsive`] and never signals the recorded pid.
+//!
+//! (3) is deterministic, not timing-dependent: with a zero drain budget the
+//! accept loop checks the outstanding counts in the same poll in which it signals
+//! the sessions to close, before any session task can be polled again, so the
+//! session is provably still counted. (4) is driven against a stub listener that
+//! replies `drained: false`.
+//!
+//! Unix-gated: the stub rendezvous is bound through `GenericFilePath`. The
+//! production code paths under test are platform-independent (the session close
+//! signal is a `tokio::sync::watch`, not a raw fd), but this host cannot execute
+//! the Windows named-pipe arm, so no Windows runtime claim is made here.
+
+#![cfg(unix)]
+
+use std::io::{BufRead, BufReader, Read, Write};
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use codegraph_core::IndexPaths;
+use codegraph_daemon::{
+    ControlAck, ControlFrame, DaemonHandle, DaemonLockInfo, DaemonOptions, ShutdownOutcome,
+    StartOrAttach, encode_lock_info, is_process_alive, request_daemon_shutdown, start_or_attach,
+};
+use interprocess::local_socket::traits::{ListenerExt as _, Stream as _};
+use interprocess::local_socket::{GenericFilePath, ListenerOptions, Stream, ToFsName};
+
+const WAIT: Duration = Duration::from_secs(10);
+
+fn temp_project(label: &str) -> PathBuf {
+    let path = std::env::temp_dir().join(format!(
+        "cg-daemon-control-{label}-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("system clock after epoch")
+            .as_nanos()
+    ));
+    std::fs::create_dir_all(&path).expect("create project");
+    path.canonicalize().expect("canonicalize project")
+}
+
+fn paths_of(project: &Path) -> IndexPaths {
+    IndexPaths::resolve(project, None).expect("resolve v2 index paths")
+}
+
+fn options(drain_budget: Duration) -> DaemonOptions {
+    DaemonOptions {
+        run_mcp: true,
+        watch: false,
+        watchdog_interval: Duration::from_millis(10),
+        drain_budget,
+        ..DaemonOptions::default()
+    }
+}
+
+fn start(project: &Path, drain_budget: Duration) -> DaemonHandle {
+    match start_or_attach(project, options(drain_budget)).expect("daemon starts") {
+        StartOrAttach::Started(handle) => handle,
+        StartOrAttach::Attached(_) => panic!("a fresh project must not attach"),
+    }
+}
+
+fn connect(socket_path: &Path) -> Stream {
+    let name = socket_path
+        .as_os_str()
+        .to_fs_name::<GenericFilePath>()
+        .expect("fs name");
+    Stream::connect(name).expect("connect to the daemon rendezvous")
+}
+
+/// Connect a data client, consume the daemon hello, and leave the connection
+/// open and SILENT — the shape that would keep the session count nonzero forever
+/// if shutdown merely waited instead of actively closing sessions.
+fn connect_silent_data_client(socket_path: &Path) -> Stream {
+    let stream = connect(socket_path);
+    stream
+        .set_recv_timeout(Some(WAIT))
+        .expect("bound the client read");
+    let mut reader = BufReader::new(&stream);
+    let mut hello = String::new();
+    reader.read_line(&mut hello).expect("read the daemon hello");
+    assert!(
+        hello.contains("\"protocol\":1"),
+        "the daemon hello must arrive first: {hello}"
+    );
+    stream
+}
+
+fn send_control_frame(socket_path: &Path, frame: &ControlFrame) -> ControlAck {
+    let stream = connect(socket_path);
+    stream
+        .set_recv_timeout(Some(WAIT))
+        .expect("bound the control read");
+    stream
+        .set_send_timeout(Some(WAIT))
+        .expect("bound the control write");
+    let mut reader = BufReader::new(&stream);
+    let mut hello = String::new();
+    reader.read_line(&mut hello).expect("read the daemon hello");
+    (&stream)
+        .write_all(format!("{}\n", serde_json::to_string(frame).expect("frame json")).as_bytes())
+        .expect("send the control frame");
+    (&stream).flush().expect("flush the control frame");
+    let mut ack = String::new();
+    reader.read_line(&mut ack).expect("read the control reply");
+    serde_json::from_str(ack.trim()).expect("decode the control reply")
+}
+
+fn wait_finished(handle: &DaemonHandle, label: &str) {
+    let deadline = Instant::now() + WAIT;
+    while Instant::now() < deadline {
+        if handle.is_finished() {
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(10));
+    }
+    panic!("{label} did not finish within {WAIT:?}");
+}
+
+#[test]
+fn authorized_shutdown_closes_a_long_lived_session_before_acknowledging() {
+    let project = temp_project("closes-session");
+    let paths = paths_of(&project);
+    let handle = start(&project, Duration::from_secs(10));
+    let socket = handle.socket_path().to_path_buf();
+
+    let mut silent = connect_silent_data_client(&socket);
+    let ack = send_control_frame(&socket, &ControlFrame::shutdown(paths.project_identity()));
+    assert!(
+        ack.accepted(),
+        "an authorized frame must be acknowledged after a completed drain: {ack:?}"
+    );
+
+    // The long-lived session was closed by the daemon, not by the client: its
+    // socket reads EOF. Reverting the active close makes this read time out.
+    let mut rest = Vec::new();
+    silent
+        .read_to_end(&mut rest)
+        .expect("the closed session must EOF, not time out");
+    assert!(
+        rest.is_empty(),
+        "no further bytes are served after shutdown: {rest:?}"
+    );
+
+    // The ACK follows rendezvous removal, so both are already gone.
+    assert!(!paths.daemon_pid().exists(), "the owner record is removed");
+    assert!(!socket.exists(), "the bound socket is removed");
+    wait_finished(&handle, "the drained daemon");
+    handle.wait().expect("the accept loop joins cleanly");
+    let _ = std::fs::remove_dir_all(&project);
+}
+
+#[test]
+fn an_unauthorized_frame_is_refused_without_shutting_the_daemon_down() {
+    let project = temp_project("refuses-foreign");
+    let paths = paths_of(&project);
+    let handle = start(&project, Duration::from_secs(10));
+    let socket = handle.socket_path().to_path_buf();
+
+    for frame in [
+        ControlFrame::shutdown("0000000000000000000000000000000000000000000000000000000000000000"),
+        ControlFrame {
+            codegraph_control: codegraph_daemon::CONTROL_PROTOCOL + 1,
+            action: "shutdown".to_string(),
+            project_identity: paths.project_identity().to_string(),
+        },
+        ControlFrame {
+            codegraph_control: codegraph_daemon::CONTROL_PROTOCOL,
+            action: "reindex".to_string(),
+            project_identity: paths.project_identity().to_string(),
+        },
+    ] {
+        let ack = send_control_frame(&socket, &frame);
+        assert!(
+            !ack.accepted(),
+            "an unauthorized frame must never be acknowledged: {frame:?} -> {ack:?}"
+        );
+        assert!(
+            paths.daemon_pid().exists() && socket.exists(),
+            "a refused frame mutates no rendezvous artifact"
+        );
+        assert!(!handle.is_finished(), "a refused frame never stops serving");
+    }
+
+    // Still serving: an authorized frame afterwards is what actually drains it.
+    let ack = send_control_frame(&socket, &ControlFrame::shutdown(paths.project_identity()));
+    assert!(ack.accepted());
+    wait_finished(&handle, "the drained daemon");
+    handle.wait().expect("the accept loop joins cleanly");
+    let _ = std::fs::remove_dir_all(&project);
+}
+
+#[test]
+fn an_exhausted_drain_budget_replies_incomplete_instead_of_success() {
+    let project = temp_project("budget-exhausted");
+    let paths = paths_of(&project);
+    // A zero budget cannot be met while any session is still outstanding.
+    let handle = start(&project, Duration::ZERO);
+    let socket = handle.socket_path().to_path_buf();
+
+    let _silent = connect_silent_data_client(&socket);
+    let ack = send_control_frame(&socket, &ControlFrame::shutdown(paths.project_identity()));
+    assert!(
+        !ack.drained,
+        "an unmet drain budget must reply with an INCOMPLETE drain: {ack:?}"
+    );
+    assert!(
+        !ack.accepted(),
+        "an incomplete drain must never be accepted as success"
+    );
+
+    // The daemon still tears down only what it owns, so a repeated `uninit --force`
+    // can continue; nothing else was touched.
+    wait_finished(&handle, "the daemon after an incomplete drain");
+    handle.wait().expect("the accept loop joins cleanly");
+    assert!(!paths.daemon_pid().exists());
+    assert!(
+        paths.current_root().is_dir(),
+        "the namespace itself survives"
+    );
+    let _ = std::fs::remove_dir_all(&project);
+}
+
+#[test]
+fn an_incomplete_drain_reply_is_unresponsive_and_never_signals_the_owner() {
+    let project = temp_project("incomplete-drain");
+    let paths = paths_of(&project);
+    std::fs::create_dir_all(paths.current_root()).expect("create the v2 rendezvous dir");
+    let socket = paths.current_root().join("daemon.sock");
+
+    // A stub rendezvous that answers every control frame with an INCOMPLETE drain,
+    // recorded as owned by THIS live process.
+    let listener = ListenerOptions::new()
+        .name(
+            socket
+                .as_os_str()
+                .to_fs_name::<GenericFilePath>()
+                .expect("fs name"),
+        )
+        .create_sync()
+        .expect("bind the stub rendezvous");
+    let stub = std::thread::spawn(move || {
+        let Some(Ok(stream)) = listener.incoming().next() else {
+            return;
+        };
+        let _ = stream.set_send_timeout(Some(WAIT));
+        let _ = stream.set_recv_timeout(Some(WAIT));
+        let mut reader = BufReader::new(&stream);
+        let _ = (&stream).write_all(b"{\"codegraph\":\"stub\",\"protocol\":1}\n");
+        let _ = (&stream).flush();
+        let mut frame = String::new();
+        let _ = reader.read_line(&mut frame);
+        let reply = serde_json::to_string(&ControlAck::for_drain(false)).expect("reply json");
+        let _ = (&stream).write_all(format!("{reply}\n").as_bytes());
+        let _ = (&stream).flush();
+    });
+
+    let owner = DaemonLockInfo {
+        pid: std::process::id(),
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        socket_path: socket.clone(),
+        started_at: 1,
+    };
+    std::fs::write(
+        paths.daemon_pid(),
+        encode_lock_info(&owner).expect("encode the owner record"),
+    )
+    .expect("write the owner record");
+
+    let outcome = request_daemon_shutdown(&project, paths.project_identity())
+        .expect("an incomplete drain is data, not an error");
+    match outcome {
+        ShutdownOutcome::Unresponsive { pid, detail } => {
+            assert_eq!(pid, std::process::id());
+            assert!(
+                detail.contains("incomplete drain"),
+                "the refusal must name the incomplete drain: {detail}"
+            );
+        }
+        other => panic!("an incomplete drain must be unresponsive, got {other:?}"),
+    }
+    assert!(
+        is_process_alive(std::process::id()),
+        "the recorded owner is never signalled"
+    );
+    assert!(
+        paths.daemon_pid().exists(),
+        "a fail-closed exchange removes no rendezvous artifact"
+    );
+
+    let _ = stub.join();
+    let _ = std::fs::remove_dir_all(&project);
+}
diff --git a/crates/codegraph-daemon/tests/lifecycle.rs b/crates/codegraph-daemon/tests/lifecycle.rs
index 4b98569..9a4e6ca 100644
--- a/crates/codegraph-daemon/tests/lifecycle.rs
+++ b/crates/codegraph-daemon/tests/lifecycle.rs
@@ -9,6 +9,10 @@ use codegraph_daemon::{
     start_or_attach, unlock_project,
 };
 
+fn pid_path_of(project: &Path) -> PathBuf {
+    daemon_pid_path(project).expect("resolve the v2 rendezvous pid path")
+}
+
 #[test]
 fn second_daemon_attaches_to_existing_project_daemon() {
     let project = temp_project("single-instance");
@@ -29,7 +33,7 @@ fn second_daemon_attaches_to_existing_project_daemon() {
     }
 
     first.stop().expect("daemon stops");
-    assert!(!daemon_pid_path(&project).exists());
+    assert!(!pid_path_of(&project).exists());
     let _ = fs::remove_dir_all(project);
 }
 
@@ -68,20 +72,21 @@ fn host_pid_watchdog_stops_daemon_after_parent_agent_exits() {
         "daemon did not stop after watched pid exited"
     );
     handle.stop().expect("finished daemon joins");
-    assert!(!daemon_pid_path(&project).exists());
+    assert!(!pid_path_of(&project).exists());
     let _ = fs::remove_dir_all(project);
 }
 
 #[test]
 fn unlock_project_removes_stale_daemon_lock() {
     let project = temp_project("unlock-stale");
-    let codegraph_dir = project.join(".codegraph");
-    fs::create_dir_all(&codegraph_dir).expect("create .codegraph");
-    let pid_path = daemon_pid_path(&project);
+    let pid_path = pid_path_of(&project);
+    fs::create_dir_all(pid_path.parent().expect("rendezvous dir"))
+        .expect("create the v2 rendezvous dir");
     let info = DaemonLockInfo {
         pid: 999_999_999,
         version: "test".to_string(),
-        socket_path: codegraph_dir.join("daemon.sock"),
+        socket_path: codegraph_daemon::daemon_socket_path(&project)
+            .expect("resolve the v2 rendezvous socket identity"),
         started_at: 1,
     };
     fs::write(&pid_path, encode_lock_info(&info).expect("serialize lock")).expect("write lock");
@@ -110,9 +115,12 @@ fn temp_project(name: &str) -> PathBuf {
         std::process::id()
     ));
     create_project(&path);
-    path
+    path.canonicalize().expect("canonicalize project")
 }
 
+/// A real project directory: `IndexPaths` derives the physical project identity
+/// from the filesystem object, so the project must exist before any rendezvous
+/// path resolves.
 fn create_project(path: &Path) {
-    fs::create_dir_all(path.join(".codegraph")).expect("create project");
+    fs::create_dir_all(path).expect("create project");
 }
diff --git a/crates/codegraph-daemon/tests/regressions.rs b/crates/codegraph-daemon/tests/regressions.rs
index 6b3f217..3d73f2e 100644
--- a/crates/codegraph-daemon/tests/regressions.rs
+++ b/crates/codegraph-daemon/tests/regressions.rs
@@ -24,6 +24,10 @@ use codegraph_daemon::{
     try_acquire_daemon_lock,
 };
 
+fn pid_path_of(project: &Path) -> PathBuf {
+    daemon_pid_path(project).expect("resolve the v2 rendezvous pid path")
+}
+
 // A pid that is not a live process on any sane Unix host; used to forge a
 // "stale" lock whose owner is provably dead.
 const DEAD_PID: u32 = 999_999_999;
@@ -91,7 +95,7 @@ fn concurrent_acquire_has_exactly_one_process_winner() {
 
     // The published pidfile is a full, valid lock record -- never the empty
     // create_new placeholder a torn write-then-publish would leave behind.
-    let pid_path = daemon_pid_path(&project);
+    let pid_path = pid_path_of(&project);
     let raw = fs::read_to_string(&pid_path).expect("winner published a pidfile");
     assert!(
         !raw.trim().is_empty(),
@@ -125,7 +129,7 @@ fn stop_flag_terminates_accept_loop_and_clears_pidfile() {
         StartOrAttach::Attached(_) => panic!("first start unexpectedly attached"),
     };
     assert!(
-        daemon_pid_path(&project).exists(),
+        pid_path_of(&project).exists(),
         "a started daemon must publish its pidfile"
     );
     assert!(
@@ -142,7 +146,7 @@ fn stop_flag_terminates_accept_loop_and_clears_pidfile() {
         "accept loop must stop within {SHUTDOWN_CEILING:?}, took {elapsed:?}"
     );
     assert!(
-        !daemon_pid_path(&project).exists(),
+        !pid_path_of(&project).exists(),
         "stopping the daemon must clean up its pidfile"
     );
     let _ = fs::remove_dir_all(project);
@@ -153,7 +157,7 @@ fn stop_flag_terminates_accept_loop_and_clears_pidfile() {
 #[test]
 fn dead_pid_lock_is_recovered_by_start_or_attach() {
     let project = temp_project("stale-dead-pid");
-    let pid_path = daemon_pid_path(&project);
+    let pid_path = pid_path_of(&project);
     write_lock(&pid_path, DEAD_PID);
 
     let handle = match start_or_attach(&project, test_options()).expect("recovers stale lock") {
@@ -177,7 +181,7 @@ fn dead_pid_lock_is_recovered_by_start_or_attach() {
 #[test]
 fn clear_stale_daemon_lock_removes_dead_pid_lock() {
     let project = temp_project("clear-dead-pid");
-    let pid_path = daemon_pid_path(&project);
+    let pid_path = pid_path_of(&project);
     write_lock(&pid_path, DEAD_PID);
 
     assert!(
@@ -195,7 +199,7 @@ fn clear_stale_daemon_lock_removes_dead_pid_lock() {
 #[test]
 fn empty_pidfile_is_not_deleted_by_reader() {
     let project = temp_project("empty-pidfile");
-    let pid_path = daemon_pid_path(&project);
+    let pid_path = pid_path_of(&project);
 
     // Durable 0-byte placeholder: `fs::write` can return before the directory
     // entry is flushed, so under load the guard's 20ms-later re-read
@@ -320,6 +324,11 @@ fn temp_project(name: &str) -> PathBuf {
         "codegraph-daemon-reg-{name}-{}-{nanos}-{seq}",
         std::process::id()
     ));
-    fs::create_dir_all(path.join(".codegraph")).expect("create project");
+    fs::create_dir_all(&path).expect("create project");
+    let path = path.canonicalize().expect("canonicalize project");
+    // Tests here write the pid record directly, so materialize the v2 rendezvous
+    // dir the daemon's lock layer would otherwise create.
+    fs::create_dir_all(pid_path_of(&path).parent().expect("rendezvous dir"))
+        .expect("create the v2 rendezvous dir");
     path
 }
diff --git a/crates/codegraph-daemon/tests/rmcp_reap.rs b/crates/codegraph-daemon/tests/rmcp_reap.rs
index 11c4c65..4d25d0d 100644
--- a/crates/codegraph-daemon/tests/rmcp_reap.rs
+++ b/crates/codegraph-daemon/tests/rmcp_reap.rs
@@ -148,6 +148,6 @@ fn temp_project(name: &str) -> PathBuf {
         "codegraph-daemon-{name}-{}-{nanos}-{seq}",
         std::process::id()
     ));
-    fs::create_dir_all(path.join(".codegraph")).expect("create project");
-    path
+    fs::create_dir_all(&path).expect("create project");
+    path.canonicalize().expect("canonicalize project")
 }
diff --git a/crates/codegraph-daemon/tests/stale_socket.rs b/crates/codegraph-daemon/tests/stale_socket.rs
index 3f64551..4086c65 100644
--- a/crates/codegraph-daemon/tests/stale_socket.rs
+++ b/crates/codegraph-daemon/tests/stale_socket.rs
@@ -13,6 +13,8 @@
 //!   2. The stale-socket self-heal helper clears the leftover `daemon.sock` +
 //!      `daemon.pid` when the recorded pid is dead, so the NEXT startup spawns a
 //!      fresh daemon cleanly.
+//!
+//! Both operate on the v2 rendezvous identities resolved through `IndexPaths`.
 
 #![cfg(unix)]
 
@@ -22,8 +24,8 @@ use std::process;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use codegraph_daemon::{
-    DaemonLockInfo, attach_to_daemon, clear_stale_daemon_socket, daemon_pid_path, encode_lock_info,
-    recorded_socket_path,
+    DaemonLockInfo, attach_to_daemon, clear_stale_daemon_socket, daemon_pid_path,
+    daemon_socket_path, encode_lock_info, recorded_socket_path,
 };
 
 // A pid that is not a live process on any sane Unix host.
@@ -39,7 +41,7 @@ const ATTACH_CEILING: Duration = Duration::from_secs(4);
 #[test]
 fn attach_to_orphaned_socket_returns_err_within_bound() {
     let project = temp_project("orphaned-sock");
-    let socket_path = project.join(".codegraph/daemon.sock");
+    let socket_path = socket_path_of(&project);
 
     // Bind a listener to create the .sock file, then DROP it: the filesystem
     // entry survives but nothing is accepting. A connect either refuses or
@@ -72,11 +74,11 @@ fn attach_to_orphaned_socket_returns_err_within_bound() {
 }
 
 /// 1b. A plain FILE at the `.sock` path (not even a socket) must also fail fast
-///     — this is the `touch .codegraph/daemon.sock` shape of the leftover.
+///     — this is the `touch <current-root>/daemon.sock` shape of the leftover.
 #[test]
 fn attach_to_plain_file_socket_returns_err_within_bound() {
     let project = temp_project("plain-file-sock");
-    let socket_path = project.join(".codegraph/daemon.sock");
+    let socket_path = socket_path_of(&project);
     fs::write(&socket_path, b"not a socket").expect("write plain file at sock path");
 
     let started = Instant::now();
@@ -101,8 +103,8 @@ fn attach_to_plain_file_socket_returns_err_within_bound() {
 #[test]
 fn clear_stale_daemon_socket_removes_dead_pid_sock_and_lock() {
     let project = temp_project("self-heal-dead");
-    let pid_path = daemon_pid_path(&project);
-    let socket_path = project.join(".codegraph/daemon.sock");
+    let pid_path = pid_path_of(&project);
+    let socket_path = socket_path_of(&project);
 
     write_lock(&pid_path, DEAD_PID, &socket_path);
     // Leave an orphaned socket file behind (the crashed daemon's residue).
@@ -141,8 +143,8 @@ fn clear_stale_daemon_socket_removes_dead_pid_sock_and_lock() {
 #[test]
 fn clear_stale_daemon_socket_preserves_live_pid_lock() {
     let project = temp_project("self-heal-live");
-    let pid_path = daemon_pid_path(&project);
-    let socket_path = project.join(".codegraph/daemon.sock");
+    let pid_path = pid_path_of(&project);
+    let socket_path = socket_path_of(&project);
 
     // Our own pid is alive — a live lock must never be cleared.
     write_lock(&pid_path, process::id(), &socket_path);
@@ -169,9 +171,18 @@ fn clear_stale_daemon_socket_preserves_live_pid_lock() {
 #[test]
 fn clear_stale_daemon_socket_removes_recorded_fallback_socket() {
     let project = temp_project("self-heal-recorded");
-    let pid_path = daemon_pid_path(&project);
-    // Record a DIFFERENT socket path than the default (a fallback-tmpdir shape).
-    let recorded = project.join(".codegraph/daemon-fallback.sock");
+    let pid_path = pid_path_of(&project);
+    // Record a DIFFERENT socket than the default: the tmpdir shape production
+    // falls back to when the in-root path exceeds the AF_UNIX limit. Keeping it
+    // in the tmpdir root is also what keeps THIS path bindable.
+    let recorded = std::env::temp_dir().join(format!(
+        "cg-v2-fallback-{}-{}.sock",
+        process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos()
+    ));
     write_lock(&pid_path, DEAD_PID, &recorded);
     {
         let listener =
@@ -179,7 +190,7 @@ fn clear_stale_daemon_socket_removes_recorded_fallback_socket() {
         drop(listener);
     }
     assert_eq!(
-        recorded_socket_path(&project),
+        recorded_socket_path(&project).expect("resolve recorded socket"),
         recorded,
         "precondition: lock records the fallback socket"
     );
@@ -189,6 +200,7 @@ fn clear_stale_daemon_socket_removes_recorded_fallback_socket() {
     assert!(healed, "stale recorded socket + dead pid must heal");
     assert!(!recorded.exists(), "the RECORDED socket must be removed");
     assert!(!pid_path.exists(), "the stale pid must be removed");
+    let _ = fs::remove_file(&recorded);
 
     let _ = fs::remove_dir_all(project);
 }
@@ -200,10 +212,13 @@ fn write_lock(pid_path: &Path, pid: u32, socket_path: &Path) {
         socket_path: socket_path.to_path_buf(),
         started_at: 1,
     };
-    fs::create_dir_all(pid_path.parent().expect("pid parent")).expect("create .codegraph");
+    fs::create_dir_all(pid_path.parent().expect("pid parent")).expect("create the rendezvous dir");
     fs::write(pid_path, encode_lock_info(&info).expect("serialize lock")).expect("write lock");
 }
 
+/// A real project directory whose v2 rendezvous dir exists. `IndexPaths` derives
+/// the physical project identity from the filesystem object, so the project must
+/// exist before any rendezvous path resolves.
 fn temp_project(name: &str) -> PathBuf {
     let nanos = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -213,6 +228,18 @@ fn temp_project(name: &str) -> PathBuf {
         "codegraph-daemon-stale-{name}-{}-{nanos}",
         process::id()
     ));
-    fs::create_dir_all(path.join(".codegraph")).expect("create project");
+    fs::create_dir_all(&path).expect("create project");
+    let path = path.canonicalize().expect("canonicalize project");
+    let pid_path = pid_path_of(&path);
+    fs::create_dir_all(pid_path.parent().expect("rendezvous dir"))
+        .expect("create the v2 rendezvous dir");
     path
 }
+
+fn pid_path_of(project: &Path) -> PathBuf {
+    daemon_pid_path(project).expect("resolve the v2 rendezvous pid path")
+}
+
+fn socket_path_of(project: &Path) -> PathBuf {
+    daemon_socket_path(project).expect("resolve the v2 rendezvous socket identity")
+}
diff --git a/crates/codegraph-store/src/lib.rs b/crates/codegraph-store/src/lib.rs
index b121c22..ccc34a6 100644
--- a/crates/codegraph-store/src/lib.rs
+++ b/crates/codegraph-store/src/lib.rs
@@ -31,4 +31,4 @@ pub use rebuild::{
     ActiveFullRebuild, FullRebuild, RebuildError, RebuildKind, begin_full_rebuild,
     resume_full_rebuild,
 };
-pub use uninit::{UninitError, UninitOutcome, uninit_index};
+pub use uninit::{UninitError, UninitOutcome, uninit_index, uninit_index_with_drain};
diff --git a/crates/codegraph-store/src/uninit.rs b/crates/codegraph-store/src/uninit.rs
index 853a96b..53a0057 100644
--- a/crates/codegraph-store/src/uninit.rs
+++ b/crates/codegraph-store/src/uninit.rs
@@ -58,6 +58,15 @@ pub enum UninitError {
         #[source]
         source: io::Error,
     },
+    /// A live daemon never acknowledged the owner-bound shutdown control frame.
+    /// Both durable markers already published, so the namespace stays recoverable
+    /// `Uninitialized` and no runtime child was removed. No pid is ever signalled.
+    #[error(
+        "uninit is incomplete: {detail}. The index is now uninitialized and its \
+         tombstone is published; rerun `codegraph uninit --force` once the daemon \
+         has exited, or run `codegraph init` to rebuild"
+    )]
+    DaemonNotDrained { detail: String },
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -65,6 +74,7 @@ enum UninitCheckpoint {
     BeforeAuthorization,
     StatePublished,
     TombstoneEnsured,
+    DaemonDrained,
     DatabaseRemoved,
     WalRemoved,
     ShmRemoved,
@@ -81,6 +91,7 @@ impl UninitCheckpoint {
             Self::BeforeAuthorization => "write authorization",
             Self::StatePublished => "uninitialized state publication",
             Self::TombstoneEnsured => "tombstone creation",
+            Self::DaemonDrained => "daemon drain",
             Self::DatabaseRemoved => "database removal",
             Self::WalRemoved => "WAL removal",
             Self::ShmRemoved => "SHM removal",
@@ -114,13 +125,34 @@ pub fn uninit_index(
     deadline: Instant,
     cancelled: impl FnMut() -> bool,
 ) -> Result<UninitOutcome, UninitError> {
-    uninit_index_with(paths, deadline, cancelled, &mut NoFault)
+    uninit_index_with_drain(paths, deadline, cancelled, || Ok(()))
+}
+
+/// [`uninit_index`] with the owner-bound daemon-drain step wired in.
+///
+/// `drain` runs INSIDE the retained exclusive lease, AFTER both durable markers
+/// (the authoritative `uninitialized` state slot, then the tombstone) have
+/// published and BEFORE any runtime child is removed — the exact order the frozen
+/// plan requires. It must send the versioned, project-identity-bound shutdown
+/// control frame and return only once the daemon has drained and removed its own
+/// rendezvous; an `Err(detail)` is fail-closed
+/// ([`UninitError::DaemonNotDrained`]), leaving the recoverable `Uninitialized`
+/// namespace and every runtime child in place. The store layer never learns how
+/// to reach a daemon, so it can never fall back to signalling a pid.
+pub fn uninit_index_with_drain(
+    paths: &IndexPaths,
+    deadline: Instant,
+    cancelled: impl FnMut() -> bool,
+    drain: impl FnOnce() -> Result<(), String>,
+) -> Result<UninitOutcome, UninitError> {
+    uninit_index_with(paths, deadline, cancelled, drain, &mut NoFault)
 }
 
 fn uninit_index_with(
     paths: &IndexPaths,
     deadline: Instant,
     cancelled: impl FnMut() -> bool,
+    drain: impl FnOnce() -> Result<(), String>,
     fault: &mut impl UninitFault,
 ) -> Result<UninitOutcome, UninitError> {
     let visible = Store::extraction_status(paths);
@@ -158,6 +190,12 @@ fn uninit_index_with(
     ensure_tombstone(paths, &lease)?;
     checkpoint(fault, UninitCheckpoint::TombstoneEnsured)?;
 
+    // Both durable markers are published, so a failure from here on classifies as
+    // recoverable `Uninitialized` and is continuable by a repeated
+    // `uninit --force`.
+    drain().map_err(|detail| UninitError::DaemonNotDrained { detail })?;
+    checkpoint(fault, UninitCheckpoint::DaemonDrained)?;
+
     let db = paths.current_db();
     remove_child(paths, &lease, &db)?;
     checkpoint(fault, UninitCheckpoint::DatabaseRemoved)?;
@@ -451,8 +489,14 @@ mod tests {
                 .expect("write legacy proof bytes");
             let legacy_before = snapshot(&legacy);
 
-            let error = uninit_index_with(&paths, deadline(), || false, &mut FailAfter(boundary))
-                .expect_err("fault checkpoint must interrupt uninit");
+            let error = uninit_index_with(
+                &paths,
+                deadline(),
+                || false,
+                || Ok(()),
+                &mut FailAfter(boundary),
+            )
+            .expect_err("fault checkpoint must interrupt uninit");
             match error {
                 UninitError::Interrupted { step, source } => {
                     assert_eq!(step, expected_step, "boundary={boundary:?}");
@@ -694,6 +738,104 @@ mod tests {
         assert_unchanged(&before, &snapshot(&project.0));
     }
 
+    #[test]
+    fn an_undrained_daemon_leaves_recoverable_uninitialized_residue() {
+        let project = TempProject::new("drain-refused");
+        let paths = project.paths();
+        stage_building_with_all_residue(&paths);
+
+        let error = uninit_index_with_drain(
+            &paths,
+            deadline(),
+            || false,
+            || Err("daemon 4242 never acknowledged the shutdown control frame".to_string()),
+        )
+        .expect_err("an undrained daemon must fail closed");
+        match &error {
+            UninitError::DaemonNotDrained { detail } => {
+                assert!(detail.contains("4242"), "detail names the owner: {detail}");
+            }
+            other => panic!("unexpected uninit result: {other:?}"),
+        }
+        let rendered = error.to_string();
+        assert!(
+            rendered.contains("uninit is incomplete") && rendered.contains("uninit --force"),
+            "the error must state the incomplete uninit and its continuation: {rendered}"
+        );
+
+        // Both durable markers published BEFORE the drain, so the namespace is
+        // recoverable — never Corrupt — and no runtime child was removed.
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Uninitialized
+        );
+        assert_eq!(classify(&paths).status(), &ExtractionStatus::Uninitialized);
+        assert!(paths.tombstone().is_file());
+        assert!(paths.permanent_lock().is_file());
+        assert!(paths.state_slots().iter().all(|slot| slot.is_file()));
+        for artifact in [
+            paths.current_db(),
+            db_artifact(&paths, "-wal"),
+            db_artifact(&paths, "-shm"),
+            paths.config_toml(),
+            paths.extension_config(),
+            paths.daemon_pid(),
+            paths.daemon_log(),
+            paths.daemon_socket(),
+        ] {
+            assert!(
+                artifact.exists(),
+                "a fail-closed uninit removes no runtime child: {}",
+                artifact.display()
+            );
+        }
+
+        // The continuation resumes idempotently once the daemon is gone.
+        uninit_index(&paths, deadline(), || false).expect("uninit continuation");
+        assert!(!paths.current_db().exists());
+        assert!(!paths.daemon_pid().exists());
+        assert_eq!(
+            Store::extraction_status(&paths),
+            ExtractionStatus::Uninitialized
+        );
+    }
+
+    #[test]
+    fn the_drain_runs_after_both_markers_and_before_any_child_removal() {
+        let project = TempProject::new("drain-order");
+        let paths = project.paths();
+        stage_building_with_all_residue(&paths);
+
+        let mut observed = None;
+        uninit_index_with_drain(
+            &paths,
+            deadline(),
+            || false,
+            || {
+                observed = Some((
+                    Store::extraction_status(&paths),
+                    paths.tombstone().is_file(),
+                    paths.current_db().exists(),
+                    paths.daemon_pid().exists(),
+                ));
+                Ok(())
+            },
+        )
+        .expect("uninit with a draining daemon");
+
+        let (status, tombstone, db, pid) = observed.expect("the drain step ran exactly once");
+        assert_eq!(
+            status,
+            ExtractionStatus::Uninitialized,
+            "the authoritative slot publishes before the drain"
+        );
+        assert!(tombstone, "the tombstone publishes before the drain");
+        assert!(db, "no database is removed before the drain");
+        assert!(pid, "no runtime child is removed before the drain");
+        assert!(!paths.current_db().exists(), "cleanup follows the drain");
+        assert!(!paths.daemon_pid().exists());
+    }
+
     #[test]
     fn nonmutation_snapshot_detects_equal_length_replacement() {
         let project = TempProject::new("snapshot-self-test");
diff --git a/crates/codegraph-watch/src/lib.rs b/crates/codegraph-watch/src/lib.rs
index d13ab5f..f09328e 100644
--- a/crates/codegraph-watch/src/lib.rs
+++ b/crates/codegraph-watch/src/lib.rs
@@ -13,7 +13,8 @@ pub use policy::{
     CODEGRAPH_NO_WATCH, TooBroadRoot, WatchPolicy, too_broad_root_reason, watch_disabled_reason,
 };
 pub use sync::{
-    SyncOutcome, sync_changed_paths, sync_project_once, sync_project_once_with_progress,
+    SyncCancellation, SyncOutcome, sync_changed_paths, sync_project_once,
+    sync_project_once_cancellable, sync_project_once_with_progress,
 };
 pub use watcher::{
     PendingFile, ProjectWatcher, WatchOptions, start_serve_watcher, watch_options_for_project,
diff --git a/crates/codegraph-watch/src/sync.rs b/crates/codegraph-watch/src/sync.rs
index 55ba12c..3784684 100644
--- a/crates/codegraph-watch/src/sync.rs
+++ b/crates/codegraph-watch/src/sync.rs
@@ -25,6 +25,62 @@ use crate::policy::WatchPolicy;
 /// timeout instead of hanging.
 const SYNC_LEASE_TIMEOUT: Duration = Duration::from_secs(30);
 
+/// Cooperative cancellation for a sync's bounded lease loop.
+///
+/// Frozen plan lines 598-601: `uninit --force` signals cancellation to queued and
+/// running watcher lock loops and drains only after every cancellation-aware
+/// lease loop has exited. Without this, a watcher sync queued behind uninit's
+/// exclusive lease would spin its full [`SYNC_LEASE_TIMEOUT`] before the daemon
+/// could finish draining. Cancellation is observed by `IndexLease`'s bounded
+/// acquisition loop, so a cancelled sync returns a typed error and mutates
+/// nothing.
+#[derive(Clone, Debug, Default)]
+pub struct SyncCancellation {
+    cancelled: Arc<std::sync::atomic::AtomicBool>,
+    running: Arc<std::sync::atomic::AtomicUsize>,
+}
+
+impl SyncCancellation {
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Refuse every queued lease loop and interrupt every running one.
+    pub fn cancel(&self) {
+        self.cancelled
+            .store(true, std::sync::atomic::Ordering::SeqCst);
+    }
+
+    #[must_use]
+    pub fn is_cancelled(&self) -> bool {
+        self.cancelled.load(std::sync::atomic::Ordering::SeqCst)
+    }
+
+    /// How many cancellation-aware lease loops are currently inside a sync.
+    /// A drain waits for this to reach zero after [`cancel`](Self::cancel).
+    #[must_use]
+    pub fn active_syncs(&self) -> usize {
+        self.running.load(std::sync::atomic::Ordering::SeqCst)
+    }
+
+    fn enter(&self) -> SyncCancellationGuard<'_> {
+        self.running
+            .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        SyncCancellationGuard(self)
+    }
+}
+
+struct SyncCancellationGuard<'a>(&'a SyncCancellation);
+
+impl Drop for SyncCancellationGuard<'_> {
+    fn drop(&mut self) {
+        self.0
+            .running
+            .fetch_sub(1, std::sync::atomic::Ordering::SeqCst);
+    }
+}
+
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct SyncOutcome {
     pub files_checked: usize,
@@ -47,6 +103,19 @@ pub fn sync_project_once(project_root: impl AsRef<Path>) -> Result<SyncOutcome>
     sync_project_once_with_progress(project_root, |_, _| {})
 }
 
+/// [`sync_project_once`] under a caller-owned [`SyncCancellation`], so a daemon
+/// shutdown can refuse this sync's queued lease loop and interrupt a running one
+/// instead of waiting out the full lease budget.
+pub fn sync_project_once_cancellable(
+    project_root: impl AsRef<Path>,
+    cancel: &SyncCancellation,
+) -> Result<SyncOutcome> {
+    let project_root = project_root.as_ref();
+    let paths = index_paths(project_root)?;
+    let scope = ProjectScope::load(project_root, &paths)?;
+    sync_project_once_with_scope(project_root, &paths, &scope, Some(cancel), |_, _| {})
+}
+
 /// Whole-project sync using watcher-owned path patterns while preserving every
 /// other scan option from the normal sync path.
 ///
@@ -59,13 +128,14 @@ pub(crate) fn sync_project_once_with_patterns(
     project_root: impl AsRef<Path>,
     include: &[String],
     exclude: &[String],
+    cancel: Option<&SyncCancellation>,
 ) -> Result<SyncOutcome> {
     let project_root = project_root.as_ref();
     let paths = index_paths(project_root)?;
     let mut scope = ProjectScope::load(project_root, &paths)?;
     scope.options.include = include.to_vec();
     scope.options.exclude = exclude.to_vec();
-    sync_project_once_with_scope(project_root, &paths, &scope, |_, _| {})
+    sync_project_once_with_scope(project_root, &paths, &scope, cancel, |_, _| {})
 }
 
 /// Like [`sync_project_once`] but invokes `on_progress(done, total)` after each
@@ -79,13 +149,14 @@ pub fn sync_project_once_with_progress(
     let project_root = project_root.as_ref();
     let paths = index_paths(project_root)?;
     let scope = ProjectScope::load(project_root, &paths)?;
-    sync_project_once_with_scope(project_root, &paths, &scope, on_progress)
+    sync_project_once_with_scope(project_root, &paths, &scope, None, on_progress)
 }
 
 fn sync_project_once_with_scope(
     project_root: &Path,
     paths: &IndexPaths,
     scope: &ProjectScope,
+    cancel: Option<&SyncCancellation>,
     mut on_progress: impl FnMut(usize, usize),
 ) -> Result<SyncOutcome> {
     let options = &scope.options;
@@ -98,7 +169,8 @@ fn sync_project_once_with_scope(
     // the incremental writer for a corroborated Current namespace or the
     // lease-retaining authorization that escalates to a forced full migration.
     // Future/Corrupt/unauthorized-Uninitialized fail here, before any byte moves.
-    match open_sync_writer(paths)? {
+    let _active = cancel.map(SyncCancellation::enter);
+    match open_sync_writer(paths, cancel)? {
         SyncWriter::Incremental(mut store) => {
             let mut candidates = codegraph_extract::engine::scan_project(project_root, options)?;
             // Cold CLI sync has no watcher event list, so deletions are found by
@@ -190,9 +262,18 @@ pub(crate) fn index_paths(project_root: &Path) -> Result<IndexPaths> {
 
 /// Acquire the ONE outer exclusive lease and classify under it. The retained
 /// status decides policy; no precheck-then-reclassify happens anywhere.
-fn open_sync_writer(paths: &IndexPaths) -> Result<SyncWriter> {
+fn open_sync_writer(paths: &IndexPaths, cancel: Option<&SyncCancellation>) -> Result<SyncWriter> {
+    if let Some(cancel) = cancel
+        && cancel.is_cancelled()
+    {
+        bail!(
+            "sync of {} was cancelled before acquiring the index lease",
+            paths.current_root().display()
+        );
+    }
     let deadline = Instant::now() + SYNC_LEASE_TIMEOUT;
-    let lease = IndexLease::acquire_or_create_exclusive(paths, deadline, || false)?;
+    let cancelled = || cancel.is_some_and(SyncCancellation::is_cancelled);
+    let lease = IndexLease::acquire_or_create_exclusive(paths, deadline, cancelled)?;
     match Store::open_for_write(paths, lease, StoreWritePurpose::IncrementalSync)? {
         StoreWriteOpen::Current(store) => Ok(SyncWriter::Incremental(store)),
         StoreWriteOpen::FullRebuildRequired(authorization) => {
@@ -214,7 +295,7 @@ pub fn sync_changed_paths(
     db_path: impl AsRef<Path>,
     paths: impl IntoIterator<Item = impl AsRef<Path>>,
 ) -> Result<SyncOutcome> {
-    sync_changed_paths_with_patterns(project_root, db_path, paths, &[], &[])
+    sync_changed_paths_with_patterns(project_root, db_path, paths, &[], &[], None)
 }
 
 /// Like [`sync_changed_paths`] but threads the `codegraph.json`/`config.toml`
@@ -227,6 +308,7 @@ pub fn sync_changed_paths_with_patterns(
     changed: impl IntoIterator<Item = impl AsRef<Path>>,
     include: &[String],
     exclude: &[String],
+    cancel: Option<&SyncCancellation>,
 ) -> Result<SyncOutcome> {
     let started = Instant::now();
     let project_root = project_root.as_ref();
@@ -254,7 +336,8 @@ pub fn sync_changed_paths_with_patterns(
     // Same classify-before-mutate gate as the cold full sync: a Current namespace
     // stays incremental, while Missing/Outdated/recoverable Building escalate to a
     // forced migration under the SAME retained exclusive lease.
-    match open_sync_writer(&paths)? {
+    let _active = cancel.map(SyncCancellation::enter);
+    match open_sync_writer(&paths, cancel)? {
         SyncWriter::Incremental(mut store) => {
             let outcome = sync_paths_with_store(
                 &mut store,
@@ -1314,6 +1397,7 @@ pub(crate) mod tests {
             ["Tools/helper.ts"],
             &["Tools/".to_string()],
             &[],
+            None,
         )
         .unwrap();
         assert_eq!(included.files_reindexed, 1);
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index ad9fe02..378f0bb 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -18,7 +18,8 @@ use codegraph_extract::ExtensionOverrides;
 
 use crate::policy::{WatchPolicy, watch_disabled_reason};
 use crate::sync::{
-    SyncOutcome, default_db_path, sync_changed_paths_with_patterns, sync_project_once_with_patterns,
+    SyncCancellation, SyncOutcome, default_db_path, sync_changed_paths_with_patterns,
+    sync_project_once_with_patterns,
 };
 
 type SyncCallback = Arc<dyn Fn(SyncOutcome) + Send + Sync>;
@@ -313,6 +314,10 @@ pub struct WatchOptions {
     /// Override for the whole-project sync a removed directory escalates to.
     /// Defaults to [`crate::sync::sync_project_once`]; tests inject a counter.
     full_sync_fn: Option<FullSyncFn>,
+    /// Cooperative cancellation shared with the default sync closures, so a
+    /// shutdown can refuse queued lease loops and interrupt a running one
+    /// (frozen plan lines 598-601).
+    cancel: SyncCancellation,
 }
 
 impl Default for WatchOptions {
@@ -332,6 +337,7 @@ impl Default for WatchOptions {
             extensions: ExtensionOverrides::empty(),
             sync_fn: None,
             full_sync_fn: None,
+            cancel: SyncCancellation::new(),
         }
     }
 }
@@ -345,6 +351,14 @@ impl WatchOptions {
     /// by one process can watch different scopes (or one not at all). An explicit
     /// `CODEGRAPH_WATCH_DEBOUNCE_MS` still wins, keeping the documented env escape
     /// hatch authoritative over config.
+    /// Share `cancel` with this watcher's default sync closures so a shutdown
+    /// can cancel queued and running lease loops.
+    #[must_use]
+    pub fn with_cancellation(mut self, cancel: SyncCancellation) -> Self {
+        self.cancel = cancel;
+        self
+    }
+
     #[must_use]
     pub fn for_project(config: &Config, extensions: Arc<ExtensionOverrides>) -> Self {
         Self {
@@ -370,6 +384,11 @@ pub struct ProjectWatcher {
     thread: Option<JoinHandle<()>>,
     watcher: SharedWatcher,
     degraded: Arc<DegradedState>,
+    cancel: SyncCancellation,
+    /// Set by the event-loop thread as its LAST action. Lets a caller observe
+    /// completion without joining, so a bounded shutdown never blocks on a
+    /// still-running sync (see [`Self::begin_shutdown`]).
+    finished: Arc<AtomicBool>,
 }
 
 pub fn start_serve_watcher(
@@ -408,12 +427,21 @@ impl ProjectWatcher {
             Some(db) => db,
             None => default_db_path(&project_root)?,
         };
+        let cancel = options.cancel.clone();
         let sync_fn = options.sync_fn.clone().unwrap_or_else(|| {
             let project_root = project_root.clone();
             let include = options.include.clone();
             let exclude = options.exclude.clone();
+            let cancel = cancel.clone();
             Arc::new(move |paths| {
-                sync_changed_paths_with_patterns(&project_root, &db_path, paths, &include, &exclude)
+                sync_changed_paths_with_patterns(
+                    &project_root,
+                    &db_path,
+                    paths,
+                    &include,
+                    &exclude,
+                    Some(&cancel),
+                )
             })
         });
         // A removed directory cannot be expressed as a path list (its tracked
@@ -423,7 +451,10 @@ impl ProjectWatcher {
             let project_root = project_root.clone();
             let include = options.include.clone();
             let exclude = options.exclude.clone();
-            Arc::new(move || sync_project_once_with_patterns(&project_root, &include, &exclude))
+            let cancel = cancel.clone();
+            Arc::new(move || {
+                sync_project_once_with_patterns(&project_root, &include, &exclude, Some(&cancel))
+            })
         });
         let (tx, rx) = mpsc::channel();
         let degraded = Arc::new(DegradedState::default());
@@ -509,6 +540,8 @@ impl ProjectWatcher {
         let debounce = options.debounce;
         let loop_degraded = Arc::clone(&degraded);
         let loop_watcher = Arc::clone(&watcher);
+        let finished = Arc::new(AtomicBool::new(false));
+        let loop_finished = Arc::clone(&finished);
         let thread = thread::spawn(move || {
             event_loop(EventLoopCtx {
                 rx,
@@ -523,6 +556,7 @@ impl ProjectWatcher {
                 watcher: loop_watcher,
                 known_dirs,
             });
+            loop_finished.store(true, Ordering::SeqCst);
         });
 
         Ok(Some(Self {
@@ -530,9 +564,55 @@ impl ProjectWatcher {
             thread: Some(thread),
             watcher,
             degraded,
+            cancel,
+            finished,
         }))
     }
 
+    /// Begin shutdown WITHOUT joining: stop delivering new OS events, refuse
+    /// queued lease loops, interrupt a running one, and ask the event loop to
+    /// exit. Idempotent and never blocks.
+    ///
+    /// The join is deliberately separated from this signal. A running sync can
+    /// hold the event-loop thread for the whole extraction pass, so joining here
+    /// (as `stop`/`Drop` do) would block past any caller-side deadline and make a
+    /// bounded drain unbounded. Callers poll [`Self::is_finished`] against their
+    /// own budget and then either [`Self::stop`] (an instant join) or
+    /// [`Self::detach`].
+    pub fn begin_shutdown(&self) {
+        self.cancel.cancel();
+        if let Ok(mut guard) = self.watcher.lock() {
+            let _ = guard.take();
+        }
+        let _ = self.tx.send(LoopMessage::Stop);
+    }
+
+    /// Whether the event-loop thread has run to completion.
+    #[must_use]
+    pub fn is_finished(&self) -> bool {
+        self.finished.load(Ordering::SeqCst)
+    }
+
+    /// Give up ownership of the event-loop thread without joining it.
+    ///
+    /// Used only after a bounded shutdown deadline elapsed: the loop is already
+    /// cancelled and will exit on its own, and the caller has already reported an
+    /// INCOMPLETE drain, so nothing destructive proceeds behind it. Dropping the
+    /// `JoinHandle` detaches the thread, and the subsequent `Drop` finds no handle
+    /// to join.
+    pub fn detach(mut self) {
+        let _ = self.thread.take();
+    }
+
+    /// The watcher's cooperative cancellation handle. A shutdown cancels it so
+    /// queued lease loops refuse immediately and a running one returns a typed
+    /// error, then waits for [`SyncCancellation::active_syncs`] to reach zero
+    /// before considering the watcher drained.
+    #[must_use]
+    pub fn cancellation(&self) -> SyncCancellation {
+        self.cancel.clone()
+    }
+
     pub fn is_degraded(&self) -> bool {
         self.degraded.is_degraded()
     }
@@ -584,10 +664,9 @@ impl ProjectWatcher {
     }
 
     fn stop_inner(&mut self) {
-        if let Ok(mut guard) = self.watcher.lock() {
-            let _ = guard.take();
-        }
-        let _ = self.tx.send(LoopMessage::Stop);
+        // Signal first (never join without cancelling: the event-loop thread may be
+        // inside a bounded lease acquisition), then join.
+        self.begin_shutdown();
         if let Some(thread) = self.thread.take() {
             let _ = thread.join();
         }
@@ -1134,6 +1213,7 @@ mod tests {
             ],
             &["Tools/".to_string()],
             &[],
+            None,
         )
         .unwrap();
         assert_eq!(
@@ -1794,6 +1874,95 @@ mod tests {
         watcher.stop();
     }
 
+    /// A watcher whose event loop is INSIDE a sync must not be forced to a join:
+    /// `begin_shutdown` returns immediately, `is_finished` truthfully stays false
+    /// while the sync runs, and `detach` releases the handle without blocking. This
+    /// is what lets the daemon's bounded drain report an INCOMPLETE result instead
+    /// of blocking past its budget inside `Drop`. The sync blocks on a barrier, so
+    /// "still running" is deterministic rather than timed.
+    #[test]
+    fn begin_shutdown_and_detach_never_block_on_a_running_sync() {
+        let dir = crate::sync::tests::TestDir::new("watch-running-sync");
+        let release = Arc::new(std::sync::Barrier::new(2));
+        let entered = Arc::new(AtomicBool::new(false));
+        let sync_release = Arc::clone(&release);
+        let sync_entered = Arc::clone(&entered);
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                debounce: Duration::from_millis(1),
+                inert_for_tests: true,
+                sync_fn: Some(Arc::new(move |_paths| {
+                    sync_entered.store(true, AtomicOrdering::SeqCst);
+                    sync_release.wait();
+                    Ok(SyncOutcome::default())
+                })),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        watcher.ingest_event_for_tests("src/app.ts");
+        while !entered.load(AtomicOrdering::SeqCst) {
+            std::thread::sleep(Duration::from_millis(5));
+        }
+
+        let started = Instant::now();
+        watcher.begin_shutdown();
+        assert!(
+            started.elapsed() < Duration::from_secs(2),
+            "begin_shutdown must not join a running sync"
+        );
+        assert!(
+            !watcher.is_finished(),
+            "a watcher inside a sync must report itself unfinished"
+        );
+
+        let started = Instant::now();
+        watcher.detach();
+        assert!(
+            started.elapsed() < Duration::from_secs(2),
+            "detach must not join a running sync"
+        );
+        release.wait();
+    }
+
+    #[test]
+    fn begin_shutdown_is_nonblocking_and_detach_skips_the_join() {
+        // Given: an inert watcher whose event loop is idle.
+        let dir = crate::sync::tests::TestDir::new("watch-begin-shutdown");
+        let watcher = ProjectWatcher::start(
+            dir.path(),
+            WatchOptions {
+                inert_for_tests: true,
+                sync_fn: Some(Arc::new(|_paths| Ok(SyncOutcome::default()))),
+                ..WatchOptions::default()
+            },
+        )
+        .unwrap()
+        .unwrap();
+
+        // When: shutdown begins.
+        let cancel = watcher.cancellation();
+        watcher.begin_shutdown();
+
+        // Then: cancellation is observable immediately and the call did not join.
+        assert!(cancel.is_cancelled());
+        watcher.begin_shutdown();
+        for _ in 0..200 {
+            if watcher.is_finished() {
+                break;
+            }
+            std::thread::sleep(Duration::from_millis(5));
+        }
+        assert!(
+            watcher.is_finished(),
+            "the event loop must exit after begin_shutdown"
+        );
+        watcher.detach();
+    }
+
     #[test]
     fn event_loop_reports_non_degrading_sync_error_through_callback() {
         // Given: an inert watcher whose injected sync_fn always fails with a
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 569c1e2..82f7dba 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -2978,3 +2978,163 @@ remains required at SHA-256
 bytes are written BEFORE repository formatting and the one authoritative
 `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run over
 these exact final bytes; no final Green is claimed until that gate passes.
+
+## Batch M item 20 acceptance closure — daemon rendezvous lifecycle under `uninit --force` (2026-07-27)
+
+Frozen plan item 20 (lines 590-612, 787-797). Two named acceptances plus the paired
+fail-closed case now exist as real-process tests in
+`crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs`:
+`daemon_start_during_uninit_observes_uninitialized_and_tombstone_before_publish`,
+`uninit_shutdown_control_drains_without_pid_kill`, and
+`unresponsive_daemon_leaves_recoverable_uninitialized_without_kill`.
+
+Behavioral Red on the pre-change bytes (compiling test, real failures — not a build
+error and not a missing environment):
+`cargo test --locked -p codegraph-rs --test batch_m_daemon_uninit_lifecycle` →
+**0 passed, 3 failed**. `daemon_start_...` failed with "lease barrier was not reached
+before its finite deadline" (startup took NO shared lease at all, so it never reached
+the store's post-acquisition checkpoint); `uninit_shutdown_control_...` failed with
+"the daemon never published its v2 rendezvous at
+…/.codegraph-v2/daemon.pid" (the rendezvous was still written under the legacy
+`.codegraph` root); `unresponsive_daemon_...` failed because `uninit --force`
+SUCCEEDED while a live recorded owner had never been drained.
+
+Green: **3/3**. Ordering evidence is deterministic, never a sleep. The concurrent-start
+test publishes the authoritative `uninitialized` slot and then the tombstone while it
+still holds uninit's exclusive lease, and the competing `serve --mcp` child is stopped
+at the store's test-only post-acquisition SHARED-lease barrier; the "published nothing"
+snapshot is taken at that exact checkpoint and re-checked after the child exits,
+against BOTH the v2 identities and the legacy `.codegraph` spellings. The drain test
+asserts process exit status, `signal() == None`, removal of pid + socket, removal of
+the v2 database, and recoverable `Uninitialized`; the fail-closed test asserts the
+recorded live owner is still running, that NO runtime child was removed, and that a
+repeated `uninit --force` resumes the cleanup idempotently once the owner is gone.
+
+Production slice. `IndexPaths` is now the sole authority for every rendezvous path:
+`crates/codegraph-daemon/src/paths.rs` derives pid/log/socket from
+`IndexPaths::resolve` and every accessor is FALLIBLE, so an unsafe or unresolvable
+configured root fails closed instead of reconstructing a `.codegraph*` path (the
+out-of-root POSIX-tmpdir and Windows namespaced names are
+`sha256("codegraph-v2-" || projectIdentity)[..8]`, provably distinct from the legacy
+`sha256(path)` name). `crates/codegraph-daemon/src/control.rs` (new) owns the
+versioned, project-identity-bound control frame plus `request_daemon_shutdown`.
+`session.rs` answers a control frame at the hello seam, BEFORE any engine or
+data-request lease exists — which is exactly why it can be served while
+`uninit --force` holds the namespace exclusively. `lib.rs` gates startup through a
+caller-supplied `StartupGate` whose returned capability is retained across
+pid/socket publication and dropped only afterwards. `codegraph-store`'s
+`uninit_index_with_drain` runs the drain INSIDE the retained exclusive lease, after
+both durable markers and before any child removal; a drain error is
+`UninitError::DaemonNotDrained`, fail-closed. `codegraph-watch` gained
+`SyncCancellation` so a shutdown refuses queued lease loops and interrupts a running
+one instead of waiting out the 30s lease budget.
+
+### Orchestrator-caught defects and their corrections
+
+The orchestrator manually READ the M20 diff and rejected the first candidate even
+though `batch_m_daemon_uninit_lifecycle` was 3/3 and `control_shutdown` was 3/3. Both
+suites passed **with a hardcoded-success mutant still in the tree**: an un-restored
+negative control at `session.rs` wrote `shutdown_reply_line(true)` and the compiler's
+`unused variable: drained` was the only signal. The lesson recorded here is that a
+green suite is not evidence when no test observes the real call site — the incomplete
+case was covered only by a stub responder and by a direct unit call to
+`shutdown_reply_line(false)`, neither of which routes through `serve_control_frame`.
+
+Corrections, each with a load-bearing test:
+
+1. **Success ACK despite an incomplete drain.** `run_accept_loop_async` logged
+   `!drained` and still sent success. `ShutdownRequest::ack` now carries the drain
+   RESULT (`oneshot::Sender<bool>`), `serve_control_frame` serializes that value, and
+   `ControlAck::for_drain(false)` is what the caller maps to
+   `ShutdownOutcome::Unresponsive`. Pinned by
+   `an_exhausted_drain_budget_replies_incomplete_instead_of_success`, which drives a
+   REAL daemon with `DaemonOptions::drain_budget = 0` and a connected silent client:
+   it reads `drained: false` off the wire. Mutant proof — reinstating
+   `shutdown_reply_line(true)` (with `let _ = drained;`) turns exactly this test red
+   (`left: true, right: false`) while the other three stay green; the byte was then
+   restored and the suite re-run 4/4.
+2. **No active session close, and a Unix-only mechanism.** Shutdown merely waited.
+   `SessionRegistry` now owns a `tokio::sync::watch` closing signal
+   (`close_all_sessions` / `is_closing`), which is platform-independent; the Unix
+   raw-fd half-close remains only as an acceleration. Both the first-line read and the
+   rmcp serve loop race that signal, so a silent client and a long-lived rmcp client
+   are both ended by the daemon. `send_replace` (not `send`) is required: `send` fails
+   when no receiver exists yet, which would let a session accepted after the signal
+   start serving. Pinned by
+   `authorized_shutdown_closes_a_long_lived_session_before_acknowledging` (the silent
+   client's socket must EOF) — disabling `close_all_sessions` turns it red with
+   `drained: false`.
+3. **Unbounded watcher join before the bounded wait.** The old order was
+   `lease_loops.cancel(); drop(watcher); drain(...)`, and `ProjectWatcher::Drop →
+stop_inner → join` can block for a whole extraction pass, making the incomplete-ACK
+   path unreachable. `ProjectWatcher` now separates signalling from joining:
+   `begin_shutdown()` (stop OS events, cancel loops, ask the loop to exit; never
+   joins), `is_finished()` (a flag the loop sets as its last action), and `detach()`
+   (release the handle so no destructor re-introduces the join). The daemon calls
+   `begin_shutdown` → `close_all_sessions` → `drain_watcher_loops_and_sessions(...)`
+   → `stop()` only when drained, else `detach()`. Pinned by
+   `begin_shutdown_and_detach_never_block_on_a_running_sync` (a barrier-blocked sync,
+   so "still running" is deterministic) and by the daemon-side
+   `drain_reports_completion_only_when_loops_and_sessions_reach_zero`, which asserts
+   an unfinished watcher ALONE yields an incomplete drain.
+4. **Owned-rendezvous cleanup could unlink a replacement owner's socket.**
+   `cleanup_owned_lock` now RETURNS ownership and `cleanup_owned_rendezvous` removes
+   the socket only when the pid record still names this process; an owner mismatch
+   preserves both the replacement record and its socket. Pinned by
+   `cleanup_owned_rendezvous_preserves_a_replacement_owners_record_and_socket`.
+5. **Slot-only startup validation.** The gate previously checked
+   `Store::extraction_status == Current` plus tombstone absence, which would still
+   publish a rendezvous for a `Current` slot whose database was deleted, whose
+   sidecars reappeared, or whose extraction stamp is stale.
+   `authorize_daemon_startup` now uses `Store::open_for_read`, which acquires ONE
+   bounded shared lease and, under it, corroborates the full contract (owner-bound
+   slots, tombstone absence, DB presence, sidecar-freedom, exact stamp from the
+   checkpointed main file). The returned `Store` OWNS that same lease, so retaining it
+   across publication needs no second acquisition — no nested lock, no TOCTOU window.
+6. **Foreign control versions leaked into the data path.** `parse_control_frame`
+   rejected `codegraph_control == 0`, which would have routed those bytes into the
+   JSON-RPC executor. Every line that deserializes as a `ControlFrame` is now
+   recognized and refused explicitly; authorization stays the only gate. Pinned by
+   `a_foreign_protocol_version_is_never_authorized` (0, +1, `u8::MAX`) and by
+   `an_unauthorized_frame_is_refused_without_shutting_the_daemon_down`, which sends a
+   foreign identity, a foreign version, and a foreign action against a live daemon and
+   asserts each is answered `drained: false` with the rendezvous intact and the daemon
+   still serving.
+
+A finite caller-side wait is now honest on every platform: `interprocess`'s
+send/recv timeouts are Unix-only, so `request_daemon_shutdown` runs the exchange on a
+worker thread and bounds the WAIT with a monotonic channel deadline. No PID is ever
+signalled on any path; `uninit` only ever REPORTS the recorded pid.
+
+Migrated coverage, never weakened. Pre-existing daemon/CLI tests changed only because
+the rendezvous moved to the v2 current root: they now resolve pid/socket/log through
+`IndexPaths` instead of hardcoding `.codegraph/daemon.*`, and their project fixtures
+canonicalize a real directory because `IndexPaths` derives a PHYSICAL identity.
+`lease_lifetime.rs`'s barrier listener now accepts EVERY arrival instead of only the
+first, because a daemon legitimately reaches the shared-lease checkpoint twice (its
+startup capability, then a per-request lease) — the test releases the startup arrival
+and still asserts the per-request one, which strengthens rather than loosens it. No
+test was deleted, skipped, ignored, or timing-loosened.
+
+Verification, with `bash scripts/check-workspace-versions.sh` before every Cargo batch
+and `--locked` on every Cargo command: `codegraph-rs`
+`batch_m_daemon_uninit_lifecycle` **3/3**; `codegraph-daemon` `control_shutdown`
+**4/4** and the whole package green (98 unit + every integration suite);
+`codegraph-watch` **green**; `codegraph-store` uninit suite **8/8** including the two
+new drain tests; `codegraph-rs` **all targets green**;
+`cargo clippy --locked --workspace --all-targets -- -D warnings` clean.
+
+Limitations, stated honestly. Changed-file LSP diagnostics were attempted and the tool
+again rejected this external worktree with `LSP file path must be inside request cwd`;
+locked Cargo check/Clippy/tests are the fallback and no LSP-clean result is claimed.
+Native Windows/MSVC runtime was NOT executed: the cross-platform claim covers the
+mechanism (a `tokio::sync::watch` close signal and a thread-bounded caller wait, with
+no Unix-only primitive on the correctness path) and compilation, not a Windows run.
+This slice adds no dependency and changes no schema, node-ID formula, extraction or
+golden byte; the frozen plan is untouched at SHA-256
+`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450` and `Cargo.lock`
+remains at SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`. These evidence
+bytes are written BEFORE repository formatting and the one authoritative
+`bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run over
+these exact final bytes; no final Green is claimed until that gate passes.

From f691415f3788b446ae02932a3de15b27b28ed14f Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Mon, 27 Jul 2026 15:05:22 +0800
Subject: [PATCH 38/91] fix(daemon): remove the rendezvous socket before
 releasing its ownership record

---
 crates/codegraph-cli/src/main.rs              |  22 +-
 .../tests/batch_m_daemon_uninit_lifecycle.rs  |  63 ++++++
 crates/codegraph-daemon/src/lock.rs           | 193 ++++++++++++++++--
 crates/codegraph-store/src/connection.rs      |  52 +++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 113 ++++++++++
 5 files changed, 422 insertions(+), 21 deletions(-)

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 00ddeab..ae6084e 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1165,20 +1165,26 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
 
 /// Daemon-startup gate (frozen plan lines 590-592, 603-604).
 ///
-/// ONE bounded shared acquisition validates everything: `Store::open_for_read`
-/// acquires the shared `IndexLease` and, under it, corroborates the FULL `Current`
-/// contract — both owner-bound state slots (so `Future`, `Corrupt`, `Building`,
-/// `Uninitialized`, `Outdated`, and an owner mismatch are all refused), tombstone
-/// absence, database presence, sidecar-freedom, and the exact extraction stamp
-/// read from the checkpointed main-file bytes. Slot phase alone would let a
-/// `Current` slot with a deleted database or a stale stamp publish a rendezvous.
+/// ONE bounded shared acquisition validates everything:
+/// `Store::open_for_daemon_startup` acquires the shared `IndexLease` and, under it,
+/// corroborates the FULL `Current` contract — both owner-bound state slots (so
+/// `Future`, `Corrupt`, `Building`, `Uninitialized`, `Outdated`, and an owner
+/// mismatch are all refused), tombstone absence, database presence, and the exact
+/// extraction stamp read from the checkpointed main-file bytes. Slot phase alone
+/// would let a `Current` slot with a deleted database or a stale stamp publish a
+/// rendezvous.
+///
+/// A LIVE `-wal`/`-shm` sidecar is deliberately tolerated (the one difference from
+/// `Store::open_for_read`): a killed daemon leaves those behind on an otherwise
+/// untouched namespace, and refusing them would make a replacement daemon
+/// unstartable after any hard kill.
 ///
 /// The returned `Store` OWNS that same lease, so retaining it across pid/socket
 /// publication requires no second acquisition: there is no nested lock and no
 /// window between validation and publication for another writer to reclassify.
 fn authorize_daemon_startup(project_root: &Path) -> Result<codegraph_daemon::StartupAuthorization> {
     let paths = index_paths(project_root)?;
-    match Store::open_for_read(
+    match Store::open_for_daemon_startup(
         &paths,
         std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
         || false,
diff --git a/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
index 972343d..66d9d36 100644
--- a/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
+++ b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
@@ -510,6 +510,69 @@ fn uninit_shutdown_control_drains_without_pid_kill() {
     assert_recoverable_uninitialized(&paths, "after a drained uninit");
 }
 
+/// A daemon that was KILLED rather than closed leaves its SQLite `-wal`/`-shm`
+/// sidecars behind on an otherwise untouched `Current` namespace. The startup gate
+/// must still admit a replacement daemon, because refusing those sidecars would
+/// make the namespace unstartable after any hard kill — while every other part of
+/// the `Current` contract stays enforced (proved by the tombstone case below, which
+/// is refused with the very same sidecars present).
+#[test]
+fn a_killed_daemons_live_sidecars_do_not_block_a_replacement_start() {
+    let project = TestProject::indexed("live-sidecars");
+    let paths = project.paths();
+
+    let sidecars: Vec<PathBuf> = ["-wal", "-shm"]
+        .iter()
+        .map(|suffix| {
+            let mut path = paths.current_db().into_os_string();
+            path.push(suffix);
+            PathBuf::from(path)
+        })
+        .collect();
+    for sidecar in &sidecars {
+        fs::write(sidecar, b"").expect("plant a killed daemon's live sidecar");
+    }
+
+    let mut daemon = ChildGuard::new(
+        daemon_command(project.path())
+            .spawn()
+            .expect("spawn daemon"),
+    );
+    let pid = wait_for_owner_record(&paths);
+    assert!(
+        is_process_alive(pid),
+        "a replacement daemon must start despite a killed predecessor's sidecars"
+    );
+
+    // The same namespace WITH those sidecars is still refused once it carries a
+    // tombstone, so this relaxation did not weaken the state contract.
+    let output = uninit_force(project.path());
+    assert!(
+        output.status.success(),
+        "uninit --force must drain the replacement daemon; stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(daemon.wait_bounded("the drained daemon").code(), Some(0));
+    assert_recoverable_uninitialized(&paths, "after draining the replacement daemon");
+
+    let refused = ChildGuard::new(
+        daemon_command(project.path())
+            .spawn()
+            .expect("spawn daemon"),
+    )
+    .finish("the refused daemon start");
+    let stderr = String::from_utf8_lossy(&refused.stderr).to_string();
+    assert!(
+        !refused.status.success() && stderr.contains("tombstone"),
+        "a tombstoned namespace must still refuse a daemon start: {stderr}"
+    );
+    assert_no_rendezvous(
+        project.path(),
+        &paths,
+        "after the tombstoned start was refused",
+    );
+}
+
 #[test]
 fn unresponsive_daemon_leaves_recoverable_uninitialized_without_kill() {
     let project = TestProject::indexed("unresponsive");
diff --git a/crates/codegraph-daemon/src/lock.rs b/crates/codegraph-daemon/src/lock.rs
index c390663..fad7da0 100644
--- a/crates/codegraph-daemon/src/lock.rs
+++ b/crates/codegraph-daemon/src/lock.rs
@@ -177,8 +177,13 @@ pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
     true
 }
 
+/// Whether the published pid record currently names `pid`.
+fn record_names(pid_path: &Path, pid: u32) -> bool {
+    read_lock_info_tolerant(pid_path).is_some_and(|info| info.pid == pid)
+}
+
 pub(crate) fn cleanup_owned_lock(pid_path: &Path, pid: u32) -> bool {
-    let owned = read_lock_info_tolerant(pid_path).is_some_and(|info| info.pid == pid);
+    let owned = record_names(pid_path, pid);
     if owned {
         let _ = fs::remove_file(pid_path);
     }
@@ -238,25 +243,60 @@ pub fn recorded_socket_path(project_root: &Path) -> Result<PathBuf> {
     }
 }
 
-/// Remove the rendezvous artifacts this daemon process itself published: its
-/// owner-bound pid record and, on Unix, its bound socket file.
+/// The two mutation boundaries of [`cleanup_owned_rendezvous`], exposed only so a
+/// test can drive a competing daemon start at an exact point with no timing
+/// assumption.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum RendezvousCleanupCheckpoint {
+    /// The pid record was just corroborated as ours and is STILL PUBLISHED. The
+    /// socket has not been touched.
+    OwnershipCorroborated,
+    /// Our socket is gone; the pid record is still published and still ours.
+    SocketRemoved,
+}
+
+/// Remove the rendezvous artifacts this daemon process itself published: on Unix
+/// its bound socket file, then its owner-bound pid record.
 ///
-/// Socket removal is CONDITIONAL on the pid record still naming this process. If
-/// the record was already replaced by a new owner (its own claim published a new
-/// record and rebound the same socket path), unlinking the socket here would strip
-/// the LIVE daemon's rendezvous while its record still advertises it, leaving
-/// every client unable to attach. In that case both the replacement record and its
-/// socket are preserved and this reports `false`. The permanent index lock is
-/// never named here.
+/// ORDER IS LOAD-BEARING. The published pid record IS the single-instance
+/// exclusion: `try_acquire_daemon_lock` claims it with `create_new`, so while our
+/// record exists a competing start reports `Taken` and never binds this socket
+/// path. Removing the record FIRST (as an earlier revision did) opens a window in
+/// which a replacement daemon legitimately claims the record and binds the same
+/// path — and the departing process's later unlink then destroys the LIVE
+/// daemon's socket while its record still advertises it. So the record is held as
+/// exclusion until our socket is unlinked, and only then is the record removed,
+/// re-corroborated against our pid.
+///
+/// Crash behavior between the two operations is fail-closed and self-healing: the
+/// namespace is left with a pid record naming a now-dead pid and no socket. A
+/// client's attach to the recorded socket fails fast (bounded, never hangs), and
+/// `clear_stale_daemon_lock` / `clear_stale_daemon_socket` clear that record on the
+/// next start because the recorded pid is provably not alive. The inverse order
+/// could instead leave a LIVE daemon with no socket, which nothing can heal.
+///
+/// An already-replaced record (an owner mismatch observed on entry) preserves BOTH
+/// the replacement record and its socket and reports `false`. The permanent index
+/// lock is never named here.
 pub(crate) fn cleanup_owned_rendezvous(pid_path: &Path, socket_path: &Path, pid: u32) -> bool {
-    let owned = cleanup_owned_lock(pid_path, pid);
-    if !owned {
+    cleanup_owned_rendezvous_with(pid_path, socket_path, pid, |_| {})
+}
+
+fn cleanup_owned_rendezvous_with(
+    pid_path: &Path,
+    socket_path: &Path,
+    pid: u32,
+    mut checkpoint: impl FnMut(RendezvousCleanupCheckpoint),
+) -> bool {
+    if !record_names(pid_path, pid) {
         debug!(
             pid_path = %pid_path.display(),
             "daemon rendezvous is owned by another process; leaving its record and socket intact"
         );
         return false;
     }
+    checkpoint(RendezvousCleanupCheckpoint::OwnershipCorroborated);
+
     #[cfg(unix)]
     if let Some(stale) = crate::transport::Rendezvous::from_socket_path(socket_path).cleanup_path()
     {
@@ -264,7 +304,11 @@ pub(crate) fn cleanup_owned_rendezvous(pid_path: &Path, socket_path: &Path, pid:
     }
     #[cfg(not(unix))]
     let _ = socket_path;
-    true
+    checkpoint(RendezvousCleanupCheckpoint::SocketRemoved);
+
+    // Re-corroborate at the second mutation boundary: only a record that STILL
+    // names this process may be removed.
+    cleanup_owned_lock(pid_path, pid)
 }
 
 fn now_millis() -> u128 {
@@ -516,6 +560,129 @@ mod tests {
         let _ = fs::remove_dir_all(&base);
     }
 
+    /// The former vulnerable midpoint. A competing start is driven at the EXACT
+    /// boundary where the old revision had already removed the pid record, and it
+    /// is allowed to claim the record and rebind the same socket path. The
+    /// departing owner must not destroy that replacement.
+    ///
+    /// Deterministic by construction: the replacement runs inside the checkpoint
+    /// callback, so it is ordered by the call itself, not by any sleep.
+    ///
+    /// Under the OLD pid-record-first order this test fails — `try_acquire` would
+    /// succeed (the record was gone), and the subsequent unlink would delete the
+    /// replacement's socket.
+    #[test]
+    fn a_replacement_start_at_the_cleanup_midpoint_keeps_its_own_rendezvous() {
+        let base = temp_base("cleanup-midpoint");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+
+        // The DEPARTING owner: a distinct, provably dead pid, with its record
+        // published and its socket bound.
+        let mut departing = 4_000_000_000u32;
+        while departing == process::id() || is_process_alive(departing) {
+            departing -= 1;
+        }
+        let old = DaemonLockInfo {
+            pid: departing,
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            socket_path: socket.clone(),
+            started_at: 1,
+        };
+        fs::write(&pid_path, encode_lock_info(&old).unwrap()).unwrap();
+        fs::write(&socket, b"old").unwrap();
+
+        let mut replacement_claim = None;
+        let cleaned = cleanup_owned_rendezvous_with(&pid_path, &socket, departing, |checkpoint| {
+            if checkpoint != RendezvousCleanupCheckpoint::OwnershipCorroborated {
+                return;
+            }
+            // A competing start races here. While OUR record is still published it
+            // must be refused, which is exactly what keeps the replacement from
+            // binding a socket the departing owner is about to unlink.
+            replacement_claim = Some(try_acquire_daemon_lock(&base).expect("competing start"));
+        });
+
+        match replacement_claim.expect("the competing start ran at the checkpoint") {
+            AcquireResult::Taken { existing, .. } => {
+                let existing = existing.expect("the departing record is readable");
+                assert_eq!(
+                    existing.pid, departing,
+                    "the published record must still be the departing owner's, so the \
+                     replacement is refused instead of binding a doomed socket"
+                );
+            }
+            AcquireResult::Acquired { .. } => panic!(
+                "a competing start must NOT be able to claim the record before the departing \
+                 owner has finished unlinking its socket"
+            ),
+        }
+
+        assert!(cleaned, "the departing owner cleans its own rendezvous");
+        assert!(!pid_path.exists(), "its record is removed last");
+        assert!(!socket.exists(), "its socket was removed first");
+
+        // The replacement can now claim a clean namespace and bind its own socket,
+        // and nothing left over can delete it.
+        let AcquireResult::Acquired { .. } =
+            try_acquire_daemon_lock(&base).expect("post-cleanup acquire")
+        else {
+            panic!("a cleaned namespace must be claimable");
+        };
+        fs::write(&socket, b"new").unwrap();
+        assert!(
+            !cleanup_owned_rendezvous(&pid_path, &socket, departing),
+            "a second cleanup pass by the departed owner must be refused"
+        );
+        assert!(pid_path.exists() && socket.exists());
+        let _ = fs::remove_dir_all(&base);
+    }
+
+    /// The socket is unlinked BEFORE the record, so a crash between the two
+    /// boundaries leaves a dead-pid record with no socket — the self-healing
+    /// residue `clear_stale_daemon_socket` is built to clear. The inverse order
+    /// would leave a live daemon with no socket, which nothing can heal.
+    #[test]
+    fn a_crash_between_cleanup_boundaries_leaves_only_self_healing_residue() {
+        let base = temp_base("cleanup-crash");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        let mut departing = 4_000_000_000u32;
+        while departing == process::id() || is_process_alive(departing) {
+            departing -= 1;
+        }
+        let old = DaemonLockInfo {
+            pid: departing,
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            socket_path: socket.clone(),
+            started_at: 1,
+        };
+        fs::write(&pid_path, encode_lock_info(&old).unwrap()).unwrap();
+        fs::write(&socket, b"old").unwrap();
+
+        // Simulate the crash by panicking-free early return: run cleanup only up to
+        // the socket-removed boundary and drop the process there.
+        let mut reached_socket_removed = false;
+        let _ = cleanup_owned_rendezvous_with(&pid_path, &socket, departing, |checkpoint| {
+            if checkpoint == RendezvousCleanupCheckpoint::SocketRemoved {
+                reached_socket_removed = true;
+                assert!(!socket.exists(), "the socket is gone at this boundary");
+                assert!(
+                    pid_path.exists(),
+                    "the record is STILL published as exclusion at this boundary"
+                );
+            }
+        });
+        assert!(reached_socket_removed);
+
+        // The residue is exactly what the stale-socket self-heal clears.
+        assert!(clear_stale_daemon_socket(&base));
+        assert!(!pid_path.exists());
+        let _ = fs::remove_dir_all(&base);
+    }
+
     #[test]
     fn clear_stale_daemon_socket_removes_lock_and_socket_when_dead() {
         let base = temp_base("socket-dead");
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index ef14026..f807af0 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -340,6 +340,58 @@ impl Store {
         open_current_read_only(paths, lease)
     }
 
+    /// The daemon-startup read gate: identical to [`Self::open_for_read`] except
+    /// that a LIVE SQLite sidecar is tolerated.
+    ///
+    /// `-wal`/`-shm` are legitimately present on an untouched `Current` namespace
+    /// whenever a long-lived reader holds a connection — the MCP engine does for a
+    /// whole request — and they SURVIVE a daemon that was killed rather than closed.
+    /// Demanding sidecar-freedom here would therefore refuse to start a replacement
+    /// daemon after any hard kill, which is precisely the recovery path
+    /// `spawn_detached_daemon` exists for. This is the same relaxation the
+    /// incremental-sync writer already takes (see
+    /// `corroborate_current_database_options`), and for the same reason: the
+    /// extraction stamp is still read from the already-checkpointed MAIN-file bytes,
+    /// so the version gate, tombstone gate, DB-presence gate, owner-bound state
+    /// slots, and the retained shared lease are all unchanged.
+    pub fn open_for_daemon_startup(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<Self> {
+        Self::open_for_read_with_sidecar_policy(paths, deadline, cancelled, true)
+    }
+
+    fn open_for_read_with_sidecar_policy(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+        allow_live_sidecar: bool,
+    ) -> Result<Self> {
+        let lease = match IndexLease::acquire_shared_existing(paths, deadline, cancelled) {
+            Ok(lease) => lease,
+            Err(IndexLeaseError::LockNotFound { .. }) => {
+                return Err(lockless_state_error(paths)?);
+            }
+            Err(error) => return Err(StoreError::Lease(error)),
+        };
+        let status = Self::extraction_status(paths);
+        reject_missing_database_artifacts(paths, &status)?;
+        if status != ExtractionStatus::Current {
+            return Err(StoreError::StateRejected { status });
+        }
+        let (conn, source_conn) =
+            corroborate_current_database_options(paths, false, allow_live_sidecar)?;
+        Ok(Store {
+            conn,
+            _source_conn: Some(source_conn),
+            path: paths.current_db(),
+            access: StoreAccess::StateRead,
+            guarded_paths: Some(paths.clone()),
+            lease: Some(lease),
+        })
+    }
+
     /// Probe status under a short shared lease. Contention is status data rather
     /// than an error and never opens SQLite. Non-Current states are reported
     /// without SQLite; Current is corroborated through [`Self::open_for_read`]'s
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 82f7dba..5a7545c 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3138,3 +3138,116 @@ remains at SHA-256
 bytes are written BEFORE repository formatting and the one authoritative
 `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo --locked'` run over
 these exact final bytes; no final Green is claimed until that gate passes.
+
+## Batch M item 20 correction — rendezvous cleanup ownership order (2026-07-27)
+
+Manual orchestrator review of the committed `df86a5a` found one remaining ownership
+race and rejected it. `cleanup_owned_rendezvous` called `cleanup_owned_lock` FIRST
+(which corroborates ownership and removes the pid record), then unlinked the socket.
+The published pid record IS the single-instance exclusion — `try_acquire_daemon_lock`
+claims it with `create_new` — so between those two operations the namespace was
+unowned: a replacement daemon could legitimately claim the record and bind the SAME
+socket path, and the departing process's later unlink then destroyed the LIVE
+daemon's socket while its record still advertised it. Every client would fail to
+attach with no artifact left to explain why.
+
+Correction: the order is inverted and ownership is re-corroborated at BOTH mutation
+boundaries. `cleanup_owned_rendezvous` now (1) corroborates that the record names
+this pid and LEAVES IT PUBLISHED, (2) unlinks the socket while that record still
+excludes every competing start, (3) removes the record only via `cleanup_owned_lock`,
+which re-reads ownership immediately before deleting. An owner mismatch observed on
+entry still preserves both the replacement record and its socket and reports `false`.
+No PID is signalled, no wait was introduced, and the permanent index lock, state
+slots, tombstone, and DB are never named by this path.
+
+Crash behavior is explicitly asymmetric and that asymmetry is why this order was
+chosen. A crash between (2) and (3) leaves a pid record naming a now-dead pid and no
+socket: a client's attach to the recorded socket fails fast (the bounded attach from
+Fix A, never a hang), and the next start clears the record through
+`clear_stale_daemon_lock` / `clear_stale_daemon_socket` because the recorded pid is
+provably not alive — self-healing residue. The old order's failure mode was the
+opposite and unrecoverable: a LIVE daemon with no socket, which nothing heals.
+
+Tests. A narrow, crate-local seam `cleanup_owned_rendezvous_with(..., checkpoint)`
+exposes the two boundaries (`OwnershipCorroborated`, `SocketRemoved`); production
+`cleanup_owned_rendezvous` passes a no-op, so no production behavior is conditional
+on a test. `a_replacement_start_at_the_cleanup_midpoint_keeps_its_own_rendezvous`
+drives a REAL `try_acquire_daemon_lock` from inside the callback at the former
+vulnerable midpoint — ordered by the call itself, with no sleep — and asserts the
+competing start is refused with `Taken { existing.pid == departing }`, that the
+socket is removed before the record, that the record is removed last, and that a
+second cleanup pass by the departed owner is refused after the replacement rebinds.
+`a_crash_between_cleanup_boundaries_leaves_only_self_healing_residue` asserts at the
+`SocketRemoved` boundary that the socket is gone while the record is STILL published,
+then proves `clear_stale_daemon_socket` clears that residue. The pre-existing
+`cleanup_owned_rendezvous_preserves_a_replacement_owners_record_and_socket`
+(mismatch-before-entry) is unchanged.
+
+Negative control, executed: reinstating the exact old pid-record-first body turns
+BOTH new tests red and nothing else — `a_replacement_start_...` fails with "a
+competing start must NOT be able to claim the record before the departing owner has
+finished unlinking its socket" (the competing `try_acquire` returned `Acquired`), and
+`a_crash_between_...` fails with "the record is STILL published as exclusion at this
+boundary". The corrected bytes were then restored exactly (`grep -c MUTANT` → 0) and
+the suite re-run 16/16.
+
+Verification, with `bash scripts/check-workspace-versions.sh` before every Cargo batch
+and `--locked` on every Cargo command: `codegraph-daemon` **100 unit + every
+integration suite green** (11 `test result: ok`, rc=0), `codegraph-rs`
+`batch_m_daemon_uninit_lifecycle` **3/3**, `cargo clippy --locked -p codegraph-daemon
+--all-targets -- -D warnings` clean, and the final authoritative
+`make ci CARGO='cargo --locked'` over these exact bytes.
+
+Limitations. Changed-file LSP diagnostics were attempted on
+`crates/codegraph-daemon/src/lock.rs` and refused again with
+`LSP file path must be inside request cwd` (external worktree); locked Cargo
+check/Clippy/tests are the fallback and no LSP-clean result is claimed. The race and
+its fix are exercised on the Unix filesystem-socket arm, which is where a socket path
+can be unlinked at all; Windows uses a namespaced pipe with no filesystem entry, so
+the `#[cfg(not(unix))]` arm removes nothing and only the record ordering applies —
+native Windows runtime was NOT executed and is not claimed. No dependency, version,
+`Cargo.lock`, schema, node-ID, golden, state-protocol, or permanent-index-lifecycle
+byte changed; `Cargo.lock` remains SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` and the frozen
+plan is untouched at SHA-256
+`5b64aa335fb32cd228d98404c2e44153e9134d26a912ecb02d71fcf5c5798450`.
+
+### Same correction pass — the startup gate refused a killed daemon's live sidecars
+
+Verifying the cleanup fix surfaced a SECOND, independent defect introduced by
+`df86a5a`'s fifth correction. That correction routed `authorize_daemon_startup`
+through `Store::open_for_read`, whose `Current` contract demands a sidecar-FREE
+database. A daemon that is KILLED rather than closed leaves `-wal`/`-shm` behind on
+an otherwise untouched `Current` namespace, so every replacement start then failed
+with `Current index state has an unexpected SQLite sidecar at …/codegraph.db-wal`
+and published no rendezvous — exactly the recovery path `spawn_detached_daemon`
+exists for.
+
+This was NOT found by reading code. `make ci CARGO='cargo --locked'` failed on the
+pre-existing `spawn_detached_daemon_twice_no_stale_deadlock` (kill the first daemon,
+clear its stale artifacts, respawn) with "second daemon pid after respawn"; repeated
+`cargo test --locked -p codegraph-rs --test daemon_spawn` reproduced it in 2 of 6
+runs, and a hand-built repro confirmed the refusal message directly from a planted
+`codegraph.db-wal`. The intermittency is why it was mistaken for load flake earlier
+in this session: the sidecars survive only when the SIGKILL lands while a connection
+is open, so the same test passes whenever the kill happens to land between
+connections. That earlier "known flake" note was wrong, and this ledger corrects it.
+
+Fix: `Store::open_for_daemon_startup` — `open_for_read` with `allow_live_sidecar`,
+the SAME relaxation the incremental-sync writer and the uninit continuation already
+take, and for the same reason (the extraction stamp is read from the
+already-checkpointed MAIN-file bytes, so nothing about the version gate changes).
+Every other gate is untouched: owner-bound state slots, tombstone absence, DB
+presence, the exact stamp, and the retained shared lease held across pid/socket
+publication.
+
+New acceptance `a_killed_daemons_live_sidecars_do_not_block_a_replacement_start`
+plants both sidecars on a real indexed project, proves a replacement daemon
+publishes its v2 rendezvous, then — with those same sidecars still present — drains
+it via `uninit --force` and proves the now-tombstoned namespace is STILL refused.
+That second half is what shows the relaxation did not weaken the state contract.
+Negative control, executed: reverting the single call site to `Store::open_for_read`
+turns exactly this test red ("the daemon never published its v2 rendezvous at
+…/.codegraph-v2/daemon.pid") while the other three acceptances stay green; the
+corrected byte was then restored and the suite re-run 4/4. Repeated
+`--test daemon_spawn` is now 8/8 green where it was 4/6.

From 8c66848b494dfe7b34f465194afad5f82dded0b6 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Mon, 27 Jul 2026 17:18:06 +0800
Subject: [PATCH 39/91] revert(store): drop the out-of-scope daemon-startup
 sidecar relaxation

---
 crates/codegraph-cli/src/main.rs              |  22 +--
 .../tests/batch_m_daemon_uninit_lifecycle.rs  |  63 --------
 crates/codegraph-store/src/connection.rs      |  52 -------
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 142 ++++++++++++++++++
 4 files changed, 150 insertions(+), 129 deletions(-)

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index ae6084e..00ddeab 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1165,26 +1165,20 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
 
 /// Daemon-startup gate (frozen plan lines 590-592, 603-604).
 ///
-/// ONE bounded shared acquisition validates everything:
-/// `Store::open_for_daemon_startup` acquires the shared `IndexLease` and, under it,
-/// corroborates the FULL `Current` contract — both owner-bound state slots (so
-/// `Future`, `Corrupt`, `Building`, `Uninitialized`, `Outdated`, and an owner
-/// mismatch are all refused), tombstone absence, database presence, and the exact
-/// extraction stamp read from the checkpointed main-file bytes. Slot phase alone
-/// would let a `Current` slot with a deleted database or a stale stamp publish a
-/// rendezvous.
-///
-/// A LIVE `-wal`/`-shm` sidecar is deliberately tolerated (the one difference from
-/// `Store::open_for_read`): a killed daemon leaves those behind on an otherwise
-/// untouched namespace, and refusing them would make a replacement daemon
-/// unstartable after any hard kill.
+/// ONE bounded shared acquisition validates everything: `Store::open_for_read`
+/// acquires the shared `IndexLease` and, under it, corroborates the FULL `Current`
+/// contract — both owner-bound state slots (so `Future`, `Corrupt`, `Building`,
+/// `Uninitialized`, `Outdated`, and an owner mismatch are all refused), tombstone
+/// absence, database presence, sidecar-freedom, and the exact extraction stamp
+/// read from the checkpointed main-file bytes. Slot phase alone would let a
+/// `Current` slot with a deleted database or a stale stamp publish a rendezvous.
 ///
 /// The returned `Store` OWNS that same lease, so retaining it across pid/socket
 /// publication requires no second acquisition: there is no nested lock and no
 /// window between validation and publication for another writer to reclassify.
 fn authorize_daemon_startup(project_root: &Path) -> Result<codegraph_daemon::StartupAuthorization> {
     let paths = index_paths(project_root)?;
-    match Store::open_for_daemon_startup(
+    match Store::open_for_read(
         &paths,
         std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
         || false,
diff --git a/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
index 66d9d36..972343d 100644
--- a/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
+++ b/crates/codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs
@@ -510,69 +510,6 @@ fn uninit_shutdown_control_drains_without_pid_kill() {
     assert_recoverable_uninitialized(&paths, "after a drained uninit");
 }
 
-/// A daemon that was KILLED rather than closed leaves its SQLite `-wal`/`-shm`
-/// sidecars behind on an otherwise untouched `Current` namespace. The startup gate
-/// must still admit a replacement daemon, because refusing those sidecars would
-/// make the namespace unstartable after any hard kill — while every other part of
-/// the `Current` contract stays enforced (proved by the tombstone case below, which
-/// is refused with the very same sidecars present).
-#[test]
-fn a_killed_daemons_live_sidecars_do_not_block_a_replacement_start() {
-    let project = TestProject::indexed("live-sidecars");
-    let paths = project.paths();
-
-    let sidecars: Vec<PathBuf> = ["-wal", "-shm"]
-        .iter()
-        .map(|suffix| {
-            let mut path = paths.current_db().into_os_string();
-            path.push(suffix);
-            PathBuf::from(path)
-        })
-        .collect();
-    for sidecar in &sidecars {
-        fs::write(sidecar, b"").expect("plant a killed daemon's live sidecar");
-    }
-
-    let mut daemon = ChildGuard::new(
-        daemon_command(project.path())
-            .spawn()
-            .expect("spawn daemon"),
-    );
-    let pid = wait_for_owner_record(&paths);
-    assert!(
-        is_process_alive(pid),
-        "a replacement daemon must start despite a killed predecessor's sidecars"
-    );
-
-    // The same namespace WITH those sidecars is still refused once it carries a
-    // tombstone, so this relaxation did not weaken the state contract.
-    let output = uninit_force(project.path());
-    assert!(
-        output.status.success(),
-        "uninit --force must drain the replacement daemon; stderr: {}",
-        String::from_utf8_lossy(&output.stderr)
-    );
-    assert_eq!(daemon.wait_bounded("the drained daemon").code(), Some(0));
-    assert_recoverable_uninitialized(&paths, "after draining the replacement daemon");
-
-    let refused = ChildGuard::new(
-        daemon_command(project.path())
-            .spawn()
-            .expect("spawn daemon"),
-    )
-    .finish("the refused daemon start");
-    let stderr = String::from_utf8_lossy(&refused.stderr).to_string();
-    assert!(
-        !refused.status.success() && stderr.contains("tombstone"),
-        "a tombstoned namespace must still refuse a daemon start: {stderr}"
-    );
-    assert_no_rendezvous(
-        project.path(),
-        &paths,
-        "after the tombstoned start was refused",
-    );
-}
-
 #[test]
 fn unresponsive_daemon_leaves_recoverable_uninitialized_without_kill() {
     let project = TestProject::indexed("unresponsive");
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index f807af0..ef14026 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -340,58 +340,6 @@ impl Store {
         open_current_read_only(paths, lease)
     }
 
-    /// The daemon-startup read gate: identical to [`Self::open_for_read`] except
-    /// that a LIVE SQLite sidecar is tolerated.
-    ///
-    /// `-wal`/`-shm` are legitimately present on an untouched `Current` namespace
-    /// whenever a long-lived reader holds a connection — the MCP engine does for a
-    /// whole request — and they SURVIVE a daemon that was killed rather than closed.
-    /// Demanding sidecar-freedom here would therefore refuse to start a replacement
-    /// daemon after any hard kill, which is precisely the recovery path
-    /// `spawn_detached_daemon` exists for. This is the same relaxation the
-    /// incremental-sync writer already takes (see
-    /// `corroborate_current_database_options`), and for the same reason: the
-    /// extraction stamp is still read from the already-checkpointed MAIN-file bytes,
-    /// so the version gate, tombstone gate, DB-presence gate, owner-bound state
-    /// slots, and the retained shared lease are all unchanged.
-    pub fn open_for_daemon_startup(
-        paths: &IndexPaths,
-        deadline: Instant,
-        cancelled: impl FnMut() -> bool,
-    ) -> Result<Self> {
-        Self::open_for_read_with_sidecar_policy(paths, deadline, cancelled, true)
-    }
-
-    fn open_for_read_with_sidecar_policy(
-        paths: &IndexPaths,
-        deadline: Instant,
-        cancelled: impl FnMut() -> bool,
-        allow_live_sidecar: bool,
-    ) -> Result<Self> {
-        let lease = match IndexLease::acquire_shared_existing(paths, deadline, cancelled) {
-            Ok(lease) => lease,
-            Err(IndexLeaseError::LockNotFound { .. }) => {
-                return Err(lockless_state_error(paths)?);
-            }
-            Err(error) => return Err(StoreError::Lease(error)),
-        };
-        let status = Self::extraction_status(paths);
-        reject_missing_database_artifacts(paths, &status)?;
-        if status != ExtractionStatus::Current {
-            return Err(StoreError::StateRejected { status });
-        }
-        let (conn, source_conn) =
-            corroborate_current_database_options(paths, false, allow_live_sidecar)?;
-        Ok(Store {
-            conn,
-            _source_conn: Some(source_conn),
-            path: paths.current_db(),
-            access: StoreAccess::StateRead,
-            guarded_paths: Some(paths.clone()),
-            lease: Some(lease),
-        })
-    }
-
     /// Probe status under a short shared lease. Contention is status data rather
     /// than an error and never opens SQLite. Non-Current states are reported
     /// without SQLite; Current is corroborated through [`Self::open_for_read`]'s
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 5a7545c..49014fd 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3251,3 +3251,145 @@ turns exactly this test red ("the daemon never published its v2 rendezvous at
 …/.codegraph-v2/daemon.pid") while the other three acceptances stay green; the
 corrected byte was then restored and the suite re-run 4/4. Repeated
 `--test daemon_spawn` is now 8/8 green where it was 4/6.
+
+### Correction — the sidecar relaxation was REVERTED, and doing so re-exposed a real defect
+
+The section immediately above is superseded on the SCOPE question and CORRECTED on the
+evidence question. Two separate things happened in `f691415`, and only one was
+authorized.
+
+**Retained in full: the rendezvous-cleanup ownership-ordering fix.** `record_names`,
+`RendezvousCleanupCheckpoint`, `cleanup_owned_rendezvous_with`, the
+socket-before-record ordering, the second-boundary re-corroboration, and both
+`a_replacement_start_at_the_cleanup_midpoint_keeps_its_own_rendezvous` and
+`a_crash_between_cleanup_boundaries_leaves_only_self_healing_residue`.
+`crates/codegraph-daemon/src/lock.rs` is byte-identical to its `f691415` content,
+SHA-256 `a14583b40c8695318f07552fc9633622fd4356581bec7c5ad16cfe89203814fe`.
+
+Negative control, re-executed over these exact bytes. Reinstating the old
+pid-record-first body — `cleanup_owned_lock` called BEFORE the socket unlink and before
+the `OwnershipCorroborated` checkpoint, with no second-boundary re-corroboration —
+turned BOTH retained tests red in one run:
+`a_replacement_start_at_the_cleanup_midpoint_keeps_its_own_rendezvous` with "a competing
+start must NOT be able to claim the record before the departing owner has finished
+unlinking its socket" (`lock.rs:617`), and
+`a_crash_between_cleanup_boundaries_leaves_only_self_healing_residue` with "the record
+is STILL published as exclusion at this boundary" (`lock.rs:673`) — 98 passed, 2 failed.
+
+Worth recording precisely, because it shows the two tests guard different bytes: an
+INTERMEDIATE mutant that released the record early but left the `OwnershipCorroborated`
+checkpoint above it turned only the crash test red (99 passed, 1 failed) while the
+midpoint test still passed, since the competing start then ran before the release. Only
+the faithful old ordering — release first, checkpoint after — reproduces the original
+race the midpoint test was written for. The corrected bytes were then restored via
+`git checkout --` (`grep -c MUTANT` → 0, file SHA-256 back to
+`a14583b40c8695318f07552fc9633622fd4356581bec7c5ad16cfe89203814fe`) and
+`codegraph-daemon --lib` re-run **100/100**.
+
+**Reverted as out of scope: the daemon-startup SQLite sidecar relaxation.**
+`Store::open_for_daemon_startup` and its private `open_for_read_with_sidecar_policy`
+helper are removed from `crates/codegraph-store/src/connection.rs`;
+`authorize_daemon_startup` calls `Store::open_for_read` again and its doc comment
+again describes the full `Current` contract INCLUDING sidecar-freedom, exactly as at
+`df86a5a`; and the acceptance
+`a_killed_daemons_live_sidecars_do_not_block_a_replacement_start` is removed.
+`git diff df86a5a..HEAD` is empty for both `connection.rs` and `main.rs`, and
+`batch_m_daemon_uninit_lifecycle` is back to its original 3 tests, **3/3** green.
+
+The scope objection is upheld: relaxing a state/artifact contract that was verified at
+`df86a5a` is its own change with its own evidence, and it does not ride along inside a
+cleanup-ordering fix. The objection to the removed test also stands on its own terms —
+it planted two ZERO-BYTE sidecars, which is not what a killed daemon actually leaves,
+so it did not prove the relaxation was necessary.
+
+**But the underlying defect is REAL, and this pass measured it directly.** It was
+expected to stay open and unproven; it did not. Measurements taken on this Linux host
+over the reverted bytes:
+
+- The PRE-EXISTING acceptance `spawn_detached_daemon_twice_no_stale_deadlock` (kill the
+  first daemon, remove its stale pid/socket, respawn) fails **3 of 10** locked runs at
+  the default test-thread count, always on the same assertion, `second daemon pid after
+respawn` at `crates/codegraph-cli/tests/daemon_spawn.rs:227`. Two independent batches
+  of 10 gave 3 failures each (runs 3/5/7, then runs 1/2/5).
+- A 0.03 s-interval watcher captured the failing runs' own daemon log verbatim:
+  `Error: running as detached MCP daemon: refusing to start a daemon for
+/tmp/codegraph-daemon-spawn-twice-…/mini: Current index state has an unexpected SQLite
+sidecar at …/.codegraph-v2/codegraph.db-wal; index state is current and its
+uninitialized tombstone is absent. No daemon pid, socket, or log was published. Run
+`codegraph init` to rebuild.`
+- The same watcher captured the residue those runs actually left behind:
+  `codegraph.db-shm` at **32768 bytes** — non-empty, a live shared-memory header — and
+  `codegraph.db-wal` at 0 bytes. Contrast run: a PASSING run's namespace held
+  `codegraph.db` alone, no sidecars. So the failures correlate exactly with surviving
+  sidecars, and the residue is a real hard-killed daemon's, not a planted placeholder.
+- The intermittency is timing, not load. With `-- --test-threads=1` the same suite ran
+  **12 of 12** green; the failures only appear when the two tests in the file run
+  concurrently and the SIGKILL lands while a connection is open. A standalone
+  `serve --mcp` + `kill -9` loop with no client attached left NO sidecars in 10 of 10
+  iterations, which is why this was mistaken for load flake earlier. That earlier
+  "known flake" note was wrong, and it stays corrected.
+
+So the answer to "does a hard-killed daemon block a replacement start" is **YES,
+intermittently** — when the kill lands while a connection is open, the sidecars survive
+and the strict `Current` gate refuses every subsequent start until `codegraph init` is
+re-run.
+
+**This defect is PRE-EXISTING, not introduced by this revert — measured, not argued.**
+`daemon_spawn.rs`, `connection.rs`, and `main.rs` are all byte-identical to `df86a5a`,
+and the retained `lock.rs` cleanup ordering is not on this path (the test removes the pid
+record and socket itself, and the refusal happens in the store gate before any
+rendezvous is published). To close that off by measurement rather than reasoning,
+`lock.rs` was temporarily swapped to its `df86a5a` content (SHA-256
+`a25868072cfcf31477bad9d77376edda27f4727eae2f76a2eb3e00120463b35e`) — i.e. the tree with
+the retained fix REMOVED — and the same suite still failed **1 of 10** locked runs on the
+identical assertion at `daemon_spawn.rs:227`. The retained fix was then restored and
+`lock.rs` re-proved byte-identical to `f691415` (`a14583b4…`, empty
+`git diff f691415 -- crates/codegraph-daemon/src/lock.rs`). So the flake exists with and
+without the cleanup fix; the sidecar gate is its cause, and this pass neither introduced
+nor cured it.
+
+**Consequence, stated plainly rather than papered over:** over the reverted bytes,
+`make ci CARGO='cargo --locked'` is NOT reliably green — it fails whenever
+`spawn_detached_daemon_twice_no_stale_deadlock` hits the ~3-in-10 timing window. The
+reverted tree is honest about scope and carries a pre-existing intermittent red. No
+test was weakened, skipped, slept, or deleted to hide this, and no relaxation was
+re-introduced under another name.
+
+What remains genuinely OPEN is the FIX, not the defect: whether the right answer is a
+sidecar-tolerant startup read, a checkpoint-and-clear on startup, or a narrower
+recovery path is undecided and belongs to its own plan item with its own failing-first
+evidence. The measurements above are that item's starting evidence, and they replace
+the zero-byte-placeholder test that was removed.
+
+Verification of this correction, with `bash scripts/check-workspace-versions.sh` before
+every Cargo batch (exit 0, workspace 0.40.4 across all 10 packages) and `--locked` on
+every Cargo command: `codegraph-daemon --lib` **100/100** including both retained cleanup
+tests; `codegraph-rs --test batch_m_daemon_uninit_lifecycle` **3/3** (its original three);
+`codegraph-rs --test daemon_spawn` **2/2** on a single run and **12/12 runs** green at
+`--test-threads=1`, but **3 of 10 runs** red at the default thread count for the
+pre-existing sidecar reason measured above.
+
+The final gate, `bash scripts/check-workspace-versions.sh && make ci CARGO='cargo
+--locked'` over these exact bytes, was run **four** times: **exit 2, exit 0, exit 0,
+exit 2**. Both failures are the same single assertion, `daemon_spawn.rs:227 second daemon
+pid after respawn`; `fmt --check`, `clippy --workspace --all-targets -D warnings`, and
+`scripts/guardrail.sh` passed every time, and 76 other test-binary result lines were `ok`
+in the failing runs too. So this tree is **NOT reliably green**, and that is reported as a
+fact rather than smoothed over by re-running until a green appears: the gate is a coin
+flip on a pre-existing defect that predates both this correction and `f691415`.
+
+One further confirmation run of that same gate was executed after this ledger text was
+finalized, so that the last gate run covers these exact committed bytes; its exit code is
+reported in the closeout summary rather than restated here, since no code byte differs
+between it and the four runs above.
+
+Limitations. Changed-file LSP diagnostics were attempted on BOTH
+`crates/codegraph-store/src/connection.rs` and `crates/codegraph-cli/src/main.rs` and
+both were refused with `LSP file path must be inside request cwd` — the worktree at
+`/config/workspace/ProdDir/AI/.cgworktrees/v15-impl` is still outside the request cwd,
+even though it was expected to be inside it — so no LSP-clean result is claimed; locked
+Cargo build/Clippy/tests are the fallback. The sidecar measurements are Linux-only; native
+Windows/MSVC runtime is unavailable on this host and nothing about it is claimed. No
+dependency, version, `Cargo.lock`, schema, node-ID, golden, state-protocol, or
+permanent-index-lifecycle byte changed; `Cargo.lock` remains SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.

From 721709a3f47d3467c46af3696f935beeaebaea1e Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 03:13:27 +0800
Subject: [PATCH 40/91] fix(store): recover a killed daemon's leftover WAL on
 startup

---
 crates/codegraph-cli/src/main.rs              |  75 ++++
 .../tests/daemon_stale_wal_recovery.rs        | 325 ++++++++++++++++++
 crates/codegraph-store/src/connection.rs      | 143 +++++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 175 ++++++++++
 4 files changed, 715 insertions(+), 3 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 00ddeab..0594c84 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1176,8 +1176,83 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
 /// The returned `Store` OWNS that same lease, so retaining it across pid/socket
 /// publication requires no second acquisition: there is no nested lock and no
 /// window between validation and publication for another writer to reclassify.
+/// Bounded budget for the ONE exclusive acquisition of the stale-sidecar
+/// recovery attempted before the strict startup read gate.
+///
+/// Deliberately much shorter than [`REBUILD_LEASE_TIMEOUT`]: this acquisition is
+/// a best-effort repair on the latency-critical daemon-startup path, and the ONLY
+/// legitimate reason it cannot be taken is that another cooperating holder (a
+/// live reader or writer) owns the namespace — in which case there is nothing to
+/// recover and startup must proceed to its unchanged verdict immediately instead
+/// of stalling behind a long-lived MCP reader's shared lease.
+const STALE_SIDECAR_RECOVERY_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(500);
+
+/// Whether this project's PREVIOUS rendezvous owner may still be running.
+///
+/// Read-only by construction: unlike `clear_stale_daemon_lock`, which removes a
+/// stale record as a side effect, the startup gate must only OBSERVE liveness —
+/// the record is the single-instance exclusion `try_acquire_daemon_lock` claims
+/// moments later, so removing it here would open a double-start window.
+///
+/// Fail-closed: an unreadable or empty pid record is reported as LIVE. An empty
+/// record is an in-flight `create_new` placeholder whose rename has not landed,
+/// exactly as the daemon lock layer already treats it.
+fn previous_daemon_owner_may_be_live(project_root: &Path) -> bool {
+    let Ok(pid_path) = codegraph_daemon::daemon_pid_path(project_root) else {
+        return true;
+    };
+    match std::fs::read_to_string(&pid_path) {
+        Ok(raw) => match codegraph_daemon::decode_lock_info(&raw) {
+            Some(info) => info.pid > 0 && codegraph_daemon::is_process_alive(info.pid),
+            None => true,
+        },
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => false,
+        Err(_) => true,
+    }
+}
+
+/// Recover a provably dead previous owner's leftover `-wal`/`-shm` before the
+/// strict gate runs.
+///
+/// A daemon killed with an open SQLite connection leaves an un-checkpointed
+/// write-ahead log behind, and the sidecar-freedom clause of the `Current` read
+/// contract then refuses EVERY later daemon start until `codegraph init` is
+/// re-run. The remedy is recovery, not permission: fold that log back into the
+/// main database under an exclusive lease and delete the checkpointed sidecars,
+/// then let the UNCHANGED gate decide. Nothing is relaxed — the gate below still
+/// demands sidecar-freedom, and a namespace this repair cannot fix is still
+/// refused.
+///
+/// Both guards must hold: the rendezvous owner is provably not alive AND the
+/// exclusive lease is obtainable within a short bound, so a live daemon's or a
+/// live MCP reader's sidecars are never folded underneath them. A failure here is
+/// swallowed to a log line: recovery is opportunistic, and the authoritative
+/// verdict is always the gate's.
+fn recover_dead_owner_sidecars(paths: &codegraph_core::IndexPaths, project_root: &Path) {
+    if previous_daemon_owner_may_be_live(project_root) {
+        return;
+    }
+    match Store::recover_stale_current_sidecars(
+        paths,
+        std::time::Instant::now() + STALE_SIDECAR_RECOVERY_TIMEOUT,
+        || false,
+    ) {
+        Ok(true) => tracing::info!(
+            project = %project_root.display(),
+            "folded a dead daemon's leftover write-ahead log back into the index"
+        ),
+        Ok(false) => {}
+        Err(error) => tracing::warn!(
+            %error,
+            project = %project_root.display(),
+            "could not recover leftover SQLite sidecars; the startup gate decides"
+        ),
+    }
+}
+
 fn authorize_daemon_startup(project_root: &Path) -> Result<codegraph_daemon::StartupAuthorization> {
     let paths = index_paths(project_root)?;
+    recover_dead_owner_sidecars(&paths, project_root);
     match Store::open_for_read(
         &paths,
         std::time::Instant::now() + REBUILD_LEASE_TIMEOUT,
diff --git a/crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs b/crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs
new file mode 100644
index 0000000..1a073a4
--- /dev/null
+++ b/crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs
@@ -0,0 +1,325 @@
+//! A daemon killed with an open SQLite connection leaves an un-checkpointed
+//! `-wal` behind. The strict `Current` startup gate demands sidecar-freedom, so
+//! before this recovery existed that residue refused EVERY later daemon start
+//! until `codegraph init` was re-run.
+//!
+//! These tests plant a REAL un-checkpointed write-ahead log — a child process
+//! writes a row with `wal_autocheckpoint=0` and then dies without closing SQLite
+//! — and drive the PRODUCTION daemon-start path over it. Zero-byte sidecar files
+//! would prove nothing, so the planted log is asserted non-empty and the planted
+//! row is asserted absent from the main database file before startup.
+
+#![cfg(unix)]
+
+use std::fs;
+use std::io::{BufRead, BufReader};
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+use codegraph_daemon::{
+    daemon_pid_path, daemon_socket_path, is_process_alive, spawn_detached_daemon, unlock_project,
+};
+use codegraph_store::Store;
+use interprocess::local_socket::traits::Stream as _;
+use interprocess::local_socket::{GenericFilePath, Stream, ToFsName};
+
+/// Env var carrying the database a child process must plant a live write-ahead
+/// log into before dying.
+const PLANT_WAL_DB: &str = "CODEGRAPH_TEST_PLANT_WAL_DB";
+
+/// The metadata key the planted row uses. It exists ONLY in the write-ahead log
+/// until something folds that log back into the main database file.
+const WAL_ONLY_KEY: &str = "stale_wal_recovery_probe";
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+fn workspace_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-cli is under crates/")
+        .to_path_buf()
+}
+
+fn copy_tree(src: &Path, dst: &Path) {
+    fs::create_dir_all(dst).expect("create fixture copy dir");
+    for entry in fs::read_dir(src).expect("read fixture dir") {
+        let entry = entry.expect("fixture dir entry");
+        let from = entry.path();
+        let to = dst.join(entry.file_name());
+        if from.is_dir() {
+            copy_tree(&from, &to);
+        } else {
+            fs::copy(&from, &to).expect("copy fixture file");
+        }
+    }
+}
+
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-stale-wal-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("clock after epoch")
+                .as_nanos()
+        ));
+        fs::create_dir_all(&path).expect("create test dir");
+        Self(path)
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+fn indexed_project(label: &str) -> (TestDir, PathBuf) {
+    let dir = TestDir::new(label);
+    let project = dir.0.join("mini");
+    copy_tree(
+        &workspace_root().join("crates/codegraph-bench/fixtures/mini"),
+        &project,
+    );
+    let status = Command::new(bin())
+        .args(["init", project.to_str().expect("utf8 project path")])
+        .status()
+        .expect("run codegraph init");
+    assert!(status.success(), "init failed for {}", project.display());
+    (dir, project)
+}
+
+fn index_paths(project: &Path) -> codegraph_core::IndexPaths {
+    codegraph_core::IndexPaths::resolve(project, None).expect("resolve v2 index paths")
+}
+
+fn sidecar(db: &Path, suffix: &str) -> PathBuf {
+    let mut native = db.as_os_str().to_os_string();
+    native.push(suffix);
+    PathBuf::from(native)
+}
+
+/// Plant a genuinely un-checkpointed write-ahead log by re-invoking THIS test
+/// binary as a child that writes one row with WAL auto-checkpointing disabled and
+/// then dies without closing SQLite. A real dead process is the point: an
+/// in-process leak would keep the connection open and look like a LIVE owner.
+fn plant_unckeckpointed_wal(db: &Path) {
+    let output = Command::new(std::env::current_exe().expect("current test binary"))
+        .arg("--exact")
+        .arg("plant_uncheckpointed_wal_child_process")
+        .arg("--nocapture")
+        .env(PLANT_WAL_DB, db)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .expect("run WAL-planting child");
+    assert!(
+        !output.status.success(),
+        "the planting child must die without closing SQLite, so it never exits successfully"
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stdout).contains("PLANTED"),
+        "the planting child must report a committed row before dying: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+/// The child half of [`plant_unckeckpointed_wal`]. A no-op in an ordinary run.
+#[test]
+fn plant_uncheckpointed_wal_child_process() {
+    let Ok(db) = std::env::var(PLANT_WAL_DB) else {
+        return;
+    };
+    let store = Store::open(Path::new(&db)).expect("open the planted database");
+    store
+        .connection()
+        .pragma_update(None, "wal_autocheckpoint", 0)
+        .expect("disable WAL auto-checkpointing");
+    store
+        .set_project_metadata(WAL_ONLY_KEY, "1")
+        .expect("commit the WAL-only row");
+    println!("PLANTED");
+    // Die exactly like a SIGKILLed daemon: no SQLite close, no checkpoint, so the
+    // committed row stays in the `-wal` sidecar only.
+    std::process::abort();
+}
+
+/// Read one metadata key from a COPY of the main database file alone, with no
+/// sidecar beside it. A value visible here is durably folded into the main file;
+/// a value only in the write-ahead log is not.
+fn metadata_in_main_file_only(db: &Path, label: &str) -> Option<String> {
+    let dir = TestDir::new(label);
+    let copy = dir.0.join("main-only.db");
+    fs::copy(db, &copy).expect("copy the main database file");
+    let store = Store::open(&copy).expect("open the main-file-only copy");
+    let value = store
+        .get_project_metadata(WAL_ONLY_KEY)
+        .expect("read the probe key");
+    drop(store);
+    value
+}
+
+fn read_pid_from_hello(socket: &Path) -> Option<u32> {
+    let name = socket.to_fs_name::<GenericFilePath>().ok()?;
+    let stream = Stream::connect(name).ok()?;
+    let mut line = String::new();
+    BufReader::new(&stream).read_line(&mut line).ok()?;
+    serde_json::from_str::<serde_json::Value>(line.trim())
+        .ok()?
+        .get("pid")
+        .and_then(serde_json::Value::as_u64)
+        .map(|pid| pid as u32)
+}
+
+fn poll_for_daemon_pid(socket: &Path, timeout: Duration) -> Option<u32> {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        if socket.exists()
+            && let Some(pid) = read_pid_from_hello(socket)
+        {
+            return Some(pid);
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    None
+}
+
+fn process_is_gone_or_zombie(pid: u32) -> bool {
+    if !is_process_alive(pid) {
+        return true;
+    }
+    match fs::read_to_string(format!("/proc/{pid}/stat")) {
+        Ok(stat) => stat
+            .rsplit_once(')')
+            .and_then(|(_, rest)| rest.split_whitespace().next())
+            .map(|state| state == "Z")
+            .unwrap_or(false),
+        Err(_) => true,
+    }
+}
+
+fn kill_and_reap(pid: u32) {
+    let _ = Command::new("kill").arg("-9").arg(pid.to_string()).status();
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while Instant::now() < deadline {
+        if process_is_gone_or_zombie(pid) {
+            return;
+        }
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    panic!("daemon pid {pid} must be dead after teardown");
+}
+
+/// A dead owner's leftover, genuinely non-empty write-ahead log no longer bricks
+/// the namespace: the daemon starts, and the row that existed ONLY in that log is
+/// folded into the main database file instead of being discarded.
+#[test]
+fn a_dead_owners_uncheckpointed_wal_is_recovered_on_daemon_startup() {
+    let (_dir, project) = indexed_project("recover");
+    let paths = index_paths(&project);
+    let db = paths.current_db();
+    let wal = sidecar(&db, "-wal");
+
+    plant_unckeckpointed_wal(&db);
+
+    // The residue is REAL: a non-empty log holding a row the main file lacks.
+    let planted = fs::metadata(&wal).expect("planted -wal exists").len();
+    assert!(
+        planted > 0,
+        "the planted -wal must carry bytes; a zero-byte sidecar proves nothing"
+    );
+    assert_eq!(
+        metadata_in_main_file_only(&db, "before"),
+        None,
+        "the probe row must live ONLY in the write-ahead log before recovery"
+    );
+
+    let socket = daemon_socket_path(&project).expect("resolve the rendezvous socket identity");
+    spawn_detached_daemon(&bin(), &project, true).expect("spawn a daemon over the stale residue");
+    let pid = poll_for_daemon_pid(&socket, Duration::from_secs(5)).unwrap_or_else(|| {
+        panic!(
+            "a daemon must start over a dead owner's leftover WAL; daemon log:\n{}",
+            fs::read_to_string(paths.daemon_log()).unwrap_or_default()
+        )
+    });
+
+    assert_eq!(
+        metadata_in_main_file_only(&db, "after").as_deref(),
+        Some("1"),
+        "recovery must FOLD the log into the main database file, not discard it"
+    );
+    assert!(
+        paths.permanent_lock().exists(),
+        "the permanent index lock must survive recovery"
+    );
+    assert_eq!(
+        Store::extraction_status(&paths),
+        codegraph_store::ExtractionStatus::Current,
+        "the namespace must still classify as Current"
+    );
+
+    kill_and_reap(pid);
+    unlock_project(&project);
+}
+
+/// The paired fail-closed control: the SAME stale residue in a namespace carrying
+/// the uninitialized tombstone is still refused. Recovery never becomes a way
+/// around the state protocol.
+#[test]
+fn the_same_stale_residue_under_a_tombstone_is_still_refused() {
+    let (_dir, project) = indexed_project("tombstoned");
+    let paths = index_paths(&project);
+    let db = paths.current_db();
+    let wal = sidecar(&db, "-wal");
+
+    plant_unckeckpointed_wal(&db);
+    assert!(
+        fs::metadata(&wal).expect("planted -wal exists").len() > 0,
+        "the planted -wal must carry bytes"
+    );
+    fs::write(paths.tombstone(), b"").expect("plant the uninitialized tombstone");
+
+    let output = Command::new(bin())
+        .args(["serve", "--mcp", "--path"])
+        .arg(&project)
+        .env("CODEGRAPH_DAEMON_INTERNAL", "1")
+        .env("CODEGRAPH_NO_WATCH", "1")
+        .output()
+        .expect("run the gated daemon start");
+
+    assert!(
+        !output.status.success(),
+        "a tombstoned namespace must refuse to start a daemon"
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("refusing to start a daemon"),
+        "the refusal must be reported: {stderr}"
+    );
+    assert!(
+        fs::metadata(&wal)
+            .expect("the -wal survives a refusal")
+            .len()
+            > 0,
+        "a refused start must fold nothing"
+    );
+    assert!(
+        !daemon_pid_path(&project)
+            .expect("resolve the rendezvous pid path")
+            .exists(),
+        "a refused start must publish no pid record"
+    );
+    assert!(
+        !daemon_socket_path(&project)
+            .expect("resolve the rendezvous socket identity")
+            .exists(),
+        "a refused start must publish no socket"
+    );
+}
diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index ef14026..293b13f 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -60,6 +60,13 @@ pub enum StoreWritePurpose {
     /// continuation. Only `Current`, recoverable `Building`, or
     /// `Uninitialized` may issue this capability.
     UninitContinuation,
+    /// Fold a PREVIOUS owner's un-checkpointed write-ahead log back into the
+    /// main database file of an otherwise fully corroborated `Current`
+    /// namespace, so the sidecar-free artifact shape the read gate requires is
+    /// restored instead of the namespace staying permanently unreadable. Only
+    /// [`Store::recover_stale_current_sidecars`] issues this purpose, and only
+    /// `Current` may authorize it.
+    StaleSidecarRecovery,
 }
 
 impl std::fmt::Display for StoreWritePurpose {
@@ -69,6 +76,7 @@ impl std::fmt::Display for StoreWritePurpose {
             Self::FullRebuild => "full rebuild",
             Self::IncrementalSync => "incremental sync",
             Self::UninitContinuation => "uninit continuation",
+            Self::StaleSidecarRecovery => "stale sidecar recovery",
         })
     }
 }
@@ -237,6 +245,14 @@ pub enum StoreError {
         #[source]
         source: rusqlite::Error,
     },
+    #[error("write-ahead log {path} still holds {remaining} bytes after a truncating checkpoint")]
+    WalNotFolded { path: PathBuf, remaining: u64 },
+    #[error("failed to remove the checkpointed SQLite sidecar {path}: {source}")]
+    RemoveSidecar {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
     #[error("failed to stamp extraction version in SQLite database {path}: {source}")]
     StampExtractionVersion {
         path: PathBuf,
@@ -452,18 +468,26 @@ impl Store {
         }
 
         match purpose {
-            StoreWritePurpose::CurrentMutation | StoreWritePurpose::IncrementalSync
+            StoreWritePurpose::CurrentMutation
+            | StoreWritePurpose::IncrementalSync
+            | StoreWritePurpose::StaleSidecarRecovery
                 if status == ExtractionStatus::Current =>
             {
                 // Corroborate through a separate read-only/no-create handle before
                 // any write-capable setup can alter pragmas or sidecars. An
                 // incremental sync tolerates a live reader's sidecars (see
                 // `corroborate_current_database_options`); the stamp still comes
-                // from the checkpointed main-file bytes.
+                // from the checkpointed main-file bytes. Stale-sidecar recovery
+                // exists precisely BECAUSE sidecars are present, so it tolerates
+                // them for the same reason — and folds them away afterwards.
                 let (corroboration, source_conn) = corroborate_current_database_options(
                     paths,
                     false,
-                    purpose == StoreWritePurpose::IncrementalSync,
+                    matches!(
+                        purpose,
+                        StoreWritePurpose::IncrementalSync
+                            | StoreWritePurpose::StaleSidecarRecovery
+                    ),
                 )?;
                 drop(corroboration);
                 drop(source_conn);
@@ -611,6 +635,70 @@ impl Store {
         })
     }
 
+    /// Fold a DEAD previous owner's leftover write-ahead log back into the main
+    /// database file of an otherwise fully corroborated `Current` namespace and
+    /// remove the checkpointed `-wal`/`-shm` sidecars, so the sidecar-free
+    /// artifact shape [`Self::open_for_read`] requires is restored.
+    ///
+    /// A daemon SIGKILLed with an open SQLite connection leaves un-checkpointed
+    /// `-wal`/`-shm` behind. The read gate then refuses the namespace forever,
+    /// which is correct as a READ contract but leaves recovery impossible
+    /// without `codegraph init`. This is that recovery, and it never relaxes the
+    /// read gate: the fold happens under the ONE outer exclusive lease, the
+    /// `Current` contract (tombstone absence, database presence, exact
+    /// main-file extraction stamp) is corroborated first, and the caller then
+    /// re-enters the UNCHANGED strict read path.
+    ///
+    /// Reports `Ok(false)` — touching nothing — when there is nothing to
+    /// recover (no sidecar), when the namespace is not a tombstone-free
+    /// `Current`, or when the bounded exclusive acquisition loses to a LIVE
+    /// holder (a running daemon or a long-lived MCP reader legitimately owns
+    /// those sidecars). Callers must additionally prove the previous RENDEZVOUS
+    /// owner is not alive before calling: the lease excludes concurrent
+    /// cooperating writers, not a live daemon that is merely idle.
+    ///
+    /// A leftover rollback `-journal` is deliberately NOT unlinked here: the
+    /// write-capable open below is what lets SQLite itself replay and retire a
+    /// hot journal, and unlinking one by hand would discard committed pages.
+    /// `-shm` carries no durable content (it is a derived shared-memory index),
+    /// so it is removed once the log is proven folded.
+    pub fn recover_stale_current_sidecars(
+        paths: &IndexPaths,
+        deadline: Instant,
+        cancelled: impl FnMut() -> bool,
+    ) -> Result<bool> {
+        if Self::extraction_status(paths) != ExtractionStatus::Current {
+            return Ok(false);
+        }
+        if artifact_exists(&paths.tombstone())? {
+            return Ok(false);
+        }
+        if first_existing_database_sidecar(paths)?.is_none() {
+            return Ok(false);
+        }
+        let lease = match IndexLease::acquire_exclusive_existing(paths, deadline, cancelled) {
+            Ok(lease) => lease,
+            Err(IndexLeaseError::TimedOut { .. } | IndexLeaseError::Cancelled { .. }) => {
+                return Ok(false);
+            }
+            Err(error) => return Err(StoreError::Lease(error)),
+        };
+        let store = match Self::open_for_write(
+            paths,
+            lease.clone(),
+            StoreWritePurpose::StaleSidecarRecovery,
+        )? {
+            StoreWriteOpen::Current(store) => store,
+            other => {
+                unreachable!("stale sidecar recovery returned unexpected Store open: {other:?}")
+            }
+        };
+        store.finish_current_mutation()?;
+        remove_checkpointed_sidecars(paths, &lease)?;
+        drop(lease);
+        Ok(true)
+    }
+
     /// Explicit fallible completion of ONE state-gated incremental mutation of a
     /// `Current` namespace: fold the write-ahead log back into the main database
     /// file, then close the final SQLite connection (which releases this Store's
@@ -934,6 +1022,55 @@ fn first_existing_database_artifact(paths: &IndexPaths) -> Result<Option<PathBuf
     Ok(None)
 }
 
+/// Remove the `-wal`/`-shm` pair AFTER the log is proven folded into the main
+/// file. A closing SQLite connection normally unlinks both itself, so this is
+/// usually a no-op; it exists so the post-recovery artifact shape is guaranteed
+/// rather than dependent on SQLite's cleanup succeeding.
+///
+/// A `-wal` that still carries bytes is refused instead of deleted: deleting an
+/// un-checkpointed log discards committed transactions.
+fn remove_checkpointed_sidecars(paths: &IndexPaths, lease: &IndexLease) -> Result<()> {
+    let db = paths.current_db();
+    let wal = database_sidecar_path(&db, "-wal");
+    if let Some(remaining) = artifact_len(&wal)?
+        && remaining > 0
+    {
+        return Err(StoreError::WalNotFolded {
+            path: wal,
+            remaining,
+        });
+    }
+    for path in [wal, database_sidecar_path(&db, "-shm")] {
+        lease.validate_exclusive(paths)?;
+        match std::fs::remove_file(&path) {
+            Ok(()) => {}
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(source) => return Err(StoreError::RemoveSidecar { path, source }),
+        }
+    }
+    Ok(())
+}
+
+/// Append SQLite's sidecar suffix to the native database pathname without a
+/// Unicode rendering round-trip, so both Unix byte paths and Windows wide paths
+/// stay lossless.
+fn database_sidecar_path(db: &Path, suffix: &str) -> PathBuf {
+    let mut native = db.as_os_str().to_os_string();
+    native.push(suffix);
+    PathBuf::from(native)
+}
+
+fn artifact_len(path: &Path) -> Result<Option<u64>> {
+    match std::fs::symlink_metadata(path) {
+        Ok(metadata) => Ok(Some(metadata.len())),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(source) => Err(StoreError::InspectArtifact {
+            path: path.to_path_buf(),
+            source,
+        }),
+    }
+}
+
 fn first_existing_database_sidecar(paths: &IndexPaths) -> Result<Option<PathBuf>> {
     let db = paths.current_db();
     for path in [
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 49014fd..752d091 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3393,3 +3393,178 @@ Windows/MSVC runtime is unavailable on this host and nothing about it is claimed
 dependency, version, `Cargo.lock`, schema, node-ID, golden, state-protocol, or
 permanent-index-lifecycle byte changed; `Cargo.lock` remains SHA-256
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+## The killed-daemon sidecar defect — RECOVERY, not relaxation (2026-07-28)
+
+This closes the item the section above left explicitly OPEN: "whether the right answer is
+a sidecar-tolerant startup read, a checkpoint-and-clear on startup, or a narrower
+recovery path is undecided". The answer is checkpoint-and-clear under proven-dead
+ownership. The strict read gate is unchanged.
+
+### Confirmed Red, and a correction to the measured failure rate
+
+The orchestrator recorded 7 PASS / 1 FAIL over 8 locked runs of
+`spawn_detached_daemon_twice_no_stale_deadlock`. That was re-measured on this host before
+any code changed and **did NOT reproduce: 28 of 28 consecutive locked runs passed**
+(`cargo test --locked -p codegraph-rs --test daemon_spawn
+spawn_detached_daemon_twice_no_stale_deadlock -- --exact`, exit 0 each time). Running one
+test by name serializes what the earlier whole-file runs raced, and the residue survives
+only when the SIGKILL lands while a connection is open — so the earlier 3-in-10 and
+1-in-8 figures and this 0-in-28 are all consistent, and the honest statement is that the
+end-to-end test is an UNRELIABLE detector of this defect, not that the defect is absent.
+
+So the defect was instead confirmed DIRECTLY against the production daemon-start path,
+which is deterministic. A real `codegraph init` project was given a genuinely
+un-checkpointed log by a child process that opened the DB, set `wal_autocheckpoint=0`,
+committed one `project_metadata` row, and died without closing SQLite — leaving
+`codegraph.db-wal` at **8272 bytes** and `codegraph.db-shm` at **32768 bytes**. Running the
+real gate over it (`CODEGRAPH_DAEMON_INTERNAL=1 codegraph serve --mcp --path …`) refused
+verbatim:
+
+`Error: running as detached MCP daemon: refusing to start a daemon for …: Current index
+state has an unexpected SQLite sidecar at …/.codegraph-v2/codegraph.db-wal; index state is
+current and its uninitialized tombstone is absent. No daemon pid, socket, or log was
+published. Run `codegraph init` to rebuild.`
+
+That is the same refusal, reproduced 100% of the time, from residue that is a real dead
+writer's rather than a zero-byte placeholder.
+
+### Root cause
+
+`Store::open_for_read`'s `Current` contract requires sidecar-freedom, which is correct as
+a READ contract — the rebuild finalizer checkpoints and closes before publishing
+`Current`, so a reappeared `-wal` means something wrote outside the state protocol. But a
+SIGKILLed daemon's residue is indistinguishable from that at the artifact level, and the
+gate offered no way back: every later start was refused until `codegraph init` rebuilt the
+namespace, discarding the whole index over a recoverable log.
+
+### The fix, and why recovery beat relaxing the read gate
+
+`f691415` relaxed the gate (`open_for_daemon_startup` = read + `allow_live_sidecar`).
+That makes the daemon read a namespace whose main-file bytes are NOT the whole truth: the
+`-wal` may hold committed pages the deserialized main-file image cannot see, so the daemon
+would serve a silently stale graph, and the residue would persist indefinitely. Recovery
+instead makes the artifact shape match the contract, so the daemon reads through the
+identical strict path afterwards and the residue is gone for good.
+
+New `Store::recover_stale_current_sidecars(paths, deadline, cancelled) -> Result<bool>`
+(`crates/codegraph-store/src/connection.rs`):
+
+1. Refuses unless the state is `Current` and the tombstone is ABSENT — checked before any
+   lease, so a tombstoned or non-`Current` namespace is never touched.
+2. Reports `Ok(false)` immediately when no `-wal`/`-shm` exists (nothing to recover).
+3. Acquires the ONE outer EXCLUSIVE lease via the existing
+   `IndexLease::acquire_exclusive_existing`. A timeout or cancellation is `Ok(false)`,
+   not an error: a live holder means startup proceeds to its unchanged verdict.
+4. Opens through `Store::open_for_write` under a NEW narrow purpose
+   `StoreWritePurpose::StaleSidecarRecovery`, which corroborates the full `Current`
+   contract (tombstone, DB presence, exact main-file extraction stamp) and tolerates the
+   sidecars only because their presence is the reason it was called.
+   `StoreWritePurpose::IncrementalSync` was deliberately NOT reused: its semantics are
+   "one incremental sync", including escalation to a full rebuild for
+   `Missing`/`Outdated`/`Building`, none of which this repair may ever do.
+5. Calls the existing `finish_current_mutation` (`wal_checkpoint(TRUNCATE)` then an
+   explicit `close`), then `remove_checkpointed_sidecars`, which REFUSES with the new
+   `StoreError::WalNotFolded` if `-wal` still carries bytes. A non-empty log is never
+   unlinked; `-shm` is removed only after the log is proven folded, because it is derived
+   shared memory with no durable content. A leftover rollback `-journal` is left alone on
+   purpose — the write-capable open is what lets SQLite replay and retire a hot journal,
+   and hand-unlinking one discards committed pages.
+
+CLI side (`crates/codegraph-cli/src/main.rs`), before the UNCHANGED gate:
+
+- `previous_daemon_owner_may_be_live` is a READ-ONLY liveness predicate over the pid
+  record. `clear_stale_daemon_lock` was not reused because it REMOVES the record as a side
+  effect, and that record is the single-instance exclusion `try_acquire_daemon_lock`
+  claims moments later — removing it here would open a double-start window. Fail-closed:
+  a missing record is dead, an unreadable or EMPTY record is treated as LIVE (an empty
+  record is an in-flight `create_new` placeholder, matching the lock layer).
+- `recover_dead_owner_sidecars` runs the repair only when that predicate says dead, and
+  swallows any error to a `warn!`; the authoritative verdict is always the gate's.
+- `STALE_SIDECAR_RECOVERY_TIMEOUT = 500ms`, deliberately far below the 30s
+  `REBUILD_LEASE_TIMEOUT`. This is a best-effort repair on the latency-critical startup
+  path, and the only legitimate reason the exclusive lease is unavailable is that a live
+  cooperating holder owns the namespace — including a long-lived direct-mode MCP reader,
+  which holds a shared lease for its whole server lifetime and therefore blocks exclusive
+  acquisition on its own. In that case there is nothing to recover, so startup must reach
+  its normal verdict in half a second rather than stall for 30.
+- `crates/codegraph-daemon/src/lock.rs` is byte-for-byte untouched (SHA-256
+  `a14583b40c8695318f07552fc9633622fd4356581bec7c5ad16cfe89203814fe`), and nothing here
+  signals or kills any pid.
+
+`grep -rn "open_for_daemon_startup\|open_for_read_with_sidecar_policy" crates/` and
+`grep -rn "a_killed_daemons_live_sidecars" crates/` both return nothing (exit 1):
+`8c66848`'s revert stands, and no sidecar-tolerant READ path exists under any name.
+
+### New tests and the negative control
+
+`crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs`:
+
+- `a_dead_owners_uncheckpointed_wal_is_recovered_on_daemon_startup` re-invokes the test
+  binary as a child that commits a row with `wal_autocheckpoint=0` and then `abort()`s, so
+  the residue is a REAL dead writer's. It asserts the `-wal` is NON-EMPTY before startup
+  and that the probe row is absent from a sidecar-free COPY of the main file, then drives
+  the production `spawn_detached_daemon` path and requires a published rendezvous. After
+  startup it re-reads that main-file-only copy and requires the probe row to be
+  PRESENT — proving the log was folded in, not discarded — and asserts the permanent lock
+  survives and the state is still `Current`.
+- `the_same_stale_residue_under_a_tombstone_is_still_refused` is the paired fail-closed
+  control: identical non-empty residue plus the tombstone still refuses, folds nothing
+  (the `-wal` is still non-empty afterwards), and publishes neither pid nor socket.
+
+Negative control, executed: the single `recover_dead_owner_sidecars` call site was
+disabled and the recovery test went RED on the real refusal text
+(`… unexpected SQLite sidecar at …/codegraph.db-wal`) while the tombstone control stayed
+green — so the test genuinely exercises the production path, not a helper. The call site
+was restored and `crates/codegraph-cli/src/main.rs` re-proved as SHA-256
+`3f745cf88dc30937adacf23341674974009a68861db016707fde1932e1736acf`, the pre-mutation
+hash.
+
+### Verification
+
+`bash scripts/check-workspace-versions.sh` was run before every Cargo batch (exit 0,
+workspace 0.40.4 across all 10 packages) and `--locked` was passed to every Cargo command.
+
+- `spawn_detached_daemon_twice_no_stale_deadlock`: **20 of 20** consecutive locked runs
+  green, zero failures (plus the 28 pre-change runs noted above).
+- `--test daemon_stale_wal_recovery`: 3/3 (both acceptances plus the child-process
+  helper).
+- `cargo clippy --locked --workspace --all-targets -- -D warnings`: exit 0.
+
+**Correction to the previous section's `make ci` statement.** That section said
+`make ci CARGO='cargo --locked'` is NOT reliably green over the reverted bytes, and it was
+right at `8c66848`: the sidecar defect was unfixed and the end-to-end test could hit it.
+That record stands as written for those bytes. Over THESE bytes the cause is removed —
+the daemon now recovers the residue instead of refusing forever — so the final gate's
+measured result is reported in the closeout summary for these exact committed bytes rather
+than inherited from that earlier measurement.
+
+Limitations. Changed-file LSP diagnostics were attempted on
+`crates/codegraph-store/src/connection.rs` and
+`crates/codegraph-cli/tests/daemon_stale_wal_recovery.rs`; both were refused with `LSP
+file path must be inside request cwd` (the worktree at
+`/config/workspace/ProdDir/AI/.cgworktrees/v15-impl` is outside the request cwd), so no
+LSP-clean result is claimed and locked Cargo build/Clippy/tests are the fallback. The new
+test file is `#![cfg(unix)]`: the child-abort WAL plant and the socket handshake are
+Unix-specific. On Windows the recovery itself is portable by inspection — it uses only
+`IndexLease`, SQLite pragmas, and `std::fs::remove_file`, and the sidecar paths are built
+with `OsString::push` so wide paths stay lossless — but native Windows/MSVC runtime is
+unavailable on this host and no Windows runtime claim is made. The remaining gap is that
+`spawn_detached_daemon_twice_no_stale_deadlock` stays a probabilistic detector of this
+defect; the deterministic coverage is the new file.
+
+A SEPARATE pre-existing intermittent failure was found while running the final gate and is
+recorded rather than left implicit: `make ci` failed once on
+`formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+(`crates/codegraph-cli/src/main.rs:6209`, `assertion failed: elv.is_file()`).
+`cargo test --locked -p codegraph-rs --bin codegraph` reproduced it in **2 of 5** runs with
+these changes applied and in **4 of 8** runs with them fully STASHED away, i.e. on the
+untouched `8c66848` tree — so it is pre-existing and unrelated. It is an in-process
+`HOME`/`XDG_DATA_HOME` env race across `#[test]`s in the same binary; nothing here touches
+that code path, and no test was weakened, skipped, slept, or deleted over it. It is a
+known open item, not something this pass introduced or cured.
+
+No dependency, version, `Cargo.lock`,
+schema, node-ID, golden, state-protocol, or permanent-index-lifecycle byte changed;
+`Cargo.lock` remains SHA-256
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.

From 288d89292f73a94e163b63bc36f2746558658200 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 03:26:57 +0800
Subject: [PATCH 41/91] docs(cli): restore the daemon-startup gate doc comment

---
 crates/codegraph-cli/src/main.rs | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 0594c84..00ebca0 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -1163,19 +1163,6 @@ fn cmd_uninit(path: Option<PathBuf>, force: bool) -> Result<()> {
     Ok(())
 }
 
-/// Daemon-startup gate (frozen plan lines 590-592, 603-604).
-///
-/// ONE bounded shared acquisition validates everything: `Store::open_for_read`
-/// acquires the shared `IndexLease` and, under it, corroborates the FULL `Current`
-/// contract — both owner-bound state slots (so `Future`, `Corrupt`, `Building`,
-/// `Uninitialized`, `Outdated`, and an owner mismatch are all refused), tombstone
-/// absence, database presence, sidecar-freedom, and the exact extraction stamp
-/// read from the checkpointed main-file bytes. Slot phase alone would let a
-/// `Current` slot with a deleted database or a stale stamp publish a rendezvous.
-///
-/// The returned `Store` OWNS that same lease, so retaining it across pid/socket
-/// publication requires no second acquisition: there is no nested lock and no
-/// window between validation and publication for another writer to reclassify.
 /// Bounded budget for the ONE exclusive acquisition of the stale-sidecar
 /// recovery attempted before the strict startup read gate.
 ///
@@ -1250,6 +1237,19 @@ fn recover_dead_owner_sidecars(paths: &codegraph_core::IndexPaths, project_root:
     }
 }
 
+/// Daemon-startup gate (frozen plan lines 590-592, 603-604).
+///
+/// ONE bounded shared acquisition validates everything: `Store::open_for_read`
+/// acquires the shared `IndexLease` and, under it, corroborates the FULL `Current`
+/// contract — both owner-bound state slots (so `Future`, `Corrupt`, `Building`,
+/// `Uninitialized`, `Outdated`, and an owner mismatch are all refused), tombstone
+/// absence, database presence, sidecar-freedom, and the exact extraction stamp
+/// read from the checkpointed main-file bytes. Slot phase alone would let a
+/// `Current` slot with a deleted database or a stale stamp publish a rendezvous.
+///
+/// The returned `Store` OWNS that same lease, so retaining it across pid/socket
+/// publication requires no second acquisition: there is no nested lock and no
+/// window between validation and publication for another writer to reclassify.
 fn authorize_daemon_startup(project_root: &Path) -> Result<codegraph_daemon::StartupAuthorization> {
     let paths = index_paths(project_root)?;
     recover_dead_owner_sidecars(&paths, project_root);

From 1839504b9d3f79f30aaef6865e85a534b00f95d3 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 04:36:30 +0800
Subject: [PATCH 42/91] fix(cpp): resolve explicit operator calls to the
 operator method

---
 .../fixtures/cpp/operators.cpp                |  22 ++
 crates/codegraph-extract/src/lang/cpp.rs      |  85 ++++++++
 crates/codegraph-extract/src/lang/mod.rs      |   5 +-
 crates/codegraph-extract/src/walker.rs        | 127 +++++++++++
 crates/codegraph-resolve/src/name_matcher.rs  | 115 ++++++++++
 docs/equivalence.md                           |  16 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 110 ++++++++++
 reference/golden/cpp/colby.db                 | Bin 151552 -> 167936 bytes
 reference/golden/cpp/edges.json               | 120 +++++++++++
 reference/golden/cpp/files.json               |   8 +
 reference/golden/cpp/nodes.json               | 198 ++++++++++++++++++
 11 files changed, 803 insertions(+), 3 deletions(-)
 create mode 100644 crates/codegraph-bench/fixtures/cpp/operators.cpp

diff --git a/crates/codegraph-bench/fixtures/cpp/operators.cpp b/crates/codegraph-bench/fixtures/cpp/operators.cpp
new file mode 100644
index 0000000..0dde49f
--- /dev/null
+++ b/crates/codegraph-bench/fixtures/cpp/operators.cpp
@@ -0,0 +1,22 @@
+struct Vec2 {
+    int x;
+    Vec2 operator+(const Vec2& o) const { return Vec2{x + o.x}; }
+    Vec2 operator[](int i) const { return Vec2{x + i}; }
+    int get() const { return x; }
+};
+
+Vec2 explicit_operator_call(const Vec2& a, const Vec2& b) {
+    return a.operator+(b);
+}
+
+Vec2 explicit_subscript_call(const Vec2& a) {
+    return a.operator[](3);
+}
+
+Vec2 explicit_pointer_operator_call(const Vec2* p, const Vec2& b) {
+    return p->operator+(b);
+}
+
+int plain_member_call(const Vec2& a) {
+    return a.get();
+}
diff --git a/crates/codegraph-extract/src/lang/cpp.rs b/crates/codegraph-extract/src/lang/cpp.rs
index 2f9f95a..c10ed18 100644
--- a/crates/codegraph-extract/src/lang/cpp.rs
+++ b/crates/codegraph-extract/src/lang/cpp.rs
@@ -479,6 +479,91 @@ fn recover_cpp_macro_defined_name(node: Node<'_>, source: &str) -> Option<String
     Some(name)
 }
 
+/// What an explicit-operator `call_expression` should contribute as a `Calls`
+/// ref (#1268).
+pub(crate) enum ExplicitOperatorCall {
+    /// Emit this callee name (`a.operator+`, or the bare `operator+` for
+    /// `this->`).
+    Callee(String),
+    /// A receiver that cannot aid type inference (`w.obj()->operator+`): emit
+    /// NOTHING. A bare operator name would fall through to exact-name matching,
+    /// which guesses among unrelated same-named operators — a silent miss is
+    /// preferable to a wrong edge.
+    Drop,
+}
+
+/// Recover the callee of a C++ explicit operator call (`a.operator+(b)`,
+/// `p->operator+(b)`, `a.operator[](3)`) — upstream #1268.
+///
+/// tree-sitter-cpp cannot parse an `operator_name` in field position, so the
+/// `call_expression` carries `function: <receiver>` plus an ERROR child wrapping
+/// the `operator_name` instead of a `field_expression` callee. Reading the
+/// `function` field alone yields just the receiver (`a`), an unresolvable ref.
+///
+/// `None` means "not this shape" — the caller continues down the normal call
+/// path (which still owns `V::operator+(a, b)` and the `a.operator bool()` word
+/// form, both of which parse without a stranded `operator_name`).
+pub(crate) fn recover_explicit_operator_call(
+    node: Node<'_>,
+    source: &str,
+) -> Option<ExplicitOperatorCall> {
+    let operator_name = node
+        .named_children(&mut node.walk())
+        .filter(|child| child.kind() == "ERROR")
+        .find_map(|error| {
+            error
+                .named_children(&mut error.walk())
+                .find(|c| c.kind() == "operator_name")
+        })
+        .map(|op| compact_operator_name(&node_text(op, source)))?;
+    let func = child_by_field(node, "function").or_else(|| node.named_child(0))?;
+    let receiver: String = node_text(func, source)
+        .replace("->", ".")
+        .chars()
+        .filter(|c| !c.is_whitespace())
+        .collect();
+    if receiver == "this" {
+        return Some(ExplicitOperatorCall::Callee(operator_name));
+    }
+    if !is_simple_receiver_chain(&receiver) {
+        return Some(ExplicitOperatorCall::Drop);
+    }
+    Some(ExplicitOperatorCall::Callee(format!(
+        "{receiver}.{operator_name}"
+    )))
+}
+
+/// Call sites may space a symbolic operator name (`it.operator * ()`,
+/// `other.operator < (*this)` in nlohmann/json) while the definition indexes
+/// compact (`operator*`). Squeeze the whitespace out of the SYMBOLIC forms only
+/// — the word forms (`operator new`, `operator bool`) need their space.
+fn compact_operator_name(raw: &str) -> String {
+    let trimmed = raw.trim();
+    let Some(symbol) = trimmed.strip_prefix("operator") else {
+        return trimmed.to_string();
+    };
+    let symbol = symbol.trim();
+    let symbolic = symbol
+        .chars()
+        .next()
+        .is_some_and(|c| !c.is_alphanumeric() && c != '_');
+    if !symbolic {
+        return trimmed.to_string();
+    }
+    let squeezed: String = symbol.chars().filter(|c| !c.is_whitespace()).collect();
+    format!("operator{squeezed}")
+}
+
+/// `^[A-Za-z_][\w.]*$` — an identifier or plain member chain, the only receiver
+/// shapes downstream receiver-type inference can work with.
+fn is_simple_receiver_chain(receiver: &str) -> bool {
+    let mut chars = receiver.chars();
+    chars
+        .next()
+        .is_some_and(|c| c == '_' || c.is_ascii_alphabetic())
+        && chars.all(|c| c == '_' || c == '.' || c.is_ascii_alphanumeric())
+}
+
 fn declarator_qualified_id<'tree>(declarator: Node<'tree>) -> Option<Node<'tree>> {
     let mut queue = vec![declarator];
     while let Some(current) = queue.pop() {
diff --git a/crates/codegraph-extract/src/lang/mod.rs b/crates/codegraph-extract/src/lang/mod.rs
index ade65d1..d162557 100644
--- a/crates/codegraph-extract/src/lang/mod.rs
+++ b/crates/codegraph-extract/src/lang/mod.rs
@@ -44,7 +44,10 @@ pub(crate) use cfml::{
     cfml_component_name_from_path, cfml_string_attr_value, cfml_tag_attr, is_bare_script_cfml,
 };
 pub use cpp::CPP_SPEC;
-pub(crate) use cpp::{ExportMacroClass, detect_export_macro_class};
+pub(crate) use cpp::{
+    ExplicitOperatorCall, ExportMacroClass, detect_export_macro_class,
+    recover_explicit_operator_call,
+};
 pub use csharp::CSHARP_SPEC;
 pub use dart::DART_SPEC;
 pub use erlang::ERLANG_SPEC;
diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 2ea0795..1ff0fa8 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -2893,6 +2893,16 @@ impl<'a, 'tree> TreeSitterWalker<'a, 'tree> {
                 }
             }
         }
+        if self.spec.language() == Language::Cpp {
+            match crate::lang::recover_explicit_operator_call(node, self.source) {
+                Some(crate::lang::ExplicitOperatorCall::Callee(callee)) => {
+                    self.push_ref(&caller_id, &callee, EdgeKind::Calls, node);
+                    return;
+                }
+                Some(crate::lang::ExplicitOperatorCall::Drop) => return,
+                None => {}
+            }
+        }
         let mut callee_name = String::new();
         let func = child_by_field(node, "function").or_else(|| node.named_child(0));
         if let Some(func) = func {
@@ -5921,6 +5931,123 @@ void caller() { operator<<(a, b); }
         );
     }
 
+    // ---- Batch B1: C++ explicit operator calls (upstream 6103f5e / #1268) ----
+
+    const CPP_OP_HEADER: &str = concat!(
+        "struct V {\n",
+        "  V operator+(const V& o) const;\n",
+        "  V operator[](int i) const;\n",
+        "  V operator()(int i) const;\n",
+        "  bool operator==(const V& o) const;\n",
+        "  int get() const;\n",
+        "};\n"
+    );
+
+    fn cpp_call_refs(body: &str) -> Vec<String> {
+        let src = format!("{CPP_OP_HEADER}{body}");
+        let (_, refs) = run("op.cpp", &src, Language::Cpp);
+        refs.iter()
+            .filter(|r| r.reference_kind == EdgeKind::Calls)
+            .map(|r| r.reference_name.clone())
+            .collect()
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_recovers_receiver_operator() {
+        let refs = cpp_call_refs("V f(const V& a, const V& b) { return a.operator+(b); }\n");
+        assert!(
+            refs.iter().any(|r| r == "a.operator+"),
+            "explicit `a.operator+(b)` should emit a `a.operator+` Calls ref, got: {refs:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_normalizes_arrow_receiver() {
+        let refs = cpp_call_refs("V f(const V* p, const V& b) { return p->operator+(b); }\n");
+        assert!(
+            refs.iter().any(|r| r == "p.operator+"),
+            "`p->operator+(b)` should normalize to `p.operator+`, got: {refs:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_covers_symbolic_forms() {
+        let refs = cpp_call_refs(concat!(
+            "V f1(const V& a) { return a.operator[](3); }\n",
+            "V f2(V& a) { return a.operator()(1); }\n",
+            "bool f3(const V& a, const V& b) { return a.operator==(b); }\n"
+        ));
+        for want in ["a.operator[]", "a.operator()", "a.operator=="] {
+            assert!(
+                refs.iter().any(|r| r == want),
+                "missing `{want}` among explicit operator refs: {refs:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_compacts_spaced_names() {
+        let refs = cpp_call_refs(concat!(
+            "bool f(const V& a, const V& b) { return a.operator == (b); }\n",
+            "V g(const V& a) { return a.operator [] (3); }\n"
+        ));
+        for want in ["a.operator==", "a.operator[]"] {
+            assert!(
+                refs.iter().any(|r| r == want),
+                "spaced call-site operator should compact to `{want}`, got: {refs:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_drops_complex_receiver() {
+        let refs = cpp_call_refs(concat!(
+            "struct W { V* obj(); };\n",
+            "V f(W& w, const V& b) { return w.obj()->operator+(b); }\n"
+        ));
+        assert!(
+            !refs.iter().any(|r| r.contains("operator+")),
+            "a call-result receiver must not emit a guessable operator ref, got: {refs:?}"
+        );
+        assert!(
+            refs.iter().any(|r| r == "w.obj"),
+            "the inner `w.obj()` call must still ref normally, got: {refs:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_explicit_operator_call_this_receiver_is_bare() {
+        let src = concat!(
+            "struct V {\n",
+            "  V operator+(const V& o) const;\n",
+            "  V twice() const { return this->operator+(*this); }\n",
+            "};\n"
+        );
+        let (_, refs) = run("op.cpp", src, Language::Cpp);
+        let calls: Vec<&str> = refs
+            .iter()
+            .filter(|r| r.reference_kind == EdgeKind::Calls)
+            .map(|r| r.reference_name.as_str())
+            .collect();
+        assert!(
+            calls.contains(&"operator+"),
+            "`this->operator+(...)` should emit the bare `operator+`, got: {calls:?}"
+        );
+        assert!(
+            !calls.iter().any(|r| r.contains("this")),
+            "no `this` receiver should leak into the ref name, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_plain_member_call_unaffected_by_operator_recovery() {
+        let refs = cpp_call_refs("int f(const V& a) { return a.get(); }\n");
+        assert!(
+            refs.iter().any(|r| r == "a.get"),
+            "plain member call must stay `a.get`, got: {refs:?}"
+        );
+    }
+
     #[test]
     fn cpp_ue_reflected_class_recovered() {
         let src = r#"
diff --git a/crates/codegraph-resolve/src/name_matcher.rs b/crates/codegraph-resolve/src/name_matcher.rs
index 5d348ad..861cc0d 100644
--- a/crates/codegraph-resolve/src/name_matcher.rs
+++ b/crates/codegraph-resolve/src/name_matcher.rs
@@ -1342,6 +1342,11 @@ fn parse_method_call(name: &str, language: Language) -> Option<(String, String)>
     if let Some(captures) = match_dot_call(name) {
         return Some(captures);
     }
+    if matches!(language, Language::C | Language::Cpp) {
+        if let Some(captures) = match_cpp_operator_dot_call(name) {
+            return Some(captures);
+        }
+    }
     if let Some(captures) = match_colon_call(name) {
         return Some(captures);
     }
@@ -1366,6 +1371,11 @@ fn is_inferable_receiver_call(name: &str, language: Language) -> bool {
     if match_dot_call(name).is_some() {
         return true;
     }
+    if matches!(language, Language::C | Language::Cpp)
+        && match_cpp_operator_dot_call(name).is_some()
+    {
+        return true;
+    }
     if matches!(language, Language::Lua | Language::Luau) && match_lua_colon_call(name).is_some() {
         return true;
     }
@@ -1442,6 +1452,37 @@ fn match_dot_call(name: &str) -> Option<(String, String)> {
     Some((receiver.to_string(), method.to_string()))
 }
 
+/// Matches `/^([\w.]+)\.(operator[^\w\s.]+)$/` — a C++ explicit operator call
+/// (`a.operator+`, `it.operator[]`) reaching the resolver from the extraction
+/// recovery (#1268). The operator's symbol chars fail `match_dot_call`'s
+/// selector-like method part, so they are admitted here instead. At least one
+/// non-word char after `operator` is required, so `a.operatorTable` stays on the
+/// plain dotted pattern (tried first); every downstream strategy compares the
+/// method part by exact string equality, so a stray match cannot invent an edge.
+fn match_cpp_operator_dot_call(name: &str) -> Option<(String, String)> {
+    let idx = name.rfind(".operator")?;
+    if idx == 0 {
+        return None;
+    }
+    let receiver = &name[..idx];
+    let method = &name[idx + 1..];
+    if !receiver
+        .chars()
+        .all(|c| c.is_alphanumeric() || c == '_' || c == '.')
+    {
+        return None;
+    }
+    let symbol = method.strip_prefix("operator")?;
+    if symbol.is_empty()
+        || !symbol
+            .chars()
+            .all(|c| !c.is_alphanumeric() && c != '_' && c != '.' && !c.is_whitespace())
+    {
+        return None;
+    }
+    Some((receiver.to_string(), method.to_string()))
+}
+
 /// Matches `/^(\w+)::(\w+)$/` (name-matcher.ts:771).
 fn match_colon_call(name: &str) -> Option<(String, String)> {
     let idx = name.find("::")?;
@@ -3950,6 +3991,80 @@ mod tests {
         assert_eq!(res.resolved_by, ResolvedBy::InstanceMethod);
     }
 
+    #[test]
+    fn cpp_explicit_operator_call_resolves_via_receiver_type() {
+        // `const V& a; a.operator+(b)` reaches the resolver as `a.operator+`
+        // (#1268). `Aaa` declares the SAME operator and sorts first, so only
+        // receiver-type inference can pick `V`.
+        let v_op = mk(
+            "method:v_plus",
+            NodeKind::Method,
+            "operator+",
+            "V::operator+",
+            "src/optest.cpp",
+            Language::Cpp,
+        );
+        let decoy = mk(
+            "method:aaa_plus",
+            NodeKind::Method,
+            "operator+",
+            "Aaa::operator+",
+            "src/optest.cpp",
+            Language::Cpp,
+        );
+        let ctx = Ctx::default()
+            .file(
+                "src/optest.cpp",
+                "struct Aaa { Aaa operator+(const Aaa& o) const; };\nstruct V { V operator+(const V& o) const; };\nV add(const V& a, const V& b) { return a.operator+(b); }\n",
+            )
+            .name("operator+", vec![decoy, v_op]);
+        let r = refv(
+            "a.operator+",
+            EdgeKind::Calls,
+            "src/optest.cpp",
+            Language::Cpp,
+            3,
+        );
+        let res = match_method_call(&r, &ctx).expect("explicit operator call resolves");
+        assert_eq!(
+            res.target_node_id, "method:v_plus",
+            "receiver type V must win over the same-named Aaa::operator+"
+        );
+        assert_eq!(res.resolved_by, ResolvedBy::InstanceMethod);
+    }
+
+    #[test]
+    fn cpp_operator_dot_shape_is_a_method_call_shape() {
+        assert_eq!(
+            parse_method_call("a.operator+", Language::Cpp),
+            Some(("a".to_string(), "operator+".to_string()))
+        );
+        assert_eq!(
+            parse_method_call("it.operator[]", Language::Cpp),
+            Some(("it".to_string(), "operator[]".to_string()))
+        );
+        // Word-shaped names keep the plain dotted pattern.
+        assert_eq!(
+            parse_method_call("a.operatorTable", Language::Cpp),
+            Some(("a".to_string(), "operatorTable".to_string()))
+        );
+        // The symbolic form is C/C++-only.
+        assert_eq!(parse_method_call("a.operator+", Language::TypeScript), None);
+        // `operator` with no trailing symbol is NOT the operator shape; it stays
+        // an ordinary dotted call (handled by the plain pattern, tried first).
+        assert_eq!(match_cpp_operator_dot_call("a.operator"), None);
+        assert_eq!(
+            parse_method_call("a.operator", Language::Cpp),
+            Some(("a".to_string(), "operator".to_string()))
+        );
+        // A dotted receiver chain is accepted; a bare `.operator+` is not.
+        assert_eq!(
+            match_cpp_operator_dot_call("w.inner.operator=="),
+            Some(("w.inner".to_string(), "operator==".to_string()))
+        );
+        assert_eq!(match_cpp_operator_dot_call(".operator+"), None);
+    }
+
     #[test]
     fn cpp_receiver_auto_new_initializer() {
         // `auto f = new Foo();\n f.v()` — infer type from the `new Foo` initializer.
diff --git a/docs/equivalence.md b/docs/equivalence.md
index b929fd9..8b67d53 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -281,9 +281,21 @@ UObject` plus line-leading `GENERATED_BODY()`/`UPROPERTY(...)`/`UFUNCTION()`,
   reclassifies the `.h` to C++, and the offset-preserving pre-parse blanking
   recovers the `UFoo` class + its `Extends UObject` clause (both dropped before).
 
+A further file exercises the Batch B explicit-operator gain (upstream #1268):
+
+- **explicit operator calls** — `operators.cpp` defines `struct Vec2` with
+  `operator+` / `operator[]` / a plain `get`, then calls each through the
+  EXPLICIT syntax (`a.operator+(b)`, `a.operator[](3)`, `p->operator+(b)`) plus
+  one plain `a.get()` control. tree-sitter-cpp strands the `operator_name` in an
+  ERROR child, so before the fix the extractor emitted the bare receiver (`a`)
+  and no edge existed; the golden now carries four `Calls` edges resolved by
+  `instance-method` at confidence 0.9 (`Vec2::operator+` twice,
+  `Vec2::operator[]`, `Vec2::get`).
+
 The minimal source corpus lives at `crates/codegraph-bench/fixtures/cpp/`
-(`base.hpp`, `derived.cpp`, `namespaced.cpp`, `templated_call.cpp`,
-`ue_actor.h`). The inheritance base classes live in a `.hpp` file (not `.h`,
+(`base.hpp`, `derived.cpp`, `namespaced.cpp`, `operators.cpp`,
+`templated_call.cpp`, `ue_actor.h`). The inheritance base classes live in a
+`.hpp` file (not `.h`,
 which maps to `Language::C` by extension); `ue_actor.h` deliberately uses `.h` to
 guard the content-based C++ reclassification.
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 752d091..a6f1605 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3568,3 +3568,113 @@ No dependency, version, `Cargo.lock`,
 schema, node-ID, golden, state-protocol, or permanent-index-lifecycle byte changed;
 `Cargo.lock` remains SHA-256
 `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+## Batch B1 — C++ explicit operator calls resolve to the operator method (2026-07-28)
+
+Ports upstream `6103f5e` (`fix(cpp): resolve explicit operator calls
+(a.operator+(b)) to the operator method`, upstream #1268 / issue #1247). Behavior
+only — the TypeScript regex/AST shapes were re-derived against
+`tree-sitter-cpp 0.23.4` in this workspace, not transliterated.
+
+### Red (documented, with the actual wrong output)
+
+Five new `#[test]`s in `crates/codegraph-extract/src/walker.rs` drive the REAL
+extraction path (`extract_source` → `Walker::extract_call`) and failed on the
+pre-change bytes. `cargo test --locked -p codegraph-extract --lib
+cpp_explicit_operator` → **5 failed, 1 passed** with these observed values:
+
+| assertion                                                 | expected              | ACTUAL on pre-change bytes |
+| --------------------------------------------------------- | --------------------- | -------------------------- |
+| `a.operator+(b)`                                          | ref `a.operator+`     | `["a"]`                    |
+| `p->operator+(b)`                                         | ref `p.operator+`     | `["p"]`                    |
+| `a.operator[](3)` / `a.operator()(1)` / `a.operator==(b)` | 3 operator refs       | `["a", "a", "a"]`          |
+| `a.operator == (b)` / `a.operator [] (3)` (spaced)        | compact operator refs | `["a", "a"]`               |
+| `this->operator+(*this)`                                  | bare ref `operator+`  | `["this"]`                 |
+
+The bare receiver name is exactly upstream's reported defect: the callee is read
+from the `function` field, but tree-sitter-cpp cannot parse an `operator_name` in
+field position, so the `operator_name` is stranded in an ERROR sibling and the
+`function` field holds only the receiver. `cpp_explicit_operator_call_drops_complex_receiver`
+passed pre-change for the WRONG reason (no operator ref existed at all), so it is
+a guard, not a Red.
+
+Two resolver `#[test]`s in `crates/codegraph-resolve/src/name_matcher.rs` were the
+second Red: `cpp_operator_dot_shape_is_a_method_call_shape` failed with
+`parse_method_call("a.operator+", Cpp)` returning **`None`** (expected
+`Some(("a","operator+"))`) — the operator's symbol chars fail `match_dot_call`'s
+selector-like method part — and
+`cpp_explicit_operator_call_resolves_via_receiver_type` failed at
+`.expect("explicit operator call resolves")`, i.e. `match_method_call` returned
+`None` even with the recovered name.
+
+### Green (minimal)
+
+- `crates/codegraph-extract/src/lang/cpp.rs`: new
+  `recover_explicit_operator_call` returning `ExplicitOperatorCall::{Callee,Drop}`.
+  It finds an `operator_name` inside an ERROR child of the `call_expression`,
+  compacts a spaced SYMBOLIC name (`operator ==` → `operator==`, word forms like
+  `operator new` keep their space), normalizes `->` to `.`, emits the bare
+  operator name for a `this` receiver, and returns `Drop` for a receiver that is
+  not a simple identifier/member chain (`w.obj()->operator+`) so exact-name
+  matching cannot guess among unrelated same-named operators.
+- `crates/codegraph-extract/src/walker.rs`: `extract_call` consults it first, for
+  `Language::Cpp` only.
+- `crates/codegraph-resolve/src/name_matcher.rs`: new
+  `match_cpp_operator_dot_call` admitted by `parse_method_call` and
+  `is_inferable_receiver_call` for `Language::{C,Cpp}` AFTER the plain dotted
+  pattern, so `a.operatorTable` is unaffected and `a.operator` (no symbol) stays
+  an ordinary dotted call.
+
+### Golden row delta (`reference/golden/cpp/`, additions only)
+
+New fixture `crates/codegraph-bench/fixtures/cpp/operators.cpp` (struct `Vec2`
+with `operator+`/`operator[]`/`get`, three explicit-operator call sites, one
+plain-member control). `git diff --numstat reference/golden/` showed ONLY `cpp/`
+paths: `files.json +8/-0`, `nodes.json +198/-0`, `edges.json +120/-0`,
+`colby.db` binary; `refs.json` and `schema.sql` byte-identical. Deleted-line
+count across the three JSON files: **0** — every pre-existing declaration keeps
+its node ID and row.
+
+Added rows: 9 `operators.cpp` nodes (file, `struct Vec2`, methods
+`Vec2::operator+` @3 / `Vec2::operator[]` @4 / `Vec2::get` @5, functions
+`explicit_operator_call` @8 / `explicit_subscript_call` @12 /
+`explicit_pointer_operator_call` @16 / `plain_member_call` @20) and 4 `Calls`
+edges, all `resolvedBy=instance-method` at confidence 0.9:
+`explicit_operator_call → Vec2::operator+`,
+`explicit_pointer_operator_call → Vec2::operator+`,
+`explicit_subscript_call → Vec2::operator[]`, and the control
+`plain_member_call → Vec2::get`. Before this change the three operator call sites
+produced an unresolved `a`/`p` ref and NO edge.
+
+Recipe fidelity: `docs/equivalence.md` says `cp
+/tmp/cg-fixture-cpp/.codegraph/codegraph.db`, but Batch M moved the index to the
+isolated v2 namespace, so the database is actually written to
+`/tmp/cg-fixture-cpp/.codegraph-v2/codegraph.db`. That path substitution is the
+ONLY deviation, and it was proven inert: re-running the documented recipe over
+the five PRE-EXISTING fixture files alone regenerated `nodes.json`, `edges.json`,
+`refs.json`, `files.json` and `schema.sql` byte-identical to the committed golden
+(`cmp -s` on all five → IDENTICAL) before `operators.cpp` was added.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0 (workspace 0.40.4, 10
+  packages), run before every Cargo batch; every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-extract --lib cpp_` → exit 0, **56 passed, 0
+  failed** (includes the 5 new Reds now green plus the pre-existing
+  `cpp_operator_lt_call_not_stripped`, `cpp_template_arg_call_strips_to_base`,
+  `strip_cpp_template_args_cases`, UE/export-macro and namespace tests).
+- `cargo test --locked -p codegraph-resolve --lib -- cpp_explicit_operator
+cpp_operator_dot` → exit 0, **2 passed**.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26
+  passed, 0 failed**, including `generated_golden_matches_committed_cpp_fixture`
+  and `cpp_db_is_self_equivalent_to_cpp_golden`, and every non-cpp oracle
+  (`godot`, `ruby`, `mini`, `metal`, `cuda`, `arkts`, `solidity`, `nix`,
+  `terraform`, `erlang`, `cfml`).
+- `git diff --stat reference/golden/` → only `cpp/` paths; godot, ruby and the
+  original upstream corpus unchanged.
+
+`lsp_diagnostics` was NOT usable here: it has consistently refused this worktree
+with `LSP file path must be inside request cwd` (the worktree at
+`/config/workspace/ProdDir/AI/.cgworktrees/v15-impl` is outside the request cwd),
+so locked Cargo build/Clippy/test is the honest fallback and no LSP-clean result
+is claimed. No dependency, version or `Cargo.lock` byte changed.
diff --git a/reference/golden/cpp/colby.db b/reference/golden/cpp/colby.db
index a509717a0fdc5b859ff84b3f65b99d30e5dbcbbe..c36acfe1bd7b633bd5972ef611a3ddef49ef84e9 100644
GIT binary patch
delta 16135
zcmeG@33MFQk^Q@Sj-H<WUxy{@m{Xe3=+=zpkj5uRh&gNy-->MH(HvMomV^!x;|+s0
zU<{5iPH)m?V+_uQO~?gC0h5Ga6LJ8X5R>c%a1sK6BpV<c3nV0jDD``$TQeHjqmb;r
zmwndQ{qL&!)m8QXuljw>?ZP#;TW)ruro*mh2-{$m&n!vE7nhvrFfa_m(+AQYYSBoG
z#;J!&mXdp14-o#2<(_i+SVz0-j^%a!^M(e-2V#S+vG~^HwwOAQyaW9i4|zw%{<eh=
z8<PBM{C0i;w~PHFdntMjjRXAM`wm6f4}0ZDLfcKA%07E-Z9qN{saC$W3%TUUa0jZF
z4~H)|@2G>ejt-yvc&H}b)zzQuj)fzs&Tz0Z>hB5#gWZu-G#KpcPV{%jQWHb*@qyu?
zk-^x&P~W!Xw*KU3UpzKASWq!Mk{peV508$u$45rs--61?YBwM{?>t{QLS_M|H^U#p
zRG2lOi#mhpK)k;*+SMNog`&x*Kavb~rxKA!vMcHjhWtAE<cCKF2jT<ceIvsIL*qb#
zhE1jA)U8@qjj)ok^~reWr04?T7N-}VoVxyKFwz<F2cnT=BGwt`OvYoWNFW^V4){}@
zozYHh8an#1iT<(p=)lN$K2`bE`Q)TWMyyz+M{oi?(dfy^35TMwq`w=u73oTb!|_D2
zE0G8%V~J=q9_dO13dqqg<x`VaJDi^N*31@4Ox#h~TV3v?v>>FvIL5p!Ilgr`u_zGg
z>Pq!@b@%%tsd%b89E$}y{mEp1D$pNHq!Qswx66{_6xO0ekkOE8@4#T--4k{|l6JSv
z!cw7QN%=z&m|QB}8A|!%-QB@NIFa&qC&H;f!k-9buxOBbH)oK|l(n3Oljr$v+GorL
zc%3a7v}t{II^J+F80++hyF!U*XFMMCM`PW=&QK`O9}jkQCi>&~cw6$(w#>%Lar~LI
z%cfeuT2bLE7jkuhxyU>=J~|N}Uli+##)Hvlpeq%Pc6TL0!OpNh6;F2cCz6rwkUyO1
zMj_Gvv#}UA)Kms4d_JE%8LC*4*P0p_Oy*UbyZ~CeaLN|>xzGz-@p&!uDLlepA3iE=
zmyVNfk!`{w*2hRCc@<x6-6{Us5*OaEd`T26Ve!uvlO=6!wfqFHwthhD664Y;aj*0l
z{31D%?6)4ovh^+L9my?z9ZcS+pq&38YOeN`b1jI{w`d~S7mI`OXy4k<#`Ph2%f=>y
zm*$kiyHHcwQ_C&RbR17^1Isg>OsGOlO-()Rrpf-IXc2o>m)E;9cxv<G&h$=aY~Z3|
z2EmmFyqLZ^Tew~{FO5nk!j9a|MHIuH)3=x~+i2fnB3P4^!P-hLka-Qd3{Cyv0uzsO
zR;VVrLS5|h?KgLser%dB`HW8+cN>=)UNk6%i}>I31KdxzRqRpLj}D@<nZx@It>Y$1
zv)sGpX4E9Vyrvg5%IB`#hkWvhwKt&#d0^ch<b`KgZe71o@CZy#Pwiz0$${H^%986*
zo7}ao4Vz0R#d@uYktY|oD7Re?fQC2tQJsAIh7HIqzrA4vEP`ijT#cOYY?2??*qC1F
z5ST!p9mJebrBI(0m8*G+RD5`792Up1mG=2S%MrQsoJ*b#&Nd%##Y9qvR$B-ytuNR5
zT#L!92ClD0V0wF1&J`1$tnADo=;^uE4jn`Fd&N*hJ9Gq9>Gz1Cm`-UJ&R+;T&oHS_
zynt<<`PlubpKf%TsD3pz-?QaS;vxd#7NTV0vgBBY1l2}qCqw>~1n_rouk^CClbTnF
zO&H}jKGGxIvAq5*bQ^3fYuIfDx##Nsv|dxi4e%D<q*Trt42a2-{74`c?*_r@@A5}O
z34a9kg8pDvG!PC1Q^8;~6z@uPMUtJ-XfPJ`C%VG@(NuR5mdJ1@5s$}H5l|i$QM6g)
zRl)#gX#!NpAphX%4VIY(*`MyqE#8ve<eX_0=mKOUw=m>Q@&b8+93`J4w@j6~t|PMj
z8H|kbu?H)$p_KC>oqYLwd&6Gw6ATj1VZ?Jz^#eXRMd?B!GCj4mu*q?kGjhqs2Kh$^
zoEHA_zS@OQ7busXSlz5#{0cJ3ZMQnod|BT@TJI}obd4#t;KbTt`$IR(V-=!KW_F9r
zFx;`e`q>b3EJVJ6NM|?2BkdZX78P*mT!6Rsd1nJIW-DSk+}_P9U@0H)T6nQQGASgv
znAw<toS|5l0X%iqt>0u<`*06KULjAz7UM3mlUzYIfkgL^x5=l79lwfq;y5wjxAA@W
zPJ96G#oO^9xtWxa=gH&btK>6e2T74j$YRofpT>{lhspc#3-Eq9oEAV=;)AiVF`t>M
zP?xR-D`(fY3*Ov<N9$6bTU(b~aOW0Wxdo?%tIjUwj+tzweI{?C*^IHAdgaTNXthr|
z!H}28N^%dG0O_tL5z<c%Nhk0FAn!Zy@5oQc64*X%CA;uH;iY&BR>+-%!(Ya?;csIf
zIfi*siJz4IhcuCOxI}uM?1wpDE6Eo<Zf^Hs&W&<5Ra8kvCx-g;?UPsJYSGB(a6CCS
z=Anv|uCL%aP{FCLu8uno=?9!SPhW1jIn%r3A9h?dTy&;Q6I*rf<}`8T2z0|iNgW<(
z%bXs2H`^u7sVj7gjlLAR<E_op^Qj*`*oiowv`01_bGJ)-@FYGTZ^IjbbL;U@62~3V
zYq%VLk6cH_@Ll*u>4bCyACT^l9+o}{T<ZGA;S%KroxggFax7oKwPlMMGl64t8=dK+
zRi2b@%H!K8-*(8R<DuFiyb0LWjT`U+%u26G&q&{u?v`$mZj^Qale`i&vn8`di3$sB
z$>=jHIC*b|nzp)v8h1gBtDweNP~#}5u@}_X3Wv=Sl^xIA08_?~%BE+RmJxv<{0ICx
z{tbQ(jKvf9QJCo%K9>q3Q0~j74cXM2O+DGPKAYBMQ+GCXWmBhI`sy3N--v8_EmV63
zZo}2sAiXaAOnOwhS2`r!AdN^Hq!m&Gus&;*|NGsNw2$y^Ay-$c_y9t>qUz@y-g}Y;
z*0Ycg2y=|6FXw$oS0(iryr6D&9XKFL+_NjeDd8%tGdm0G435G&-d<S8*~)mIkWWl4
zt+LG2O<nls`*gFYnZT8*5u_$^PD4nZ$eP0XtTBv$Iqatf5lrdxsxi%&#RxSd6RF|h
z+44*!>L1rMURhuokNgm$4%BA3i4nPj40%iZJ{iD|;3d+3N?WW?TZhHBxr6yX{zZ_+
z5w2{{)??SeAL5x$t%Z%(=iPoeaG_hVSD>bIi+Fq-EXO*FY`pC($2pW^JCVas!g6pJ
zOGjOXQkqi&mm`;<jKYx5-0VDGq?N^X**4m}h)c|=?5;o;Du*9LPD3^AuN=A_IhD67
z(8>nZS;XT~s}5Lp9gM9~>3#iHmtlcQ<f@BY%4L<P6<L)VD$x=PMu<hMI+f?_sD3HS
z!G_OiMTkc%&+>Ew!sh((TApT%!`ntC#*<ah8(?spNqN2!xh+=ABg8=kul%VJ*@5bJ
zZKzJET8KWt0-Mk(R|Sw_%KAkqE=mD#^-G&vK?#~T@T)+Lz_L~rh+tV$)|FcY-2g2-
zIlBC2@hYEQh#Gv>vJ6th^T;@`ZDe?KTvP$D#-aG&L?S5~5zktcpDsj^G>c)I4<z!1
z8Iy{G5@Z>QZA*@g#Nx?BCFZhx0-SVeEE+Q#X(#$1YR;^!V74q>D4Vj`F#;N^$-q$@
zRmgV66$>&QSfsxM4%E3?t3_jFT2|}88dR5CnaUicy9)Wzsv2qibdprM5dWdk*ocs6
z<aw{x<Ee*-_VYk4?5Xrhj*?2}0#7M4mwHRfBwUZn*4xYKtW^sn_?6nNE6{RPxh7L^
ztl8@J=WLqOb2@aLAW%Hrh-;FB%-S|ff8V+<-3e^enMa#d+415sI3)7-WDvIk;+1ZH
zq5C$S@4p3Y&XWyf%$(jGfP<&3a!?lWUP%Pl8#1sX0Q(YvUEBz0(Cjl5hlWS(83x0Q
zDFS;2fmjCTjo)hsnk*c%5zsKK;A4am1=XM$o?*_tU1_LB9c@0K+K}1oQ#w^!pM9mg
z*JAw&)3{n4Y;Iu8CCWoKRK0fDfvmxsq%9GnUv)w@XsU;JdTwt3XlQE#He}Qpu@lJ#
zO_KQ%!743dyen16CNE=B$yxwpUAkXssX-kZy+D@!mb?Iqil;YA7!ve_o>pbvnIuW~
zGIj4)K^i@bv4nczLA{|F3<?4|80Nx%QN9Jx)1F-D9)NDrHud_{CG29HXQ<E&^^9Q_
zG=@3nW{n9LIxRK$smRr9JYZRHvFdYI8Bz~uvUI1x6I-t{gGd6ti?J<Iaq)EwpNorO
z20x}D+5|n~Zhx_}a~(`hRe(B}3^k=QjI0A1Kq}KT9z|Oz=a4}?zR)7IaJ&~wC1ed#
z9a8Dx+zhAF!!VQFt}HeGOx+CI-TsrFyR*k`w?>T{5Eu|^0Ch}f?JuoT?XUi(-9VtO
zkF;5(-;_N;(F$Eb%g8U7%664V*2S<HA{l1%T8&*>p>4qJpX2<V&I?GnGzwiBKHXr@
zntTFX^eyVAHQKHd1n9~eReF#U5(E^1*NLg}tv`D;W3-U{j6n7=<d5VH2YH$Nk~~A6
zB*)34WZ$gcjo_@=LY5eLWJRT{nv}2rFn|b6VhGdZ14yFD8f2x(N+i<c9Au%%GUYoR
zXc_F@uTo5Yw6qLAhL3?4;EVXvct5@gUyHATt&0bz%|4E)1Py^0V*})Pj)R<+*0BJ_
z?9p56_0~FCr}lHx91kjMcIkCaJ?Ee~M4{OAoK4TwsyUG&u7NDavY+LbqtcQN>3&9f
zQF>PTvGhIZo6`M?^<ors-UW1j0`I~*@DPsSwRj2kV-K#vR?OgYr8i+NtEG(3f;x;k
zRPP1Nwd=VyJ=dz|TJ&5qJ=JHH?Xf1BPkwkjIg}V{%*p$5@(nq8)gu7?({z9*r=gza
zvp`jEi00o^y&+mb^@eB#Cv}Zz1xIedo?Ecx7HYEvo;uTyeC<+nKC*R~dl|gWGKIe_
z9k#5pz`}322HYia$tp}Kt}Uq2Z~2w=CF^6>I|bQ#gZP;EdGSW^gW&daiJbXip+)F3
z_nP;be=l7s{K~r4>J;ft_brq1!4INfx+BQ<E!15>MI%SlDvq`1k11v{)G=-OV>B&Z
zeX_8!I;b^&P|jXq&aHwvrbRgj^D;I&`Cu)Q_w-bo#+o|$9>`y^wn4F9j!eeJAm0mR
zchm=#K@|<3^0CWNCu+zfUgap1jGoM}$;B{i5SbR&+xWKHOynn#938kanV`pfO(tx7
z3%Jzs!+6@ucPo8^$OBt^nxvghK9KFI?ej9x*=z{KQKa2oq}_Jv_Vie7i0`!*jdx{3
z7TO$Y-piosIR=GK8r{`URn0MhBL@c2R<6IpxR;UM#2+_3E!9c8$@k4qk%W1<;I&?a
z-!b1|9yMD9(R5V!vt`h@SGZaHkkBK1*R)&wvL%cg#a|j9w)~sPXL-u{TT_qmEm4xz
z<L{6Th|JdD&DM`fN3HjZXMt`s8L4hydSk?$R&7v#?_D^*C}kp?QIXsc#SU>91<4&T
zvw>VQci2Cp9=Sv2g``DQDEX3}W&@p9vogFLRU1_OP)7DZyz$nxCe)}rupN}ar@Ts&
zhD^z;CRv?Oj_-x~W7i`Ss#if6>w<ib9YO4%-RO?+eURO<F#rO8#tt|lIn|nZ2MaVY
zaO4jwYG$(PW6vMfA5EY70*i*umOrkjvB{##DAOE)Jw2|M&bbt#A<Jl!Hmb;RK^v6O
zrtF}i?>kFhRjB2!(DoxkJJ2Wj{to6UhX1zpN@;-m0xyUj{xWc&^x}KjSA^r3NRN`Q
zlL|a+{jqqhwawx;)Jsmw3HCwrFNKisQRBx<jmBlh6XshCFB$e5E=EhxpV&<R@Tcei
zx6-oRbfxJ@bN9YO3zS3GqFB14&(sIXh33BoX<RGfjZsykLToR9pC?G^IqqA{m%~(r
zO2xJU1lr<uvb9Z{0DbN0Q{3%QXCR5K1qh1C=3g-ZaZC_fVx~UW1Rxo$Y?k+|Y3Iy*
zvy!|HbqGzHO>or!UJfjtYsAXZ#!F4TnKCS%vSnQxS0?(DyLY0Hd~ltQlUf^SVKee7
z_<Be@${<bZmB+3}twP-jQwtagif7|eZhG3SEZ>DzgOPxwQN4;VJ?&g&g1ZP*8t6)z
zw><vU_G5b5F%M`t(s1gl2-DN{d4MbS?loPWp0*W0`x~wzOi$NtF~MB~;N1VxRfOs3
zn)irdp4M%8I$izVFwEB!PES`|V1l~{bBfn|uOb{du?sbuN{r-34EYiH19_eNhCD}}
zo+{mPlo$*gL2>!1S6iX|C_{b+k<Dkxf04(?QE2}Hxy-_W-$K0;V4TSsX0rTDmYd14
z0%s61!z|J_7$kk1kv=YcLwZSi39rz8WWmf2_ArBzdb`X(z)^HIy-Ah^zXn?|ZzTeU
z8Tz%}J4Z?Kqw!g<fE9XwRqs8g4lK*LGYTFvv|I09%$k8`0&V`}4XEkJ@dsf;;<<o9
zWI02YlM7D%0}fOZ<*FYbaRqRIxi{+%qQ0Fw)yoL<*2rx+cL-nx%-)#@eeY(Vk-2)N
zqD9&F19XMQ${_qMgWo;X4{$$;Y1FWnqJC5NZRtTQO2yCeY#XKKKk{lQJzveMp#*(a
zuTfGzN1yUa%Rw5fjAWITOB3*WUi;x+%>00!Us;t`e+x$%Dh&^*7Yo(<9I8z0p8v|L
zagN<EGp3km<nx%Fxpn{-2?tKSGn?VQ`Z~}rX0R5MnVF$2RD3?CE^X;sO-J^;f<A<}
z4pOO@UPCLY$SQI!Ih!maQ4)faKr`{e<)T_r2|T+SFX1@`b<jsUeYDX>D}A)kM>Bmi
z(MKbF_~@g7KD_kdIkI{hO_rECsor`#$_c{SEFph;NG;djSHdD!3%pU5z@3jN(nDgf
zqk0HWV7K&wG%A%_zhu3_>J}doW1`V=6L$~@8a*AHnspucba3i)a0-0ff3M)w6%S~>
z=Ktg1)Y|(s#I0Zw{=UJfp08-I|EAzn`lP|Bp1WruD7GDgn6(!DvgO7H^kAnN{IY4m
zuk*f0;in-WKUoRfIm_)Y_LTsb1!T-@gKMdD<i<65uNeNEN-)R3JwB#`_k$C!Mho<0
zf?YK<Dxfd5YNXYq22-%0d=p%N${HK$Q%=~>sB(oJEme-&(OTtf2U@9o!2!7{Cwd>d
z(I>k@J#cw@N9cloKZ7l~&(ER~BVhD0yJeF<bo%Qhjlt@^NQ>#t{cV%hRr`wN^w&%3
zS7s{bPJg`wN~L{NH&4$;rkf^J{|~=jdO<MJGet9VST<eUe)>C<lem&{4lk#6{;WLx
z9m;$A(q*2`pT2*X?@$^|aF^A=kU{(ueji*EcEHKZD#7Pl9rB~AZ|*B?7Z~to4?`4Q
zcW@ND;i371=i$(npIz@x!)I3Gv7vafEi<t0BNgIgX<H%Q9O<6ZYco${sk)(e)Pd(R
zHIPUS#pRdRR}|7v3N*A9(lDnlD906~&AphMP+xmd8YG~hrI3bV&Vs*z59I~#LJ<D~
DhaK8M

delta 4029
zcmbVP33OD|8NUB}Z<e>+I|CuxESbq9Bw@)yXnHh+fQleSNCF6vzz~v&31%Y;n^nRR
ziegxNZLgN9&_i7gDrnGXwSXL<l_MH@sve~$Qj4txAqdv09BTjfCK*!noSxIUGxOi&
zzu&*z<-eV~l+Io9_7q5eA<)l+G^a7uRb!O8rm8kV2t@yOOiAep1oGI6f!CQ7zH-)M
z9L~uOgs=SV^leS`?e$d+fwt<pNMn_bQ~Xj2VXv`jdfuS9<K=y}Dbg`%wUp9x(sfD{
z7WnzXVxa<j{H0>yc43v*=+0dY9>bB>1j)vVynA}RwZa+s7R5wTrxTh%59zD*KK3SS
zRHtjlSv(t{_iLNfPt;cRfckHBlQxc)Yj^2)=zHi{HkCc1Jx&enpZXO&h!REB_`_{u
z68$5^u~1vz5V^4<60WLlZ*I-5^Nkn7d|fAuv3aouhA%Hm@_58T{zMlf_FTPPl&EP=
zNH|8=Z`oZe&Y-0kNjsdA9bY*fcew29ZC~1Ir4OWO;#qNla14d562x^Z#Dm?!c9o^d
zBpgn-8-V=c0m$Or>mi%}W~&e|_Lu9DQ>q9W)5;b?z}Q{3LrIaz!U~VcYXon|;P-BT
z@y7P@Jn$Q(bAH4>-T)bfe@-6wu-Oe>qaXi0M#J2P&|}}soexPy*}UnHXnZ~|iy!WS
zOrb0R>t(%XRtW(|kF?|>^Q$t52@t8dJJJ?1t+MG~5cW%!M~~6@`WLAC$GT8sGdAB>
zp@**=Jqk}?kV8VFWL&s!sT%9?i^j40mngAzijliEJiPhn+DhNGQP~WljqN4uOLm5x
zL@(~`aR(k{{Axc?uo<p{@kZaaJfC)vfVPWhyMCykZtFE+mTFAjSt^Jw<I$b-dv1U1
zRbh&s9wF=k`w&;gKDLQ1XO(Eq5%x9P$$WHxzRhg(Yx)U&k8Nio*k9Q@>{Ygh-OFlO
z87pL?*{ukCKOHBdTdEtX+S>e1ag?=0e46Nk+K#5`_WI@~@9;*?h3De|<vvK*Iab16
zWF2T!h!wD<Y&U%njl7qB#ZIwFxDM;sX7&sd*<pHs#nTVyuUQtGM-NkjJ%Vy?rAGG&
zXSSb;K^V3m-C_o`b~J_CBaJN$Rqc@)uPS<=rM0;_($?lN-PQB{!E6xybhhC*9Q4xJ
zDDzHw2>06Ctc$hLeRMVb6}_8w(FG_){lBH`e5c-&;xin56XkkZP7CQc>O;s6bt`tR
z>oqrZ!-Z-7NA+CW--QUwZ8%OB;k*;na1UG-{rYEy<KjfQkfu^u|3?1|hxX`3!Bv;r
z&!nI{+!;p8)dWHEB1w$%BuIHO#M~0Du4-uLnf33NW5F15eTn6KGcZE|IBA6-G#G>e
z48u}05Ew86LlzB2ff@Ra+UDl#&HCQ~>3yHVSQzizLfq0>!p=DV&epI*x|iOp_vy>E
zkF+`J5p{-gM9Gq$lhdTLW<jH0mqz?F>CI03fJC+y5F&O2bB(-NL4I;1WEo55r0^wi
zxI?Ba3fNRZ#A9OL9YJ0+3dhzLr|@S+L5YB!C9{KkV?2!Guf@Xzzs*|5!my7Nt2>+d
z`~(P&0I1P4009I6x1dS+;RLAUWr>i>pG<_&abT}+Y-w(7S8=Yrsk)(~CZh7oiBO<|
z(A4I%n=|eFsU$qX?a7c{w6e9TMUFyBQhIvY;CD=#?oH6++}NSgL{*<a6XV=+8>zHR
zUKfWa!&Ef+WO=}}R4R~`Hn-QghE$81;t~WYo!+2`WEHX#V2l)E<0ocAV1B~f{Ldap
zj+X%x02KhI>tNbN$c$I`w;sqD??>-N(fp{mWJP&Uij=O%m&lDPEI8^TGzvHJIygcm
zAK=Tq5I5OJB>)i+Q8Mom9|A(1kJ<nv5b)a(@li4AT*)PC%2x8@77JYW5<Lp;8V*j#
z;{E)T7jka)BBnET<{++!=YV&}8**&rn_Z>?Qo63I31s3j3tsaOEefy4;0c-aEMMw_
zoP5u4Y!6~PhE9~2A9VF+B(KK8Qj>`q#j1{C5i;%R!G*exB1@4i*W7-|L%tA%mX_q0
z4=l$dqmXMlC&zrkbXm(J*^4bfN)l0`f@~;=5dPdGp_XYclCcY{aXFF5*0`6CEE2+*
zdI`xaw?>=^#OVg}gZ@W<V^A;zb^wQk(^@37rt8m>^b(8P5l<XH$c-Y;6bVJCG>xR*
zYO&f!5&QR9kuNw|n43bkk(4PGpDm8quH!?dj>$ramwrdQH(E^6NFohqLXI~OCW+OM
zq=^=XID&{V4jdj;EZmY)-9Exx^(s3_;<GI_!A*oH8zH3|heDBtW4GZ3T6;rat=n9Y
z=KgU<w=_2Gjgj`c<{CG(TqNMmWNd(p%(M`}g#-{2lLC_Hzd3gjv15<h#3ble^9Kss
zK^ViU?pt=5ea=2*{p<tQ$KGN`Fu6Oxo?}n4C)k5#!8?5kn`D=8`?&=~px`n|9WcS_
zq*0<ri54YllqeSA$8umYUO0c^j$APBi|sVm=@&^nYEOvMhc!tQvF0`V1VndwVx!5?
z(Wj(ha63bE2EqGk29GO+e71)^LLZ`?w4K(`{j?H+ztz`TH$JZ5wot5=YTmQaW3Me}
z)+4LhBTY4JfnoKOVRiqox^GzBx~~W4dd&Vo%w#i*sBUg*uc~kA{rzGn0&hrJM(8~C
z5<RNFpgyElP*FXE8AY|ODVKO)3B)IA>DoE%xb}?lM{T1P)^1WBSC;9E)pWGNtMF|r
zfbuP!5U`uOu`R^I^^k8*O_B0FV02d`+1r8>qzVsrH9`jOuLp-ckS{I7F-$O>gDR%*
zJC?x&@JES{cVf%#HK&2Gu5dK(Uj~jsk5?M+iRR8Vk=FVZk(%u4mX;yIywX@qmi{}j
z9yGKqi3je1G)S~a@6!!XDb5VZ4x)caAC@1`Q}r$EgtD2{$OFoI+H877nWv=6uPd*~
z&9XzCqOMeBxlnzcW~!fR=k+`3F_weLeKK97ZO{*Cub>-Vb((I-w}<kjZ~_=*6=Mun
znFOi)&`L<MMeT3thM2tpuB}3QQ+TmS{Lz-rB7<i0zHKmi$UPnl$DW)oRrr7}FBUS4
z?eiSAqyj1IvmOrobQd_$zU`}_pm)W+uvMBFl6DhEgSJAix0l=Zt7#6Zo?r{<OSYfO
zeU#~M;occVo3;1VjoNr6*Ku4=Q9iOooS(`Q<qgh<oyCrS*+gl#?Xt2O?VBU<HJwle
zAzry2Nh&|M9&#YaFRX_}5a1;nU@;oAcLTQkCYi{KHbR!ux5!a}Aq2kdKFBoa+;OVY
z?H%kh13T8(H8)cf-5wt5f^m?{OS@n?B=K|jbTHo!W6&h5m-n983;_qVu~P)I+Hcqw
z>>uneJ?<rMF`G?fP;HzZNW;<Ngnfni@M-oQJC38TFn(ws*l#kQ0X9X%lNsL<M~_O^
zs^Yb(Ad7hVTMP>AAV6mlI+J!pOK<XiSfv}MU5Cv#oK3~EX$ybjcaUYncLgjmpH;nm
z2QiY~O_&?3A((k>`hLOFsgm*HcR|$<fvg$4{P>P{VYzoMPMk*Av>z%MfQ;x<Wu!Ur
z+1Mp)rJua^W7z4YsRZ-^q7Ps~Yn9&Q({M>cozHRYJWQ~Z?vE~(#`EB?G=JKFk}<~G
z#~i)g7holbAy&>E7hyUIlvr>1cd*Xo$g^HxnfxOrc$NIz?A&PkWf!J>PeG~R>V+x7
GckDk|#^_rB

diff --git a/reference/golden/cpp/edges.json b/reference/golden/cpp/edges.json
index 8fcdbd6..221d16a 100644
--- a/reference/golden/cpp/edges.json
+++ b/reference/golden/cpp/edges.json
@@ -23,6 +23,54 @@
     "source": "file:namespaced.cpp",
     "target": "file:base.hpp"
   },
+  {
+    "col": 11,
+    "kind": "calls",
+    "line": 13,
+    "metadata": {
+      "confidence": 0.9,
+      "resolvedBy": "instance-method"
+    },
+    "provenance": null,
+    "source": "function:b936240196eda212ecaf615c810f2292",
+    "target": "method:1f046d99fc24f0c883d5df08d5f1d0d4"
+  },
+  {
+    "col": 11,
+    "kind": "calls",
+    "line": 17,
+    "metadata": {
+      "confidence": 0.9,
+      "resolvedBy": "instance-method"
+    },
+    "provenance": null,
+    "source": "function:231cb297b9449e906e38fd66e790340a",
+    "target": "method:533a20574d92cc309a832441bc372dbc"
+  },
+  {
+    "col": 11,
+    "kind": "calls",
+    "line": 21,
+    "metadata": {
+      "confidence": 0.9,
+      "resolvedBy": "instance-method"
+    },
+    "provenance": null,
+    "source": "function:977be8a56f253290743386f93328db8a",
+    "target": "method:1477fb78b06fcf85aa120eebf1b3dfd5"
+  },
+  {
+    "col": 11,
+    "kind": "calls",
+    "line": 9,
+    "metadata": {
+      "confidence": 0.9,
+      "resolvedBy": "instance-method"
+    },
+    "provenance": null,
+    "source": "function:549ae0829767e55cde7dd5ead99c67d1",
+    "target": "method:533a20574d92cc309a832441bc372dbc"
+  },
   {
     "col": 11,
     "kind": "extends",
@@ -308,6 +356,51 @@
     "source": "file:namespaced.cpp",
     "target": "import:d427e262bde770416cf520f12c124a85"
   },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:operators.cpp",
+    "target": "function:231cb297b9449e906e38fd66e790340a"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:operators.cpp",
+    "target": "function:549ae0829767e55cde7dd5ead99c67d1"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:operators.cpp",
+    "target": "function:977be8a56f253290743386f93328db8a"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:operators.cpp",
+    "target": "function:b936240196eda212ecaf615c810f2292"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:operators.cpp",
+    "target": "struct:a79c39917f9987d43250fce7bde68405"
+  },
   {
     "col": null,
     "kind": "contains",
@@ -343,5 +436,32 @@
     "provenance": null,
     "source": "struct:418731e230da99cc3237d0e7e35385f1",
     "target": "method:eaf644a1dae18b22184dd0d0b882e1bd"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "struct:a79c39917f9987d43250fce7bde68405",
+    "target": "method:1477fb78b06fcf85aa120eebf1b3dfd5"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "struct:a79c39917f9987d43250fce7bde68405",
+    "target": "method:1f046d99fc24f0c883d5df08d5f1d0d4"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "struct:a79c39917f9987d43250fce7bde68405",
+    "target": "method:533a20574d92cc309a832441bc372dbc"
   }
 ]
diff --git a/reference/golden/cpp/files.json b/reference/golden/cpp/files.json
index 8e0c3bc..b98437b 100644
--- a/reference/golden/cpp/files.json
+++ b/reference/golden/cpp/files.json
@@ -23,6 +23,14 @@
     "path": "namespaced.cpp",
     "size": 102
   },
+  {
+    "content_hash": "61ac8b93b7094d0633203791513f3394c7f76e2993a50d75b9f8e32454dcccf6",
+    "errors": null,
+    "language": "cpp",
+    "node_count": 9,
+    "path": "operators.cpp",
+    "size": 513
+  },
   {
     "content_hash": "e72bc5982add705d170ebd03d4a3db5286237e5b8ab662fc9ed35cd51da438c9",
     "errors": null,
diff --git a/reference/golden/cpp/nodes.json b/reference/golden/cpp/nodes.json
index 961e88a..9b7a8b8 100644
--- a/reference/golden/cpp/nodes.json
+++ b/reference/golden/cpp/nodes.json
@@ -263,6 +263,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 23,
+    "file_path": "operators.cpp",
+    "id": "file:operators.cpp",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "file",
+    "language": "cpp",
+    "name": "operators.cpp",
+    "qualified_name": "operators.cpp",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -307,6 +329,50 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 18,
+    "file_path": "operators.cpp",
+    "id": "function:231cb297b9449e906e38fd66e790340a",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "cpp",
+    "name": "explicit_pointer_operator_call",
+    "qualified_name": "explicit_pointer_operator_call",
+    "return_type": "Vec2",
+    "signature": null,
+    "start_column": 0,
+    "start_line": 16,
+    "type_parameters": null,
+    "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 10,
+    "file_path": "operators.cpp",
+    "id": "function:549ae0829767e55cde7dd5ead99c67d1",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "cpp",
+    "name": "explicit_operator_call",
+    "qualified_name": "explicit_operator_call",
+    "return_type": "Vec2",
+    "signature": null,
+    "start_column": 0,
+    "start_line": 8,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -373,6 +439,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 22,
+    "file_path": "operators.cpp",
+    "id": "function:977be8a56f253290743386f93328db8a",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "cpp",
+    "name": "plain_member_call",
+    "qualified_name": "plain_member_call",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 20,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -395,6 +483,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 14,
+    "file_path": "operators.cpp",
+    "id": "function:b936240196eda212ecaf615c810f2292",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "cpp",
+    "name": "explicit_subscript_call",
+    "qualified_name": "explicit_subscript_call",
+    "return_type": "Vec2",
+    "signature": null,
+    "start_column": 0,
+    "start_line": 12,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -439,6 +549,50 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 33,
+    "end_line": 5,
+    "file_path": "operators.cpp",
+    "id": "method:1477fb78b06fcf85aa120eebf1b3dfd5",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "get",
+    "qualified_name": "Vec2::get",
+    "return_type": null,
+    "signature": null,
+    "start_column": 4,
+    "start_line": 5,
+    "type_parameters": null,
+    "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 56,
+    "end_line": 4,
+    "file_path": "operators.cpp",
+    "id": "method:1f046d99fc24f0c883d5df08d5f1d0d4",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "operator[]",
+    "qualified_name": "Vec2::operator[]",
+    "return_type": "Vec2",
+    "signature": null,
+    "start_column": 4,
+    "start_line": 4,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -461,6 +615,28 @@
     "type_parameters": null,
     "visibility": "public"
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 65,
+    "end_line": 3,
+    "file_path": "operators.cpp",
+    "id": "method:533a20574d92cc309a832441bc372dbc",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "operator+",
+    "qualified_name": "Vec2::operator+",
+    "return_type": "Vec2",
+    "signature": null,
+    "start_column": 4,
+    "start_line": 3,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -658,5 +834,27 @@
     "start_line": 18,
     "type_parameters": null,
     "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 6,
+    "file_path": "operators.cpp",
+    "id": "struct:a79c39917f9987d43250fce7bde68405",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "struct",
+    "language": "cpp",
+    "name": "Vec2",
+    "qualified_name": "Vec2",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
   }
 ]

From 302aa40734aab79cc87bd1fc536f733b4f8c013e Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 04:53:25 +0800
Subject: [PATCH 43/91] fix(cpp): strip template args from out-of-line method
 receiver qualifiers

---
 .../fixtures/cpp/template_method.cpp          |  19 ++++
 crates/codegraph-extract/src/lang/cpp.rs      |  15 ++-
 crates/codegraph-extract/src/walker.rs        | 103 +++++++++++++++++-
 docs/equivalence.md                           |  13 ++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  75 +++++++++++++
 reference/golden/cpp/colby.db                 | Bin 167936 -> 176128 bytes
 reference/golden/cpp/edges.json               |  45 ++++++++
 reference/golden/cpp/files.json               |   8 ++
 reference/golden/cpp/nodes.json               |  88 +++++++++++++++
 9 files changed, 362 insertions(+), 4 deletions(-)
 create mode 100644 crates/codegraph-bench/fixtures/cpp/template_method.cpp

diff --git a/crates/codegraph-bench/fixtures/cpp/template_method.cpp b/crates/codegraph-bench/fixtures/cpp/template_method.cpp
new file mode 100644
index 0000000..ef7392c
--- /dev/null
+++ b/crates/codegraph-bench/fixtures/cpp/template_method.cpp
@@ -0,0 +1,19 @@
+template <typename T>
+class Box {
+public:
+    T get() const;
+    void set(T v);
+
+private:
+    T value;
+};
+
+template <typename T>
+T Box<T>::get() const {
+    return value;
+}
+
+template <typename T>
+void Box<T>::set(T v) {
+    value = v;
+}
diff --git a/crates/codegraph-extract/src/lang/cpp.rs b/crates/codegraph-extract/src/lang/cpp.rs
index c10ed18..8c8162d 100644
--- a/crates/codegraph-extract/src/lang/cpp.rs
+++ b/crates/codegraph-extract/src/lang/cpp.rs
@@ -8,7 +8,7 @@ use tree_sitter::{Language as TsLanguage, Node};
 
 use crate::lang::c::{include_import, normalize_c_return_type};
 use crate::spec::{ImportInfo, LanguageSpec};
-use crate::walker::{child_by_field, node_text};
+use crate::walker::{child_by_field, node_text, strip_cpp_template_args};
 
 pub struct CppSpec;
 
@@ -84,7 +84,18 @@ impl LanguageSpec for CppSpec {
             .filter(|part| !part.is_empty())
             .map(str::to_string)
             .collect::<Vec<_>>();
-        (parts.len() > 1).then(|| parts[..parts.len() - 1].join("::"))
+        if parts.len() <= 1 {
+            return None;
+        }
+        // An out-of-line template method definition spells the class's template
+        // parameter list in the qualifier (`template<typename T> T Box<T>::get()`)
+        // while the class node is indexed as bare `Box` — strip `<…>` so the
+        // receiver matches it, the same normalization #1043 applies to
+        // base-class refs. A multi-line parameter list otherwise leaks whole
+        // `<…>` blocks (newlines included) into `qualified_name`, which can
+        // exceed NAME_MAX (#1309).
+        let receiver = strip_cpp_template_args(&parts[..parts.len() - 1].join("::"));
+        (!receiver.is_empty()).then_some(receiver)
     }
     fn get_return_type(&self, node: Node<'_>, source: &str) -> Option<String> {
         recover_return_type(node, source)
diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 1ff0fa8..572ed89 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -4123,7 +4123,7 @@ fn is_builtin_type(name: &str) -> bool {
     )
 }
 
-fn strip_cpp_template_args(name: &str) -> String {
+pub(crate) fn strip_cpp_template_args(name: &str) -> String {
     let mut depth: i32 = 0;
     let mut out = String::with_capacity(name.len());
     for ch in name.chars() {
@@ -5902,6 +5902,107 @@ WINAPI HRESULT DoThing(int x) { return x; }
         assert_eq!(f.qualified_name, "f");
     }
 
+    // ---- Batch B2: out-of-line template method receivers (upstream 4dd29ea) ----
+
+    #[test]
+    fn cpp_out_of_line_template_method_receiver_strips_template_args() {
+        let src = concat!(
+            "template <typename T>\n",
+            "class Box {\n",
+            "public:\n",
+            "    T get() const;\n",
+            "    void set(T v);\n",
+            "};\n",
+            "\n",
+            "template <typename T> T Box<T>::get() const { return T(); }\n",
+            "template <typename T> void Box<T>::set(T v) {}\n"
+        );
+        let (nodes, _) = run("box.cpp", src, Language::Cpp);
+        let qns: Vec<&str> = nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Method)
+            .map(|n| n.qualified_name.as_str())
+            .collect();
+        assert!(
+            qns.contains(&"Box::get"),
+            "out-of-line `Box<T>::get` should qualify as `Box::get`, got: {qns:?}"
+        );
+        assert!(
+            qns.contains(&"Box::set"),
+            "out-of-line `Box<T>::set` should qualify as `Box::set`, got: {qns:?}"
+        );
+        assert!(
+            !qns.iter().any(|q| q.contains('<')),
+            "no method qualified name may keep template args, got: {qns:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_multiline_template_parameter_list_cannot_leak_into_qualified_name() {
+        let src = concat!(
+            "template <typename CType,\n",
+            "          typename CPPType,\n",
+            "          int kSentinelConstantForTheHelperTemplateClassInstanceGuardLong>\n",
+            "class ApiHelper {\n",
+            "public:\n",
+            "    CPPType* validate();\n",
+            "};\n",
+            "\n",
+            "template <typename CType,\n",
+            "          typename CPPType,\n",
+            "          int kSentinelConstantForTheHelperTemplateClassInstanceGuardLong>\n",
+            "CPPType* ApiHelper<CType,\n",
+            "                   CPPType,\n",
+            "                   kSentinelConstantForTheHelperTemplateClassInstanceGuardLong>::validate() {\n",
+            "    return nullptr;\n",
+            "}\n"
+        );
+        let (nodes, _) = run("capi_helper.cpp", src, Language::Cpp);
+        let validate = nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Method && n.name == "validate")
+            .find(|n| n.qualified_name.contains("::"))
+            .expect("out-of-line validate method");
+        assert_eq!(
+            validate.qualified_name, "ApiHelper::validate",
+            "multi-line template parameter list must not leak into the qualified name"
+        );
+        assert!(
+            !validate.qualified_name.contains(['<', '>', '\n']),
+            "qualified name must carry no template/newline bytes: {:?}",
+            validate.qualified_name
+        );
+        assert!(
+            validate.qualified_name.len() < 255,
+            "qualified name must stay under NAME_MAX, got {} bytes",
+            validate.qualified_name.len()
+        );
+    }
+
+    #[test]
+    fn cpp_out_of_line_template_method_links_to_its_class() {
+        let src = concat!(
+            "template <typename T>\n",
+            "class Box {\n",
+            "public:\n",
+            "    T get() const;\n",
+            "};\n",
+            "\n",
+            "template <typename T> T Box<T>::get() const { return T(); }\n"
+        );
+        let (nodes, _) = run("box_link.cpp", src, Language::Cpp);
+        let class = node(&nodes, NodeKind::Class, "Box");
+        let method = nodes
+            .iter()
+            .find(|n| n.kind == NodeKind::Method && n.name == "get")
+            .expect("get method");
+        assert_eq!(
+            method.qualified_name,
+            format!("{}::get", class.qualified_name),
+            "the out-of-line definition must share the class node's qualifier"
+        );
+    }
+
     #[test]
     fn cpp_template_arg_call_strips_to_base() {
         let src = r#"
diff --git a/docs/equivalence.md b/docs/equivalence.md
index 8b67d53..f4ba97f 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -281,6 +281,16 @@ UObject` plus line-leading `GENERATED_BODY()`/`UPROPERTY(...)`/`UFUNCTION()`,
   reclassifies the `.h` to C++, and the offset-preserving pre-parse blanking
   recovers the `UFoo` class + its `Extends UObject` clause (both dropped before).
 
+Two further files exercise the Batch B C++ gains:
+
+- **out-of-line template method receivers** (upstream #1309) —
+  `template_method.cpp` declares `template <typename T> class Box` with `get` /
+  `set` and defines both OUT OF LINE (`template <typename T> T Box<T>::get()`).
+  The receiver qualifier carries `<T>`, which the class node never spells, so the
+  golden pins both methods at `Box::get` / `Box::set` (template args stripped)
+  plus the `contains` edges from `class Box` to each — the link that a `Box<T>::`
+  qualifier breaks.
+
 A further file exercises the Batch B explicit-operator gain (upstream #1268):
 
 - **explicit operator calls** — `operators.cpp` defines `struct Vec2` with
@@ -294,7 +304,8 @@ A further file exercises the Batch B explicit-operator gain (upstream #1268):
 
 The minimal source corpus lives at `crates/codegraph-bench/fixtures/cpp/`
 (`base.hpp`, `derived.cpp`, `namespaced.cpp`, `operators.cpp`,
-`templated_call.cpp`, `ue_actor.h`). The inheritance base classes live in a
+`template_method.cpp`, `templated_call.cpp`, `ue_actor.h`). The inheritance base
+classes live in a
 `.hpp` file (not `.h`,
 which maps to `Language::C` by extension); `ue_actor.h` deliberately uses `.h` to
 guard the content-based C++ reclassification.
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index a6f1605..3f7d2e0 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3678,3 +3678,78 @@ with `LSP file path must be inside request cwd` (the worktree at
 `/config/workspace/ProdDir/AI/.cgworktrees/v15-impl` is outside the request cwd),
 so locked Cargo build/Clippy/test is the honest fallback and no LSP-clean result
 is claimed. No dependency, version or `Cargo.lock` byte changed.
+
+## Batch B2 — strip template args from out-of-line method receiver qualifiers (2026-07-28)
+
+Ports upstream `4dd29ea` (`fix(cpp): strip template args from out-of-line method
+receiver qualifiers`, upstream #1309 / issue #1286). Behavior only.
+
+### Red (documented, with the actual wrong output)
+
+Three new `#[test]`s in `crates/codegraph-extract/src/walker.rs` drive the REAL
+extraction path (`extract_source` → `Walker::extract_method` →
+`CppSpec::get_receiver_type`). `cargo test --locked -p codegraph-extract --lib --
+cpp_out_of_line cpp_multiline_template` → **3 failed, 0 passed**:
+
+| assertion                                            | expected                   | ACTUAL on pre-change bytes                                                                                                                   |
+| ---------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `template <typename T> T Box<T>::get()` + `set`      | `["Box::get", "Box::set"]` | `["Box<T>::get", "Box<T>::set"]`                                                                                                             |
+| out-of-line method shares its class node's qualifier | `Box::get`                 | `Box<T>::get` (class node is `Box`)                                                                                                          |
+| ICU-shaped multi-line parameter list                 | `ApiHelper::validate`      | `"ApiHelper<CType,\n                   CPPType,\n                   kSentinelConstantForTheHelperTemplateClassInstanceGuardLong>::validate"` |
+
+The third Red is the NAME_MAX shape upstream reports: the qualified name carried
+embedded newlines and the whole `<…>` block.
+
+### Green (minimal)
+
+`CppSpec::get_receiver_type` (`crates/codegraph-extract/src/lang/cpp.rs`) now runs
+the receiver qualifier through `strip_cpp_template_args` — the SAME normalization
+#1043 already applies to base-class refs — and returns `None` when stripping
+leaves nothing. `strip_cpp_template_args` was widened from private to
+`pub(crate)` in `walker.rs`; its body is unchanged, so the #1043 templated-base
+behavior is bit-identical.
+
+### Negative control, executed
+
+The single new call was reverted in place
+(`strip_cpp_template_args(&parts[..len-1].join("::"))` → `parts[..len-1].join("::")`)
+and all three tests went RED again on the same wrong values; the file was then
+restored and re-proved as SHA-256
+`42fcc019fe88ce2178a7ace9eec32e53778d65bfdddeeda2afbd21e16ff35a43`, the
+pre-mutation hash. The tests therefore exercise the production path, not a helper
+call.
+
+### Golden row delta (`reference/golden/cpp/`, additions only)
+
+New fixture `crates/codegraph-bench/fixtures/cpp/template_method.cpp`
+(`template <typename T> class Box` with `get`/`set` declared inline and defined
+out-of-line). `git diff --numstat reference/golden/` showed ONLY `cpp/` paths:
+`files.json +8/-0`, `nodes.json +88/-0`, `edges.json +45/-0`, `colby.db` binary;
+`refs.json` and `schema.sql` byte-identical (`git diff --stat` on both is empty).
+Deleted-line count across the three JSON files: **0**.
+
+Added rows: 4 `template_method.cpp` nodes (file, `class Box` @2, `method Box::get`
+@12, `method Box::set` @17) and 5 `contains` edges — `file → class Box`,
+`file → Box::get`, `file → Box::set`, and critically `class Box → Box::get` /
+`class Box → Box::set`. Those last two are the fix: with a `Box<T>::` qualifier
+the out-of-line definitions never matched the `Box` class node, so the
+class→method containment did not exist.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked --release -p codegraph-rs` → exit 0 (golden regeneration
+  binary).
+- `cargo test --locked -p codegraph-extract --lib -- cpp_out_of_line
+cpp_multiline_template` → exit 0, **3 passed**.
+- `cargo test --locked -p codegraph-extract -p codegraph-resolve -p
+codegraph-bench` → exit 0, **1382 passed across 35 test binaries, 0 failed**,
+  including `generated_golden_matches_committed_cpp_fixture` and the untouched
+  `..._godot_fixture` / `..._ruby_fixture` / `..._mini_fixture` oracles.
+- `git diff --numstat reference/golden/` → only `cpp/` paths; godot, ruby and the
+  original upstream corpus unchanged.
+
+`lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
+request cwd`), so locked Cargo is the fallback; no LSP-clean claim is made. No
+dependency, version or `Cargo.lock` byte changed.
diff --git a/reference/golden/cpp/colby.db b/reference/golden/cpp/colby.db
index c36acfe1bd7b633bd5972ef611a3ddef49ef84e9..0b41f1a942f53bdd088bdcefb0ba2e2ada4a3d36 100644
GIT binary patch
delta 8457
zcmeG>YjhM<n)OvxcXd_Qy*Et)A(O;($fI9*bf>$MG>C9eaRk(ahnfTu^5{T>JRm$o
z)Ffnh_{acTqn8m@@XV+Svoc789Gy`Z9o!L@0p^VBAhQgvdUiztcNZOJW|{1*>PH$j
zfyj@YJ!dEBQ}?^~*8T2xzxVyBdzaFER@ssTo|o-ENK#B3$E6vMew*D-_S;`4LS?P0
z9WE{wDyyez|503H>HxyMu=TmQU5oO@)ubh7`jY`HGFxb2e;h|Ft>G1m+nXl(1La;{
zso&@Ih8i16OPYKQ!G=I6<PSE5g5GeTA@bUy@QP{e4^EuO+7;o}j-~Z0!gZ0EqQ;I6
z_EYiPy4-P9smaM#ZKPccS!Ol{!eyZ*Um)DjTpucLF0U{11p~hFFx$lI4~6R+m)3W7
zvJKd8c=Wv7o-=OpSij$|J?zVzm9Ten%hK>LYeqN32v6z%(3gX6^T<vPJMba22Av>3
zC#|wmJ*t$EapWR?RNY|xSEWIIOP-^=WR>NotbdjlDP3xTavIN8tF2|$Ms$~Am4DYi
zb?RA*_KQ2+<2}iO2Xx9Nt_;`JH?C-3UbNU<DAduOZg87i3<53F=MtUi!X&zLJ&f;i
zc!U~=i6qqEYi{y2m50j9nwmmo^?~wWS$PA4N*luAV10h#yVnt4o?EB_gS`{4C4@{}
z3b`4=<OtPQaj*ZO8Sk3XKQ}#NnkfF8xJe8O{~|miOyghS^I;n(+}f?rrK>$^fy~uZ
zr7r^DwCs?BuI+_FZOd#Qc(jT+LHfI1aA-Hp@qwFl`@p50VNa*FbncUE{10>QgM6)W
z-W`yqeLl}c53dI&Uzy9`%C6cRnX9VFWU9+u{~-D~M#;v;_O=!EEp43@6J&031ivA&
zs}A3#Yxp-rS(|->Bo8Cau0(5$(`>&c&50xrgK{{G_hd1QRR))@<bpTB&UG`rrXK0+
z?+@O4REC263kOMR05PdaXe>vbAwK*zu0iL}S~Rx*WYVC@H%Z#2N2=Az1s7oF^Odz@
z_*S!a;gQC!*nmxFH!1!el+2q<z+EL4{fORRNm-e{w7x!A?k)5C%0s?TlRwzN+*r7z
z(cfI&)EH<8d&A6YG&ZxLvS85PP#$V(42Hbk(uT4CL&2Tb_l{Cv6I(>Zq18RQK#mV-
zM;>iR=y|&qCiK4FwZI;KQ&#k|k{*s+A|I2J<Pdq0Y#}|&MK2-r@)^J&X-RL4OEISk
zez@v1{jY7FkyP!$UXENKr<eo!G1)+tk@<{i4`VO+nrtVT_#)nb7vPD+guliI@ou~W
zZ^jk)R<_9)@)7wZd6oQ-tR>B)l1w7`_!RynehV+d&15?Mm@)iUXr3&jMtp(CB8)XG
z-K`3l(7dv(aYajen=7&7jJ@JegtVw<${zyr;<)<P@9lzbdC(q?d`4zriR>pU+39mg
zDQO_jp*>p0zHjBDL9&|&crV_Gk6;HmjDAhV;rG#-#D#uO=3#=)qJFZCQ8^1~ea9?C
z9xP--g735m4p_djtuDs4CYM!6hmPg#jp5Etr_R;_ha@CJXLv=v-m*BAr?)Ji<PO7b
z?Y(0w`{^64Fvf%C=ybnFvWXSFhF(Iuw4}pnFh_GA&apm%cc3NcP4pO=&q(`Hy+P7S
z9Xex;_^Hzu?_7t-{`Za*^MVJZYto77wztt<^fY=DEkYG2gxn~dQS`cM=vC6y+|v2M
z9IXB{cr)KI3=ebz${%4oZ-nvTc-epIpFNCByjzpb-ebW(!>{6(@oq-lOl;Rhz_#&3
zTX(c|MO$b8I~OK_;8Blj(ihWhn@}5?izcE8NLIg4&#K26l4Yt^dO6AFA!4?is1RDm
z<y2mDv1WXiGgb7-af@oIYph?oR6m^~P4q*2JRxVW<&QL@=8ZJN=Z+WsL%Sqk>)&;`
ziLZ_tz$LO4e??A{S>$Fc;d6#DEGC<n6;H+sF-^1sax!WOIZ<0EHLRf_Vh_x8`q3Wz
z)2LOH>gKqzxxM{rS>LE-G>mK+0~A9mxQU=}<V)ox(t>}1Z$`gD&FVRIiS_r^)yl_0
zm7oaEM*hWfOisV$`ET!|e@usBJJSX*8Ijt<^B@{Ts{lOkyqKrl^7nLE2BZ|bu?Qdl
zdso!sjhnp+i{01+AOg>RE5mLqL{}xr>cF$f@P)b1dMB6F-3=nw)6AUh;%sj)5ULM*
z%S%{pR2B{f6@lwu6C95`9HOVwAw5Y3Pynm|j0TRY{X2R(1B$1)*v6K)<71l(%)Pjx
zWP&{8XV{QVrI?41^&h#SS_8Y{<P-zD#ISSR-9MxanNaL>CL(n*q*Ba7#m|q_TR9Is
znGTM-Z{O9;{`9k8hIF#YtLv>J#ulDu3LIyL!6OI5I7FEv&K|<-<p{kq1M=t3*%8C(
zW;kbNv+Vjhxg;Z5V7icRX5s;JB-ZEa{4iXVApmxG#fomD2QwgN{+w-B?{J+2BQLr`
zp0R_VJG}@ugxGd@hGHPpPp4*r{jTZXi|vra&M-yv>Z%%(jQv_!tdYd>0x#-$N-o2S
z^5}s~$h!NEEisg1A}E=6$hnfaIYY<KiOB#gF+IqMGaJjc0sBqx0pxoY-dW9=6|#*(
zWGhGhNdA+2PCg-L$ou33d5647enMU$FAdo3u$Fkn0^!-#^?>!J8W3+5nMSIS#u{l9
zqoHpX!!69A&Zd$Vm`Clv&3HbZ&5Z04y4B(lxN*!>*gek8AW;w)<kH7@hS=ha&pP6>
z`No(&n`b}+Pu&9Twxj@B&7s|BCwdA!fqKwtno<F`rrm)j;zDf4$>>k$BKioukKRRx
zu!Q>A_7dtcqCQj8&OjXU$Dxuq<cmYzI8>}h?3UJ!_T?)&i*z{5?s{!aorMW-K?3Ya
zfZb7ezP`W+{n5oveIkm~h_bN+*@&{SPM#ieW1ZZ@PEJB+V0JC+2YW#3;qW~96h4Ap
zmOJICSdd>}ZoCnxmQ%_(Wec@0gw$eH{Y*Wo?zX(DK4v{?-D7>+`hfK|>rKkfl_kn_
z#U*`eskE$@dZYuEOjOI<*Fv^PqMKI%rcZQ(-K^VsXMk>A41SZ}FV>}M`)0TmW3<HR
zo{4pRdY5)Q1Rj&V#!Ks3z;7<j68-6*^;M;rJBv!hs&tyv3J!Xv1tfE!U#wws><(s$
zvZ;XH^#GKBC(^iSH|v>Q`ZCaZCgsyJ4}dhunIRUYNA7=3;pHu>!cBS*jWIVv^sr3v
z$}4S*rTNsp1acwIXu5L!VijZesO}0e3^{q?<S6=>$t6VC*jp1ugZZ9VO(A-{%N`YK
z`-pE1ELZ|BiuVRg8##0d|Bd-1%TJyl$D|XaNh-5ss`tnm{*&~#(gTuc5zGVfpOvMi
zjh0Q;)s{;6AI!bhy-E-}t)G~FqWr*|rTj)cFW1U0%O%SpbEWD0Kt%@>nsmMJn*%<v
zCKV{^fdZ3XhpBBXxD;LJCB~GtHQ<P-i0{g2udX7XRaUvRq)HKr>7mt-W{RjqM<2x1
zppdE$GBqfmQ}o6Y>A8(2stxqSX2_3ejnlwmb{Jfz%ck%SZOc5#lwT^=Wg3+XdUicn
znAo?hfzqzrfLN0`+7d=gqB%FRXu=hXqT#1&qykoKtL))cU2l<nG#Y0p93QS9cw-Gr
zGuP@49>{U_<UHg!e8tbT=JNZk$4Cu603rE=X_ELDyYalk;=@?nuKtttJ8Gfg71~gi
z@&U+}Pvn5yYkpF4nr|_GVEMl3ylK1msaPs}By8ti1WIeWA!F;lLi$iQ*l6oIs9^Gb
zV;vMj5xuYu7C<4L)eE&u$Uo|3J&)c5=;ZH!%i>-jRWXYPy7>`yFTisPtQMOqI;Q&p
zkG5;BQxI%UnzJ4Xm^Z0d4|hO5{frf3^oop|iJHN)yK?I!R*(T0rICNb;>qA(PNl>O
zG7SHfm55j&qU#&iV+IE&+!)Ej<~ChJ)zO%84Gv~so8}>shebIYMtg<C3NpiRp-3;>
z>b`k&K6b#r0d~kDQ%AQU*i=WPQ1LED-X(t^|4u$7AF`Um$$s0y1H@z!2sCOZE(XR(
z<Q0y5#V*HZ+4cA+D`&hiki83@C%3bTholHBQ#UFn<{{8D1d2l-yD7xp<z>MnN0uGj
z2jWyAfG<<&3#e0wji^K-Jig2ljXs<v3LFIVhhKk`=ntR%@D7X{gr6m`a`$-p0pW9W
z;9wFj+LO#^J4dz=5B@2hhQ37G2U5KJM#SImp*2(ZDsa;SQ}~(ugD$PlyN0R1<ZEMf
z$5p;1i<|R@E0A;X0{L|^=!jObY&mwpA1;7(bl8#)PUX#Z%L^Q{`$l|T!`>->Ez<vw
zPYJ^_FJ<7vdOim$1>9PWyhf@?iiRu7{#ub{pKq?CoiPXX|GFYQ5M0F{ms2d(og8T+
z$+!odM^)+()o0zwyv;_d&_e<=yN}<h_+_rHCbga2ujs|s!DS?4^!e}dK0MaiV=IZz
zYA?@l(N>nJ(PNu=pUK81ef0Eqc@4a@eKWsR?IFeN<+@b;Ysk}&F-(2ySb%1j?ApHB
zNVJGmMcVC^HS7z?bCsKG6`))ygg7BdU4>fyw^IgFq0q+F(TZNEzTvb%Vrhf;DWp>e
zOBVi;se@@dH+#6C8Ht(yH&X{?jTju6=D%?2VB#&x8rY`Or+s)|k=Aj)bKvPs@DZ3$
z7Wbn}TG`9K=<TU49(ez8_%^Sn88fKwNl4K`3yKGt``}sr<_z;&963mqvYP05{4B1-
z0y@A7*=g!A^<mX*{f%|KwM025tydmboaVQrJn0kp9eJ@VSzfT*&J48ItS7tmERFqb
zH`IZj-rU2Q61symvTvbOW8{i4;;e&%;}gd2rNK=Q()Qlxq`%$>V`xn;*mZJ+!9iOr
zQ=Y$$VK1itrK9zZob`@2!yBbbW=ZL2G3q&E*EK%U$GrUD;D|}%H_I7^5N6Gkd<K8%
z_cp*7?ZEvy=Thk{8z4s;yw^$dHnJPS*RO+}_H2M6?XLTrY(CwXr$62R9?LArACXUA
u)ifrXl)EK=ouNz@@6XVxtDJ0XY{J-WZ27p@g(j;H#%q@hVI@)4nepHL+JG_u

delta 3791
zcmd59X>?T8`F;1jS>AH*osbO)kO{NAWRfrwBH;*R=}`i;P)GzZ1Q@~)Of(x=5TuYq
z6c-2qpY4T$2**PeJR&fa@zhFOiYzV1aI^|oZ9ED+1s7BhtSG&2l1xT_+CQC{GvD{_
zz2EoUZ~tCLpVF~Y*^~}h2b@nk!U@hodeHd_6^q@8#;bn6SUe_ReC4mSw1P!gzj@a!
zc!eh=I7-*^5&`V8v8y17op=SDY;6&m2yS+`2sMC<<rbrR!yo0j$YfnUCJ>$U;FY+S
z{)N`d$FvhPg?>TSXzSE}DIxi5<#|<B#;ZRlHl<z5QQjxz+B|iF8p1Qe(@Og6MxWzZ
zBlDNOoAg968<y7ARZncI4pxO)8=J@0cyq-du-9IJEXl)BwqXVMEbcUM5*Q`3Q^RX+
zKWa(6U}2V-(p9Ned|#Y_dQbp%z^%f8&AaAkozy1_!C>m$00Il_MRS?A3ptJNW?^iX
zDzaoDUr!6lc7Y{yg3hLNqio1z%eqmw*s1BpnpqpcYv8gj@bLffMsL|&;5M?#yA+o!
zR8*vyT#e32*~Z24yI_oQ+Z}Tu!`ObuRB##-W@j0Ab{3>_tSnr3=j$@~4lcSull@o_
z1S?)A(BIQM@+PUopW=1lQ;uegmROC{)$_Ds*A;kbcd>f}s<#-cSBI3rh2f%6xu!~v
zJsL;WERK5$v@eQ#+S<NgbnK+8m_q4RfnKJc&{MRBK1;XqP<V*4?>__rR%26lO89Vh
zsbic@Dg^pDJ;Po30$oR!(fRzE74#b2Mn{n^$T||D7IKXoB74Yo(oI&9I%DF_krFK>
zpKvWiVg&ZdF5NCBM?LA)#8I%cts&G}+t}cVe+WOcuN{W#_^d!L(&_XdZR7WH(E_@d
z?!sq{(fda@=^iSQedH-}gy{5DBGDA`9{!4E(K*C{Kc-u_ya#cCDQZq>W1~*Q42TPy
z1W||PwuWG9b$wG^RcrMUk1D1?Q*&dex~0W!Dr}rNxh%{M*MnEbUFJ3ZPBW-Vchk*u
z7A>KFrD3k{Ke@VB=tSznT}I$lmmDG6@oxME{vDS-;eU}HK65e~i8@|o*m_Ilqj*2w
ziXX$PI9m^ndd2Zmjm$gqNHqVW_YZ&YfzCOQ<A$woCZ}s5;p3lA0?xC*uw5#ZAH_|0
zE}n`D_+Fo8ymj4?pi?PBj<=F=>H2Wa^V0RyWaLhj@??nFD;TP(s|#=cz6O;Kxal%o
zMZTf$b9YT97osk!p^uQ?kV3MEupw{JQv?2T4S1}8`)sl4HSXGv@mcccc;B@x{kgu2
zFaq`9Q^g$uy`r9^wd5F?jNieFv@=?xdQIH%<F9mq+o4H}?8rx#tdcerirM26QL7{f
z(m|$7LUT=QE~}n|<~syIyxP$LlF(ToWGSM+decBh({?f~5&TYWb+Cl$s#;ofgg}aF
zpaCF2Nb)G!AK8?V;GJ5uy@P*D9z6Mk0&5^z(!4|h5P@@$%u?s&44}qKEC3Q9{%foD
z5^;c+L)LH+J310vXyF!iegyanJe<%TODIk(@)-9F2nRXlJafsEB6%>zFS626;6%TE
zf~`ygf4e)Lhnw@T4Q5452~3<qdWm^&WN`@=2bdpzQ+_jkeL<MAX;3%9&lFk$W~{gd
zRYRz$$rV#6s;7&K8MvK;=b|g7BgJyWIU3ILB)s$1a>1(5ErLup3-mwqYx*fYM?a+R
z(O!C-CuQ^-aXMiY&CUagxa2AzCYT4<1b2XDg6W`|U<xQEC}MB=p@^r+{md2sGf&(k
z&8~|=3fD&v>|TyZqR26ixrQRYErP}bhabNr;0w49zl;BdU&k-8q*-t)kNW^|li@@o
z0-1&{b7tk3S3FBQSHHzCi>Y85qGfCh%Z*_<F)TZV@z_m++WMx(=GK-h6R%#;THUau
zB{L4!<8W^r9xZ1B=iMoB8!i*?XBsJA2nS)Y-(D$@IZBuu!3UHX$_OGV9Xx$QSd+sv
ziJqs7P9xuvXUL;u0zQWgT%w%UE@~&VJ+h%as-95ys*kDns8dv@D%#(Wv*n<@(%x;q
ziWkb~wb@#_YG&3I8+*772<yHZJXU|c6ifxy`8@K;QG=Mz#{S!V)~J1Q*{B-Gha6VM
zfh9Y-3DbQ_bkmnE<)<-6CnOm=E3DR*tZ`BWf364JK4>1M)pBy3mDIvG@J4~f6Ft_w
z8gx8p6>|l6gZ2&*x|ntkjD#^P%LEzh-h05!M;jAFYVU<@(saMITfmpe<F+$+3|>!9
z+E3FZ_F~zi%_QI1ciWronylJ-<R6qeYqz{fy-%)?kJ{F&`;_q{Q$1&WLwVY!E2p*3
zY!%ikk$Fv!YYF!`hJk6CeDJfE+aM3dva;nI<g#=Va3gSFjT!-rvI-yT+lVBq?<Pr4
z1D4l~k|2wnTFw>CWKZ4)<1D(VmeDjbW)5$39X$QO&3gGMt1FIv3>&qAi_c(XE1-bu
z`v?b-H&?<$>q2ud@C)|~(h+Srt`(n?WYsO*&5LOzc@cds_Y#Va)0b&7Y1H0TAJlS{
zfW?K=m9yxu{hWNWyw<wGmT4`rp0#haT(oSl%!0{q9nI$q{{h>@>1<&KjAYMrKtlfv
zdHD}0Ap3*1U}Y+=CuVqLu{)nZW96~2wNo3=93?@`9avx)HQ-|#yHJjZ)g1QNUKF%v
zSK0VT2Vn4!F%}fqSziZa@>7#vKz?qkTRLF@x7G1IXrZhxu<<#K%QC*aC7WeE06y6p
zzht~smZ{(*&%hev;ge}pl;?={1UGZ6<&0dcVJ+nFklD5trpg)Rwn@QJCcl!|PCnpe
zsyA*p<JP7{Car@fWcJomXuQKp-xlcG^jrER{WtxHo(U%`>Y)~kNFijL{vwC(_XzYG
zK6mu-$>Rj=;rq|gUnnB)1$_Q<U9k?KmLXIcLd78z$)ZK>Cp)wsq!Q6jQ<&`%1bJre
zCy|sJ@S1~<{BCxZA{R$oha5<9IuPa4UYJ(UD(>RfNLwT+fF8!|+A6rIJ(af!v8Jgh
zb=Y9TlEB(uS5gr|)`n1B+mh;3D@aI6@Ho_hEzzDJ3e7yG0#YE<)RZ#V5&D}Qudbjp
zRMl6vG*yMFm!!m+0Fh@rG1yQ>bL!HJK*-oT-I>p?V6Crit!Z46Orq_Fw@6r)O!^xn
z?`{b{?nFfy0prUjojFOIu)jkmahb3zDc0GP85@2g$v802d2`~Bq{JafEs61x9vLJw
zdmfj>(tE&}Jd9I9%di0f$kN)}c9+hcEJPK&GF>f1zdBTctWNuSfu~W3d}fe9@y~eI
zihNXsTtx8+2L$>jI*%q9WY&cL|2LmV;c|3TCKfzepmpRlxs8vxqj^Ybn00PM$;NZr
soa~+TD5#9(uW6O3jpl1wv??s!fU0<fJhlNDyh6_J;vkz{>O!0U3nixTi~s-t

diff --git a/reference/golden/cpp/edges.json b/reference/golden/cpp/edges.json
index 221d16a..565f471 100644
--- a/reference/golden/cpp/edges.json
+++ b/reference/golden/cpp/edges.json
@@ -230,6 +230,24 @@
     "source": "class:b28eae813de1699c6b7d7727db856721",
     "target": "method:c3338e5d52c4d38bfa7dd8dce45aa47d"
   },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "class:c4e79d14ebfa98f8a715418e5d9039ea",
+    "target": "method:34801631009cb62d1b5b49935d950e4b"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "class:c4e79d14ebfa98f8a715418e5d9039ea",
+    "target": "method:39b1fd1d8987dd97a48578bd976bee5a"
+  },
   {
     "col": null,
     "kind": "contains",
@@ -401,6 +419,33 @@
     "source": "file:operators.cpp",
     "target": "struct:a79c39917f9987d43250fce7bde68405"
   },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:template_method.cpp",
+    "target": "class:c4e79d14ebfa98f8a715418e5d9039ea"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:template_method.cpp",
+    "target": "method:34801631009cb62d1b5b49935d950e4b"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:template_method.cpp",
+    "target": "method:39b1fd1d8987dd97a48578bd976bee5a"
+  },
   {
     "col": null,
     "kind": "contains",
diff --git a/reference/golden/cpp/files.json b/reference/golden/cpp/files.json
index b98437b..18c9c27 100644
--- a/reference/golden/cpp/files.json
+++ b/reference/golden/cpp/files.json
@@ -31,6 +31,14 @@
     "path": "operators.cpp",
     "size": 513
   },
+  {
+    "content_hash": "0527736aa5807318919d35bb62e2c3f8dc4be0e333cf2e27553b89dc59006b74",
+    "errors": null,
+    "language": "cpp",
+    "node_count": 4,
+    "path": "template_method.cpp",
+    "size": 237
+  },
   {
     "content_hash": "e72bc5982add705d170ebd03d4a3db5286237e5b8ab662fc9ed35cd51da438c9",
     "errors": null,
diff --git a/reference/golden/cpp/nodes.json b/reference/golden/cpp/nodes.json
index 9b7a8b8..c337218 100644
--- a/reference/golden/cpp/nodes.json
+++ b/reference/golden/cpp/nodes.json
@@ -175,6 +175,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 9,
+    "file_path": "template_method.cpp",
+    "id": "class:c4e79d14ebfa98f8a715418e5d9039ea",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "class",
+    "language": "cpp",
+    "name": "Box",
+    "qualified_name": "Box",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 2,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -285,6 +307,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 20,
+    "file_path": "template_method.cpp",
+    "id": "file:template_method.cpp",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "file",
+    "language": "cpp",
+    "name": "template_method.cpp",
+    "qualified_name": "template_method.cpp",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -615,6 +659,50 @@
     "type_parameters": null,
     "visibility": "public"
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 14,
+    "file_path": "template_method.cpp",
+    "id": "method:34801631009cb62d1b5b49935d950e4b",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "get",
+    "qualified_name": "Box::get",
+    "return_type": "T",
+    "signature": null,
+    "start_column": 0,
+    "start_line": 12,
+    "type_parameters": null,
+    "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 19,
+    "file_path": "template_method.cpp",
+    "id": "method:39b1fd1d8987dd97a48578bd976bee5a",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "set",
+    "qualified_name": "Box::set",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 17,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,

From bc36c6e51a60e2039381f170b919194fe857fed8 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 05:04:46 +0800
Subject: [PATCH 44/91] fix(cpp): compose namespace prefix into out-of-line
 method qualified names

---
 .../fixtures/cpp/namespaced_member.cpp        |  11 ++
 .../fixtures/cpp/namespaced_member.hpp        |   8 ++
 crates/codegraph-extract/src/walker.rs        | 108 +++++++++++++-
 docs/equivalence.md                           |  19 ++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  82 +++++++++++
 reference/golden/cpp/colby.db                 | Bin 176128 -> 176128 bytes
 reference/golden/cpp/edges.json               |  60 ++++++++
 reference/golden/cpp/files.json               |  16 +++
 reference/golden/cpp/nodes.json               | 132 ++++++++++++++++++
 9 files changed, 431 insertions(+), 5 deletions(-)
 create mode 100644 crates/codegraph-bench/fixtures/cpp/namespaced_member.cpp
 create mode 100644 crates/codegraph-bench/fixtures/cpp/namespaced_member.hpp

diff --git a/crates/codegraph-bench/fixtures/cpp/namespaced_member.cpp b/crates/codegraph-bench/fixtures/cpp/namespaced_member.cpp
new file mode 100644
index 0000000..4c02581
--- /dev/null
+++ b/crates/codegraph-bench/fixtures/cpp/namespaced_member.cpp
@@ -0,0 +1,11 @@
+#include "namespaced_member.hpp"
+
+namespace simulator {
+int ManifestStartup::Apply(int input) {
+    return input;
+}
+}
+
+int run_manifest() {
+    return simulator::ManifestStartup::Apply(1);
+}
diff --git a/crates/codegraph-bench/fixtures/cpp/namespaced_member.hpp b/crates/codegraph-bench/fixtures/cpp/namespaced_member.hpp
new file mode 100644
index 0000000..cf05bb3
--- /dev/null
+++ b/crates/codegraph-bench/fixtures/cpp/namespaced_member.hpp
@@ -0,0 +1,8 @@
+#pragma once
+
+namespace simulator {
+class ManifestStartup {
+public:
+    static int Apply(int input);
+};
+}
diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 572ed89..4acee61 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -2104,7 +2104,8 @@ impl<'a, 'tree> TreeSitterWalker<'a, 'tree> {
                 is_async: self.spec.is_async(node),
                 is_static: self.spec.is_static(node, self.source),
                 return_type: self.spec.get_return_type(node, self.source),
-                qualified_name: receiver_type.map(|receiver| format!("{receiver}::{name}")),
+                qualified_name: receiver_type
+                    .map(|receiver| self.compose_receiver_qualified_name(&receiver, &name)),
                 ..NodeExtra::default()
             },
         );
@@ -3559,6 +3560,37 @@ impl<'a, 'tree> TreeSitterWalker<'a, 'tree> {
             .or_else(|| child_by_field(node, self.spec.body_field()))
     }
 
+    /// Qualified name for a method defined out-of-line via a receiver qualifier
+    /// (`Type::method() {}`). The declarator spells the receiver RELATIVE to the
+    /// enclosing namespace, so the active C++ namespace prefix must compose in —
+    /// `namespace sim { Output ManifestStartup::Apply() {} }` otherwise indexes as
+    /// `ManifestStartup::Apply` while its own class node carries
+    /// `sim::ManifestStartup`, and qualified call sites never resolve (#1310).
+    ///
+    /// The source may legally re-spell part or all of the namespace path
+    /// (`namespace sim { void sim::M::f() {} }`), so the receiver is anchored at
+    /// the first prefix segment it names: everything before that anchor comes
+    /// from the prefix, the receiver supplies the rest. `namespace_prefix` is only
+    /// ever non-empty for C++, so every other receiver language (Go, Rust,
+    /// Kotlin, Lua) passes through unchanged.
+    fn compose_receiver_qualified_name(&self, receiver: &str, name: &str) -> String {
+        let base = format!("{receiver}::{name}");
+        if self.namespace_prefix.is_empty() {
+            return base;
+        }
+        let receiver_head = receiver.split("::").next().unwrap_or(receiver);
+        let anchor = self
+            .namespace_prefix
+            .iter()
+            .position(|segment| segment == receiver_head);
+        let prefix = &self.namespace_prefix[..anchor.unwrap_or(self.namespace_prefix.len())];
+        if prefix.is_empty() {
+            base
+        } else {
+            format!("{}::{base}", prefix.join("::"))
+        }
+    }
+
     fn build_qualified_name(&self, name: &str) -> String {
         let mut parts: Vec<&str> = self.namespace_prefix.iter().map(String::as_str).collect();
         for node_id in &self.node_stack {
@@ -5902,6 +5934,80 @@ WINAPI HRESULT DoThing(int x) { return x; }
         assert_eq!(f.qualified_name, "f");
     }
 
+    // ---- Batch B3: namespaced out-of-line methods (upstream e437918) ----
+
+    #[test]
+    fn cpp_out_of_line_method_in_namespace_carries_namespace_prefix() {
+        let src = concat!(
+            "namespace simulator {\n",
+            "class ManifestStartup {\n",
+            "public:\n",
+            "    struct Input { int x; };\n",
+            "    struct Output { int y; };\n",
+            "    static Output Apply(const Input& input);\n",
+            "};\n",
+            "ManifestStartup::Output ManifestStartup::Apply(const Input& input) { return {}; }\n",
+            "}\n"
+        );
+        let (nodes, _) = run("manifest_startup.cpp", src, Language::Cpp);
+        let class = node(&nodes, NodeKind::Class, "ManifestStartup");
+        assert_eq!(class.qualified_name, "simulator::ManifestStartup");
+        let apply_qns: Vec<&str> = nodes
+            .iter()
+            .filter(|n| n.name == "Apply")
+            .map(|n| n.qualified_name.as_str())
+            .collect();
+        assert!(
+            apply_qns.contains(&"simulator::ManifestStartup::Apply"),
+            "the out-of-line definition must carry the namespace prefix, got: {apply_qns:?}"
+        );
+    }
+
+    #[test]
+    fn cpp_receiver_that_respells_the_namespace_is_not_double_prefixed() {
+        let src = concat!(
+            "namespace sim {\n",
+            "class M { public: static void f(); static void g(); };\n",
+            "void sim::M::f() {}\n",
+            "void M::g() {}\n",
+            "}\n",
+            "void sim::M::f2() {}\n"
+        );
+        let (nodes, _) = run("m.cpp", src, Language::Cpp);
+        let qns: Vec<&str> = nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Method)
+            .map(|n| n.qualified_name.as_str())
+            .collect();
+        for want in ["sim::M::f", "sim::M::g", "sim::M::f2"] {
+            assert!(
+                qns.contains(&want),
+                "missing `{want}` among method qualified names: {qns:?}"
+            );
+        }
+        assert!(
+            !qns.iter().any(|q| q.contains("sim::sim")),
+            "a re-spelled namespace must not be double-prefixed, got: {qns:?}"
+        );
+    }
+
+    #[test]
+    fn go_receiver_method_qualified_name_unaffected_by_namespace_composition() {
+        let src = concat!(
+            "package main\n",
+            "\n",
+            "type Server struct{}\n",
+            "\n",
+            "func (s *Server) Start() {}\n"
+        );
+        let (nodes, _) = run("srv.go", src, Language::Go);
+        let start = nodes
+            .iter()
+            .find(|n| n.kind == NodeKind::Method && n.name == "Start")
+            .expect("Start method");
+        assert_eq!(start.qualified_name, "Server::Start");
+    }
+
     // ---- Batch B2: out-of-line template method receivers (upstream 4dd29ea) ----
 
     #[test]
diff --git a/docs/equivalence.md b/docs/equivalence.md
index f4ba97f..7e6b957 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -281,7 +281,18 @@ UObject` plus line-leading `GENERATED_BODY()`/`UPROPERTY(...)`/`UFUNCTION()`,
   reclassifies the `.h` to C++, and the offset-preserving pre-parse blanking
   recovers the `UFoo` class + its `Extends UObject` clause (both dropped before).
 
-Two further files exercise the Batch B C++ gains:
+Four further files exercise the Batch B C++ gains:
+
+- **namespaced out-of-line method + fully-qualified call** (upstream #1310) —
+  `namespaced_member.hpp` declares `namespace simulator { class ManifestStartup }`
+  with a static `Apply`, and `namespaced_member.cpp` defines it OUT OF LINE inside
+  the same namespace block, then calls it through the fully-qualified path
+  (`simulator::ManifestStartup::Apply(1)`) from a function OUTSIDE the namespace.
+  The receiver qualifier is spelled relative to the namespace, so the golden pins
+  the method at `simulator::ManifestStartup::Apply` (matching the class node's
+  `simulator::ManifestStartup`) plus the `Calls` edge
+  `run_manifest → simulator::ManifestStartup::Apply` resolved by
+  `qualified-name` — the edge that a namespace-less qualifier loses.
 
 - **out-of-line template method receivers** (upstream #1309) —
   `template_method.cpp` declares `template <typename T> class Box` with `get` /
@@ -303,9 +314,9 @@ A further file exercises the Batch B explicit-operator gain (upstream #1268):
   `Vec2::operator[]`, `Vec2::get`).
 
 The minimal source corpus lives at `crates/codegraph-bench/fixtures/cpp/`
-(`base.hpp`, `derived.cpp`, `namespaced.cpp`, `operators.cpp`,
-`template_method.cpp`, `templated_call.cpp`, `ue_actor.h`). The inheritance base
-classes live in a
+(`base.hpp`, `derived.cpp`, `namespaced.cpp`, `namespaced_member.cpp`,
+`namespaced_member.hpp`, `operators.cpp`, `template_method.cpp`,
+`templated_call.cpp`, `ue_actor.h`). The inheritance base classes live in a
 `.hpp` file (not `.h`,
 which maps to `Language::C` by extension); `ue_actor.h` deliberately uses `.h` to
 guard the content-based C++ reclassification.
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 3f7d2e0..f8f557e 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3753,3 +3753,85 @@ codegraph-bench` → exit 0, **1382 passed across 35 test binaries, 0 failed**,
 `lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
 request cwd`), so locked Cargo is the fallback; no LSP-clean claim is made. No
 dependency, version or `Cargo.lock` byte changed.
+
+## Batch B3 — compose namespace prefix into out-of-line method qualified names (2026-07-28)
+
+Ports upstream `e437918` (`fix(cpp): compose namespace prefix into out-of-line
+method qualified names`, upstream #1310 / issue #1291). Behavior only.
+
+### Red (documented, with the actual wrong output)
+
+Two new C++ `#[test]`s plus one cross-language control in
+`crates/codegraph-extract/src/walker.rs` drive the REAL extraction path
+(`extract_source` → `Walker::extract_method` → the `receiver_type` →
+`qualified_name` composition). `cargo test --locked -p codegraph-extract --lib --
+cpp_out_of_line_method_in_namespace cpp_receiver_that_respells
+go_receiver_method_qualified` → **2 failed, 1 passed**:
+
+| assertion                                                                  | expected                                      | ACTUAL on pre-change bytes                                                                                        |
+| -------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `namespace simulator { … ManifestStartup::Apply(...) {} }`                 | `simulator::ManifestStartup::Apply`           | `["ManifestStartup::Apply"]` — the class node meanwhile carried `simulator::ManifestStartup`, so the two DIVERGED |
+| `namespace sim { void sim::M::f(){} void M::g(){} }` + global `sim::M::f2` | all of `sim::M::f`, `sim::M::g`, `sim::M::f2` | `["sim::M::f", "M::g", "sim::M::f2"]` — the RELATIVE form `M::g` lost its namespace                               |
+
+`go_receiver_method_qualified_name_unaffected_by_namespace_composition` (Go
+`func (s *Server) Start()` → `Server::Start`) passed pre-change and is the
+cross-language non-regression control, not a Red.
+
+### Green (minimal)
+
+New `Walker::compose_receiver_qualified_name(receiver, name)` in
+`crates/codegraph-extract/src/walker.rs`, called from the ONE
+`qualified_name: receiver_type.map(...)` site in `extract_method`. It prepends the
+active `namespace_prefix`, anchored at the first prefix segment the receiver
+re-spells, so `namespace sim { void sim::M::f() {} }` yields `sim::M::f` and never
+`sim::sim::M::f`. `namespace_prefix` is pushed only by `visit_cpp_node`, so it is
+empty for every other language and Go/Rust/Kotlin/Lua receivers pass through the
+identical `{receiver}::{name}` string.
+
+### Negative control, executed
+
+The single call site was reverted in place to the old
+`receiver_type.map(|receiver| format!("{receiver}::{name}"))` and BOTH C++ tests
+went RED again on the same wrong values while the Go control stayed green; the
+file was then restored and re-proved as SHA-256
+`2b7e3601743ed319d09a61a73f05246d5a17fa4b3b269bf389e190d0428990ab`, the
+pre-mutation hash.
+
+### Golden row delta (`reference/golden/cpp/`, additions only)
+
+Two new fixture files —
+`crates/codegraph-bench/fixtures/cpp/namespaced_member.hpp` (the namespaced class
+declaration) and `namespaced_member.cpp` (the out-of-line definition inside the
+same namespace block plus a fully-qualified call from OUTSIDE it). `git diff
+--numstat reference/golden/` showed ONLY `cpp/` paths: `files.json +16/-0`,
+`nodes.json +132/-0`, `edges.json +60/-0`, `colby.db` binary; `refs.json` and
+`schema.sql` byte-identical. Deleted-line count across the three JSON files:
+**0**.
+
+Added rows: 6 nodes — `file namespaced_member.hpp`, `class
+simulator::ManifestStartup` @4; `file namespaced_member.cpp`, its
+`import namespaced_member.hpp`, `method simulator::ManifestStartup::Apply` @4,
+`function run_manifest` @9 — and 6 edges: the `imports` edge (`resolvedBy=import`,
+0.92), four `contains` edges, and the decisive
+`calls run_manifest → simulator::ManifestStartup::Apply` with
+`resolvedBy=qualified-name` at confidence 0.85. Before this change the method
+indexed as `ManifestStartup::Apply`, the fully-qualified call site matched
+nothing, and that `Calls` edge did not exist.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked --release -p codegraph-rs` → exit 0.
+- `cargo test --locked -p codegraph-extract --lib -- cpp_out_of_line_method_in_namespace
+cpp_receiver_that_respells go_receiver_method_qualified` → exit 0, **3 passed**.
+- `cargo test --locked -p codegraph-extract -p codegraph-resolve -p
+codegraph-bench` → exit 0, **1385 passed across 35 test binaries, 0 failed**,
+  including `generated_golden_matches_committed_cpp_fixture`,
+  `cpp_db_is_self_equivalent_to_cpp_golden`, and the untouched godot / ruby /
+  mini oracles.
+- `git diff --numstat reference/golden/` → only `cpp/` paths.
+
+`lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
+request cwd`); locked Cargo is the fallback. No dependency, version or
+`Cargo.lock` byte changed.
diff --git a/reference/golden/cpp/colby.db b/reference/golden/cpp/colby.db
index 0b41f1a942f53bdd088bdcefb0ba2e2ada4a3d36..ba2b2ab89c075e2b22adaf0be3683927c283df05 100644
GIT binary patch
delta 16398
zcmeHO33yw@wZ3x~N%!jBJKo~mmUmgQWl3HnOCcLe$qGrxW<s!KStf?qF|iX8ctLT2
z0D%y~r3^F)A&;$4ngHfC1xi9+p>5cbycP;+*;=6NO<JJrd1tP4WqFIud+pbL?_njH
zGiPSbEa%LenSVwbUXwPwCf)y-n`;q|X^*=hw4`W%anH!Qo&TKg<v!y!u%EHFu_vQv
z(IVy;6WO{eo$C|JwQK4&p)xJAz73UXm(;H@m1Hi>u~lgs>a#W6uox9<=QS)tMcR`M
zi^V?Pmf4h5HO;TR9>|Q=M*NZ5`iQ^2v9YzT(bpJmXsr#@)`vXa#)kSpI1pYD>gkyi
z>gs5Z^z@$98(P)7y1S>NbM=Z)@5)ud;E<HAP-mp4I~0zzHFrijTO+G#mUnlDySsVw
zMTMEuCiwmSbP-uB48vI94+8B*e@b&w-u8|akr9QAp9$58>k2ZP3(Cv==?GawZI>@2
z+~^P0d3_##YoMXd8;W?KgRP#raH!n}NuE%seRWs3w_|13s?}Z1o$>A_)5GhBdT3SF
zJ}w^yJL^n8xorxY6>V&6_ebjL!=c)SdSAd_8}fR?;gCNP_BFP(HuxGlBfZO4woU8q
zUa@ZUaSR6a45L-boBAs9pwh&6&N0T*67A^hUb(6_7-_BbwAR%}BH^}HpRd8w2>%-z
z8$+!=FZ92?E|zV01)#5SGGqN`OFO#4D^|Bfic0iyIYYHya#3zf^V$`D+k8XSP<Uij
zL&EU-M`HqC?$7tVEw+0t0Y<f}`;~Q8tQ^8m;7&_GeoCB<Gx49*OXZE$SFJ(mQ?bYL
z8%vwGPs+92W&PUPWLYa-FIS82tMlcvt^Lw;saKgJ=39<Rw<&j6uT<Z~)9}smt*Rz}
ztbCyqOV9KlPC01SDrY!zyy;vOqCE(%jx>kDFc)f;dt6*IB0qZ!Ie0ga<l42!Db(a~
z6OlG`K^Agpug<7K)tYr?6<_7#n#lE+BRlWR=Oz*FeQXYLXwjK2RH^-Fri-`J^2N)M
zldquE)_YkeUtYy6CHq&SN}&uWq;0LY!(`twt4b)*<F7Ba^TnB*m%P3arALdP2Bc5k
z;8;`KR>)0@^=0_TgE<t^ZW+@fIMzHWpl#`lM5&Pn$C?ZIH1jwOHtz(j1Utwb+{%7=
z_HhmdQ=aQ^U2i$b{FYfWpKf}~bcLx*ctN;I2=edq+xQvWI~?Ks>>KP>b_P0z!p!s9
z;glY(&+5_~^EXS?BGc5AcOF8F);F<AdvE>{RHdDI)?(z;wx4x6Xw1LBp(zU-P?3MZ
zd}P;7TIeVHL9OiE3T^vB$4&RKcJ|zIU^m0+ynW$3P}qkH=b{pA%Az^2C{I~bM)qt(
zmF(;yN^8d#Igm}K<}7xgLM^bwuk8k^K&S8$2g(PkMaUBw?^12+qAc>K`&f5$UarVY
zYbt={l+jIcL^Y1j7Q!pLdP5yuJqvO`Wb=tc!kEX6BHA^kRTyIDXM@<KV~CBdkYgH8
zLguWjaR?o!mG%FANr{<txE^fz2v?+vh|5Bew(}xAK?Md^lsydoKK81=P|s3cSJo(k
ze3R^fMIlpW+e9sE{n>Jhcm(advqk(H+iB6(uMZ~}A9E|s+WYGx0}Q^yq%FI&IcgO7
zMC=wMf1i?$1OYK4>aeb@zO^CL7KnH}ZN30q-9rtHt!+L(_%*NJ+X_CeuA#o6v8_Ge
ztq%kOKA%6(Sl8GPYH0HWLT!G~+4*|&VvYQmy^xopv`Tj5Dj|QQzTO+~2I|{F9)CUT
z34E>o*4nzZ)^Nb@Zw%Ch+uGYgfl#2<SL^Y@o}ty(*w7Y^`069=t!>`+IuD3o_9xfL
zcW{y;sh8UGm(CZBG5A>Xz<3z3PqbU2%gS2BLwfm7M2YGE&tdRK_zip*@5MXtHMj?#
zgXi?87S&<$)hkFvqIUh3Ok~mUzO0kYshl0H?2fFWo0Xm#Xp1R_^P>^RRv0lwduB_6
zLpsPHDauIEu|8l53nli9RPFR_b6LTw-Lh?o^kQ>X7Azq4bcXc(h;?XX+Y7Dy#^%yE
zQ+r^hLtC@GjOA;z?c0|~&kv;Rs&kOpA0n$(yCWyct#1y{BK~w{+-vcW%~^a?5e}_b
z(IZ)h4+0Di)fU60P4nl87QHI!;b_jugLie1Z+Lm|6|q^?Gc2wD<Q@OXwtJOh4E_+m
z1nzkc-iR**&3V;_)k(@R{3+gs3)DZWKUeQpPge_-FR-9~sy?G$q@J%XQ|GFwDvz(n
zY3dvJkN7$KFuns{g4^*tJP}u@FR9;Gx2Tt^wW=L|N4*o2aHXPoc8gK3g`1!|Hjm5|
zBwUy~IZ|U}aY<Yb_$}(Tst3p_5f%V_<#ZYu9m&NjlOy)zNQKNr2kI;z5Lq@rmJX05
zl<etUwL08eY}8bgsN80-3X`iS7$}}k$=KlM8F_R2Kiw@O7<3n--h$u5vz1NwLA+W$
z8>UVv_Tg5%OL3`FU@~2zeu968PlEl<a(tC?TzOpiqnfLH7vF<9^)dB!wM+G?CF*qL
zUi`SS7-y<islQcD!w%(QyimD82`fH)GYtCAWgo42;dfT9^r~DjO4=CFX-GHIy^+pt
zI5<Sw+*U3Rb+1|(j`Z}@&<UI4GIQyuC(>I@!}B7&RWv+#<yt45$XSjFoEt&W4%nRQ
z=Za=(#g*F8XG_5Aw(QG86`K3G+?w)u=`z{?W8yDeR;qBeM6{}eHgi!VT&tm1(xY@E
zH)NvNMqCQ$QKm43E7yBs91#krj`Y2H{-}lWMoxh_l$*x&zqAiFl3sZa11fqR7h|iE
zsfhBI_)feP&&5;m)3_hz#j7wMKE^@pl=mnvD|aael!riZi`4x%tX!kaR#w7X`L4QL
z&B9mU9(9lMmg19N0<~?If2n+`o~#tgZ^}ObC7t%aQBtXknja`77^Ip?ME<Ahnp#fv
zLNyT#f{d~Z&J~X(sgCL=mc?KWQ6SwHj((E*Cb}%=&OCvn`0_ba&qV_V-H{dDPoC>U
zoL7!&=0o-Fc6Bx^RN2bc${Wgm!A#q&Y*#iZYn66ofpW6qRMO<n<v++z%MZyr<m==p
zsBD6)JGPXelS=n<Zv9)ILU6!<sR9QK`dy`e>yszy80G~lhjHw~I2FS<<-<5-!#JhG
zI3?QAm&>9fPXU-wC(zHxWnkJAjG8i3IdR>Dv%9-TQO+f=Tn)-m*J<Y07R%}`^%ixj
zdbQf8u7i=ss)w#8P@^{<8gX|#UK0=X)eG`f_uup3QmSmHW<FZ)Zd40Yq`av-1!~@=
zT&46XEihLbl`<to{!;#<d_dkKe@|X7x5=~QiLw)_eB7!X{4yogi}_+Pc?H#uewmHj
z@ST;*)@1Qs5hd1AeJP}S8<*DgRW_Sitp{=y1UZ5;o39hKzLzuLu(Io`^huTJyd5Q$
zLVZh=Vjs?vD~9td<=U~Y(xYX=Q~1*1Jgy{-w~K>oDjv=%%H#cL<P8~b%jNyz(6nd_
zQz{&#91Me4FnSuFKaxxk3FY!ePs+{U9r0H7FZ=rLB&TXP&)N7SWfM41aIiz2C^+0f
zZWJGmJJQmGEA{Elv^C~V!7clA$DHI;SGWKDoNDVo&Z(|RcB+Pp?1_PfCz$9XI@J(G
z$VQpZux^Yzov9wdsqTGAMU}{9Eo4m0(+vJty%n#=CF&y(8TLUpA)cGazpEWi*^zeR
ztS2_WAL5yNa^bA;NwG)so>5E=r=#gY8OyOYEoF%fm6FLBaO8h*kxj7c%nbpXBb8EP
zfT=c?Lq%lXeQc3Xr5F6!0-I2+Gj01J<=zZ5Lnxssq-8m>3FS0NYgtev)acZnImKks
z1T<&*7+_`r6)^@5nXfnC;F(3dUVmsKDiSL7S{|5OM4p=fJucQ;^7wVEEj=4ZUe}0>
z5Q|tI+I4J45oykZfwtYS*oG>|<(cThEDo)8#<H-;gxL63k#^7QVyFl@wsRe_d7VIV
zu!AdytUQ&L6bgtHjJTlk2yuwzh&>Ax@>Z6$l2fwK)Dj_9&Sa#EYMjFx1lg2@_D-^m
z0fXj2L(FTtS9F9sdTC>zYb>o?56R4IG-)Ew(m#=9DPfMo#MzKd=U8-tmSR~Gd~<Xo
z6BEFh$<A!l80FLAo#X}1XdN=ecI(h1IVRZ@gHf#}#IrK};^`N%7}KZ#gwl}^&G8A9
z55voG@v2xs-xlW@<AI<~nj7(aI%hDYxCo9XUu2`%>9oE2zr--JWO@!NDL^V09|91g
z=ixcd;F0rlP=2%|UU7V|I5sYuhE$^>>M1fxAVJ@{^RXf<9MW~6Txp!anpSpn^+s0N
z4H>5R$-pRpF3d2<cv;LL4o(y~aW+qWPaDP3U8yddV=cxd1sx}rqhG9`AF$F`7DL3c
zy0s^~s-wHN0*dHkg?iN?)qrutk1P(OGa_np88pjwudu``1Zx-Rc+)kon0Rtg)ts`j
z^4Nz45TRcxd^MD1PAD&{DND%=W|XB;ZgF`*@dVYMnw6GW-5yMH%0($D851((3?(fi
zO-?PqB1bOHLp4#l4p<BTpazs@HcnCTmh<I+RPm?jYgnHOfXO7mL(fVs!w8_w-L8Zg
z@)R(1fgCZhpGfqM$BGDOz-KX8PLMT=T%3<eTy(|az>QSLCV2eR3_>{lSP)YHUoKgp
z^iJ|&K5|Wl<xVeBr5B--q$)9PvGP?g4ay~GJQr_#3RF0S_fU65E-65c5M4BQdL8A2
ztV%h<u%E`7mKMtiYrkV~#~jcmQ%t<W=s&U;Jx!>TSH)D2b}yM)h+N;Hiy*HbFQJ9{
z;*=Qh%9uQQu~i9)y3xdJn@05&p<Gp<;jEuLQ;2GofqRI_qNc4cY?erTwV@n+Y9*xG
zLAu2_<j`cja&!0K$-$SaX$tfh-A6iY$Q7+Hs-R{ZYpziR<qWQ(0;&*uh8n&u5+v5e
zhO-@pb9u1`uK(bktg$v%;+P<?7?$@kd@7=UEbTmEnCaINIUTv9UTB1%<0M|Ff!DVy
z@ybD|_&g@3UYEdm7%m}!VJ2S{_qKgB)o1ePHz}Tks&wo0fJC(1lh7=?I^r=VAfF=2
z_z%p4%o<%h>t@)Pc!oLma`IL#G|df7OAN6aWYKlQZH&x-*;5u(C`=%V^`=+q5)l=Q
zKqf%JOt!as(fN!d;jIjhH!=8g{8#)w-Zc6L%JydzEyK+w>fusZh%ZGctRBNO7D6fw
z&PECi&O$N`W+N*NPD2t6Cd0A<fgf3D;6Y{@IFN}3B}kw_9(l)&^57JcNz5Ju$C&Br
zWVK#(szquhoGI>8q82a5WWq4Qy{iW(Sj~ZQQyvQfEH#N#S0c4q=h4)v1m#TRb0qRr
zQl2i)PAQ&;5)}zvxlToCb!C)9RA6a>DoIeqIz<~;1Qe$?%a%wj1S;0(0?N}<^Yv6J
zIge7%1m2RH$d{AIm(4MIGp3-UDQQ7~!j#oYv$9Z`rA$-&ii>2-MYD5Nlk%DJzVfQ_
zOXX2zk8-<008{z35>+~2^d67_OBA9MG!5#29HjyYsxd+N6O=DOHBg)@4vN+%xOGX~
zT1rRO_C~tedb~-rCy55M%wl9Bk1a!m!MMmO3c(onAkO57j#3&aI!YOj>`grv{S`%n
zrj3lcPz<O~Di2tGZMjY5L=zld!isDONHfKwI0L_h37)Qgrrr(bVLu#VHD#)}LVizv
zO1{UEBlpQove&#%7On4ComNSDS9(giL%LKd6Q36E60bIWXkKJ~)4a*F(e#M9L^;>8
z!upUkYMlwzO8@#_OyNxA%GF3ETh2q}reGc4oP{Vr?iBU$rE%^4nNAa3h<h4I!E#iG
z{A3;kEj~T7;RMINd!iB=D)?!6qg`@><1loj*NbL5CB5D{8()`4Qu<Jac3YFl)Kgo_
zH$l7;*<l%vsf@@S&@vC1+JS13TMvX9J=>P`$gae*xhMz0C1Qn9u$su{qkL3F95ir}
z3(iMn$Po)F$@S-hP&+BS0F}eWT91{-Vr6<Dl-hW2fqv6VZd-vYLdlSL@sN1Y;5f1o
z+X_^V3S&Wm9*_eUpyH^Vp9Z+Kf%^}J{o&kY*i`O`^1*-_`EtgYFFT$uBYxp9sN%ib
zSD@uwG{`qG%17!A!k0>k^zX_w_*v5zxXsjRo-Uth*{6PC`jzQ>Cbzjp_=9kz=nx6t
zWbU_KB)wq%H_Kmy-PYY=i&|-Y(|R($S$vK^CUNoyma8obEH?AILMgvrYE%{p3$2R!
z3+#q#|6FyMe3`Oe{)yBXvsr4iFL2ao>rjw9x*B;=fXrJ1K_juz0L&ADW}lZ|niaoF
z82b`)Oyh(xPc}}Z&1-U!*RF%(L0t}S&qKt!h0Q><<nS6WKrh*G5vmnD)ZDc0GZSX&
z*7>L=7P!bE$YrWdDqlqk)<VCWWZqij13SEm29;$0S}+oOET|you7g;)9*`~PqXxmp
zHy7x$){9EW*Xxi^D5fm>a-m8qT5J}I^eBD4pmi>`2)25DX#su1;2?)CMrKnXjq5KN
zH1`q<Dj>=wP(!|MjnTY1z6n-0y5Sr134>v6xq6Gnzcj>eyL0q*#5RhC%FY<|1&>i#
zwq7cxoH5_q?CrV)-ORT<NNuSKKgisPIBOXSS)avA)&CF=aqn`CDpn5QNAU!8rTl{R
za@i$$*aF2S9kIMA){B>!|76)}nPk3Em?->~|3J9fJe}Xp&*W}q-(+uKXG-f#<*?TN
zY3r^jmStvmv;dnl?N|Vom+vB{=uT#72j^8vN=8kbM_`?*)SBj3bCy&WNx2LyL)E0~
zGE@y~)3(dd>7sMKc_OG8<V{^r1g{+`t;df$l6cd(<Hsw>#4C`GK7DWq_Ic(>OUbb-
z;H|=A3oY;j!U0PdBsUA?$ti9qRz^O!0?nm(%0@H?ObCKf`XIuIigg+uL{vhyqF7|k
zVp_GW#k>@Z2AcEwVz;(uu^o7YNxVf6FGz~lXx&SwkbLs&ee5hDZ@zh26FIh<O`l@C
zMWU<PH?p$h$8#5&r;%N|*^E;RA+Y3qW3xMcJm)O)G#D#r&9o#zgAH*^J3M|oJ0Yev
zNz8aH^T<``MH6h>7$>o9M%m=@JuGbcAui%a88FDt@G<-jejV;@590&)XK>fP3kw2=
zQCNHY&!=XJ_*Mpg0=HMM!Tr@!ct3s!E)H*nT$kgh!~rZr-$NV`2T02RX&xX=1EerO
z@&hC{K(Znyh`QWElG4o}<upb)P3cx{h0o_nAN2X&-21@`(<fU3J>p%jKhF~A39VJX
zju$YH_4E>6fWtCt(q07$_W$Tb4X)qk%Rt>bZoR^J7ya8Pt`qD7h7>Kk>1yQIduSi5
z)s>kH!V-fec%yd04{SnTQ^}Nr$Qp${Fz?1s{PcYMN~i{o($ELyH{CVH(Xomi`=1CU
z;!Bs&15N(`qYApk+&*XUqt5vC7W9F+YS{ffz59gblN%4BPKWv;gVY0zdSI*%G<>J3
zUtZCMqe|o8-IlnrfIgs9quu&#1ntZ5K^)qf4+e2)cYZgBLpyX}c&lO1X@B-~rN9%0
zK|2c4{wms5AV0|<`36S5L4H#HLjFSONdD~2eGT=>ME(F=B{UzN@#)4xIzIr<1q}z&
z)=fw<bif{_JJyuJieQQUj!%1TyG-qhJx71cr@!lnLaW)5#JhwsH?pHD481(sh7AT_
z_^8BmiGHBLK39wGFz?;`A-V{0LG@K)K8iYIczE$w^+WX?^$qn^P+?dt<T(Zf=~sY$
zHPSCX{qoVThP_{XjgF*nE#lYY2xdzu@#7ShFRGNKhZ(#|eL-zf-d3)JJLn(FGpt9f
zE!K4DVe29566qs2G6cAZPzmPJHm`X+js|S&W*E~W1K7KRL_1)|+5(_^#W*o`15S5n
z{}9Za+zTi?84DTzDXGjt1t<nto8thrj!T!01D7WAvXO7Xh@dmMD;s(L*|@Sbfh))G
z<T>OFz+kISh#j-2#}We#0glBca(50o3B|zMyb}Pngv~{c=tZkS-C_*5;dua4jSq!c
zDXt2zYI$)=rY(-CmS?2J5Y@6Xf@#@+re;VPsck<s5U1I&Fq~8D8S`;$0@*s<2H+7k
z;CSO!E7l$kP&ET@w$Tm(>XkF&Cq`YFP}elULtVoX*rHEjo8ZLww@K`5*$wa1?RIbC
zojQ5yF}Mf1Y%&{!&HBE{Y!`A7*A#XI?8&}Ag>7fgtI~epfp@`Ls<#EMbXR%1<w_9Y
zcH0L;Z2A#fq?Oc8hL<s++HLSM=BwIkems>m6<H$Gorl#AG}Yt!_7??1eFAlIBd(UP
zihlcxf-z4xvF+xF12|45j5GZEr~jg0Z+<)bwpgNA;I-l^aDoe!pDWAd7v%G-zqU@1
zekf&$msyU%-SX4g;gmbSy)x$DD)`$g<M>U>|LrT|dTSpJicE8J7W^hc+qKO}esc}m
zECqnIG;1YXFX$U$(ta%)0#NK%*RmRbV&`mzz(<a5W^Y)U+K|XP?o-t`Ps5~mGdlrl
zePs(<G)b~{*29kirsXxmJLb_(WFx1L;1<>=)fxR{i058*F{#)LUiFK)iellLYDK2b
zuFEE=eSnXhwuP+%?CruW>=v$1_Gp*Ry$&90Df2d?8u)I|4$WJn(nE`jd7i<K;Inat
zrp~p0`@@vj&jY^^_VWMrhbeo1zm_dCw@d6yCWpC`LHp%3O2=Rnkv(!E9PyuoA_`U9
z&CK;==Vj=WVMt;T3G@Nn=uHL>`I*f8k-<Z0ov_hJ`G<ms(mM8?IKcR?4IWDCkoGSC
z9`1zaat!msz3Vrj`2sn(lWjP)NN8m&Gw}oPBZCR%JJkK^1!|V^1pH#EQa&PID^Iol
z*}B6zOZrs0Q(9&!GreJc+kC3fDm-DjT>M(xA)aLUo#kRc1#$&)_Xd<2I~09%7wZv&
z&1P^lfd0lj&7!;68ZnUI9ln-bD5Y8(;|v{nA=hnYt2xE$C!6kNo1;D>^WWS5=of~P
zwc!*qxE;|l3L@j8FBC_1JM{Pw+e7!%hs@w(!NpR9W|_}IUfTfA?CQu#dsw$vI~3do
zz&k&QHxvNZL2>}V3(2}oC`1n2!=4ML&+$R~W`OpSL3<s}7b=ojgQg;d*a^Fvr9Wj%
zAom8cuK|EhCT@h=01EL7#R(*SssUQV2z+BCJ^_9Ioe=ayV?a^kM9_^3q2tH1jC+B^
X<pNcA{LSE)0N;R|95Qb=``&*8u(eEs

delta 9734
zcmeG?3v^UPmapo)*RS8FUgiJqba#H;=}t)JL&6`%Q4v9h@RNWcgwQ}FB!MI#B7}@O
zf{vs3R*Nz6JL?ER5!Q$qM-d%Icm1PhcN~}*2S?pe6vXv2AAfu6bzUcd(KG9rJ!kiv
z$%EWmx2o=~x^?Tmd+*EUliKE!+My$5V(lWsdZG;Af+^O2l}$^3N{&irrS(#ZxCQ?O
zFG6pic0`4Hx9ypOmlrbMM7%;NNUKXvPOh}x7@Ni}z7F}=(-U!llAks)wX(93)lR@3
zMke9QP##-232#Jxc6<`<b@|d7Jmbf+*C*jD>(A4C?4ikchPy}g0(tCMo6P=l1M*pW
zBhyi?^-*Lg@>uiB*P<Nj<?>FHZCzMVuVkf_rv?H6E+f@CQZb=Fr}`arL0An6X23j3
z){|rO7j%^xG@jFHXd3;%++_Sf|AV$feM+6J9ne+v4*g4Yxz=rzXumdR84L6py@_0=
z>FV$FTgg4<Df%6{-Pmbb#wX-6;@2PTe<k5Lw>9>XP)0ae45MYuEzxmZ(T2vR&bBq9
zR)k8$2DW(}3Q5HrtM5c1IhZYuN33xIPDcUj>?L7TWaUf?ONAk^j(vC?3P=Sx;zU+^
zJ<3G+)@{>DQJ(cU{PtV#Pb-yuzy`4oZ$QP8H!Ln>+d5HD&IJsylh@z?C}j7gVJU}q
zt-b~YrR+4ZoV{^BPVWC=x+$Sz%a~al-tMkZeyMaR0oQTY&8~^^`|@4#IO!c}i!@sN
zy?B>+0e%P<q3uW$Hf-CIE%q2CZ2l(vBQ2~7b#>Xx5fZEq$A(#UH?Gq{BWZoz_zJy8
zFLtO_`K|!FwFi~5!<%ra=}zp?gHE4d^^6Z&ch$}ZJ$zJq1?XY=tf^X|DvWRN2=K#o
zl);|fk0W|*!8z27`)~v=%D3K|U1PP+4$66|Fma)^XO4#*xevS96QD=D$Pe8OvTt}-
z8UCKv+A(J)*w2|cmw~#@%qg%I&n*TU0*oEJ9|!S_Y@7NyP_wLe=G9pB^NLZXjXe%n
z24IWjbX6!{Xib@$&KBH{%lhA%pQYen$%BhOrg>CFVmgX0T^{YIBCrpIqzd#dT5djL
zE+nVO29gR!^Ob>@Dptj{3yj+OGicXOY8NHpRW57$wM}tCqSz)|%EssrL28z)t2Z`i
z&Xh#edS+9j8gE*W?#07eKklyg#rsr^FNO99^ke!KeT5#Sd+BYor$5oRl3LxrF(m~|
z#p?My8M&<77t>8SQ4FBA_UM{Mu;dQwg<D4#>URi8zevz8`lbi==GF1#)atowrY@~)
z$W8})DNhzy&pI$axwi-<StY$QvG|0wsdt_(u4pLaBLc~Sb#_{@<-WTJQLF6kdHvIO
zJc1X5&4@tH(Bp7v57Hmd)$~fx<F#gl{)zTdkNJW51GC;7M`iO*=EG*6dAE71In(?u
zY%GbsNnfIm(0k|xx{TJ+@wCW1ZoXtbWv(`t(TmNuV4bg$ZWT_dsim=_BkUGa?b{nN
zL=Rfl)!NkA+}2t=yb*MU1T--dt%`Q8Xj@t|gcinm6*vR)hfmKN-tfm7lVW0g!@Img
zEOUoY&k&l!(T>hFT}}O`A4o?F!eqZd-=i~3g+55T;Arz{HC;mYkp1RkaM&BnPwB7e
z1aMs|=oZl3M02sp$XB$Fisl36F7s(KK%XH0PSecS$j@mp`6HccQgV{?)9s+68N@pH
zg1bCyiheZAuW{p8)79G08C})h(%2bYTC9uNsC`XaQ?#QaIA}?k0Yywk9nsDr4wpwe
z3pu=??dk$<Vd?p)Vi|(j&8-cqqN|of*EBRWwzT9~PaMeuZ`bx>Hn{q)j$}>n4$jWy
zYj7-bVZDcl-gq;d!*xC{+EkG}!fyLteY}EeXg1f-e^5Ww$<N3EvYY;dZlg2l6#6{v
z2P^s=SkNbQ91W4#W{-KPxyqamnww`HrA=lTIcp}HFVGukhk4MviJTxC&AZ7;@^iA4
zTnQTb#Q63a$`A092aSvy$JG>Xd|O>z?&V71Y8W>Tc;u#trGu?udgJe@*bs;Kwc2AZ
ztwLg$WLwIys{B^-N>I%hv&c*_F*!?KC(n=v$em;pSx#n>u_Q#YK^;d7?oE=<HJCw@
zkcu6|F%oe8U<}~=`R_vew{0HQf#23FA90qWn%djF=TUOcqj=7v<eW!2$4WN5z7_Uq
z_F2lwD_{@P&HlbK3xQ(1Y$<1}@~4=kW~M2V56N%Iv*a+@L$;7sGKY*Kc|<kN8YhjH
zVb*HH3VoiC8m5w89e!6bq;kX^t4k_&P>h4t#?N^GaPadCoLB@P6E+VG7cR(<Dpkw>
zVoG;@vJ^mZ6Yt>rPsux<mf%01X86vhxxMGp<lOUVk|#zhbDTdHEaoIh0d?eJvPY8o
zFaPr4xHoeA&J6H83iuxGnZCyV&{qaMQ2w9~s<yq*l9(R?Kh|%1vY0nwr3C$5-O-Z&
zJ$JPBJa;tks)@=_srDm*ikd(_(GJjN^WV$~<W;iFIAyHV|ERCi-V*CXP23rKq*Gv7
zzrpyDL+r6!RMs8FB9dcoER2!VwXCfzY#@XY#!{g+>Hf{|gCwDc2T;|nh#iN9Ao4>Z
zf|(MJPeU*ftq7SiLK4F8uPYid#X%kks&UJTCkDCn&JhIHet#s=6seAksi|qIvBqDX
z&b~}Qm&mzT#9nLjrC!;CMKPD1T!C`g!<9J5a21};wk08-oMVsqVy+i?*=I>;4Lh8S
z3Rqw?p2nu8ATP>hEu(P}+dUe;ZiwLfy|5F$B(|{{=dzvEc#<->a&}`H8c>z1+gqBO
znmfI0LpqwsKCQu2b-`{#?(5h`>1a#=ay74NZ(Gx;V{BlIU9C+mT}z|73rX1EzmRKH
zlpV=HGZ11qnLGi>L^(M*F%^nv5MqE_VJhm#V!fG=z;ukoem_DTNwE<anK6ZlSmtly
z&LoUgj9Eh#N@Z`3#YwV#_^dArg}Vz2oTmV=(FJLRBsU?=n^KTiSOEVMlZcsbCe8CC
z<rx_%1fE2XK27k(4ssbB<O+Xebk*3#Xk<*q*qZ8^=;+a!D75n<#w09|1jK*fP~i|k
zUvRE2gcO9_2&o8ZuwotYoe9FCeXQGy%A&<!3+{N3!!-ym^I~Uf>d;#qNL&w6AtCw;
z!l*^IOf4vA-z-xQF283p^Jk+`-NE6af*?w9qJ%+lz}xt)5T0+dRs(|i4Xg#>qTPeG
z*<-?liE@O;3<1Z$F>Y@U#0{HU``l;%WDe~p5Vv#+uKQ^rILnsnE)v{dCsz<=-|Ywu
z!RYD!i1p-b->f3onF#Kq$OV^=+m#&<a%I}@a@#&YbDB;r6bfh9Vw6Hb`Kw|;#`evd
znI{L8E-oD8TWIs;wp|!gmFNg5v@bg${X*WwHeXkP;5whLAYA-U&cYL5++-=jy&c<<
zgNnNg;BHDh@+|;nq|o#U-YGUOIbV>^;Ux%DZ*v$W#TdaWA%BFTqxnNh$al^IxgAr=
zkL%r36U~D{C}*54P0ACb;nD=5<%f=_D`7;FKXT`K<ZH+SrAT&s2)eM{R@{E`VuE=D
znKx*!NVelj-i&!hlO)jDLS~gMQ}hdBT&5uOh+8(Z8$4jEen*HOCdvrQ$Q>PYIh?{-
z4P6^QZ#WSY@3vQ^w6`_4c1G85LhR<4NhFE>UPv2d%f>zd$7Bn_n(LjNu7JK~Kg-EQ
z{%)VM2%p0<z6eekxd<ODLha~U($Tc0xxJJ3$AtpR<e)7Rc>y4h3W=$Z5neoPf#A~U
zc7f1s0{sj9h`vwXrmxf2=rQ^%P5e21ls-fcKztl~Zh{nXF>P>3$UuqM1_>A#rXtEg
zBQiNyfJm&*hygtYv=~rhz#Rih47g%IwgG#$3}r(IHj60{#AC3JNw+&J3Tfch1i>8w
zOcF)Fia8B~NOv&a8;JK7*)-l;7{?0Y<MQL<@;J@r=jWIt!3<xV=C!d(E-sg&h%@xW
zv79)TZDV|aS%8Tc@0BK_#DprcP9S|`7rBGnOnS&VmNpa3NPvRT2jori8hM@^H5Jki
zn^XuZtw-v_Dm!-sPu5Wx$137jc^r$xu`-@-#a?ynk$RL{9lg3U+PbtO%;|%8Xc%ti
zXM^<M(A<H<Md%~cQl<0==3Mo-`84?#wL_g^it4=(vNaLIeOx=G-9}UBe^N#-G5>7t
zHMg2I<ZWV+DVkxtXFO;0xgRmM>d)!>^_%po^b7S|?HAfg?P9H1dDmU*zCr0x4!b>M
zk!l!o46n}PnM8%vbt049v<~?-zU!(=sUaP))st|si(m4NN_J)$s+21@-TGi!h|OG%
zWLJ4?7?i(4DjyZGyU~o0W=|^fN|o8Hb{|f$cGtOF9iu9wx@`8w?Kl88$kt9NYgvIR
zQ3>0<0#%@}4O}5U3|Vi?EFy!$ier?X@kP$WAZuwxIVixk0&o=-NaH=R8lKtI*4hav
zY)9b`O?7Am>})fL%V(ReLWK}(*e!po<+Fk8^-AR)yFzzo3v$c3Bb%NPP4>=8D3x}v
zL{%s&1~P3RXN(v&u&)JODYjI}Hwxrq^LE!Okfq#AUsR6KrAm$4V|-7w%+Hh^%2kTw
z7F`4Cms*Q_qkD_K&RwhitLr-b0d2Gy)ZdmL)&AM#)qZ81Ru`$o?vLF^UA6LQosfCv
zGqen<pjl?UaUD5o{8YaH&NN--XIhD>*e#u?996QT98|CmIVg{{BJ6=K7*fVYt%K_3
zDE4_53>edl3^r~p3dki~?N<Bu0_>Kx5Wj?3*;+WIPz)5a&v+|n&vgYVr8<5B-$$cR
z5xaIBs+J3@r3Mc#v4*Y4Yz5*>@718Fd>hDlRnkI_<((E}o392n`$se(yyGY1@^TI_
zD`dX){4_YhdU9IG+C0~dJZ$lLRPD-%jRGSqhXD4a^{C2~#o5^v*dU8s153|jW3B<=
z8TRoEtlfZalNP@WUQ!6tm(izqj$VKt)L*0v&BJJ{dQ2WKZH1D{v*37B%{Jqg`t?Ss
z77<&CS37}J_uFcfdY$WsO3*dQb;A8)`Lx_Cy(?9VZ;HLbUc|KZ%39?$_n2*azN0iM
z4RDW;1y{nVuXbB?b$JTEC~m2YUAhmKfzD6dj_aWu`(+<qq?XhxP|$_g(W&PKby5-@
zL4<;CP$VfK*4TsUQ87EpL6CXAk4oS+)bGbr)uLGnRBVAuykJ|Q7LKGrxwZmM<kWSj
z8p^c+@vE=$*^c`lSAaroF<cDjXaLg&QY{?D2lwHbtm^<SU<q*3A+0!lJ(R*1&ke#n
zkKN#f+7QZ#b$o7jWU~o<crjcI05#Upd0a>)Z&b5G`(SVen{q#%KJeBS^pcA`xC?v0
z<qIKuBk6%yZS;8o%0YjoAJTW}8&Gn5r9W};VJgcaMNQVR52}(B`j9|Bg+kIvC?!1y
z71W2|)wq+god=Q90EJdX6Cw77T5kOr*AOZXq0$fv8J;s1tD>yNrfKAefXM9vxt$y#
z?~(V+sm?Qydk6){wnMf2TZ2p?^8c<~QI#PK#;LaFl%d#+{=kkMLB+BG=p($KD(isV
zY=1G3VV9`>&aJ3;;Mn7El?tW{h)x#hWIFxpAGq0>lxZ&`eJThQ4i5(JJoxTw90jo{
zuW;{bALRr>VUR4`+8A#ytcL{%n}!Hsw(VuqUPuiAnO_Lz7vJ=N@YhUUPFl!if9%AP
zOYK4-uS)P`{MHd|7fASWo*zNs3wmS(g|BFDoWhp<4)tb|$)I>cAO@LCy5M=!c?NP%
zqE5p)nXrl7{ywU(RsW>@O@|EW0^b~S8=9jMe1+{c4)yB%D6ogW!=ScpxcG7WKK2DC
zVVF|*(d@IYZTAjk;FdFJ9TKa|FPL%`HG>vzF$cc*5}inZZ*dvy1jYFrc{l+}zMzZr
z3UoUSn~#|nkWWaj=_hZIH6+<MV5~O$`jdL2?$UlF?gTDt#H90cd#n6%|35N%9@+ox
z8U2M$J`ef(-<r{{e#{B>2Qzx>J9qo$d!1n4DSZrO9Go&T*!K?4ICytF)}QlJhj|Iu
z_6$f+6Uu$#p+plajl?*`)5l!kBk}q~F3&I_|JLgsa^_dV{91p6CH7(86sYVtDW_++
zY>&gx=HiKQ(Ua;9oy&z+fu=we$l;PRoJ+juVspuHxJ--Ju+m^H7r<T`D|{{4oQeI>
zqchuCe)gb-q(Xi4K3jCGDpDpzz&B*YlTf?rl?AiZ_@&PpmX0>u<1G6E5O@V_{?Oyd
zH#HL^#&gU}n60%ou8MZFH#S9=W)3RfuAA@%KPXUS%KY69FP>`7^hX+5`)Hgu4=GJ;
ztJ=FdqZy9s;;b`(HE!+5i0wa-tc({M766MSa%4$kM>IWY&=@2U`Ic5y)I=+)=ZD#&
z<8Yl4N(-m@{eJtCH;atN<w`MpF%JaFStEQ&XE(2d>f4_2cpSX8e={Dp!fSi_1l$5)
z6MU*qVJ}R;vmTy;T|W1{0t6sU=4s1}l>Yzv$Ul&?48NmlCBg=Q{){f5DV8}i@Q=^j
zfA`Pa5Ix}>C4;|X-TE$pw$fy?hnyyL#?wZ*z6)M4H|j<Ytx^RDL;2qc*dYolT8|sF
zN+2#wZ{tLs=CPly$BhvEXI+CWNDm$Wphbp;@V{_ise3VGY8#-QOv~8uYw>LmzFxHv
zFVsryKOwMrC9VQ{RxKC^e_)WvDmUT0Wg22aIvNW_9%C(O{yz|JtEFPA(7*$2*0>3x
z|0MleM&5EzdKZ!o|MyYw+ehCDMBj3+FpKTE4?^r=5xDHv)=Q%~`Le%T6b`~Nwe@H_
zo6?6X&W*(HKoao^_pv>FxPIWoP3R)bgYrvR`43TwHMYKNVA&456Hmx-JtfeGX$yQx
zI&JPWYfTZp!7V45#*4<aMo9maeuG}2ol<VlZqkCTr<6kFZS`4og{rvkbzcNFd7X<b
z`3Y`Rs~QxrKz<000hVZ~dgUOM$7^iHHMm4e)GHhsuROrt)s%=tFCURhoSS6u#A8Pv
zKI$&{D=8QqOu^#v9qS&&uH26=`5z=u!*ix#$r3ntp4_1HbCaXXoa6~|B)0W_T*R{|
m7i3X0lu9;b3rb<7E0D&j58~&X{Lp&~q)IQ{3Re@bOaB`l)TGe>

diff --git a/reference/golden/cpp/edges.json b/reference/golden/cpp/edges.json
index 565f471..985865e 100644
--- a/reference/golden/cpp/edges.json
+++ b/reference/golden/cpp/edges.json
@@ -23,6 +23,30 @@
     "source": "file:namespaced.cpp",
     "target": "file:base.hpp"
   },
+  {
+    "col": 0,
+    "kind": "imports",
+    "line": 1,
+    "metadata": {
+      "confidence": 0.92,
+      "resolvedBy": "import"
+    },
+    "provenance": null,
+    "source": "file:namespaced_member.cpp",
+    "target": "file:namespaced_member.hpp"
+  },
+  {
+    "col": 11,
+    "kind": "calls",
+    "line": 10,
+    "metadata": {
+      "confidence": 0.85,
+      "resolvedBy": "qualified-name"
+    },
+    "provenance": null,
+    "source": "function:87a31607b9531ae0a01b03caf6c870aa",
+    "target": "method:88f7e34ca2546972a11cca7ec68db568"
+  },
   {
     "col": 11,
     "kind": "calls",
@@ -374,6 +398,42 @@
     "source": "file:namespaced.cpp",
     "target": "import:d427e262bde770416cf520f12c124a85"
   },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:namespaced_member.cpp",
+    "target": "function:87a31607b9531ae0a01b03caf6c870aa"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:namespaced_member.cpp",
+    "target": "import:eb20b34eecdb66508650588ab6131af3"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:namespaced_member.cpp",
+    "target": "method:88f7e34ca2546972a11cca7ec68db568"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:namespaced_member.hpp",
+    "target": "class:2e7e24e7488b3868c5b2924a018549c9"
+  },
   {
     "col": null,
     "kind": "contains",
diff --git a/reference/golden/cpp/files.json b/reference/golden/cpp/files.json
index 18c9c27..5f68468 100644
--- a/reference/golden/cpp/files.json
+++ b/reference/golden/cpp/files.json
@@ -23,6 +23,22 @@
     "path": "namespaced.cpp",
     "size": 102
   },
+  {
+    "content_hash": "e4419194da0741856b7b23dbc977893cdfda9a926201018b685dce64efbd1f30",
+    "errors": null,
+    "language": "cpp",
+    "node_count": 4,
+    "path": "namespaced_member.cpp",
+    "size": 191
+  },
+  {
+    "content_hash": "3d4b5ad9e00d6934eea58bd6707b171b7a335458df91499966798385a5d09ad7",
+    "errors": null,
+    "language": "cpp",
+    "node_count": 2,
+    "path": "namespaced_member.hpp",
+    "size": 106
+  },
   {
     "content_hash": "61ac8b93b7094d0633203791513f3394c7f76e2993a50d75b9f8e32454dcccf6",
     "errors": null,
diff --git a/reference/golden/cpp/nodes.json b/reference/golden/cpp/nodes.json
index c337218..c5c608b 100644
--- a/reference/golden/cpp/nodes.json
+++ b/reference/golden/cpp/nodes.json
@@ -65,6 +65,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 7,
+    "file_path": "namespaced_member.hpp",
+    "id": "class:2e7e24e7488b3868c5b2924a018549c9",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "class",
+    "language": "cpp",
+    "name": "ManifestStartup",
+    "qualified_name": "simulator::ManifestStartup",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 4,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -285,6 +307,50 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 12,
+    "file_path": "namespaced_member.cpp",
+    "id": "file:namespaced_member.cpp",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "file",
+    "language": "cpp",
+    "name": "namespaced_member.cpp",
+    "qualified_name": "namespaced_member.cpp",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 9,
+    "file_path": "namespaced_member.hpp",
+    "id": "file:namespaced_member.hpp",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "file",
+    "language": "cpp",
+    "name": "namespaced_member.hpp",
+    "qualified_name": "namespaced_member.hpp",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -461,6 +527,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 11,
+    "file_path": "namespaced_member.cpp",
+    "id": "function:87a31607b9531ae0a01b03caf6c870aa",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "cpp",
+    "name": "run_manifest",
+    "qualified_name": "run_manifest",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 9,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -593,6 +681,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 2,
+    "file_path": "namespaced_member.cpp",
+    "id": "import:eb20b34eecdb66508650588ab6131af3",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "import",
+    "language": "cpp",
+    "name": "namespaced_member.hpp",
+    "qualified_name": "namespaced_member.hpp",
+    "return_type": null,
+    "signature": "#include \"namespaced_member.hpp\"",
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -747,6 +857,28 @@
     "type_parameters": null,
     "visibility": "public"
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 6,
+    "file_path": "namespaced_member.cpp",
+    "id": "method:88f7e34ca2546972a11cca7ec68db568",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "method",
+    "language": "cpp",
+    "name": "Apply",
+    "qualified_name": "simulator::ManifestStartup::Apply",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 4,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,

From e95072c61f8a85ed1ca5776bf5b9233886dd4f23 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 05:26:31 +0800
Subject: [PATCH 45/91] fix(c): blank leading attribute macros so functions
 index under real names

---
 .../codegraph-bench/fixtures/cpp/attr_macro.c |  19 +++
 crates/codegraph-extract/src/lang/c.rs        |  93 +++++++++++-
 crates/codegraph-extract/src/walker.rs        |  83 +++++++++++
 docs/equivalence.md                           |  24 +++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  99 +++++++++++++
 reference/golden/cpp/colby.db                 | Bin 176128 -> 176128 bytes
 reference/golden/cpp/edges.json               |  45 ++++++
 reference/golden/cpp/files.json               |   8 ++
 reference/golden/cpp/nodes.json               | 132 ++++++++++++++++++
 9 files changed, 494 insertions(+), 9 deletions(-)
 create mode 100644 crates/codegraph-bench/fixtures/cpp/attr_macro.c

diff --git a/crates/codegraph-bench/fixtures/cpp/attr_macro.c b/crates/codegraph-bench/fixtures/cpp/attr_macro.c
new file mode 100644
index 0000000..7b361a8
--- /dev/null
+++ b/crates/codegraph-bench/fixtures/cpp/attr_macro.c
@@ -0,0 +1,19 @@
+#define SEC_ATTR __attribute__((section(".init")))
+#define VOID void
+
+typedef unsigned int UINT32;
+
+SEC_ATTR VOID GoodName (VOID) {
+}
+
+SEC_ATTR UINT32 LostName (VOID) {
+    return 0;
+}
+
+UINT32 NoAttr (void) {
+    return 0;
+}
+
+SEC_ATTR UINT32 *PtrRet (VOID) {
+    return 0;
+}
diff --git a/crates/codegraph-extract/src/lang/c.rs b/crates/codegraph-extract/src/lang/c.rs
index e4e16d1..5f1ac1c 100644
--- a/crates/codegraph-extract/src/lang/c.rs
+++ b/crates/codegraph-extract/src/lang/c.rs
@@ -1,6 +1,9 @@
 //! C `LanguageSpec`, ported from `upstream extraction/languages/c-cpp.ts:98-142`.
 
+use std::sync::OnceLock;
+
 use codegraph_core::types::{Language, NodeKind};
+use regex::Regex;
 use tree_sitter::{Language as TsLanguage, Node};
 
 use crate::spec::{ImportInfo, LanguageSpec};
@@ -80,12 +83,55 @@ impl LanguageSpec for CSpec {
         include_import(node, source)
     }
     fn pre_parse(&self, source: &str, _file_path: &str) -> String {
-        if crate::lang::cpp::looks_like_cuda_source(source) {
-            crate::lang::cpp::blank_cuda_constructs_str(source)
+        let blanked = blank_c_leading_attr_macros(source);
+        if crate::lang::cpp::looks_like_cuda_source(&blanked) {
+            crate::lang::cpp::blank_cuda_constructs_str(&blanked)
         } else {
-            source.to_string()
+            blanked
+        }
+    }
+}
+
+/// Blank an unknown attribute macro sitting in front of a C function
+/// definition's return type: `SEC_ATTR UINT32 LostName(VOID) { … }` (a macro
+/// wrapping `__attribute__((…))`, common in embedded/kernel/firmware C).
+/// tree-sitter's C grammar reads the macro as the declaration's type and the real
+/// return type as the declarator, so the function indexes under the RETURN TYPE's
+/// name (`UINT32`) or, in other spacings, under its parameter list — the real name
+/// is lost and the symbol is unfindable (#1311).
+///
+/// Attribute macros are project-specific, so this keys on STRUCTURE, not a
+/// curated list, matched tightly: a line-leading (declaration-position) ALL-CAPS
+/// token of ≥3 chars, followed by TWO identifier tokens (return type, then name;
+/// `*` allowed between them for pointer returns) and then `(` — i.e. exactly the
+/// `MACRO Ret name(` definition shape. `MACRO name(` calls, `#define` lines (they
+/// start with `#`, which `^[ \t]*` cannot skip), multi-word builtin returns
+/// (`MACRO unsigned int f(`, where the grammar already keeps the name), and
+/// mid-line uses are all rejected by construction.
+///
+/// Blanking replaces the macro with equal-length ASCII spaces, so every byte
+/// offset — and therefore every line/column — is preserved, exactly like the C++
+/// blanks in `lang/cpp.rs`.
+fn blank_c_leading_attr_macros(source: &str) -> String {
+    static RE: OnceLock<Regex> = OnceLock::new();
+    let re = RE.get_or_init(|| {
+        Regex::new(r"(?m)^[ \t]*([A-Z][A-Z0-9_]{2,})\s+[A-Za-z_]\w*[\s*]+[A-Za-z_]\w*\s*\(")
+            .expect("c-leading-attr-macro regex")
+    });
+    let spans: Vec<(usize, usize)> = re
+        .captures_iter(source)
+        .filter_map(|caps| caps.get(1).map(|m| (m.start(), m.end())))
+        .collect();
+    if spans.is_empty() {
+        return source.to_string();
+    }
+    let mut bytes = source.as_bytes().to_vec();
+    for (start, end) in spans {
+        for b in bytes.iter_mut().take(end).skip(start) {
+            *b = b' ';
         }
     }
+    String::from_utf8(bytes).unwrap_or_else(|_| source.to_string())
 }
 
 pub(crate) fn include_import(node: Node<'_>, source: &str) -> Option<ImportInfo> {
@@ -201,4 +247,45 @@ mod tests {
         let src = "int add(int a, int b) { return a + b; }";
         assert_eq!(CSpec.pre_parse(src, "m.c"), src);
     }
+
+    #[test]
+    fn blank_c_leading_attr_macro_blanks_the_definition_shape() {
+        let src = "SEC_ATTR UINT32 f(void) {}";
+        let out = blank_c_leading_attr_macros(src);
+        assert_eq!(out, "         UINT32 f(void) {}");
+        assert_eq!(out.len(), src.len());
+    }
+
+    #[test]
+    fn blank_c_leading_attr_macro_is_offset_preserving() {
+        let src = "SEC_ATTR\nUINT32 f(void) {}\nSEC_ATTR VOID g(VOID) {}\n";
+        let out = blank_c_leading_attr_macros(src);
+        assert_eq!(out.len(), src.len());
+        assert_eq!(
+            out.bytes().filter(|&b| b == b'\n').count(),
+            src.bytes().filter(|&b| b == b'\n').count()
+        );
+    }
+
+    #[test]
+    fn blank_c_leading_attr_macro_leaves_other_shapes_untouched() {
+        for src in [
+            "UINT32 helper(void) {}",
+            "MY_ASSERT(x);",
+            "#define SEC_ATTR __attribute__((section(\".init\")))",
+            "SEC_ATTR unsigned int f(void) {}",
+            "x = SEC_ATTR UINT32 y(z);",
+        ] {
+            assert_eq!(blank_c_leading_attr_macros(src), src, "changed: {src}");
+        }
+    }
+
+    #[test]
+    fn blank_c_leading_attr_macro_handles_pointer_returns() {
+        let src = "SEC_ATTR UINT32 *f(void) {}";
+        assert_eq!(
+            blank_c_leading_attr_macros(src),
+            "         UINT32 *f(void) {}"
+        );
+    }
 }
diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 4acee61..4bbdfcb 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -5592,6 +5592,89 @@ struct Bar { int x; };
         assert!(has_node(&nodes, NodeKind::Struct, "Bar"));
     }
 
+    // ---- Batch B4: C leading attribute macros (upstream b6a05d1) ----
+
+    fn c_names(src: &str) -> Vec<String> {
+        let (nodes, _) = run("attrs.c", src, Language::C);
+        nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Function)
+            .map(|n| n.name.clone())
+            .collect()
+    }
+
+    #[test]
+    fn c_leading_attr_macro_function_indexes_under_its_real_name() {
+        let names = c_names("SEC_ATTR UINT32 Foo (VOID) { return 0; }\n");
+        assert_eq!(
+            names,
+            vec!["Foo".to_string()],
+            "a function behind a leading attribute macro must index as `Foo`"
+        );
+    }
+
+    #[test]
+    fn c_leading_attr_macro_with_macro_return_type_indexes_under_its_real_name() {
+        let names = c_names("SEC_ATTR VOID Foo (VOID) { }\n");
+        assert_eq!(
+            names,
+            vec!["Foo".to_string()],
+            "a macro return type behind a leading attribute macro must not become the name"
+        );
+    }
+
+    #[test]
+    fn c_isolation_table_functions_all_index_under_real_names() {
+        let src = concat!(
+            "#define SEC_ATTR __attribute__((section(\".init\")))\n",
+            "typedef unsigned int UINT32;\n",
+            "#define VOID void\n",
+            "\n",
+            "SEC_ATTR VOID   GoodName (VOID)  { }\n",
+            "SEC_ATTR UINT32 LostName (VOID)  { return 0; }\n",
+            "UINT32 NoAttr (void) { return 0; }\n",
+            "SEC_ATTR int BuiltinRet (void) { return 0; }\n",
+            "__attribute__((section(\".init\"))) UINT32 RawAttr (void) { return 0; }\n",
+            "SEC_ATTR UINT32 OneNamedArg (UINT32 x) { return x; }\n",
+            "SEC_ATTR UINT32 *PtrRet (VOID) { return 0; }\n"
+        );
+        let names = c_names(src);
+        for want in [
+            "GoodName",
+            "LostName",
+            "NoAttr",
+            "BuiltinRet",
+            "RawAttr",
+            "OneNamedArg",
+            "PtrRet",
+        ] {
+            assert!(
+                names.iter().any(|n| n == want),
+                "missing `{want}` among C function names: {names:?}"
+            );
+        }
+        assert!(
+            !names.iter().any(|n| n.contains('(')),
+            "no parameter list may be stored as a function name: {names:?}"
+        );
+    }
+
+    #[test]
+    fn c_plain_typedef_return_and_macro_call_shapes_unaffected() {
+        assert_eq!(c_names("UINT32 helper (void) { return 0; }\n"), ["helper"]);
+        assert_eq!(
+            c_names("SEC_ATTR unsigned int f(void) { return 0; }\n"),
+            ["f"]
+        );
+        let (nodes, _) = run("call.c", "void g(void) { MY_ASSERT(x); }\n", Language::C);
+        let names: Vec<&str> = nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Function)
+            .map(|n| n.name.as_str())
+            .collect();
+        assert_eq!(names, ["g"]);
+    }
+
     // #1093 NEGATIVE — a bodiless class in a language where that is a COMPLETE
     // definition (Kotlin `class Empty`) must still be indexed.
     #[test]
diff --git a/docs/equivalence.md b/docs/equivalence.md
index 7e6b957..d2873fa 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -281,7 +281,18 @@ UObject` plus line-leading `GENERATED_BODY()`/`UPROPERTY(...)`/`UFUNCTION()`,
   reclassifies the `.h` to C++, and the offset-preserving pre-parse blanking
   recovers the `UFoo` class + its `Extends UObject` clause (both dropped before).
 
-Four further files exercise the Batch B C++ gains:
+Five further files exercise the Batch B C/C++ gains:
+
+- **C leading attribute macros** (upstream #1311) — `attr_macro.c` is the one `.c`
+  file in this corpus (extension-mapped to `Language::C`, so it guards the C
+  walker, not the C++ one). It `#define`s an attribute macro + a `VOID` macro,
+  `typedef`s `UINT32`, and declares four functions: two behind the macro
+  (`GoodName` with a macro return type, `LostName` with a typedef'd one), one
+  without it (`NoAttr`, the control), and one pointer-returning (`PtrRet`).
+  tree-sitter's C grammar reads the macro as the type and the real return type as
+  the declarator, so before the fix these indexed under the RETURN TYPE's name
+  (`VOID` / `UINT32`); the golden now pins all four under their real names with
+  their real return types.
 
 - **namespaced out-of-line method + fully-qualified call** (upstream #1310) —
   `namespaced_member.hpp` declares `namespace simulator { class ManifestStartup }`
@@ -314,12 +325,13 @@ A further file exercises the Batch B explicit-operator gain (upstream #1268):
   `Vec2::operator[]`, `Vec2::get`).
 
 The minimal source corpus lives at `crates/codegraph-bench/fixtures/cpp/`
-(`base.hpp`, `derived.cpp`, `namespaced.cpp`, `namespaced_member.cpp`,
-`namespaced_member.hpp`, `operators.cpp`, `template_method.cpp`,
-`templated_call.cpp`, `ue_actor.h`). The inheritance base classes live in a
-`.hpp` file (not `.h`,
+(`attr_macro.c`, `base.hpp`, `derived.cpp`, `namespaced.cpp`,
+`namespaced_member.cpp`, `namespaced_member.hpp`, `operators.cpp`,
+`template_method.cpp`, `templated_call.cpp`, `ue_actor.h`). The inheritance base
+classes live in a `.hpp` file (not `.h`,
 which maps to `Language::C` by extension); `ue_actor.h` deliberately uses `.h` to
-guard the content-based C++ reclassification.
+guard the content-based C++ reclassification, and `attr_macro.c` uses `.c` so the
+C walker (not the C++ one) is the thing under test.
 
 Regenerate the committed database + canonical JSON reproducibly from the corpus:
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index f8f557e..532d5bb 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3835,3 +3835,102 @@ codegraph-bench` → exit 0, **1385 passed across 35 test binaries, 0 failed**,
 `lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
 request cwd`); locked Cargo is the fallback. No dependency, version or
 `Cargo.lock` byte changed.
+
+## Batch B4 — blank leading C attribute macros so functions index under real names (2026-07-28)
+
+Ports upstream `b6a05d1` (`fix(c): blank leading attribute macros so functions
+index under real names`, upstream #1311 / issue #1211). Behavior only.
+
+### Red (documented, with the actual wrong output)
+
+Four new `#[test]`s in `crates/codegraph-extract/src/walker.rs` drive the REAL
+extraction path (`extract_source` for `Language::C` → `CSpec::pre_parse` → the
+walker). `cargo test --locked -p codegraph-extract --lib -- c_leading_attr_macro
+c_isolation_table c_plain_typedef_return` → **3 failed, 1 passed** on the
+pre-change bytes:
+
+| assertion                                                    | expected  | ACTUAL on pre-change bytes |
+| ------------------------------------------------------------ | --------- | -------------------------- |
+| `SEC_ATTR UINT32 Foo (VOID) { … }`                           | `["Foo"]` | `["UINT32"]`               |
+| `SEC_ATTR VOID Foo (VOID) { }`                               | `["Foo"]` | `["VOID"]`                 |
+| `SEC_ATTR unsigned int f(void)` (control, must be untouched) | `["f"]`   | `["int"]`                  |
+
+The name is the RETURN TYPE, not the function — exactly upstream's defect (their
+grammar/spacing lost the name into the parameter list, `"(VOID)"`; this Rust
+workspace's `tree-sitter-c 0.24.2` loses it into the return type instead). Either
+way the real symbol is unfindable.
+
+Honest scoping note: `c_isolation_table_functions_all_index_under_real_names`
+PASSED pre-change and is therefore a guard, not a Red. With `#define`/`typedef`
+lines present ahead of them, that particular multi-declaration shape already
+recovered the names in this grammar version; it is kept because it pins the whole
+issue table (including the `RawAttr` raw-`__attribute__` and `OneNamedArg`
+non-void-param rows) against future regressions. The `c_plain_typedef_return...`
+control's `SEC_ATTR unsigned int f(void)` row was ALSO red pre-change and is now
+green — a real gain, not just a control.
+
+### Green (minimal)
+
+New `blank_c_leading_attr_macros` in `crates/codegraph-extract/src/lang/c.rs`,
+called from `CSpec::pre_parse` BEFORE the existing content-gated CUDA blank. It is
+structural, not a curated macro list: a line-leading ALL-CAPS token of ≥3 chars
+followed by TWO identifier tokens (`*` allowed between them for pointer returns)
+and then `(` — the `MACRO Ret name(` definition shape. The macro is replaced with
+equal-length ASCII spaces, so byte offsets and therefore all line/column values
+are preserved, exactly like the C++ blanks. `MACRO name(` calls, `#define` lines
+(they start with `#`, which `^[ \t]*` cannot skip), and mid-line uses are rejected
+by construction; a source with no match is returned unchanged.
+
+Four unit tests in `lang/c.rs` pin the blank itself: the definition shape, byte
+and newline-count preservation, pointer returns, and five untouched shapes
+(plain typedef return, ALL-CAPS call, `#define` line, multi-word builtin return,
+mid-line use).
+
+### Negative control, executed
+
+`CSpec::pre_parse` was edited in place to skip the new blank
+(`let blanked = source.to_string();`). Both `c_leading_attr_macro_*` tests went RED
+again on the same wrong values (`["UINT32"]`, `["VOID"]`) while the four
+`blank_c_leading_attr_macro_*` unit tests stayed green — proving those unit tests
+alone do NOT cover the production path and the walker tests do. The file was
+restored and re-proved as SHA-256
+`d4735def134c9fa94d26fb132ec210bd67e2a993883488ee89b32e409a09aae7`, the
+pre-mutation hash.
+
+### Golden row delta (`reference/golden/cpp/`, additions only)
+
+New fixture `crates/codegraph-bench/fixtures/cpp/attr_macro.c` — the corpus's
+first `.c` file, so it exercises the C walker rather than the C++ one. `git diff
+--numstat reference/golden/` showed ONLY `cpp/` paths: `files.json +8/-0`,
+`nodes.json +132/-0`, `edges.json +45/-0`, `colby.db` binary; `refs.json` and
+`schema.sql` byte-identical. Deleted-line count across the three JSON files:
+**0**.
+
+Added rows: the `files.json` entry (`"language": "c"`, `node_count` 6) and 6
+nodes — `file attr_macro.c`, `type_alias UINT32` @4, and four functions with
+their REAL names and real return types: `GoodName` @6 (`rt=VOID`), `LostName` @9
+(`rt=UINT32`), `NoAttr` @13 (`rt=UINT32`, the no-macro control), `PtrRet` @17
+(`rt=UINT32`) — plus 5 `contains` edges from the file to each. Before this change
+`GoodName` would have indexed as `VOID` and `LostName`/`PtrRet` as `UINT32`,
+colliding on the return-type names and losing all three real symbols.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked --release -p codegraph-rs` → exit 0.
+- `cargo test --locked -p codegraph-extract --lib -- blank_c_leading_attr_macro
+c_leading_attr_macro c_isolation_table c_plain_typedef_return c_header_cuda
+c_plain_untouched` → exit 0, **10 passed** (the pre-existing
+  `c_header_cuda_content_blanked` and `c_plain_untouched` prove the new blank did
+  not disturb the CUDA path or plain C).
+- `cargo test --locked -p codegraph-extract -p codegraph-resolve -p
+codegraph-bench` → exit 0, **1393 passed across 35 test binaries, 0 failed**,
+  including `generated_golden_matches_committed_cpp_fixture`,
+  `cpp_db_is_self_equivalent_to_cpp_golden`, and the untouched godot / ruby / mini
+  oracles.
+- `git diff --numstat reference/golden/` → only `cpp/` paths.
+
+`lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
+request cwd`); locked Cargo is the fallback. No dependency, version or
+`Cargo.lock` byte changed.
diff --git a/reference/golden/cpp/colby.db b/reference/golden/cpp/colby.db
index ba2b2ab89c075e2b22adaf0be3683927c283df05..45edc05b9461561888aa2b70f725a6a25919c463 100644
GIT binary patch
delta 19933
zcmeHv33MFAwP;r_)5~;sX|!*n(Q56QO`6eSOLo|7yl>dDEsN1;WGiUH8n4(MI|(n4
zV8H2wA_<$52Ly01n}LLnf%ifn2@uHtWFf41fxG}Q@c1DlEc&;)r$-~n3*;y7{Bu6C
zPgm8gTep_3TXnadeJ?BfURLgSFe9TtU>L@HIB3psx2rUW?<#!|b7QXCjEBA6=$Px0
z1tWv;!N^eQcyx1YI70Cd{s5j#CH_F)tbME*+7k6Wb)P!R`F-a?<wfO7N`d^iyj=QF
zx=ad-kBLK$cOBO_0>TTzu#mxD#aDAjxDb1Q713oVi@EIJp>}RRUuAq4xLB;rotG01
zhspBUY>x48OQvxoxDZts9|SKF%X8Nk<Sh-8W3$;jWAoZl<DTaEsLc4N`DU?nYO5aP
zF-k()QHgO?Xau<pA-oe68;S4+RAf9K9z})5qSjTYz&O-8i1H0*+j)*Wpk3iLUJ2(L
ziMI8Q+}!TGoE&3$Yo76!woc=>;Sz)2P-={~2aJWSZsQNjs*FFhXQ3>h<~H&>R-jCv
zSZsW`qZPS~hdZ{38M%!)6%`fMG*--RabV~mr`jm%%r|bFy;#(tgRCOA@k(2skuhgB
z(u~D(hC~&h9uI})lJI_1YP>h63OSA9&K;rxRe5=C@<=;Oe#cUe@l2;1$;MlqTSdtn
ztkvq5*Ry5Dce)CZNFE$z&qxe9a(mqc1yvX!B*Pn%;16E7G_Z9f8Xp`TX%EGMzUKZG
zf5ab)g@Vy=e@kCqptZHt7moM_g8j`l;<EUb6|uPWjKt$xdWR#?Eu&4*s4Giey<o|z
zU|_S5>PoV^N=)f191Aozw+#eCzGx^AiZsXkt&w1;wbeh+-xqCb@!NeZ8J!0`SkEba
zY1ry&n1`<1?vu~T-|q{zMnj<$k^bi9P^drJ@AE-_t)V`cXJ0JRVt2J@bUeN!G90th
zDc#A=<kT+UCi^3aE;c6-X{J*N_YK7SvHn;~v@aO!YwHg{xBb4Bmj0Mc|D4g$eoEg?
zr_gtZ@_9=aoVkh3jh0#ONJ6Q1#7Oa-W3k@I&|qY|JsOEbnwwk0t$trH(jN?TMZ>`;
zbQfwFXbJZF!+}X$YlW=ml-_v0csa`T=2TTxVe-x#Han4CJuo;FOD~@=4}+_&Qs5aD
zI~c82dqllRajC!1f2@y+9nL4DbM<`uhW?JW&v}XRiZWaNo3vH@r8t0lrHAEW@q3uV
zekY@>7k5ct!v~y=P112~m2-n~R6bYUrY@CA#Q&1Nqu!)ks=cY7p?}MHgZ2&QU(}D(
z3i&Dgz}?SeJnAso=GWziv$%Rh$J@RY)+ZVt-O{u<)X4RcecMqT-$HXeaa1QX7jYek
zMBubQLF4WD^(bHzFR17JbzC=j=ZmPC_Z4$<$nr0t0^~KWT+oP`jAQU@G~Qg$C^P^W
zMBcd=)$;ZA+<I~_j%tKD$RYCbF18xg8aJF<&)3kZ3wNO!zB-rllUEM2S!kAl7uKOF
z<E4c~(&n+TN=nFZHP`YL6xnqV&?z_R9Jn3mlmT7|aQep!8wHPvy1ctqD4__(4c*ne
zJC6&J<=<no;Q+gCQ9WNoNB_##*lMBBB=W>9K%~GZTU^iQQ~K}h2Ksq`gp7CEW(m0_
zp^w&Aqa5Su#dSiqS$1_)3t1-4{*GCECT-WS7u6KFvbjcUW&2}W2Diofo1$Z58MHbA
z)d(98EvXZ9lSJ3XYC)qUh<`ttg;ZnS(t0?mhL_gy3T<#r0v1K4gPquhsuPlntF|cj
zMaE-Iur4B<tj#8;J%$`puupf82ve}(Fi4oE!O0E-ehT{OSex^5Q8dYKGk9}4YqHs#
zHzAw*HJz!_uF-n9Mt`dB(ZkxWw1b*oeM9}KdY1E5=eM0Jl>bt0Q5GnSe1m+R^k?a?
zv`Cx~?+_!R=J<gl>c|j&Bt!+4Kg6%(1@1m>kjrO(%nrbAxd%m%&it4e0d8d&jyca~
zyt{l2Z1jaI&QY3VrlZ$QD=2&9lSgl5ea_{L)1djcu|9TVgYm}7urao>MyQvWIqQu>
ztK8(l+gOP_3@pTMtb^)ap*FqB%Py@ku3fbZRU5}wEe3u#zN*qVe|0VJ1mwt(!)y(^
zsM3Uf2+#`SKhFyrJ?GV;ax-@fa%GS^UnrFs|9WHY>O8XUFzZ#8dt_!_Hyt*)a5tN8
z99<KTO8{ifgo26<b*&$+`_8p1fm=G)RuEt@FT1$Ncx~+xxb$CJTV<^4uH_44CTPrC
zn?o8mBgMF>yAFhaXS#b)p5b3NALSam)}0URQrc5Mp1J~gog1@drhC1)T$HDbRqK6l
z^ZVC%KsG2NOZFg<-I!@SwZ0ebehOW@p;pP5YyvE1+_b?5+(RqB+)+kK_d=8TI`psr
zF8<H=^aA^gZ7e3@HdIR99zl|^b%V?BY+MGT8{2r6B2N;#aOo`L)r~$tp$&Xjpc;0g
zXl&^1MGh14>nqrr#6m%4yw>}jvF$!F$3;g+;*r6T@rC>+AU1^|6DPRZQ`ERmK+V3r
zPsXn)V(bZtB}~C2HPO@YvrTO=2uR+j`I={}+NWUm=%|D8T%GT(^Cz&oOM|@Pe4N2o
z<ADAXeWUh<wo}v9Yt<&_<8Y-NcC!775!k&>9dliduD@~2br(A<8&~g+rT}+vqmm)+
ziA@6dLDAT;r#IJba)&(TP{RAQEF=hsF%DgkW3YSAnXG0n6wGSYtoC1<W5oB)PbbG4
zkMHeG18m}qV4`Odp!T!IHHmeJ$qomQQng>hCdKqqEfNa^TR@}>w6?Uhv<!fBG7xHs
zMB17|t+ANjKM)Os+WZ5NXdv3x-`3U_4uLe-7wQiOAPq*^TB9h-Tm@?_?sQOLL&38d
z{5Jj%jQ=No7~h01!@F=FUWjMI`juiM@x0C}aQhnjKg<G&xa7&aEc3P*9gA&=fN(HQ
zFEP;=Iaa_s3b?RQ_Hph!A(N{`BOsTJk42)^HOFJF0;OGhoXWY8eOa-XtCG{_dDoSE
zMk1`;$l&kb19%6H;&xnxGxS&WVeK95M*KcLjF;-q=-<`1>;2jX+Ap*t_<8(u{BQWE
z{saB6zE7{$OLUjcYmaL8<1;~mx*8Mw1w4$`VlOVlg8r8NoPI!G0)kMh_L}xv{cn0V
z{v)i$<lo&dW|V6Qnae}bp~(1nSmJWbD>g(&Zg2mV^g^?Z5>&VXG#ra>9_<fIX8kEz
zJ{!@S-n=Qj&}bDBmLAcNUR6IyvTib4JDIJa+41<6t<iY3-P5d8=T$bSGM#9}Wb<;G
z9ULAT-4ZWL*vO^n$e#2<$t1el#x9<uR+Q?va1vNRv(^anC!u*M)La{AG#$xzr@)yM
zY>muicV)zmcoWuIJ5z{?-F~!RP5~vmiI_foM|wd>FYxIFPUp(f#1dBIa!jGa6xS2#
zD~!GvUym8B6A$28{A>I(T?cNu8200@^w)7NUah`@U)A0PM*AN2>bK%6^tbiva50{(
z-L1tnqCKUBaF2eUexbfbFV|kxeyM$^ZNzcS38Kqv{j2I<^%t}zENf?LdFtzU(d0Iz
zxw~J==uwR$Pe}eS9cG%`PUXTaTSt21vEi|yNIcfx;^d0Z*p|^~Y<#>q$<_ryk;_8k
zv3P){n__W4O+Pof!$;XY&zr+}5wsp0=^c&@_r<pKMk7N*O~%6ymV-1u`eYGmFeV->
zTwR}RT}Q`Y9}nw$YBkQ2D%RJ~mvCMz8mOj2v$4!WWENFC7Dq+~2V&##mGQ`y_|~y1
zdax8%W^h&JG=`J474)Uf8yg$iS#F*@WyzB#QA$r9I^oIF$3tfv9UUIq8jqFGS8AU+
z?wO}lF|EH4rb$`1NZ>G9UPwXXNl*a=t<0xqS>I@Ua}t_I=kz%!=O!p}JPFRB$g8p`
zs6PqHqM$P~Daam$Yudq>L5XeO5*fpEIaiGh=@hVebf{mW3weemH^jE6bWQBHLWfIt
ze*!I|?@2KS2%12$TiF~Sl%@2ZMam?W$-zOhmPNp10b5@;S-@7VIf`UyzB3MNlMU49
zC<9Dzss60~kor^gLG=#YjnBfo{=X?h06Qe`CSZu~>INLrx9G?97u6^*#X)VIwny7+
zvWB9M<2((nb*%yp@sM7u{S3F^YCWobOMP8EpuMUuQ!mmEYwxMQP`{}T!4>r<=ik5a
zD}r=AV57IU)7_sc{Jku&rk=hcy1U!kfkqwG_pFk=(SaT4E}sfKB~z4e^N{gSb0LWL
zzzVrDS)qzsN)gIHzNeS)DOrK;i;?m6_D{+V6n}Yp`!tTA(3P-c$=#J?3VKRVCTMRr
zStDUF(IjusR;$|Er*Q{`p4s01X&8ha9CQ-E8}02Tr%(=0LUg*klu3+l{@j_E#xkJn
zTMW|PKAm%tjAKp$7zHNr4`83fr{tdkDu}&=pTZA<eDiI5Io^-sz%uLbVmucI@hrGU
z9Qu3uYx*xiqPbVUNxw?}7k!&Pps&>D>WzA#&VVfQgm#y9wYFCq($<w~^R<vxsby-6
zdR%>8{gHZD{kpnajj2o2uv()Q0RMc~NkzP@=@&=xYT#S!jD1;vu?H>%F!s==-+Y?a
z#Afe|1HEYmq;UqMVFsjr2BdBZ#F+C!2i@rwL-3W!qo1#^Gv#(>Dl1Ih2vlPA%sl){
zW`a(1MbI6aCdd{|D;G{H7htY>N(1xuNF$J!YG6G2;--b^Cp1nk=;;M5y`ZKSoRbCP
z(wFKI^qNQ)tsT<=!gK&X9l%WoocQ?HS2Oqn{Ac_Y{v&7;FW_hKllajMu$PbG@8cWs
zwfGw#%U_K5;H@Bs$8Zl`4g2~mJO{VnMv(5^I0tJWnSZ4JS^pDA`Y*sW@}&N#{-AzT
z|Gs{sey#oukk~H<L(W!xSdZyF`fAv|FKIq{Pr@4wC(}?eZAqrh$<!2b055R&&f{xQ
zg5JbYhxruDCs=p@!kJH&=dc_#FE!^67?{!X_$T;Y{9Sw{C=uhhABKK54&xeJfEE3(
z`hNmL{z$(|zd^rT->rXMU#p+3H|wRks{KX#o%R^qS670N*R9Rb>a;wKQ{Pg5Tc|#!
z-mP8_rl>9ITD4QHR8{A@&gYyzb^ZWmb%xWZ`!FLXjQKJ-U7XA3{fH`J4!*_CvTU=l
z=R<0PJ@R2b>k2?p0DK7r2kXn{gR)WfWOl-v#aE-L;#PLkOjt(aOqkj*6DHNqgb8&s
zVSKFxYfe`dxtdJATAn(X>Y1Qf2KqQp22&<qRmg{B<HBRPs1jg>tXu&}5!`p~j|;(;
z1<(4@Y`zvvQ#nP?34nZwaq#0Tuwub8QS9O?P&zZ`7fpxc7EXs`6-<X@=1+&<yy*}v
zcREDLNlXVx+0!9H)^rG$nZZ}c>4SDn2W05H8>IxyJUpeCqo;}qYADXoQe|4y)hR{A
zIi)BmQ;LE-rN~Jd@0L>?i<x{CnsWBI98*9E>fzFaDKH9>`57PwHv`188GMyI#cW_n
zp{6eOHVC3gO$#&n+gc}RTU0Yk*SO9Jfn3@{RW)1j!Vg=j7rxk1zD)JaR={32Rj^!3
z2?K@h^`uI-2pIMPl{9MTAF6-#{qyv%Z70{iYz=Gt^!iuizeE4JaHjq>enS0=3Y{m=
zzv46Xul`S=f5oTkUrBT3N%b#Nt~{asMFq;4`qx-|%a&N&)W1eX={;@gUqj$GrSgg?
zKW+jiCoP!z*Ve(2crY;I0@j=yqcVG{8T@DGWBBXXuOHLrYcFU6AoYzp|IF;M{-Ix?
ze(rYu_`yR<Grzv~NBiIp@yxAYLQpEoe1?BXDas@tXP`<!XF1kmxcr{lI+{y5d{1UF
z=1uH<=X!)%mg7pu%bQUN$|aY(fKsDX*XBWa<oO_5fvT=*W-En!6FjfSgIwf5Cg9bW
zfR9#t>grhzm7dOX?x0A<k;SDbhm>ZairQ@2{xmLdfi@y{97CnZLk6K00w)Gd%E_IO
z2okNoY9}fcnoRO{c9vEtl<sN#(H!w)LvxLyl1DB;9#l<+TG)!35`gg3$IQ}<$uKHH
zEMj5B;AJD7GfOPFp@l6+h2$6|<21?mHzAMQ09g(;j!52WVV70Qv`9C)MTAAV)f}iq
zkuD&_Q_3E4MGo>b6j3tMJliw8XCUdYLqqlCx6nd_p@OATB1$d{<+>0nRg_pAahzzn
zD`4B(Jv$H!e{g@06}hN_hif#Gd^H#ORX23&u>6}D<ndfohcH<hW-A1hj>kZYJwkz*
zduX9YD}$W4V{B+JIvB4f7v!O~L>7QJa6bcm2g}MVtFkaB`k(%Z$;b+hg+)yM&o?uG
zAlVRF#Ze7BIeb>MdB`3<Z(3CBYM6(p!yGuolI(mG+~BgiWgR2Yp{@Nfmjm&vN*_FZ
zAZe0Ctyh2qGh_oL$#9&*GGtXiA3&Cq#pID%P7bz$AG?&0d{`TqJl@KllM6FVPDh#4
zQ;JDb0cy$=lIMce4~xci(p!M?Q4QHqfXZF7>^+18>+m7B6`;~H8<YLAf_1{!6Gw2O
zCP$pwJRDfeJV_{T*P`)!azh(im?)>Onls-w&;p|}tT%>NA#Lp&k8T+pi#I?MIz@!w
zw4Fv9w#blf0XYOT;N3#p1++$v<WXj~;LTgfF468NK8wf$g-A(YtAgjNswyihE8tN@
z|CuS|DX>!3bx2z(b5$smW#ramSGs6LSyf@3=F-Eiyv&S@+=eynII~VI&A{0?+1XlV
zwoA%zt7kHB8p2t)e*+wb(K26KINTR&jkJUY0xiKn8^Jq~>uh=`@TTz-MnhQ*r6PTr
z=x{CbXcJVL%VE6_TBI+RuhO*)hT%U)E_S1)rEn}-wCIZx5Gx=lmShA9X;3(3Bem_a
zN|;ex5MM;80A1)8&|ztih>!$fM+kyi=Km}CA0^0}2m?{Ua#z53_^kt@qv2Hdih2)I
zzt*HFhZy-3G#RGzhUDF_pW=rcJ~I#`WN&W7Qy*Rk`aqjQ_PK-Dwym*{y&L%qS=Ht-
zH7m>xr4~jyS%(a>@fwowAn%427=CI+TYx&<m@UZ(AbHY=4IsM0e3hnY4=`1xIh+-n
z8S#XDFwByx_mQ$9)RbsW@1Yrb5N%s{YMC^>mMK5m9JM3JIA&60n6tiauZ|9Qa|9pV
z6G3}%=&2Y?EsD8PLFkDN{|w+zFv15@i-a{<{|@7sYj!6D7-3p>472h|yRSMxS_rrF
zBP&Z61YjN<NQeQ8Pm;bSx?-jw)7){eJc<+NGsW#Db>7eL>C}PrW&8FKcQI;Q<4=<F
zo8;)p>9^Jcc-ErrryE$&@Lr~%*(AsL7%oMQVa~q99wzK@ri=Gc@s(UsjA|1;V0!an
z@c|933jdDDZ8Ax)UWT<uFw8k$vfF1`?LkxbPF+MVOfNYauf5htvNwe{wWhl40uos@
zW*?}j0a66r$cSU|!-<Vs7)8Mc!R`4K2LBDei{Her;urC+@YA5;|J!|qrDzvMe)0`3
zYOHqfNJTPhCX$tiR^qS{!A!^>y{L!_YtIqUhoUN|P^|X8c3k_t_8h1N{aQi_b4)Jq
z3Iqs-AjfkY<XR|<Wg*v`stu-U115~t`cpYy3eTIuYoaidUL(!%JhW&?!RpOif_7I&
zvxpL`P33A*xoR^<2RI9IaJfRRDpgwvIcv}r6lT_zo3)g38O^~Ec&Rjn=Sks}aLlS?
z$L=JMlZqi{by8%)D49Z<GuNmf1<Oyt@=~x|3q~5ckiVa0I4J`F7BOsAQDVB8qqERb
zIn~V3IfAeZv!Hlz$|gINQ!pt76Cua3<dH6vRcDTjPgTKulMR7RE*#513^o{Dru#nb
zLXM2gF7-`DYt~A%Y)t|C>wD^(BzGBFUGxj;lh$t2uG9WS+og?YecE~2x!TvXPOS!Z
z%K#{nJxES;nQlusR>nJ1xjCua>{PBJm20O~aLYM5-j;&4ra{9rAKMX+jr5O)((<NH
zFbQwA;DaVoFbye?miN<qvMV38H`+lSra#**nEq_LVEVJ|g6Ymq7VdkY2LhcEUBVlT
z_Cx79y-v%OS|vf-EM0)}^vBf;#p~oF@@jo2{vG~z{I6g@9KZ|p55Xk35$tQnwQIC<
z)%VpKrDxP-s#n#;z0TL1$DCJ*70wao66FeIR9UKcA;#xF<V$6r?39i>RyrOK&vm>d
zyy5UTzO4Sc_>2?W(Z5%Y!0N{Y(j7-S`O0=wrqIRj3i7>qh+Npo);j1RKi)}>51^nh
zhr*4w7Sxetn~>m`ZJ|LtW1ZQo!z#aWJ6k8vR_)~2CNxWEGh3lWb&5%=)x!si%;-ai
zMRYjE!vVg#$c#P&QNVgjWN0%Aq84()W)wipX5t7^G-SN8Y?hWp3s?{cg|Zv^$<QDw
zMm};WBo1#S-{H1mHFf(PG)=-}8`enP9)#{1$llMRDpYTk>a0?&nFuu=-tRUeF|Qgz
zl2ARhIBROLYDy7RlEek58B{JaDK`@$Ux3Ppe+U(;V12R&;-QdgRAMD=GZBhQ`Jmfe
zF3rX(nh7dQfl|{dAWL_{wDQT^VdMrabmK6LBG)SAkUNK=F54_QvVwfKn=WlN@s5Ci
zm1%)p7I=S0wHaK7GE6Y}{V=MVj4CVB3i)b?455*;wsY4Wr)m-~V>wCJD3VH@C&yJN
zt}(W>nk>5lNoDfMF(r%Y)7P_23Gw7;juPIR99Oy{z#f}$>T3Sf)tptGptC*^b=D1?
z&kWDBJEs=AF78Z5eM#HH|3TH{1L`*Ye&IEJsj%1)bheAPXs-!(3;TpZM*;sNzXh+8
zvZXI@XF9Ia-^3M4pZthpllTHY*vWrW`KGi`%Tk_J8o3?P54h*0<IZ1;aj{EO9MAGP
zcdJ~X&g19G?`wC0qwI@LL7VR!QEzpAS6+*0sMs-<vVIVCkppq$N1fy$n#>{Z&}6n*
z5<2|+`aBwATuXerLHak@x|qChGpnFBa{E?j-b$LbL&S5Ke7F@jHblJJP(Wy*{As?@
z1KVI%HJeZrw2}b%0B}I$pbZ^9>zzivfSQn(?B0$-LQ{zEb<>#Zdc(I;M2*C=1NLu&
znF#gG{Cc<HSx`gv?ErqPn^J^vQigWaPzu&5MoM>5wxs~$kp*?ezSR<%Mb6)eLXIj6
z3l1?qu<BDgQM03hk~2fHYlv?b485GR?t;$COy1Q>&B2=bMtgv~90c|L#Wj+{V-bSW
z&kroDT?B;O79koiDioWY!zq|z&?0jCMKFLu6A8{juTWsl<Itj-6i&X$#Ev|R5X5DB
zfrU*@&LMx=4P(kSIoXkA5&3An*O6%sZ<3o`<e@z<mJAD=;$}>0_CkA|^gu$svInV?
zOzluDa$Os}4yW~MXh62f#7H6D1Zoy!3QsXClE~Enb%++W$(#;zLF|~Z(?(<4%ppu|
zHYE!56hWZ;)Mozvg!Q$?$&7b)cihx=pER(O4f9dAe5w%6#I&y|><&RZgHN4)PUZAk
z{Bz}8?bljBTFh=jN7c)4zP?xg8Mq1WQqP7Ey|1ZnI#()4xmEf;^DXB!@*1&Eyi;Nv
z{i5#pp~J=9&#&S>&pU)ixdQevHV5?~%seK&$A3rQg#Lqv0>u3V;Ft}!vh!u{3K62S
zL7h$oX9wh_sW1r54gjCM{zVjm(Clh%VxoaudmCFrgR*PkUWAHXIQjv!99ZnF+t_7b
zjQP`-&|)zAK~e$X*fr2-mRX<?+3>-FRq>%&QAuXs!k!NoAtYhrq4Q`D<+KnYcYF_!
z%gEfr>_VY*g*dO9%)10Wt2(;I4>%t3(CzGM;HiU`04Mfd0*vaWd5Fg*cOGGvpdy-7
zLKJq5V`8Fkkr*U%F9F7&f!HK;gsn#f<mpRc?D@p^6*M2N!fWX`a*5{vfFK&%FX!}%
z5R470lZ?goLburzyCfBk4UjDI<X3@Ard6?cLydD{!j)=ig=Eu~85V*al?@O~`&t0Z
zHh2ICXk_$q7<4K!n~Yxu=3w{bXgPAys<R{|NtN;!gl1EsvegKpv+ID_)?d%|!sl2f
z9Wy+8V#2XVg!pWj!;C=VPtAf86T<0<O<~Mag=bGp@TaHtNyD=zCb$z3Tle>cXHQJ9
zi$!k~R&C~GO?ex5w8ms2w~yZ03O-7m{YOE6egmBSzlGT0pMiM(0DR#1O>Ftojr-r4
zSC;alE7)N0dw~2h#0C5mKZNhWx8Uor0S&fea@`Rm4nX)b#BG9Yi^geRE>C7bOS7R6
zvu0<(XJTiC$t*va1%HW+z{;E;TXgTe1MzdYF8#+ud>d_5APo3f{b~JY`j0^dn5!3n
zhKIW7qmw@7(8p~0=(z8tkJ0-X@ZIM9<T=b%(9FFVEMHoaDOEA}X1qZEUwRLy{X^=D
z>gSw~I#((0Dqm5`<)iZ1(i2ibssj37;7CUhd^h(@@wL>NzLrnoVIePVMjio_ZSZ^~
z+DcL0R8LBsi`M+}9Ve5n664c3NPyp|SEO)?SLCFA5SjWx{!Zsd;uAVQk{%B*Y1n^B
zKZE6PaM)p^mO<?lUJ%<L1@3cdo21^UlY2yRFwD%;46*sKFnkE=^ZNoVYs2J$cD7p#
z<<{qvm6e&Fwh~_l>la(#>&WVAKZ$g*h2*Q-!E<$}gKY;<<@pYF1f<A?v)LgOAf@ol
zA$ejpyAni6$Zr;X@ZoA!R?z(1_3ST#!{O06Y^CVUos$y`!bfkjSvS!-*~O@dtnXy^
zz<u|dPWIc52I#G$gS-fx8Gl_+O77`m7fJi&dH}bznPBp_i(&uW>|2QHjCXzg@U7lj
z|29-({M;XhZ<5Xo^oX-^{W;au)z;^^4+du6JC}8oF1n0?IG{5j9{RIynm_xd`Ll1D
z|Nr==nSR5bt*|*vF*?eKZz=COUvoSw2IWKIK}+CwY(KropAz&v|71yD1WBKLj9Ebr
z-Nsg?OZ!5d^d5Hy1uy=`Nc_-Kx%3|UM>6*oHgF25KNqC_)gpX^X^XR#dzd`;HMU0%
z^@!bI3N(fFdQy~NYn)m`^AzAM0OYjnAc^cpJ#b4rL=%6y79iv~uVHQ@hi+jv{P$@B
zFntVS<hjIu8Ok==dZ=9gnNBd>h?Y`U{x5Zczw?vL)9C~!`Spb9F(%Q`Rc7$W_{0QN
z9m@Hq7>K1E67R)s{V9FFn4#Chm)T#`eCqEYI{j?t`_9A8^-fv2Pw7`&@=t^-9m~X3
zjyw3L1fTG>_?o;~7Nwh{vko5ee-^{^|7r}A<cx^D;5k9&uSSqrJJ}|uz<2eEz3Ty(
zG)3OOlWkCPoSjK1wMUXgy8z~L&aq+C#R9(w(csjavs10<??#ZEo7pD0!-mnHfFROt
zKvbOVXNdFW70D9VFxC{21H0K$sVzAi1I&&_Pe?MlyURuDnUVNba_;xQm>4D>-@<ML
zS4+AXX1aZb+H8_0lb&1Ib3TPFDcyWD)ow&hJ>)ls;l7zP6r~JFw!O%<D#5uqYo=A`
z1m+-WDB?>_XaTZKL~!I5+GeAa0SKb$sDUP-(=V%i@cRb%P6&6;`zQZ^0{ni0%rsUP
z^~w@s8f^@;V!>y>rtsOXDSX18QL-({pZ%Hw$lIqf#m}(B*IQRJ<#sGS%it~g@AdPv
z$F(-~W_6MChwyu2_bC<f719UNCees2i{Jfn#%xjDkGo_B&i73a_dxb<htn8N_+F(G
zfa~){DUf>12^{bdaG@3MVhwPi-42P;F^OWI;tk}6i`W*WJym0$<>!M_ZE!a`3Qo1(
z>}IcoBl`1u*!4;Xey^ju$n3>63>J6UU>nHMy{wA__p+66g0J1nUamBoSag73$u@=K
uZY4Ms2D0%Q=YD6vh8q6stH~An!4d-08g<FF-|4sO7-N4&z45K(YyJ=J(l&?y

delta 16030
zcmeHud3+qjo$pk2_w+H{T{AjH=Xgfv%;=gKOV%;IFoF0s@@-i*vMkG%99fbr3EO}X
z4!$pJI!TcO6E=Y?myIzG0$DI@*d&-3?3aZE2V$H6SqPWk3#SR*Uv<wV$?zeY_xNKM
z8M=P;tGoJJzy8&?YOa4-x&CG4zDJ!-yI`}~%tsEBa*n!u)#QHPql8-~pEDj0h1!-$
z&Z*s<{hh5{zP`4O_BE|6A0p@BX)7k@bwkh9eyUAZ&#BwgF^<O^oytebkChtv1$mh)
zOSekX#M9y?k+Xlxo-h1}|CsORKH{#&AK@S3OVJ6mz;@2oe&DurZnIoMd&c8ksF;2{
z9<M+}v}FRm3Ki1lC*XcmK&MZ{OGTeMlIi#Rjgt+T^vQ{M9JiVG8aIZwilf|<GVAK<
zSb`CbEJYq;U*sB;Zz!X;qC8{&=%0wWLvp0i&~_{uUDcPN9OFp!dX#MhYr0XEadXW^
z(e19z3<iU-$`pEHJC=-zV?rp?=o!;v)Yp5A^JD78ba!)(r>N*V6L6M+XZVb@wG}AM
zI9R(tbU{i{sK_XYW*NV0@)@J+#v-TDUAGt!sKH~rRyPOf#+fns^!-D)#JIXX9cgC5
z-Su;j$`Xv+hI-M#8t@bu2Wzs7-i9Wm7{?nLk!<8eSBsLnDJwnCV@#}f8}B#!jDL-K
zkZ8Od?Lu~A=Gayw7>CDh5P8Uzm1X6+Y}|M|XLii+MYD}t$1M^uBxh!t$@I0o$Y<1y
z&qK&)96zB4Uar4HfoDW&u<3sNn6}YDw3FmXvPNo9kIPeto4li6r*3ncaYU65<v!`(
zr4{mHO0IN=<5NeIv_amlR>*JabJWF-qskPeUz;iCOYbT_)PC&PuD?Mhk(<?nx}m<O
zo!1JKUmrc?d{#8ZPA<!dq;utHWoK7=bfCSZwXMHrT~$Z8l50Wq>`!n|2$|yM%_zuM
z<#A&v=|tIlWjWVO_4O!#DvVK6%7yYWt_c}y=adR%`P_J9oSKu(2caN6yB?LHfbsa0
zO5``*hG(gfKebXQf%1r++JgLiF{|q3J`@m&Oyv_>u^$y0&rB`n3*20UuDt=J!$i5J
zl_9Tjc3Pg)(c3$U^~u=(gP`Cs%beYY{d_*FC~`IQDG&0ELb*3huLP`B!86-fGQB(}
zD~qeP2HM@aroFGXwXJ<cRa<Yb+xX%1a)8>er<b7&<AdqtLOQF}Sli?WcwI50oOi+S
zsOwtf7o29wnL0mDm~Qqi<Og8=4f1F#{@5DGqndqs=0+HY!?=EChM<^*B2hm;>4}+T
zNHX4>SuTid&M4Z8N(H-FV%c7(OfY(8l_B2v-mG$-V^y93?I3n?e%X9S%Uk=}t6&OJ
zY(fBR!UKA@u4}*2I<!&hbLxOv;rO-V21k+dg0evg$<NB)l&hszr2W!3@ioy9C);1M
zZ?zW-&kH+*DE}t^eSRwUI!C!W{0csRr=oMH&GsBKH?cqCMQ4X&v!hbBH8tg}0>DOY
z_0wbPaV7okz3}KgjCrLZo@k@TU>4}84Y-2(58+Clb1f)0dK(v_GUHc`lTpxc&YlC9
zaLx`Idu9g#7aeozjJIY7gi_fyzS$Tx*JISp38NCww+O`v-Rqz$GIHlO0y@4icP1);
zXR-0p+#sNXN#*l`fDk5aoEKC^$+qTZ59_~icD|q1?!+NSi)X0vxgAWIKSXJKdwy8R
zlWmb^qi1dwJ+l>s?6Y%a+oUGr*n)f--i9Lfc{vbofw-5>+=nB0PPRc778!q75C(fj
z7S2U(qix|VKvdhp68hoYxIpgd?r-hv?wg)rphYuKx-n}}3qb48qA7|i**f6O@Hd6Q
zaNW|JLwk0jka8t~Sv7}2TMuDBeHN5>vJNG^)Vm8N@zrLRv3PMK*f3BT#}@|`N4$jj
z9!ia(<}lbXR^Z>(pa7mCL+w)mf`4vq0sHmVl6+>(l(tw8ue2L`m$U#1-&%6H!Y8US
zCX6ekfX@)Vj5Es|UK&K$cwuP^fC1_-jhO_Mz<dWQ?_YL-<V7`*Wi@Og-y;$I7y4Z7
ztag<qsNYe;V0+vuULhODuUV`vlTV{tZ(k;VfY(Sy_}aFF;ytcMG;Y1NJ*nV3?S^wx
zOG5F!+$$K@Y+9L6yocBF##@_KB^7)pXDqueS>!!_6*iu}ZfPRN`|1j0)C?{zUM8P3
z`|-ZajIc~*+Q?tYE94Y;h}=SUlRmP9%rw8%#<&}GSje+pbPE!*D0J;uoSrVaI6vy?
zZC}?42DFcv6}z$aF*nbaDhN4YK8*{ap@xSeToGE)zOM5s%Mf7)=aJ(J{QmvCb7e$3
zXCrTu7vL*!m~10!p%W4PVST)Ij(kYIPdxfN`p@<I^vU`t?K~0m5A|Q`>-E+8QoT`k
z={(s_()3rzpU5-hVe(^g4OvNMld+^!e?kAAextrcAFcbz*Y(@seQehTWiAV~b+z{O
zMI<iMw3A_#^PrUj-EIAyJ>8+yNL4&brNZT)HSPT!Ju51bVtJyjvUtW|YVkm7#BW6g
zt!7G7lS-0R7AM7`q*%zrzW#LsZT$uDmVAlEy>Zp3)Ji?c;`vPMT+`dLu0O9fo;f!)
zb53d`JDEKzp4-SdT;NUiA}v|DE71>Q;o;Dr)r=!vPDy5z6B(tXQcNiANu`ib@<}C^
zP-2nGG`|w28=+O&^zV|tkQv%8az9x(pf3h67m-@BoZO~W>JtIp*XZw)-;;6R9dwW#
z+6C=#?N8uaev{luIQ>!mNAOLF=!N<e?Jn}Twvf2>9r|yz%SlkXn#|X3(%Q6Iax-A(
z=c+k(^S|EH6VbT>l;TFPMX_$6yQRN<O>b9gfBTA%gUds`>w4PS`}(Tb8uC<%TsrD&
z@2_Cts`mbJ7GB!3p)9esvVxgh2toPI?v^#}YnHdKYiVok>I&R+qEPUIOM>Xc@i+@S
zi-{+4=a<B)DP}#1ugB)4MH=T#M9T}=TUgNEHo9QMs`W8%Xl847=gRiJ{<;0F>-q<J
zy=*0Wncv~$O3d-BiDmGxxu4YA+qE%2zS{HHY9GvHtDTKJx#Dx!(A#>}^bYj5XERvE
zS9;b+%iw0|Yhko(VPy&&L9;WMsxPKWXR5hr%ziBI>F<bXU2IsFLfkpXGWW;Sgk_$m
zGu4WiN@J?aRHlme!ZFMkDXg;f>sotdHly=;yCkOQ=;>M^vbp@4^}%RgXJ>N~e>tqX
z45Wjok-aY7>>zk7v1U25gAgBL=}fe$hi!n>=STr@Xl_kbKOwi11Ei5$LY^i^!OWcj
z^Y$Kzk}~zM_L6po_LTMj0C<6ZjI?RHwHaCun7(i79eNhoO8WGy!`f?Ft@;As_Xp}P
zwGZ`6!7qAM{VAaJ@_z)a{z^7wfX--?K{gTjhjBZ%giR`gWHbtu6=!gju~-U*88odd
zapmVC*|_J#DDa2?yV)1TZV7jVari_Y?R^%Buyc!jtv(yS>}7WMMWbI7!z};oXml8i
znRYHrUknm4B(oLHkQ<Gfcs8DS#y*&YGb=MM8XX2`roAj0{d+LYmOC2)z&RQ<!Oa$B
zOe3-RP2f5@7`+JCnNc#K9gPmhd<^pDNC4t6k}n4QLFQ=unVcpk$m8TFxr2O{>><~Z
zt{L#LpFzfv3X)G${S*C7{YAj|!}=XS09>!H)MvowJ6roydqw--V7L!yKhSn*8?=?$
zJnd4gOiNQgR{y9ztv;aMqV7`%0r;6J^IV+6O*AvYC}ciOgDg}g46jg;6w8xh(lQ&9
zU#jaGVM0qrXo^Q@ibiM(M`$i$oZ}!hQO$g-QOw!``M{nG!a1<{gXh;x`<t}A%pc1c
zX=bxWs)iV2<JccoEoCrEani`JxIQed4U4P8;zRAMvGz=vX{_UB*q&;Wh13Y28sSnS
zBdw{v(MCQZ=g8~iEI5y+$W!DAZ~>3Nhy6By*8#GVY$hAQo$Ms7q^Taf!l}RyG>`}h
zf&tDUE+P}8f25z&U)Rrqw|Gi_N`C^NcSOHazfJ$Hen8);Z`L;gsEB@a>)VSE{mrc?
zFlgt}WteEoo|oCk{{{c~Ir0nep#K?K-31QlYSKg|lQH0ixbzG9Tl(*z;)nFxp~6jI
zyXWflx<^OatJ-nE^Y^tKTEDgoY<s;{tU1+B)IX_DsfX2XtDDpn>U4FiS_Y1K%HPp5
z&ift4!{?ou5yBV9seVW{A3?_K7t`&0C?VpiEIuMLEvhsoe3Fe_6%gd0auyMBSvFrS
zTh9GpFrD|Kg!^E6_ZfkaI;Vf6PAwg&lS)SFgyNApzR1$mq;4y?!ZhA55A96BNR`jn
z|F<j|RtWFS<?Cc)^Gj|t3Us+x_CSy)<j2(M61=j!cw`VFxfy&A4cn@SITum#+39>x
z9+orfB09H=FG8t{C_8hw#+_km22)mAdiwB8X=%eX#5G)_IfrW$GF&6+!!?3tX$F(K
zF-~>zMRIDd9m5rh&U;Y8gUXVJL^Gu!QKvX0s@sP|6~T%Q!Z(A_I}$%6S>T35Ijr&?
zIk8n7;_k=2diZo`yTG%*p9~E5?qMe|#J?w}Vjg}G@y4C}TGP#6ZaMm}VW>5?3@PsZ
zz{>x3?*8&G!QH>=v)%o;H{bV#-2K)s!`)vy(%tX7sJqYHrHi=x{UhD|6@Q1j-#^^l
zkMTpF;qEWCHUJlO_t}SS$OlSujI!BnPus|Q`a!aZ6zY#aWW+!89mI2E`8SMH&Rf#H
zHT}u!;Sce)J9B}XdA}e`(Qf2JDm`0`iv<aD*h?qu#9lbd@VHPBoMlXMp+dolIpm|Q
zD<P|&?qmrrdM^Zmmn9hQ&hZK5tgJC{ju%zXQ!Z32q?wAf4PL=vmJV%%(uH(l8Wbxr
zi|v{1Lsj%_4K7B6-V1u9(^+GnA30_}PHseA<e?MNp+LS_*{NAx0h^Ug+KPQbz!Wb5
z`XBN1<uSNO5Y2+;Rztx8IxYhhxw1jSn?O?$!U*$pQY|hNGR*p}nB_$ReFpN$rJ&$o
zh7sLgiyOlb!5l+`RSF~BER8u1Z77TD><D9IK77=54e|+@tXA6EiM(=|SzlLI3H_H$
z<Xr?-2_X)Fl4r~iPWj{GG6)XyKWvY0Zp}tHPBd9hz)Wh(7=wpE{ccp`mURIk9tOw9
z1^7s)be0=M)GTPzZW&{R?slUxK{k7NYyf!$I}?pilNY7aPoX9)4;12t-mcEJ&i)cw
zm4zBQHBfPIssV$QF;+2#ep-EoC=<jOv6T(8VQM5(V3UKf9iAN9h*@3d#8`-Ub5jtD
zv9Ta}CJRLyVG67^u)VvjYhXpY!;W~YvIox|NQzq-4-{roDvL3DlMnBL<Kk5cCc}|S
zcV@%M2}d8uMveK&*I;!~NqV+!>dHY?9O{$k>>QL0NL`(S3SB;(v)()s%zX+^Z^=Qv
zL4T}mY>!beR;w5xFgURSamXMJ_=}vFmXD{RzO=X)&xkSG3R~|SOPy;5fa&R3$3}%Y
z_P~Nk(4}GALLep$EbnVu*V)@&3T4<tAOzNGSmRiXF-F1oK;TPU8JA(+yQEl)49Ohg
zP4iB7<f8l~vX#Q~B_+khMeu)#^^XM*VGkW1V~X9GCB;?6PIok;*u}I3C7yyzz0Q@D
z=B`*7O)FD<PG?4DhMJ+JWu&Pt50N?A=|NS4RnVdoCq}E_orrNtD>e?k1lVu>a?@mO
z*1<;|FN7IqRhd{%fSk$%>UnmwQwjCR38E}9R-S0G&BlFX)x})i>2%>JR2Z#*PH^z$
ztYCAD>@gA+M9!optoOl}C=MunYf9;YFf)9U!SI>I%gy2p>*a|VwdyK|RZ*hAK)BdI
zoY440KFq$>v2lVCoix|i%B+TIAj+VKR${Z^53L5%tP<c<28RwdnCx;eJ|{?uk3R9z
zd0lovZFf;I4^@7h8BX4${-AkgH<B+QVAaRS!2l$hu(FWPqUHiG(KQ$VuA^7yp{mvX
zcwKBs2nY*EYL6KZreP(Lwfk8l&bhE;vvIMvr?b1ieO-J}@g;hi1|vrIScC6?!FRGx
z)i&%K1Ve50ouS_9d%QiS8QNYcv?uosUnge$P<^#k{Yt35qaZw{rlGYxTt7Nj;cQV*
z*)Sim@h-&vU|qxNve~BWp&#U-P(uVdAy^zgw7{D#T&!_;(`1z`r^c*-3){Fv4K~|^
z9dvCz$_RxMZ^{I080tVB;lzu@1MT7X3gw-$O0V-GH@<QU{X;$q4ThlY#F_~~QD$C3
z@u4Sy&s6O7!4d-K+0p}Mk5Cl^2>K)=&XyhNU9j4wDCB^RC%bIqW7uiF3H!^>{0C(p
zs`Q~%1U1udhft*-6cdn)A*e$V3&KcbK@izlP>2K;<k8ndD36QiZYqXR8*F#)(FUam
zXLG~AZ8j+k63=lUg_sUQ8L29fTA4_#Fm)`oJRy}O@&yz50!(Mt=VubnLy6LauEdlE
zS#!lqM6AN1gjAT23QUQ0&<7G{cFUVc9R-rrX%EwxsrhCqt2vKJ&;?$~P2|f-<jaP+
zk2RbXQ*x3UBxr<IOhl0ttPUqjGAD?bnV3#b=(L1RP3Rn^4%;|50EzclHd9$y$&}b=
zMN^_rOhoBmazMeG3N}>eGYp35;1O#cpu&3g(5DlT-I*4J0}*XNYtiOw)3r%jomNTR
zjcC5>m)g&?!`hED3Ow>}v_Y*C-t!TazPSX+gHiKr1q^pzLqe)gNOcLRHX)5+grarU
z(^r$wR;Or3Gr4_3e|z_ezDSB3PLa)HlJ*S&GgDPcLS>3v!DOqchhAEW{CF^G-)7V2
z%MJR!X-A~rNI%p$*$x}PHcgcplxgz2B!j$0D47D(&QE~CsRO3P&@Pd?)W4|5)jOpe
zb+g)}M#RTd+3~ug%%Lc6D97Py(RE6({Iq<Bywm=+xIlbW+-2Wpe?%<Qu9UhQ4>$%L
z(_pQzzoWl%a(4Qcc2td`)VmT@+Z(F+mMlb1K8k`0Gu(akOktdxQf4=!b@XSD4b{?j
zAP~ls@{{uD6WdT84R42)*jGcRt%Brgdfh5;jYrditI%i^p{GD8gh%sDdFG`I8ty=%
z5E>S*GUM!m1{ij89xLg=4k!<Peh11&<@9Y9l+kb}Dn>yo2++fwP`AH?AMc^Q8&Iwk
zI~Omt5=s&YYAm5Rp^0ZLq9NwU7g|Aq75J>cOAoI`HE5I-c&s4bO3S0&-+&7sx%4p>
z<XAzr6=c!IF4!)(tsv71GU(ban4NU`_8R1|r`7Py9(HLZ1e+YDK~Ab&3+cp+(O@@h
zmlo|pJ~_6R>(i`+4J_e}YvJCE!z!m(flN1Tg5narvK!^v#cICEV_sLOLUvOHTaYWR
zgABYG6F8Q^yse_g8^Afd-y>7hgE9vhM-k<lY}#M-n}koaLgk;d-Q<M*JXv91E>2Oe
zkRH>|+ka*Mwml?P34au}%R!m)P2y3<dgXcXTIv4?ha89GWqQEzs^e0Aulx*uPT|zI
zq@B_{$t%7g6!FKDdToI)-=XQhAR)Nxl&ddQZ_tjZKULN+X#TtNG{>N+(_NcUfx@sD
zjquF?&epBC0yR**A4O0-eX$RMIxAL7F9Br|mf3V)KT?Dm6T^||F$`DJ6a6Sh7;WNh
z^CsA7UbqK~0MqLS0BvD9lLa9wR%Hf4rJ0xA?1^Ku!mPwzZqBmta$}Xftd?(q31@e(
z5^pR>4_<|8QGhDz0Y!c*D5Vowti%e6O`yUC_@(uz)?R2;!q%Vhx4Du~z~XHACEk(G
z%whD-i`cy;g4nIB5dB~y(&)z<P{8i7v~VpeKpQu*lOhYXd35hac>B5ZiH*=uj+F~8
zVg=}ly)gW2T6s09v1eJ;4=#)dZnJHew#0BU=}DF+!$R(+MIpel3F$Q2eGMeItOS6x
z-D!!Z0NuodHJ!W(dN>ncD`+P2*h)`~O0~LEup5N{)n{NC*cD3!*Rn!(*{Th0WEta^
zNC0sY=^{O{30k!$k!}~PLhR-X;GDr-;F!v|WmdolT`Acyyh(ug%W#XUI{|yZ8zT3^
z(^d|_?TB*}qgKZW(yae4`6TxSSFaQ8De^OtsrRVQJGQ8mN*H@IuX0*?Rj!e55dSP4
zkj9JO62=O@<=+x^ic|O>@YA@P@vHbIJWbhXF9G}e=L5G*6qkx{9}6L71q1Z_y|_Zr
zDndh)I}hOsPRppG2iD`IsFJ?Jf(rV*>rn+*z^8WN$zTCpyYL*afDi=eo?W<14z!4H
z>j)f3xYAbzSF`-$g$w@K;`nCTvK!~q-|oT@xilrud`K@zrU!T92rx0tyK$pXG*gVU
z(ED~{H(j;|R||!SIABhO>stXRTaZvv-xe_UAMD2L7FR&IaKXDwgnL}jlT%Xz>=su<
z8kMSnD_jxDlcIt9TOsbkg?xI?Zaf`6B(7~}4xc+;oJ3FU!x_dE(<C}=AFc)as&9vj
zWPez|a%Z#1T$DwRY)8e$j)eixxmg4*ana5D@C=keXYN2PfKRjwX!H|{0*(t8(qhe;
zHw7t$z6q|WVr4TuvIFwN{jCU?;M;aWF~W*Xp|9=+2~6;8K(1NO@x=kUa}U^SxSHjI
zn_8?d4l~KTtOYZpBr62uMkF~l>y#N9!@Y!+km#Fx;MfbUaXI1;yl_FJd-g!fc9wRz
zB*cr&9ssieaE<_+%~FS#vcYoncYD!72@qSBY><s0&&dq8Onznqybe22g4<BH5rN$#
zXrupnD{3f6IscK#K^u7=PV`@f6QJYd7<mBBo(@8ZEo8aE0qw)Ce4Un)B6xmrt(X+y
z?n_)NBt^LV64!D`5zCw)oAsW2@IJ&}!bSBnRD2f=fIru!KXm3(^r4emCVxs#6I{fE
z2c4Mr1yto>8(F76uQzG`p>2n20uQQF9j6`39O=r#j+2f>%3r|)YT(8~Erg?osxjdn
zxhVhW>VU7llg?tiphYtx?=VUcY|(#-Hca6Pk@&?3LRnz^SArSL`%GpK2vSA@DvSiQ
zNIv?<OjI~2+uE9a9*Y;>4ytkCALa1`;PGG~++FV*_gVDa2-faPW#sZjj%RmVOkQrX
zhDH!^3xJ5T_!uA%h$+PgxcE*t&YJyQlp964D0lE;l-fnfvyt?edDp?}g2{`;C^5!|
znQR!4VI>7lw>QRwm1Lw@JXrCpXj(RKU>Qn=D{aNU#8~*vGr%Y;DF~0IM_kCekg@3&
zt>A@yJ&6;Y@#B;jkbu#MbAw(sF~B(FO#NxRMmN+rNeD9{Y*EC#C0}4(wSTR#fUc;=
z`QS)xt_MRLqR-UhjbfF%#gms8F+w#t%%Stq?F~32R=US#Mj{dO*9w`PD2=|-fG3I-
za0fr#Q*Ag$XHoZhb|4VNW$^Xe6U7~38N1e>UTwCuevXeu#^Pcz=pLV0U0rSd9^v^p
z>2%9j_~}G|{&Fm4?%n0%@b^(EJv$EXe((}(_swW$#<2~Kv%mUf#(%$GW_+!b(NLNM
z7jf6=ujuo&pKBfJ^Xe+cZyXbqyOk{Y2I(A}XgzJ5a^C*cLDg3WRsVwzszTgm5~aWU
z2|fV(>DB*?4cJeA3V~85+gh5ldVmw8jT>O6@#LMjRjExV4d2utU33?2MPukAcj22*
z4V`&6?tzWKqj%%|!28U)2RFlp`mTGR<}e+1FWv{=fv4}qd*K`wf-!X8A-rHYTc?%q
zyA|>XSxhqifBYl{)_C7nzk~VecQBv-JD3C!px|k?9NX<SbWFWU>l{i1;M1Q+1$?PQ
zfKbleY}-#y?8INQ$bczvV!?QJx}Uyq53Y2$U6GXieu5L=r`hIw9w(q|6t-FEUpgnC
zY{aj}c!Mv<2?#mLMr6=}8*w`035?$_7!6zF{~|X4w&-q)L22^;H{b?ZWPF+E2L>3)
z^pbsO{1iqD_=M#)X&PKBT~0E^AM3~TZ|GUtlkh9AfO=Zpqh8{8$8n2ey7HlNyRy_?
zY=1@k5AiZ#x$vZYi~Om4i#$&Hy>vBft8?Kl%N8*HQ5xQgTj0~Np9S^wT^7{Q#%&PP
z()(C2hB~+7ugNv7Vhfxr04p@OFlfA6Ez!N(aR9y-4{paHY4k8U2w0^26cru88JWD2
z9OspibdK!0Qfy`f8&d`78X(xXG)MTeXfq*@q`(+OCX^=QDewnwmT^-;-o;3-8%;iJ
n2uT(J8pxZ-8)wY`nFS`f1q|#6CX3Iy7~vHovSPGWD%JI$rX6Up

diff --git a/reference/golden/cpp/edges.json b/reference/golden/cpp/edges.json
index 985865e..76282c4 100644
--- a/reference/golden/cpp/edges.json
+++ b/reference/golden/cpp/edges.json
@@ -281,6 +281,51 @@
     "source": "class:e436be77a00102552decf9de5d7cc052",
     "target": "method:a6af941ba6640f7d90fbc15666e6ba07"
   },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:attr_macro.c",
+    "target": "function:1d078c66ad4466dcd00a4e86ba1ebea5"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:attr_macro.c",
+    "target": "function:6e304d51a1ee63c7d5bb288807a0f3d4"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:attr_macro.c",
+    "target": "function:7e2449f360c626a4e18a36881fdbc951"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:attr_macro.c",
+    "target": "function:a424497bfe1ede5cb33b9d2d07d055de"
+  },
+  {
+    "col": null,
+    "kind": "contains",
+    "line": null,
+    "metadata": null,
+    "provenance": null,
+    "source": "file:attr_macro.c",
+    "target": "type_alias:caaa44878103ad32c73cd2d65f53d172"
+  },
   {
     "col": null,
     "kind": "contains",
diff --git a/reference/golden/cpp/files.json b/reference/golden/cpp/files.json
index 5f68468..239fad0 100644
--- a/reference/golden/cpp/files.json
+++ b/reference/golden/cpp/files.json
@@ -1,4 +1,12 @@
 [
+  {
+    "content_hash": "ae235688285955ff53f65aa9468ee11fc2691fac2cbd99b76f36b6d72f363a98",
+    "errors": null,
+    "language": "c",
+    "node_count": 6,
+    "path": "attr_macro.c",
+    "size": 275
+  },
   {
     "content_hash": "918ff675ba5d4bc2916b5f0b01a6efe803acec492ab71f0bf83c593be612a202",
     "errors": null,
diff --git a/reference/golden/cpp/nodes.json b/reference/golden/cpp/nodes.json
index c5c608b..544c11e 100644
--- a/reference/golden/cpp/nodes.json
+++ b/reference/golden/cpp/nodes.json
@@ -241,6 +241,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 0,
+    "end_line": 20,
+    "file_path": "attr_macro.c",
+    "id": "file:attr_macro.c",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "file",
+    "language": "c",
+    "name": "attr_macro.c",
+    "qualified_name": "attr_macro.c",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 1,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -439,6 +461,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 11,
+    "file_path": "attr_macro.c",
+    "id": "function:1d078c66ad4466dcd00a4e86ba1ebea5",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "c",
+    "name": "LostName",
+    "qualified_name": "LostName",
+    "return_type": "UINT32",
+    "signature": null,
+    "start_column": 9,
+    "start_line": 9,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -505,6 +549,50 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 19,
+    "file_path": "attr_macro.c",
+    "id": "function:6e304d51a1ee63c7d5bb288807a0f3d4",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "c",
+    "name": "PtrRet",
+    "qualified_name": "PtrRet",
+    "return_type": "UINT32",
+    "signature": null,
+    "start_column": 9,
+    "start_line": 17,
+    "type_parameters": null,
+    "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 15,
+    "file_path": "attr_macro.c",
+    "id": "function:7e2449f360c626a4e18a36881fdbc951",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "c",
+    "name": "NoAttr",
+    "qualified_name": "NoAttr",
+    "return_type": "UINT32",
+    "signature": null,
+    "start_column": 0,
+    "start_line": 13,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -593,6 +681,28 @@
     "type_parameters": null,
     "visibility": null
   },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 1,
+    "end_line": 7,
+    "file_path": "attr_macro.c",
+    "id": "function:a424497bfe1ede5cb33b9d2d07d055de",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "function",
+    "language": "c",
+    "name": "GoodName",
+    "qualified_name": "GoodName",
+    "return_type": "VOID",
+    "signature": null,
+    "start_column": 9,
+    "start_line": 6,
+    "type_parameters": null,
+    "visibility": null
+  },
   {
     "decorators": null,
     "docstring": null,
@@ -1076,5 +1186,27 @@
     "start_line": 1,
     "type_parameters": null,
     "visibility": null
+  },
+  {
+    "decorators": null,
+    "docstring": null,
+    "end_column": 28,
+    "end_line": 4,
+    "file_path": "attr_macro.c",
+    "id": "type_alias:caaa44878103ad32c73cd2d65f53d172",
+    "is_abstract": 0,
+    "is_async": 0,
+    "is_exported": 0,
+    "is_static": 0,
+    "kind": "type_alias",
+    "language": "c",
+    "name": "UINT32",
+    "qualified_name": "UINT32",
+    "return_type": null,
+    "signature": null,
+    "start_column": 0,
+    "start_line": 4,
+    "type_parameters": null,
+    "visibility": null
   }
 ]

From 87a46dcda7fc5e1de95ff39f6c1286250b79960c Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 06:32:35 +0800
Subject: [PATCH 46/91] fix(c): blank only provably attribute-like leading
 macros

---
 crates/codegraph-extract/src/lang/c.rs    | 216 ++++++++++++++++++---
 crates/codegraph-extract/src/walker.rs    |  79 +++++++-
 docs/equivalence.md                       |   5 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 219 ++++++++++++++++++++++
 4 files changed, 486 insertions(+), 33 deletions(-)

diff --git a/crates/codegraph-extract/src/lang/c.rs b/crates/codegraph-extract/src/lang/c.rs
index 5f1ac1c..fe40c52 100644
--- a/crates/codegraph-extract/src/lang/c.rs
+++ b/crates/codegraph-extract/src/lang/c.rs
@@ -1,5 +1,6 @@
 //! C `LanguageSpec`, ported from `upstream extraction/languages/c-cpp.ts:98-142`.
 
+use std::collections::BTreeSet;
 use std::sync::OnceLock;
 
 use codegraph_core::types::{Language, NodeKind};
@@ -92,35 +93,74 @@ impl LanguageSpec for CSpec {
     }
 }
 
-/// Blank an unknown attribute macro sitting in front of a C function
-/// definition's return type: `SEC_ATTR UINT32 LostName(VOID) { … }` (a macro
-/// wrapping `__attribute__((…))`, common in embedded/kernel/firmware C).
+/// Blank an attribute macro sitting in front of a C function definition's return
+/// type: `SEC_ATTR UINT32 LostName(VOID) { … }` where `SEC_ATTR` is a macro
+/// wrapping `__attribute__((…))` (common in embedded/kernel/firmware C).
 /// tree-sitter's C grammar reads the macro as the declaration's type and the real
 /// return type as the declarator, so the function indexes under the RETURN TYPE's
 /// name (`UINT32`) or, in other spacings, under its parameter list — the real name
 /// is lost and the symbol is unfindable (#1311).
 ///
-/// Attribute macros are project-specific, so this keys on STRUCTURE, not a
-/// curated list, matched tightly: a line-leading (declaration-position) ALL-CAPS
-/// token of ≥3 chars, followed by TWO identifier tokens (return type, then name;
-/// `*` allowed between them for pointer returns) and then `(` — i.e. exactly the
-/// `MACRO Ret name(` definition shape. `MACRO name(` calls, `#define` lines (they
-/// start with `#`, which `^[ \t]*` cannot skip), multi-word builtin returns
-/// (`MACRO unsigned int f(`, where the grammar already keeps the name), and
-/// mid-line uses are all rejected by construction.
+/// # Why the structural heuristic alone is WRONG
+///
+/// The obvious rule — "line-leading ALL-CAPS token, then two identifiers, then
+/// `(`" — is purely lexical, and the shape `MACRO Ret name(` is INDISTINGUISHABLE
+/// from `Ret CALLCONV name(` and from `KEYWORD_ALIAS Ret name(`. Measured on real
+/// firmware-flavoured C, the permissive form DAMAGED correct extraction:
+///
+/// | source                                 | correct      | permissive rule |
+/// | -------------------------------------- | ------------ | --------------- |
+/// | `EFI_STATUS EFIAPI DriverEntry (VOID)` | `EFI_STATUS` | `EFIAPI` ✗       |
+/// | `STATIC void helper (void)`             | `STATIC`     | dropped ✗       |
+/// | `CONST CHAR8 *GetName (VOID)`           | `CONST`      | `CHAR8`         |
+///
+/// `EFI_STATUS` / `UINT32` / `CHAR8` are typedef'd RETURN TYPES and `STATIC` /
+/// `EXTERN` / `INLINE` / `CONST` are macro aliases for keywords; none is an
+/// attribute macro, yet all are all-caps identifiers of ≥3 chars in declaration
+/// position. No all-caps-plus-length heuristic can separate them, so the token's
+/// spelling is not admissible evidence.
+///
+/// # The rule actually applied
+///
+/// Blank ONLY when the SAME translation unit proves the token is attribute-like:
+/// it has an object-like `#define TOKEN …` in this file whose replacement text is
+/// either EMPTY or contains an attribute construct (`__attribute__`, `__attribute`,
+/// `__declspec`, `__asm`, `__pragma`, `_Pragma`). Every other leading
+/// token — typedef'd return type, keyword alias, calling convention, or a macro
+/// defined in a header this pass cannot see — is left untouched, so the parse is
+/// byte-identical to not having this pass at all.
+///
+/// Function-like `#define TOKEN(x) …` is deliberately NOT accepted: those are used
+/// as `TOKEN(arg) …`, not as a bare leading token, and the `(`-suffixed name would
+/// be a different lexeme anyway.
+///
+/// # Documented limitation
+///
+/// `pre_parse` sees one file, so a macro `#define SEC_ATTR __attribute__((…))`
+/// living in a HEADER and used in a `.c` yields NO evidence and the source is left
+/// untouched — #1311's symptom persists for that (very common) layout. That is
+/// deliberate: a cross-file macro table would be non-deterministic with respect to
+/// include order, and guessing from spelling is what produced the regression
+/// above. Under-fixing is recoverable; corrupting ordinary C is not.
 ///
 /// Blanking replaces the macro with equal-length ASCII spaces, so every byte
-/// offset — and therefore every line/column — is preserved, exactly like the C++
-/// blanks in `lang/cpp.rs`.
+/// offset — and therefore every line/column and every node ID — is preserved,
+/// exactly like the C++ blanks in `lang/cpp.rs`.
 fn blank_c_leading_attr_macros(source: &str) -> String {
+    let attr_macros = attribute_like_defines(source);
+    if attr_macros.is_empty() {
+        return source.to_string();
+    }
     static RE: OnceLock<Regex> = OnceLock::new();
     let re = RE.get_or_init(|| {
-        Regex::new(r"(?m)^[ \t]*([A-Z][A-Z0-9_]{2,})\s+[A-Za-z_]\w*[\s*]+[A-Za-z_]\w*\s*\(")
+        Regex::new(r"(?m)^[ \t]*([A-Za-z_]\w*)\s+[A-Za-z_]\w*[\s*]+[A-Za-z_]\w*\s*\(")
             .expect("c-leading-attr-macro regex")
     });
     let spans: Vec<(usize, usize)> = re
         .captures_iter(source)
-        .filter_map(|caps| caps.get(1).map(|m| (m.start(), m.end())))
+        .filter_map(|caps| caps.get(1))
+        .filter(|m| attr_macros.contains(m.as_str()))
+        .map(|m| (m.start(), m.end()))
         .collect();
     if spans.is_empty() {
         return source.to_string();
@@ -134,6 +174,64 @@ fn blank_c_leading_attr_macros(source: &str) -> String {
     String::from_utf8(bytes).unwrap_or_else(|_| source.to_string())
 }
 
+/// Attribute constructs whose presence in a `#define`'s replacement text proves
+/// the macro is an attribute wrapper rather than a type or keyword alias.
+const C_ATTRIBUTE_CONSTRUCTS: [&str; 6] = [
+    "__attribute__",
+    "__attribute",
+    "__declspec",
+    "__asm",
+    "__pragma",
+    "_Pragma",
+];
+
+/// Collect the object-like `#define`s in THIS file whose replacement text is empty
+/// or contains an attribute construct — i.e. the tokens that are provably safe to
+/// blank in declaration position. A `BTreeSet` keeps membership order-independent
+/// so extraction stays deterministic.
+fn attribute_like_defines(source: &str) -> BTreeSet<&str> {
+    let mut names = BTreeSet::new();
+    if !source.contains("#define") {
+        return names;
+    }
+    for line in source.lines() {
+        let rest = match line.trim_start().strip_prefix('#') {
+            Some(rest) => rest.trim_start(),
+            None => continue,
+        };
+        let rest = match rest.strip_prefix("define") {
+            Some(rest) => rest,
+            None => continue,
+        };
+        // `#defineFOO` is not a define; a separator is required.
+        if !rest.starts_with([' ', '\t']) {
+            continue;
+        }
+        let rest = rest.trim_start();
+        let name_end = rest
+            .find(|c: char| !(c == '_' || c.is_ascii_alphanumeric()))
+            .unwrap_or(rest.len());
+        let (name, replacement) = rest.split_at(name_end);
+        if name.is_empty() || name.starts_with(|c: char| c.is_ascii_digit()) {
+            continue;
+        }
+        // Function-like macro (`#define F(x) …`) — never used as a bare leading
+        // token, so it is not a candidate.
+        if replacement.starts_with('(') {
+            continue;
+        }
+        let replacement = replacement.trim();
+        if replacement.is_empty()
+            || C_ATTRIBUTE_CONSTRUCTS
+                .iter()
+                .any(|marker| replacement.contains(marker))
+        {
+            names.insert(name);
+        }
+    }
+    names
+}
+
 pub(crate) fn include_import(node: Node<'_>, source: &str) -> Option<ImportInfo> {
     let signature = node_text(node, source).trim().to_string();
     for child in node.named_children(&mut node.walk()) {
@@ -248,18 +346,44 @@ mod tests {
         assert_eq!(CSpec.pre_parse(src, "m.c"), src);
     }
 
+    const ATTR_DEFINE: &str = "#define SEC_ATTR __attribute__((section(\".init\")))\n";
+
     #[test]
-    fn blank_c_leading_attr_macro_blanks_the_definition_shape() {
-        let src = "SEC_ATTR UINT32 f(void) {}";
-        let out = blank_c_leading_attr_macros(src);
-        assert_eq!(out, "         UINT32 f(void) {}");
+    fn blank_c_leading_attr_macro_blanks_a_same_file_proved_macro() {
+        let src = format!("{ATTR_DEFINE}SEC_ATTR UINT32 f(void) {{}}");
+        let out = blank_c_leading_attr_macros(&src);
+        assert_eq!(out, format!("{ATTR_DEFINE}         UINT32 f(void) {{}}"));
         assert_eq!(out.len(), src.len());
     }
 
+    #[test]
+    fn blank_c_leading_attr_macro_accepts_an_empty_define() {
+        let src = "#define SEC_ATTR\nSEC_ATTR UINT32 f(void) {}";
+        assert_eq!(
+            blank_c_leading_attr_macros(src),
+            "#define SEC_ATTR\n         UINT32 f(void) {}"
+        );
+    }
+
+    #[test]
+    fn blank_c_leading_attr_macro_accepts_declspec_and_asm_defines() {
+        for define in ["#define DLL_A __declspec(dllexport)", "#define NAKED __asm"] {
+            let name = define.split_whitespace().nth(1).expect("macro name");
+            let src = format!("{define}\n{name} UINT32 f(void) {{}}");
+            let out = blank_c_leading_attr_macros(&src);
+            assert!(
+                out.lines().nth(1).expect("body line").starts_with("     "),
+                "{define} should have proved `{name}` blankable, got: {out}"
+            );
+            assert_eq!(out.len(), src.len());
+        }
+    }
+
     #[test]
     fn blank_c_leading_attr_macro_is_offset_preserving() {
-        let src = "SEC_ATTR\nUINT32 f(void) {}\nSEC_ATTR VOID g(VOID) {}\n";
-        let out = blank_c_leading_attr_macros(src);
+        let src =
+            format!("{ATTR_DEFINE}SEC_ATTR\nUINT32 f(void) {{}}\nSEC_ATTR VOID g(VOID) {{}}\n");
+        let out = blank_c_leading_attr_macros(&src);
         assert_eq!(out.len(), src.len());
         assert_eq!(
             out.bytes().filter(|&b| b == b'\n').count(),
@@ -268,11 +392,21 @@ mod tests {
     }
 
     #[test]
-    fn blank_c_leading_attr_macro_leaves_other_shapes_untouched() {
+    fn blank_c_leading_attr_macro_handles_pointer_returns() {
+        let src = format!("{ATTR_DEFINE}SEC_ATTR UINT32 *f(void) {{}}");
+        assert_eq!(
+            blank_c_leading_attr_macros(&src),
+            format!("{ATTR_DEFINE}         UINT32 *f(void) {{}}")
+        );
+    }
+
+    #[test]
+    fn blank_c_leading_attr_macro_leaves_unproved_leading_tokens_untouched() {
         for src in [
+            "SEC_ATTR UINT32 f(void) {}",
             "UINT32 helper(void) {}",
             "MY_ASSERT(x);",
-            "#define SEC_ATTR __attribute__((section(\".init\")))",
+            ATTR_DEFINE,
             "SEC_ATTR unsigned int f(void) {}",
             "x = SEC_ATTR UINT32 y(z);",
         ] {
@@ -280,12 +414,38 @@ mod tests {
         }
     }
 
+    // The rows that the earlier ALL-CAPS-only rule DAMAGED: a typedef'd return type
+    // in front of a calling-convention macro, and keyword-alias macros. None has an
+    // attribute-like `#define`, so none may be touched even though `SEC_ATTR`'s
+    // define makes the pass active in the same file.
     #[test]
-    fn blank_c_leading_attr_macro_handles_pointer_returns() {
-        let src = "SEC_ATTR UINT32 *f(void) {}";
-        assert_eq!(
-            blank_c_leading_attr_macros(src),
-            "         UINT32 *f(void) {}"
+    fn blank_c_leading_attr_macro_leaves_return_types_and_keyword_aliases_untouched() {
+        for line in [
+            "EFI_STATUS EFIAPI DriverEntry (VOID) {}",
+            "CONST CHAR8 *GetName (VOID) {}",
+            "STATIC void helper (void) {}",
+            "UINT32 Untouched (void) {}",
+        ] {
+            let src = format!("{ATTR_DEFINE}{line}\n");
+            assert_eq!(
+                blank_c_leading_attr_macros(&src),
+                src,
+                "must stay untouched: {line}"
+            );
+        }
+    }
+
+    #[test]
+    fn attribute_like_defines_rejects_types_keywords_and_function_like_macros() {
+        let src = concat!(
+            "#define VOID void\n",
+            "#define STATIC static\n",
+            "#define CONST const\n",
+            "#define EFIAPI\n",
+            "#define CHECK(x) __attribute__((unused)) x\n",
+            "#define SEC_ATTR __attribute__((section(\".init\")))\n"
         );
+        let names: Vec<&str> = attribute_like_defines(src).into_iter().collect();
+        assert_eq!(names, ["EFIAPI", "SEC_ATTR"]);
     }
 }
diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 4bbdfcb..7afa82c 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -5594,6 +5594,8 @@ struct Bar { int x; };
 
     // ---- Batch B4: C leading attribute macros (upstream b6a05d1) ----
 
+    const C_ATTR_DEFINE: &str = "#define SEC_ATTR __attribute__((section(\".init\")))\n";
+
     fn c_names(src: &str) -> Vec<String> {
         let (nodes, _) = run("attrs.c", src, Language::C);
         nodes
@@ -5603,19 +5605,40 @@ struct Bar { int x; };
             .collect()
     }
 
+    fn c_function_return_types(src: &str) -> Vec<(String, i64, String)> {
+        let (nodes, _) = run("attrs.c", src, Language::C);
+        let mut rows: Vec<(String, i64, String)> = nodes
+            .iter()
+            .filter(|n| n.kind == NodeKind::Function)
+            .map(|n| {
+                (
+                    n.name.clone(),
+                    n.start_line,
+                    n.return_type
+                        .clone()
+                        .unwrap_or_else(|| "<NULL>".to_string()),
+                )
+            })
+            .collect();
+        rows.sort_by_key(|(_, line, _)| *line);
+        rows
+    }
+
     #[test]
     fn c_leading_attr_macro_function_indexes_under_its_real_name() {
-        let names = c_names("SEC_ATTR UINT32 Foo (VOID) { return 0; }\n");
+        let names = c_names(&format!(
+            "{C_ATTR_DEFINE}SEC_ATTR UINT32 Foo (VOID) {{ return 0; }}\n"
+        ));
         assert_eq!(
             names,
             vec!["Foo".to_string()],
-            "a function behind a leading attribute macro must index as `Foo`"
+            "a function behind a same-file-proved attribute macro must index as `Foo`"
         );
     }
 
     #[test]
     fn c_leading_attr_macro_with_macro_return_type_indexes_under_its_real_name() {
-        let names = c_names("SEC_ATTR VOID Foo (VOID) { }\n");
+        let names = c_names(&format!("{C_ATTR_DEFINE}SEC_ATTR VOID Foo (VOID) {{ }}\n"));
         assert_eq!(
             names,
             vec!["Foo".to_string()],
@@ -5623,6 +5646,52 @@ struct Bar { int x; };
         );
     }
 
+    // NEGATIVE CONTROL for the tightened rule (#1311 follow-up). Firmware-flavoured
+    // C where the leading ALL-CAPS token is a typedef'd RETURN TYPE or a
+    // keyword-alias macro, NOT an attribute macro. The earlier purely structural
+    // rule blanked the return type here (`EFI_STATUS`→`EFIAPI`, `STATIC`→dropped);
+    // the return types below are the ones extraction produced BEFORE any blanking
+    // existed, so this test fails under the permissive rule and passes under the
+    // `#define`-proved one. `SEC_ATTR`'s define is present so the pass is ACTIVE.
+    #[test]
+    fn c_leading_typedef_return_and_keyword_alias_macros_keep_their_return_types() {
+        let src = format!(
+            "{C_ATTR_DEFINE}{}",
+            concat!(
+                "EFI_STATUS EFIAPI DriverEntry (VOID) {\n",
+                "  return 0;\n",
+                "}\n",
+                "CONST CHAR8 *GetName (VOID) {\n",
+                "  return 0;\n",
+                "}\n",
+                "STATIC void helper (void) {\n",
+                "}\n",
+                "UINT32 Untouched (void) {\n",
+                "  return 0;\n",
+                "}\n"
+            )
+        );
+        assert_eq!(
+            c_function_return_types(&src),
+            vec![
+                ("DriverEntry".to_string(), 2, "EFI_STATUS".to_string()),
+                ("GetName".to_string(), 5, "CONST".to_string()),
+                ("helper".to_string(), 8, "STATIC".to_string()),
+                ("Untouched".to_string(), 10, "UINT32".to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn c_leading_attr_macro_without_a_visible_define_is_left_untouched() {
+        assert_eq!(
+            c_function_return_types("SEC_ATTR UINT32 Foo (VOID) { return 0; }\n"),
+            vec![("UINT32".to_string(), 1, "SEC_ATTR".to_string())],
+            "with no same-file `#define` the source must parse exactly as it did \
+             before this pass existed — #1311 stays unfixed for header-defined macros"
+        );
+    }
+
     #[test]
     fn c_isolation_table_functions_all_index_under_real_names() {
         let src = concat!(
@@ -5663,7 +5732,9 @@ struct Bar { int x; };
     fn c_plain_typedef_return_and_macro_call_shapes_unaffected() {
         assert_eq!(c_names("UINT32 helper (void) { return 0; }\n"), ["helper"]);
         assert_eq!(
-            c_names("SEC_ATTR unsigned int f(void) { return 0; }\n"),
+            c_names(&format!(
+                "{C_ATTR_DEFINE}SEC_ATTR unsigned int f(void) {{ return 0; }}\n"
+            )),
             ["f"]
         );
         let (nodes, _) = run("call.c", "void g(void) { MY_ASSERT(x); }\n", Language::C);
diff --git a/docs/equivalence.md b/docs/equivalence.md
index d2873fa..ee17963 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -292,7 +292,10 @@ Five further files exercise the Batch B C/C++ gains:
   tree-sitter's C grammar reads the macro as the type and the real return type as
   the declarator, so before the fix these indexed under the RETURN TYPE's name
   (`VOID` / `UINT32`); the golden now pins all four under their real names with
-  their real return types.
+  their real return types. The blank fires ONLY because `#define SEC_ATTR
+__attribute__((section(".init")))` is visible IN THIS FILE — the pass demands
+  same-file `#define` proof that a leading token is attribute-like, so this fixture
+  also pins that evidence requirement, not just the macro's name.
 
 - **namespaced out-of-line method + fully-qualified call** (upstream #1310) —
   `namespaced_member.hpp` declares `namespace simulator { class ManifestStartup }`
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 532d5bb..e0daa68 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -3934,3 +3934,222 @@ codegraph-bench` → exit 0, **1393 passed across 35 test binaries, 0 failed**,
 `lsp_diagnostics` remains unusable in this worktree (`LSP file path must be inside
 request cwd`); locked Cargo is the fallback. No dependency, version or
 `Cargo.lock` byte changed.
+
+## Batch B4 CORRECTION — the leading-attr-macro blank over-triggered; tightened to require same-file `#define` proof (2026-07-28)
+
+The `e95072c` section ABOVE stands as the record of what was shipped and why it
+passed its own tests; it is left intact deliberately. This section corrects it.
+Orchestrator review REJECTED `e95072c`: its `blank_c_leading_attr_macros` over-fires
+and DAMAGES correct extraction of ordinary C. This is a follow-up commit; `e95072c`
+was NOT amended.
+
+### The measured regression (reproduced here, not re-derived)
+
+Probe file `/tmp/cprobe/edk.c` (firmware-flavoured C, NO `#define` in it):
+
+```c
+EFI_STATUS EFIAPI DriverEntry (VOID) { return 0; }
+CONST CHAR8 *GetName (VOID) { return 0; }
+STATIC void helper (void) { }
+UINT32 Untouched (void) { return 0; }
+```
+
+Method: build `target/debug/codegraph` at each commit's `lang/c.rs`, then
+`codegraph init /tmp/cprobe` and
+`sqlite3 /tmp/cprobe/.codegraph-v2/codegraph.db "select name, start_line,
+coalesce(return_type,'<NULL>') from nodes where kind='function' order by
+start_line;"`. Note the DB path is `.codegraph-v2/`, not `.codegraph/`.
+
+| source line                            | parent `288d892` | `e95072c` | verdict              |
+| -------------------------------------- | ---------------- | --------- | -------------------- |
+| `EFI_STATUS EFIAPI DriverEntry (VOID)` | `EFI_STATUS`     | `EFIAPI`  | **REGRESSION**       |
+| `CONST CHAR8 *GetName (VOID)`          | `CONST`          | `CHAR8`   | improvement          |
+| `STATIC void helper (void)`            | `STATIC`         | `<NULL>`  | **information lost** |
+| `UINT32 Untouched (void)`              | `UINT32`         | `UINT32`  | untouched, correct   |
+
+Raw output, verbatim:
+
+```
+===== PARENT 288d892 =====        ===== HEAD e95072c =====
+DriverEntry|1|EFI_STATUS          DriverEntry|1|EFIAPI
+GetName|5|CONST                   GetName|5|CHAR8
+helper|9|STATIC                   helper|9|<NULL>
+Untouched|12|UINT32               Untouched|12|UINT32
+```
+
+The function NAMES were already correct at the parent in all four rows
+(`DriverEntry`, `GetName`, `helper`, `Untouched`), so #1311's "name is lost"
+symptom does NOT occur for these shapes at all — `attr_macro.c` only reproduces it
+through the specific `VOID`/`UINT32` typedef spacing it was written around. A green
+suite proved nothing because the fixture encoded only the author's assumed world.
+
+### Root cause
+
+The regex was purely structural: `(?m)^[ \t]*([A-Z][A-Z0-9_]{2,})\s+[A-Za-z_]\w*[\s*]+[A-Za-z_]\w*\s*\(`
+— "line-leading ALL-CAPS token + two identifiers + `(`" ⇒ blank the first token.
+That shape ALSO matches `RETURN_TYPE CALLCONV name(` and `KEYWORD_ALIAS Ret name(`,
+where the token blanked is the return type itself. `EFI_STATUS` / `UINT32` /
+`CHAR8` are typedef'd return types; `STATIC` / `EXTERN` / `INLINE` / `CONST` are
+macro aliases for keywords. All are lexically identical to a true attribute macro,
+so no all-caps-plus-length heuristic can separate them. The token's SPELLING is not
+admissible evidence.
+
+### The tightened rule
+
+`blank_c_leading_attr_macros` now blanks a leading token ONLY when the SAME
+translation unit proves it is attribute-like: the file contains an OBJECT-LIKE
+`#define TOKEN …` whose replacement text is either EMPTY or contains an attribute
+construct (`__attribute__`, `__attribute`, `__declspec`, `__asm`, `__pragma`,
+`_Pragma`). New helper `attribute_like_defines(source) -> BTreeSet<&str>` collects
+that set (a `BTreeSet` keeps membership order-independent, so extraction stays
+deterministic); function-like `#define F(x) …` is rejected because it is never used
+as a bare leading token. When the set is empty the function returns the source
+unchanged, so the whole pass is inert on any file without such a `#define`.
+
+Unknown token ⇒ do nothing. Never blank on suspicion.
+
+Measured per-row behaviour of the tightened version on the SAME `edk.c` (no
+`#define` present, so the pass never activates):
+
+| source line                            | tightened    | reason                                                   |
+| -------------------------------------- | ------------ | -------------------------------------------------------- |
+| `EFI_STATUS EFIAPI DriverEntry (VOID)` | `EFI_STATUS` | no `#define EFI_STATUS` here ⇒ untouched, matches parent |
+| `CONST CHAR8 *GetName (VOID)`          | `CONST`      | no `#define CONST` here ⇒ untouched, matches parent      |
+| `STATIC void helper (void)`            | `STATIC`     | no `#define STATIC` here ⇒ untouched, matches parent     |
+| `UINT32 Untouched (void)`              | `UINT32`     | never matched the shape anyway                           |
+
+Byte-identical to `288d892` on all four rows — verified by re-running the same
+`codegraph init` + `sqlite3` probe with the tightened release binary:
+
+```
+===== TIGHTENED, no #define in edk.c =====
+DriverEntry|1|EFI_STATUS
+GetName|5|CONST
+helper|9|STATIC
+Untouched|12|UINT32
+```
+
+Honest note on `STATIC` and `CONST`: if a file DID carry `#define STATIC static`
+or `#define CONST const`, those replacements are neither empty nor attribute
+constructs, so `attribute_like_defines` still rejects them and the tokens stay
+untouched — pinned by
+`attribute_like_defines_rejects_types_keywords_and_function_like_macros`. They are
+only ever blanked if a project literally writes `#define STATIC` (empty) or
+`#define STATIC __attribute__((…))`, in which case blanking is correct.
+
+#1311's fixture still works because `#define SEC_ATTR
+__attribute__((section(".init")))` is visible INSIDE `attr_macro.c`: `SEC_ATTR` is
+still blanked and `LostName` still indexes under its real name. Confirmed on the
+regenerated fixture DB:
+
+```
+attr_macro.c|1|<NULL>      UINT32|4|<NULL>     GoodName|6|VOID
+LostName|9|UINT32          NoAttr|13|UINT32    PtrRet|17|UINT32
+```
+
+A cross-file probe (`/tmp/cprobe2/hdr_defined.c`, which carries the `SEC_ATTR`
+define AND the firmware shapes) shows both behaviours coexisting in one file:
+`LostName2` keeps its real name with `rt=UINT32` (macro blanked) while
+`DriverEntry2` keeps `EFI_STATUS` and `helper2` keeps `STATIC` (untouched).
+
+### Documented limitation (deliberate under-fix)
+
+`pre_parse` receives `(source, file_path)` and sees ONE file. A macro
+`#define SEC_ATTR __attribute__((…))` living in a HEADER and used in a `.c` yields
+NO evidence, so that source is left untouched and #1311's symptom PERSISTS for
+that (very common) layout. That is the honest behaviour: a cross-file macro table
+would be non-deterministic with respect to include order, and guessing from
+spelling is exactly what produced the regression above. Under-fixing is
+recoverable; corrupting ordinary C is not. Pinned by
+`c_leading_attr_macro_without_a_visible_define_is_left_untouched`, which asserts
+the pre-blank output (`name=UINT32`, `rt=SEC_ATTR`) rather than pretending it is
+fixed.
+
+### Negative control, EXECUTED both ways
+
+New walker test
+`c_leading_typedef_return_and_keyword_alias_macros_keep_their_return_types`
+encodes the four `edk.c` rows as an explicit table asserting the return types the
+parent commit produced (`EFI_STATUS`, `CONST`, `STATIC`, `UINT32`), with
+`#define SEC_ATTR __attribute__((…))` present so the pass is ACTIVE and the test
+is about the RULE, not about the pass being switched off.
+
+1. Old permissive regex temporarily restored in place (`[A-Z][A-Z0-9_]{2,}` capture,
+   no `attribute_like_defines` gate). `cargo test --locked -p codegraph-extract
+--lib -- c_leading_typedef_return_and_keyword_alias_macros_keep_their_return_types`
+   → **exit 101, 1 failed**:
+
+   ```
+   left:  [("DriverEntry", 2, "EFIAPI"), ("GetName", 5, "CHAR8"),
+           ("helper", 8, "<NULL>"),      ("Untouched", 10, "UINT32")]
+   right: [("DriverEntry", 2, "EFI_STATUS"), ("GetName", 5, "CONST"),
+           ("helper", 8, "STATIC"),          ("Untouched", 10, "UINT32")]
+   ```
+
+   The `left` column reproduces the shipped regression exactly.
+
+2. Tightened version restored from the pre-mutation copy; file SHA-256 re-proved as
+   `067baf6a609931b9cbd62cd0449cdc782c105bf59e1f79923914788961214616`. Same test →
+   exit 0, **1 passed**.
+
+The four `e95072c` walker tests were also retargeted: they now include the
+`#define` line, because without it the tightened rule (correctly) does nothing —
+they were previously green only by virtue of the over-permissive regex.
+
+### Golden row delta
+
+**ZERO.** `git diff --numstat reference/golden/` → EMPTY output; no golden file
+changed by one byte, `cpp/` included. Every pre-existing node ID survives (nothing
+in any golden corpus has a leading token with an attribute-like same-file
+`#define`, so the tightening is inert there). Independently confirmed by
+regenerating the C++ fixture per the `docs/equivalence.md` recipe with the
+tightened release binary: the regenerated `nodes.json`, `edges.json`, `files.json`,
+`refs.json` and `schema.sql` are all byte-IDENTICAL to the committed ones
+(`cmp -s` → 0 for each). `colby.db` differs only in SQLite page-level bytes, which
+is why the oracle compares the canonical JSON, not the raw DB.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked -p codegraph-extract` → exit 0.
+- `cargo build --locked --release -p codegraph-rs` → exit 0.
+- `cargo test --locked -p codegraph-extract --lib -- c_leading_typedef_return
+c_leading_attr_macro c_isolation_table c_plain_typedef blank_c_leading_attr_macro
+attribute_like_defines c_header_cuda c_plain_untouched` → exit 0, **16 passed**
+  (includes the pre-existing `c_header_cuda_content_blanked` and `c_plain_untouched`,
+  proving the CUDA path and plain C are undisturbed).
+- Negative control with the OLD regex restored → exit **101**, 1 failed (values above).
+- `cargo test --locked -p codegraph-bench` → exit 0, **26 passed** in
+  `tests/equivalence.rs`, including `generated_golden_matches_committed_cpp_fixture`,
+  `cpp_db_is_self_equivalent_to_cpp_golden`, and the untouched godot / ruby / mini /
+  metal / cuda / arkts / solidity / terraform / erlang / nix / cfml oracles.
+- `git diff --numstat reference/golden/` → EMPTY (zero golden bytes changed).
+- `make fmt` → exit 0 (ledger prose written BEFORE formatting, so `fmt-check` is
+  clean at CI time).
+- `make ci CARGO='cargo --locked'` → exit 0 as the FINAL gate, **2928 passed across
+  115 test binaries**, `✅ All CI checks passed!` (fmt-check + clippy `-D warnings`
+  - workspace test + `scripts/guardrail.sh`). No byte was changed after it.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+An EARLIER `make ci` attempt failed on ONE unrelated test,
+`codegraph-watch watcher::tests::begin_shutdown_is_nonblocking_and_detach_skips_the_join`
+(`Option::unwrap()` on `None` at `watcher.rs:1944` — `ProjectWatcher::start`
+returned `Ok(None)`, i.e. the in-process `HOME`/env mutation of a concurrently
+running `policy.rs` test made the watch policy refuse the temp root). Nothing in
+this change touches `codegraph-watch`; `git diff --stat` covers only
+`codegraph-extract` + two docs files. Re-run in isolation: the single test → exit 0
+five times in a row, and the whole `-p codegraph-watch --lib` suite → exit 0 six
+times in a row (100 passed each). It is the same class of in-process env race as
+the known `install_completions_writes_zsh_fish_elvish_into_home` flake and was NOT
+weakened, skipped or modified. The subsequent full `make ci` was green twice.
+
+That first failing run also left four untracked SQLite byproducts
+(`reference/golden/{arkts,godot}/colby.db-{wal,shm}`) from the equivalence oracle;
+they are not in `.gitignore`, so they were deleted before staging. The tracked
+golden files were never modified.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path must
+be inside request cwd`); locked Cargo is the fallback, as in every prior batch. No
+dependency, version or `Cargo.lock` byte changed.

From 2a6af2ec7c200d719614fab8c87b82ab8cf1ef71 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 07:33:22 +0800
Subject: [PATCH 47/91] fix(resolution): calls through an imported singleton
 resolve to the method

---
 .../codegraph-resolve/src/import_resolver.rs  | 239 ++++++++++++++++++
 crates/codegraph-resolve/src/name_matcher.rs  |   8 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     |  87 +++++++
 3 files changed, 330 insertions(+), 4 deletions(-)

diff --git a/crates/codegraph-resolve/src/import_resolver.rs b/crates/codegraph-resolve/src/import_resolver.rs
index d7eb33f..6f4dbc8 100644
--- a/crates/codegraph-resolve/src/import_resolver.rs
+++ b/crates/codegraph-resolve/src/import_resolver.rs
@@ -6,6 +6,10 @@
 //! mappings + re-exports, and turns import-shaped references into edges. Every
 //! ported branch cites its upstream source range.
 
+use crate::name_matcher::{
+    local_receiver_type_patterns, normalize_inferred_type_name, regex_escape,
+    resolve_method_on_type,
+};
 use crate::path_aliases::apply_aliases;
 use crate::pathutil;
 use crate::types::{ImportMapping, ReExport, RefView, ResolutionContext, ResolvedBy, ResolvedRef};
@@ -1246,6 +1250,22 @@ pub fn resolve_via_import(
                     // `calls`/etc. to `method:bar` rather than mislinking to the class
                     // (which `create_edges` would then mis-promote to `instantiates`).
                     // Ports import-resolver.ts:1298-1316 (upstream f7441f21 / #825).
+                    if !imp.is_namespace {
+                        // An imported VALUE called through a member —
+                        // `reproStore.notifyJoinGuildStatus()` after
+                        // `import { reproStore } from './store'`. Linking the
+                        // CALL to the constant hides the real callee, so
+                        // `callers <method>` misses every cross-file use
+                        // (#1292 / upstream 2ec877b).
+                        if let Some(instance_member) = resolve_imported_instance_member(
+                            &target_node,
+                            reference,
+                            &imp.local_name,
+                            context,
+                        ) {
+                            return Some(instance_member);
+                        }
+                    }
                     let resolved_target = if !imp.is_namespace {
                         resolve_static_member(&target_node, reference, &imp.local_name, context)
                             .unwrap_or(target_node)
@@ -1535,6 +1555,71 @@ fn find_exported_symbol(
     None
 }
 
+/// Resolve a CALL through an imported VALUE to the method on the value's own
+/// type: `reproStore.notifyJoinGuildStatus()` where the exporting file declares
+/// `export const reproStore = new ReproStore()` (#1292, upstream `2ec877b`).
+///
+/// The same-file form of this call already resolves through local-variable
+/// receiver inference (#1108); this is the cross-file/import half. The type is
+/// recovered ONLY from the value's OWN declaration lines in the exporting file
+/// (the shared #1108 pattern table), so a same-named local elsewhere in that
+/// file cannot donate a type. The member is then resolved AND VALIDATED on that
+/// type by [`resolve_method_on_type`], so a failed inference or a type that does
+/// not declare the member returns `None` and the caller keeps its existing
+/// constant edge — never a fabricated one. Calls only: a plain member READ still
+/// references the value.
+fn resolve_imported_instance_member(
+    value: &Node,
+    reference: &RefView,
+    local_name: &str,
+    context: &dyn ResolutionContext,
+) -> Option<ResolvedRef> {
+    if reference.reference_kind != codegraph_core::types::EdgeKind::Calls {
+        return None;
+    }
+    if !matches!(value.kind, NodeKind::Constant | NodeKind::Variable) {
+        return None;
+    }
+    let prefix = format!("{local_name}.");
+    let remainder = reference.reference_name.strip_prefix(&prefix)?;
+    let member = remainder.split('.').next().filter(|s| !s.is_empty())?;
+
+    let source = context.read_file(&value.file_path)?;
+    let lines: Vec<&str> = source
+        .split('\n')
+        .map(|l| l.trim_end_matches('\r'))
+        .collect();
+    let start = (value.start_line.max(1) - 1) as usize;
+    let end = (value.end_line.max(value.start_line) as usize).min(lines.len());
+    if start >= end {
+        return None;
+    }
+    let decl_slice = lines[start..end].join("\n");
+
+    let escaped = regex_escape(&value.name);
+    for pattern in local_receiver_type_patterns(value.language, &escaped) {
+        let Some(captured) = pattern.captures(&decl_slice).and_then(|c| c.get(1)) else {
+            continue;
+        };
+        let Some(type_name) = normalize_inferred_type_name(captured.as_str()) else {
+            continue;
+        };
+        if let Some(resolved) = resolve_method_on_type(
+            &type_name,
+            member,
+            reference,
+            context,
+            0.85,
+            ResolvedBy::InstanceMethod,
+            None,
+            0,
+        ) {
+            return Some(resolved);
+        }
+    }
+    None
+}
+
 fn is_static_member_container(kind: NodeKind) -> bool {
     matches!(
         kind,
@@ -3697,4 +3782,158 @@ export { } from './empty';
         );
         assert!(resolve_rust_module_file(&[], "src/app.rs", &ctx).is_none());
     }
+
+    // ---- Imported-singleton instance-method calls (#1292 / upstream 2ec877b) --
+
+    /// The exporting file's source. `reproStore` is the singleton constant on
+    /// line 7; `ReproStore::notifyJoinGuildStatus` is its method.
+    const SINGLETON_STORE_SRC: &str = "export class ReproStore {\n  notifyJoinGuildStatus(): void {\n    console.log('notified');\n  }\n}\n\nexport const reproStore = new ReproStore();\n";
+
+    /// Graph + context for `reproStore.<member>` called from `src/caller.ts`
+    /// through `import { reproStore } from './store'`. `decl_line` places the
+    /// constant's declaration span so the inferrer reads only those lines.
+    fn singleton_ctx(decl_line: i64, source: &str) -> TestContext {
+        let mut existing = BTreeSet::new();
+        existing.insert("src/store.ts".to_string());
+        let mut file_contents = BTreeMap::new();
+        file_contents.insert("src/store.ts".to_string(), source.to_string());
+        let mut import_mappings = BTreeMap::new();
+        import_mappings.insert(
+            "src/caller.ts".to_string(),
+            vec![mapping("reproStore", "reproStore", "./store")],
+        );
+
+        let class_node = {
+            let mut n = exported(node(
+                "class:ReproStore",
+                "ReproStore",
+                NodeKind::Class,
+                "src/store.ts",
+                Language::TypeScript,
+            ));
+            n.qualified_name = "ReproStore".to_string();
+            n
+        };
+        let method = {
+            let mut n = node(
+                "method:notifyJoinGuildStatus",
+                "notifyJoinGuildStatus",
+                NodeKind::Method,
+                "src/store.ts",
+                Language::TypeScript,
+            );
+            n.qualified_name = "ReproStore::notifyJoinGuildStatus".to_string();
+            n.start_line = 2;
+            n.end_line = 4;
+            n
+        };
+        let singleton = {
+            let mut n = exported(node(
+                "constant:reproStore",
+                "reproStore",
+                NodeKind::Constant,
+                "src/store.ts",
+                Language::TypeScript,
+            ));
+            n.start_line = decl_line;
+            n.end_line = decl_line;
+            n
+        };
+
+        TestContext {
+            project_root: "/proj".to_string(),
+            existing_files: existing,
+            file_contents,
+            import_mappings,
+            nodes: vec![class_node, method, singleton],
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn imported_singleton_call_resolves_to_the_class_method() {
+        let ctx = singleton_ctx(7, SINGLETON_STORE_SRC);
+        let r = reference(
+            "reproStore.notifyJoinGuildStatus",
+            EdgeKind::Calls,
+            "src/caller.ts",
+            Language::TypeScript,
+        );
+        let resolved = resolve_via_import(&r, &ctx).expect("resolves");
+        assert_eq!(
+            resolved.target_node_id, "method:notifyJoinGuildStatus",
+            "a call through an imported singleton must reach the METHOD, not the constant"
+        );
+        assert_eq!(resolved.resolved_by, ResolvedBy::InstanceMethod);
+        assert_eq!(resolved.confidence, 0.85);
+    }
+
+    #[test]
+    fn imported_singleton_member_read_still_references_the_value() {
+        let ctx = singleton_ctx(7, SINGLETON_STORE_SRC);
+        let r = reference(
+            "reproStore.notifyJoinGuildStatus",
+            EdgeKind::References,
+            "src/caller.ts",
+            Language::TypeScript,
+        );
+        let resolved = resolve_via_import(&r, &ctx).expect("resolves");
+        assert_eq!(
+            resolved.target_node_id, "constant:reproStore",
+            "a plain member READ still points at the imported value"
+        );
+        assert_eq!(resolved.resolved_by, ResolvedBy::Import);
+    }
+
+    #[test]
+    fn imported_singleton_call_keeps_constant_when_type_is_uninferable() {
+        // `= makeStore()` matches no declaration pattern, so no type is
+        // recovered and the existing constant edge stands — never a guess.
+        let src = "export class ReproStore {\n  notifyJoinGuildStatus(): void {}\n}\n\nexport const reproStore = makeStore();\n";
+        let ctx = singleton_ctx(5, src);
+        let r = reference(
+            "reproStore.notifyJoinGuildStatus",
+            EdgeKind::Calls,
+            "src/caller.ts",
+            Language::TypeScript,
+        );
+        let resolved = resolve_via_import(&r, &ctx).expect("resolves");
+        assert_eq!(resolved.target_node_id, "constant:reproStore");
+        assert_eq!(resolved.resolved_by, ResolvedBy::Import);
+    }
+
+    #[test]
+    fn imported_singleton_call_keeps_constant_when_method_is_not_on_the_type() {
+        // The type infers to `ReproStore`, but `ReproStore` declares no
+        // `somethingElse`, so resolve_method_on_type validation fails.
+        let ctx = singleton_ctx(7, SINGLETON_STORE_SRC);
+        let r = reference(
+            "reproStore.somethingElse",
+            EdgeKind::Calls,
+            "src/caller.ts",
+            Language::TypeScript,
+        );
+        let resolved = resolve_via_import(&r, &ctx).expect("resolves");
+        assert_eq!(resolved.target_node_id, "constant:reproStore");
+        assert_eq!(resolved.resolved_by, ResolvedBy::Import);
+    }
+
+    #[test]
+    fn imported_singleton_type_is_read_only_from_its_own_declaration_lines() {
+        // A same-named local in ANOTHER function must not donate a type: the
+        // constant's own declaration span is line 9 only.
+        let src = "export class ReproStore {\n  notifyJoinGuildStatus(): void {}\n}\n\nexport function unrelated(): void {\n  const reproStore = new ReproStore();\n}\n\nexport const reproStore = pickStore();\n";
+        let ctx = singleton_ctx(9, src);
+        let r = reference(
+            "reproStore.notifyJoinGuildStatus",
+            EdgeKind::Calls,
+            "src/caller.ts",
+            Language::TypeScript,
+        );
+        let resolved = resolve_via_import(&r, &ctx).expect("resolves");
+        assert_eq!(
+            resolved.target_node_id, "constant:reproStore",
+            "the line-6 local must not type the line-9 constant"
+        );
+    }
 }
diff --git a/crates/codegraph-resolve/src/name_matcher.rs b/crates/codegraph-resolve/src/name_matcher.rs
index 861cc0d..6d3e14d 100644
--- a/crates/codegraph-resolve/src/name_matcher.rs
+++ b/crates/codegraph-resolve/src/name_matcher.rs
@@ -338,7 +338,7 @@ fn prefer_call_site_file(nodes: Vec<Node>, call_site_file: &str) -> Vec<Node> {
 /// Resolve a method on a type, walking supertypes (`resolveMethodOnType`,
 /// `name-matcher.ts:254-331`).
 #[allow(clippy::too_many_arguments)]
-fn resolve_method_on_type(
+pub(crate) fn resolve_method_on_type(
     type_name: &str,
     method_name: &str,
     reference: &RefView,
@@ -435,7 +435,7 @@ fn cpp_class_exists(name: &str, reference: &RefView, context: &dyn ResolutionCon
 
 /// Escape a receiver for embedding in a `Regex` (the JS
 /// `/[.*+?^${}()|[\]\\]/g` set, `name-matcher.ts:523`).
-fn regex_escape(s: &str) -> String {
+pub(crate) fn regex_escape(s: &str) -> String {
     let mut out = String::with_capacity(s.len());
     for c in s.chars() {
         if matches!(
@@ -750,7 +750,7 @@ fn is_non_type_receiver_token(seg: &str) -> bool {
 /// Normalize a captured type expression to a simple type name: drop generic
 /// args and pointer/ref markers, take the last `.`/`::`-qualified segment, and
 /// reject obvious non-types (`normalizeInferredTypeName`, name-matcher.ts:#1108).
-fn normalize_inferred_type_name(raw: &str) -> Option<String> {
+pub(crate) fn normalize_inferred_type_name(raw: &str) -> Option<String> {
     static GENERICS: OnceLock<Regex> = OnceLock::new();
     let generics = GENERICS.get_or_init(|| Regex::new(r"<[^>]*>").expect("inferred generics re"));
     let cleaned = generics.replace_all(raw, "");
@@ -768,7 +768,7 @@ fn normalize_inferred_type_name(raw: &str) -> Option<String> {
 /// most-specific first. The type-annotation / typed-parameter forms (#1125) are
 /// baked into the second pattern per language. Languages without a pattern set
 /// (the C++ path uses its own dedicated inferrer) return an empty vector.
-fn local_receiver_type_patterns(language: Language, r: &str) -> Vec<Regex> {
+pub(crate) fn local_receiver_type_patterns(language: Language, r: &str) -> Vec<Regex> {
     local_receiver_type_patterns_tagged(language, r)
         .into_iter()
         .map(|(re, _)| re)
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e0daa68..b4f30aa 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4153,3 +4153,90 @@ golden files were never modified.
 `lsp_diagnostics` was attempted and again refused this worktree (`LSP file path must
 be inside request cwd`); locked Cargo is the fallback, as in every prior batch. No
 dependency, version or `Cargo.lock` byte changed.
+
+## Batch C1 — calls through an imported singleton resolve to the method (2026-07-28)
+
+Ports upstream `2ec877b` (`fix(resolution): calls through an imported singleton
+resolve to the method`, upstream #1315 / issue #1292). Resolution behavior only;
+no extraction, schema or node-ID change.
+
+### Red (documented, with the actual wrong output)
+
+Five new `#[test]`s in `crates/codegraph-resolve/src/import_resolver.rs` drive the
+REAL production entry point `resolve_via_import` over the in-crate `TestContext`
+graph. The shape is upstream's exact repro: `src/store.ts` exports
+`class ReproStore { notifyJoinGuildStatus() }` plus
+`export const reproStore = new ReproStore();`, and `src/caller.ts` calls
+`reproStore.notifyJoinGuildStatus()` after `import { reproStore } from './store'`.
+
+`cargo test --locked -p codegraph-resolve --lib -- imported_singleton` on the
+pre-change bytes → **1 failed, 4 passed**:
+
+| assertion                                              | expected                       | ACTUAL on pre-change bytes |
+| ------------------------------------------------------ | ------------------------------ | -------------------------- |
+| `imported_singleton_call_resolves_to_the_class_method` | `method:notifyJoinGuildStatus` | `constant:reproStore`      |
+
+That is the defect verbatim: `find_exported_symbol` resolves the base to the
+exported CONSTANT and the `Calls` edge lands there, so `callers
+notifyJoinGuildStatus` misses every cross-file use while the identical same-file
+call resolves to the method through local-variable receiver inference (#1108).
+The other four tests are the guard set (member READ still targets the value;
+uninferable initializer keeps the constant; a member the type does not declare
+keeps the constant; a same-named local in another function must not donate a
+type) — they passed pre-change and must keep passing, so they are guards, not Reds.
+
+### Green (minimal)
+
+- `crates/codegraph-resolve/src/name_matcher.rs`: `resolve_method_on_type`,
+  `normalize_inferred_type_name`, `local_receiver_type_patterns` and
+  `regex_escape` widened from private to `pub(crate)`. No body changed — this
+  mirrors upstream's `export` of the same three helpers.
+- `crates/codegraph-resolve/src/import_resolver.rs`: new
+  `resolve_imported_instance_member`, consulted in the non-namespace branch of
+  `resolve_via_import`'s member-descend BEFORE `resolve_static_member`. It fires
+  only for `EdgeKind::Calls` on a `Constant`/`Variable` target, reads the value's
+  type from ITS OWN declaration lines (`value.start_line..=value.end_line`) via
+  the shared #1108 pattern table, and resolves the member through
+  `resolve_method_on_type` at confidence 0.85 / `ResolvedBy::InstanceMethod`.
+  Validation failure returns `None`, so the pre-existing constant edge stands —
+  a silent keep, never a fabricated edge. This is the same discipline as B1
+  (`1839504`): when the receiver cannot be typed, emit nothing rather than fall
+  through to bare-name guessing.
+
+The declaration-slice bound is why the line-6 local in
+`imported_singleton_type_is_read_only_from_its_own_declaration_lines` cannot type
+the line-9 constant.
+
+### Golden row delta
+
+NONE. `git diff --stat 87a46dc..HEAD -- reference/golden/` → **empty output**,
+and `git status --porcelain reference/golden/` → empty. Expected: the classification
+is golden-neutral, and the fixture corpus contains no imported-singleton call shape,
+so no golden row can move.
+
+### Negative control, executed
+
+Replaced the `return Some(instance_member)` with a discarding
+`let _ = resolve_imported_instance_member(...)` (call kept so the function stays
+live) and re-ran: `imported_singleton_call_resolves_to_the_class_method` went RED
+again with the SAME wrong value `constant:reproStore`; the four guards stayed
+green. Restored from the pre-control copy and verified
+`sha256sum -c` → `crates/codegraph-resolve/src/import_resolver.rs: OK`
+(`1a1743ff88e8d7682ea61b0aa6ef91cba42e9bb1cb38a9864c5addc2068efa51`).
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0 (workspace 0.40.4, 10
+  packages), run before every Cargo batch; every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-resolve --lib -- imported_singleton` → exit 0,
+  **5 passed**.
+- `cargo test --locked -p codegraph-resolve --lib` → exit 0, **649 passed, 0
+  failed**.
+- `cargo clippy --locked -p codegraph-resolve --all-targets -- -D warnings` → exit 0.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26
+  passed, 0 failed** (unchanged 26/26).
+- `git diff --stat 87a46dc..HEAD -- reference/golden/` → empty.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
+no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed.

From 285d5914f9ec4bdb9b67cbe66d94fdc1ee8c50d6 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 07:56:02 +0800
Subject: [PATCH 48/91] fix(resolution): literal-receiver builtins and nested
 locals stop fabricating call edges

---
 crates/codegraph-extract/src/walker.rs       | 190 ++++++++++++++++
 crates/codegraph-resolve/src/name_matcher.rs | 220 ++++++++++++++++++-
 crates/codegraph-resolve/src/resolver.rs     | 102 +++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md    | 145 ++++++++++++
 4 files changed, 655 insertions(+), 2 deletions(-)

diff --git a/crates/codegraph-extract/src/walker.rs b/crates/codegraph-extract/src/walker.rs
index 7afa82c..321e9db 100644
--- a/crates/codegraph-extract/src/walker.rs
+++ b/crates/codegraph-extract/src/walker.rs
@@ -29,6 +29,71 @@ pub fn child_by_field<'tree>(node: SyntaxNode<'tree>, field: &str) -> Option<Syn
     node.child_by_field_name(field)
 }
 
+/// tree-sitter node kinds (across grammars) for a LITERAL expression sitting in
+/// method-call RECEIVER position. A literal's methods are the language's
+/// builtins — `", ".join`, `"x".toUpperCase()`, `5.times`, `[].concat` — never
+/// project symbols, so such a call must not emit a `calls` ref that the
+/// resolver's bare-name fallback could bind to an unrelated same-named project
+/// function (#1230 / upstream `c472cfb`). A silent miss beats a wrong edge.
+///
+/// `encapsed_string` extends upstream's list: tree-sitter-php reports a
+/// double-quoted literal receiver under that kind, which upstream's set omits.
+const LITERAL_RECEIVER_KINDS: &[&str] = &[
+    // strings
+    "string",
+    "string_literal",
+    "interpreted_string_literal",
+    "raw_string_literal",
+    "template_string",
+    "concatenated_string",
+    "formatted_string",
+    "f_string",
+    "line_string_literal",
+    "string_content",
+    "heredoc_body",
+    "encapsed_string",
+    // numbers
+    "number",
+    "number_literal",
+    "integer",
+    "integer_literal",
+    "float",
+    "float_literal",
+    "int_literal",
+    "decimal_integer_literal",
+    "real_literal",
+    // chars / runes / regex / booleans / null-likes
+    "char_literal",
+    "character_literal",
+    "rune_literal",
+    "regex",
+    "regex_literal",
+    "true",
+    "false",
+    "boolean_literal",
+    "bool_literal",
+    "none",
+    "null",
+    "nil",
+    "null_literal",
+    "undefined",
+    // collection literals
+    "list",
+    "list_literal",
+    "array",
+    "array_literal",
+    "array_creation_expression",
+    "dictionary",
+    "dict_literal",
+    "object",
+    "tuple",
+    "set",
+];
+
+fn is_literal_receiver(node: SyntaxNode<'_>) -> bool {
+    LITERAL_RECEIVER_KINDS.contains(&node.kind())
+}
+
 pub struct TreeSitterWalker<'a, 'tree> {
     file_path: &'a str,
     source: &'a str,
@@ -2939,6 +3004,9 @@ impl<'a, 'tree> TreeSitterWalker<'a, 'tree> {
                         .or_else(|| child_by_field(func, "argument"))
                         .or_else(|| func.named_child(0));
                     if let Some(receiver) = receiver {
+                        if is_literal_receiver(receiver) {
+                            return;
+                        }
                         if matches!(
                             receiver.kind(),
                             "identifier" | "simple_identifier" | "field_identifier"
@@ -3038,6 +3106,9 @@ impl<'a, 'tree> TreeSitterWalker<'a, 'tree> {
         if method_name.is_empty() {
             return;
         }
+        if is_literal_receiver(object_field) {
+            return;
+        }
 
         // PHP `Cls::for($x)->method()`: receiver is a static call, re-encode as
         // `<Cls::factory>().<method>` (#608).
@@ -7154,4 +7225,123 @@ g() ->\n\
                 || has_ref(&refs, EdgeKind::Imports, "sub.cfm")
         );
     }
+
+    // ---- Literal-receiver builtin calls (#1230 / upstream c472cfb) ----------
+
+    fn call_refs(file: &str, source: &str, lang: Language) -> Vec<String> {
+        let (_, refs) = run(file, source, lang);
+        refs.iter()
+            .filter(|r| r.reference_kind == EdgeKind::Calls)
+            .map(|r| r.reference_name.clone())
+            .collect()
+    }
+
+    #[test]
+    fn python_literal_receiver_calls_emit_no_ref() {
+        let calls = call_refs(
+            "src/repro.py",
+            "def report_missing(unresolved):\n    return \", \".join(sorted(unresolved))\n",
+            Language::Python,
+        );
+        assert!(
+            !calls.iter().any(|c| c == "join"),
+            "`\", \".join(...)` is a str builtin and must emit NO call ref, got: {calls:?}"
+        );
+        assert!(
+            calls.iter().any(|c| c == "sorted"),
+            "the nested `sorted(...)` call must still be extracted, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn python_collection_and_number_literal_receivers_emit_no_ref() {
+        let calls = call_refs(
+            "src/lits.py",
+            concat!(
+                "def f(x):\n",
+                "    [1, 2].append(3)\n",
+                "    {'k': 1}.keys()\n",
+                "    {1, 2}.union(x)\n",
+                "    (1, 2).count(1)\n",
+                "    1.5.hex()\n",
+                "    None.__str__()\n",
+                "    True.__str__()\n",
+            ),
+            Language::Python,
+        );
+        assert!(
+            calls.is_empty(),
+            "every literal-receiver builtin must emit NO call ref, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn typescript_literal_receiver_calls_emit_no_ref() {
+        let calls = call_refs(
+            "src/lits.ts",
+            concat!(
+                "export function f(): void {\n",
+                "  \"x\".toUpperCase();\n",
+                "  [1, 2].map((n) => n);\n",
+                "  `t`.trim();\n",
+                "  /re/.test(\"s\");\n",
+                "  0xff.toString();\n",
+                "  true.toString();\n",
+                "}\n",
+            ),
+            Language::TypeScript,
+        );
+        assert!(
+            calls.is_empty(),
+            "every literal-receiver builtin must emit NO call ref, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn java_string_literal_receiver_call_emits_no_ref() {
+        let calls = call_refs(
+            "src/C.java",
+            "class C { void f() { \"x\".trim(); } }\n",
+            Language::Java,
+        );
+        assert!(
+            calls.is_empty(),
+            "`\"x\".trim()` is a String builtin and must emit NO call ref, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn php_string_literal_receiver_call_emits_no_ref() {
+        let calls = call_refs(
+            "src/a.php",
+            "<?php\nfunction f() { \"x\"->foo(); }\n",
+            Language::Php,
+        );
+        assert!(
+            calls.is_empty(),
+            "a literal PHP receiver must emit NO call ref, got: {calls:?}"
+        );
+    }
+
+    #[test]
+    fn identifier_receiver_calls_are_unaffected_by_the_literal_guard() {
+        let py = call_refs(
+            "src/ok.py",
+            "def f(sep, x):\n    return sep.join(sorted(x))\n",
+            Language::Python,
+        );
+        assert!(
+            py.iter().any(|c| c == "sep.join"),
+            "an identifier receiver must still emit `sep.join`, got: {py:?}"
+        );
+        let java = call_refs(
+            "src/D.java",
+            "class D { void f(String s) { s.trim(); } }\n",
+            Language::Java,
+        );
+        assert!(
+            java.iter().any(|c| c == "s.trim"),
+            "an identifier receiver must still emit `s.trim`, got: {java:?}"
+        );
+    }
 }
diff --git a/crates/codegraph-resolve/src/name_matcher.rs b/crates/codegraph-resolve/src/name_matcher.rs
index 6d3e14d..41f140a 100644
--- a/crates/codegraph-resolve/src/name_matcher.rs
+++ b/crates/codegraph-resolve/src/name_matcher.rs
@@ -203,16 +203,66 @@ fn apply_language_gate(candidates: Vec<Node>, reference: &RefView) -> Vec<Node>
     }
 }
 
+/// A function nested inside another FUNCTION is only callable from within its
+/// container — Python, JS/TS and every closure language scope it lexically.
+/// Resolving a bare name from elsewhere to a nested local fabricates an edge
+/// scope already rules out: `join(...)` in one function must never bind to a
+/// `join` defined inside a DIFFERENT function (`isLexicallyReachable`, #1230 /
+/// upstream `c472cfb`).
+///
+/// A candidate whose `qualified_name` parent resolves to a same-file
+/// function/method ENCLOSING it is kept only when the ref originates inside that
+/// parent's line range. Class members are unaffected (their parent resolves to a
+/// class-like node), as are top-level symbols and C++ namespace-prefixed names
+/// (the prefix has no node).
+fn is_lexically_reachable(
+    candidate: &Node,
+    reference: &RefView,
+    context: &dyn ResolutionContext,
+) -> bool {
+    if candidate.kind != NodeKind::Function {
+        return true;
+    }
+    let Some(sep) = candidate.qualified_name.rfind("::") else {
+        return true;
+    };
+    let parent_qualified = &candidate.qualified_name[..sep];
+    if parent_qualified.is_empty() {
+        return true;
+    }
+    let containers: Vec<Node> = context
+        .get_nodes_by_qualified_name(parent_qualified)
+        .into_iter()
+        .filter(|p| {
+            p.file_path == candidate.file_path
+                && matches!(p.kind, NodeKind::Function | NodeKind::Method)
+                && p.start_line <= candidate.start_line
+                && p.end_line >= candidate.end_line
+        })
+        .collect();
+    if containers.is_empty() {
+        return true;
+    }
+    reference.file_path == candidate.file_path
+        && containers
+            .iter()
+            .any(|p| reference.line >= p.start_line && reference.line <= p.end_line)
+}
+
 /// Try to resolve a reference by exact name match (`matchByExactName`,
 /// `name-matcher.ts:173-209`).
 pub fn match_by_exact_name(
     reference: &RefView,
     context: &dyn ResolutionContext,
 ) -> Option<ResolvedRef> {
-    let candidates = apply_language_gate(
+    let candidates: Vec<Node> = apply_language_gate(
         context.get_nodes_by_name(&reference.reference_name),
         reference,
-    );
+    )
+    .into_iter()
+    // Nested locals are only reachable from inside their container (#1230).
+    .filter(|n| is_lexically_reachable(n, reference, context))
+    .collect();
 
     if candidates.is_empty() {
         return None;
@@ -6153,4 +6203,170 @@ mod tests {
         // R separator not inferable outside R.
         assert!(!is_inferable_receiver_call("lg$log", Language::TypeScript));
     }
+
+    // ---- Nested-local lexical reachability (#1230 / upstream c472cfb) -------
+
+    /// `report_missing` (lines 5-8) calls `join`, but the ONLY project `join`
+    /// is nested inside `format_fields` (lines 1-3) — lexically unreachable.
+    fn nested_local_ctx() -> Ctx {
+        let outer = {
+            let mut n = mk(
+                "function:format_fields",
+                NodeKind::Function,
+                "format_fields",
+                "format_fields",
+                "src/repro.py",
+                Language::Python,
+            );
+            n.start_line = 1;
+            n.end_line = 3;
+            n
+        };
+        let nested = {
+            let mut n = mk(
+                "function:join",
+                NodeKind::Function,
+                "join",
+                "format_fields::join",
+                "src/repro.py",
+                Language::Python,
+            );
+            n.start_line = 2;
+            n.end_line = 3;
+            n
+        };
+        let caller = {
+            let mut n = mk(
+                "function:report_missing",
+                NodeKind::Function,
+                "report_missing",
+                "report_missing",
+                "src/repro.py",
+                Language::Python,
+            );
+            n.start_line = 5;
+            n.end_line = 8;
+            n
+        };
+        Ctx::default()
+            .name("join", vec![nested.clone()])
+            .qualified("format_fields", vec![outer.clone()])
+            .nodes_in_file("src/repro.py", vec![outer, nested, caller])
+    }
+
+    #[test]
+    fn nested_local_is_unreachable_from_another_function() {
+        let ctx = nested_local_ctx();
+        let reference = refv("join", EdgeKind::Calls, "src/repro.py", Language::Python, 6);
+        assert_eq!(
+            match_by_exact_name(&reference, &ctx),
+            None,
+            "a `join` nested in format_fields must NOT resolve from report_missing"
+        );
+    }
+
+    #[test]
+    fn nested_local_resolves_from_inside_its_container() {
+        let ctx = nested_local_ctx();
+        let reference = refv("join", EdgeKind::Calls, "src/repro.py", Language::Python, 3);
+        let resolved = match_by_exact_name(&reference, &ctx).expect("reachable from inside");
+        assert_eq!(resolved.target_node_id, "function:join");
+    }
+
+    #[test]
+    fn nested_local_is_unreachable_from_another_file() {
+        let ctx = nested_local_ctx();
+        let reference = refv("join", EdgeKind::Calls, "src/other.py", Language::Python, 2);
+        assert_eq!(
+            match_by_exact_name(&reference, &ctx),
+            None,
+            "a nested local is never reachable from a different file"
+        );
+    }
+
+    #[test]
+    fn class_member_candidate_is_not_scope_filtered() {
+        let cls = {
+            let mut n = mk(
+                "class:Fmt",
+                NodeKind::Class,
+                "Fmt",
+                "Fmt",
+                "src/fmt.py",
+                Language::Python,
+            );
+            n.start_line = 1;
+            n.end_line = 6;
+            n
+        };
+        let member = {
+            let mut n = mk(
+                "function:join",
+                NodeKind::Function,
+                "join",
+                "Fmt::join",
+                "src/fmt.py",
+                Language::Python,
+            );
+            n.start_line = 2;
+            n.end_line = 3;
+            n
+        };
+        let ctx = Ctx::default()
+            .name("join", vec![member.clone()])
+            .qualified("Fmt", vec![cls.clone()])
+            .nodes_in_file("src/fmt.py", vec![cls, member]);
+        let reference = refv("join", EdgeKind::Calls, "src/other.py", Language::Python, 9);
+        let resolved = match_by_exact_name(&reference, &ctx).expect("class members stay reachable");
+        assert_eq!(resolved.target_node_id, "function:join");
+    }
+
+    #[test]
+    fn top_level_and_unparented_candidates_are_not_scope_filtered() {
+        let top = mk(
+            "function:helper",
+            NodeKind::Function,
+            "helper",
+            "helper",
+            "src/top.py",
+            Language::Python,
+        );
+        let ctx = Ctx::default()
+            .name("helper", vec![top.clone()])
+            .nodes_in_file("src/top.py", vec![top]);
+        let reference = refv(
+            "helper",
+            EdgeKind::Calls,
+            "src/other.py",
+            Language::Python,
+            3,
+        );
+        assert_eq!(
+            match_by_exact_name(&reference, &ctx)
+                .expect("top-level symbol stays reachable")
+                .target_node_id,
+            "function:helper"
+        );
+
+        // A C++ namespace prefix has no node, so the qualified name still holds
+        // `::` but no container resolves — the candidate must survive.
+        let ns_fn = mk(
+            "function:emit",
+            NodeKind::Function,
+            "emit",
+            "sim::emit",
+            "src/sim.cpp",
+            Language::Cpp,
+        );
+        let ns_ctx = Ctx::default()
+            .name("emit", vec![ns_fn.clone()])
+            .nodes_in_file("src/sim.cpp", vec![ns_fn]);
+        let ns_ref = refv("emit", EdgeKind::Calls, "src/use.cpp", Language::Cpp, 4);
+        assert_eq!(
+            match_by_exact_name(&ns_ref, &ns_ctx)
+                .expect("namespace-prefixed symbol stays reachable")
+                .target_node_id,
+            "function:emit"
+        );
+    }
 }
diff --git a/crates/codegraph-resolve/src/resolver.rs b/crates/codegraph-resolve/src/resolver.rs
index 2181e3b..1959866 100644
--- a/crates/codegraph-resolve/src/resolver.rs
+++ b/crates/codegraph-resolve/src/resolver.rs
@@ -3431,4 +3431,106 @@ mod tests {
             errors: Vec::new(),
         }
     }
+
+    // ----------------------------------------------------------------------
+    // #1230 PORT: literal receivers + nested locals stop fabricating edges
+    // ----------------------------------------------------------------------
+
+    /// Upstream's exact repro, end-to-end through `resolve_and_persist`:
+    /// `format_fields` (lines 1-5) holds a NESTED `join`; `report_missing`
+    /// (lines 8-10) calls `", ".join(...)`. The nested `join` is the decoy — a
+    /// bare-name fallback binds the string builtin straight to it.
+    fn write_literal_and_nested_fixture(dir: &std::path::Path) -> &'static str {
+        std::fs::write(
+            dir.join("src/repro.py"),
+            concat!(
+                "def format_fields(values):\n",
+                "    def join(vals):\n",
+                "        return \"-\".join(sorted(vals))\n",
+                "\n",
+                "    return join(values)\n",
+                "\n",
+                "\n",
+                "def report_missing(unresolved):\n",
+                "    missing_list = \", \".join(sorted(unresolved))\n",
+                "    return missing_list\n",
+            ),
+        )
+        .expect("write repro.py");
+        "src/repro.py"
+    }
+
+    fn index_python_fixture(
+        slug: &str,
+        root: &std::path::Path,
+        relative: &str,
+    ) -> (Store, std::path::PathBuf) {
+        let db = temp_db(slug);
+        let mut store = Store::open(&db).expect("open store");
+        let result = codegraph_extract::extract_file(root, relative).expect("extract");
+        store
+            .upsert_file(&FileRecord {
+                path: relative.to_string(),
+                content_hash: "fixture".to_string(),
+                language: Language::Python,
+                size: 0,
+                modified_at: 0,
+                indexed_at: 0,
+                node_count: result.nodes.len() as i64,
+                errors: Vec::new(),
+            })
+            .expect("upsert file");
+        store.upsert_nodes(&result.nodes).expect("upsert nodes");
+        store.insert_edges(&result.edges).expect("insert edges");
+        store
+            .insert_unresolved_refs(&result.unresolved_references)
+            .expect("insert refs");
+        (store, db)
+    }
+
+    #[test]
+    fn literal_receiver_and_nested_local_produce_no_fabricated_call_edge() {
+        let dir = fresh_fixture_dir("lit-nested");
+        let relative = write_literal_and_nested_fixture(&dir);
+        let root = dir.to_string_lossy().to_string();
+        let (mut store, db) = index_python_fixture("lit-nested", &dir, relative);
+
+        let mut resolver = ReferenceResolver::new(root);
+        resolver
+            .resolve_and_persist(&mut store)
+            .expect("resolve_and_persist");
+
+        let nodes = store.all_nodes().expect("nodes");
+        let by_name = |name: &str| -> String {
+            nodes
+                .iter()
+                .find(|n| n.kind == NodeKind::Function && n.name == name)
+                .map(|n| n.id.clone())
+                .unwrap_or_else(|| panic!("missing function {name}"))
+        };
+        let join_id = by_name("join");
+        let format_fields_id = by_name("format_fields");
+        let report_missing_id = by_name("report_missing");
+
+        let edges = store.all_edges().expect("edges");
+        let callers_of_join: Vec<&str> = edges
+            .iter()
+            .filter(|e| e.kind == EdgeKind::Calls && e.target == join_id)
+            .map(|e| e.source.as_str())
+            .collect();
+        assert_eq!(
+            callers_of_join,
+            vec![format_fields_id.as_str()],
+            "the nested `join` must have exactly ONE caller (its own container)"
+        );
+        assert!(
+            !edges
+                .iter()
+                .any(|e| e.kind == EdgeKind::Calls && e.source == report_missing_id),
+            "`report_missing` calls only string/`sorted` builtins, so it must have NO project callee"
+        );
+
+        let _ = std::fs::remove_file(&db);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 }
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index b4f30aa..3845d82 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4240,3 +4240,148 @@ green. Restored from the pre-control copy and verified
 `lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
 must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
 no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed.
+
+## Batch C2 — literal-receiver builtins and nested locals stop fabricating call edges (2026-07-28)
+
+Ports upstream `c472cfb` (`fix(resolution): literal-receiver builtins and nested
+locals stop fabricating call edges`, upstream #1317 / issue #1230). Two
+independent defects, fixed independently in one behavior commit — exactly as
+upstream framed them, because the issue's repro needs both to stop producing the
+wrong edge.
+
+### Red (documented, with the actual wrong output)
+
+**Extraction half** — five new `#[test]`s in
+`crates/codegraph-extract/src/walker.rs` drive the REAL path
+(`extract_source` → `Walker::extract_call` / `extract_object_name_call`).
+`cargo test --locked -p codegraph-extract --lib -- literal_receiver identifier_receiver`
+on the pre-change bytes → **5 failed, 1 passed**:
+
+| assertion (language, shape)                                                                                    | expected      | ACTUAL on pre-change bytes                                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------- |
+| Python `", ".join(sorted(x))`                                                                                  | no `join` ref | `["join", "sorted"]`                                          |
+| Python `[1,2].append`, `{'k':1}.keys`, `{1,2}.union`, `(1,2).count`, `1.5.hex`, `None.__str__`, `True.__str__` | no refs       | `["append","keys","union","count","hex","__str__","__str__"]` |
+| TS `"x".toUpperCase`, `[1,2].map`, `` `t`.trim ``, `/re/.test`, `0xff.toString`, `true.toString`               | no refs       | `["toUpperCase","map","trim","test","toString","toString"]`   |
+| Java `"x".trim()`                                                                                              | no ref        | `["\"x\".trim"]`                                              |
+| PHP `"x"->foo()`                                                                                               | no ref        | `["\"x\".foo"]`                                               |
+
+`identifier_receiver_calls_are_unaffected_by_the_literal_guard` passed pre-change
+— it is the guard proving `sep.join` / `s.trim` survive, not a Red.
+
+**Resolution half** — five new `#[test]`s in
+`crates/codegraph-resolve/src/name_matcher.rs` drive `match_by_exact_name` over
+the in-crate `Ctx`. `cargo test --locked -p codegraph-resolve --lib -- nested_local
+class_member_candidate top_level_and_unparented` on the pre-change bytes →
+**2 failed, 3 passed**:
+
+| assertion                                           | expected | ACTUAL on pre-change bytes                                           |
+| --------------------------------------------------- | -------- | -------------------------------------------------------------------- |
+| `nested_local_is_unreachable_from_another_function` | `None`   | `Some(target_node_id: "function:join", confidence: 0.9, ExactMatch)` |
+| `nested_local_is_unreachable_from_another_file`     | `None`   | `Some(target_node_id: "function:join", confidence: 0.9, ExactMatch)` |
+
+The three passing ones (`nested_local_resolves_from_inside_its_container`,
+`class_member_candidate_is_not_scope_filtered`,
+`top_level_and_unparented_candidates_are_not_scope_filtered`) are the
+must-not-regress guards, including the C++ namespace-prefix shape whose
+qualified name carries `::` with no container node.
+
+**End-to-end half (the load-bearing one)** — one new `#[test]` in
+`crates/codegraph-resolve/src/resolver.rs`,
+`literal_receiver_and_nested_local_produce_no_fabricated_call_edge`, indexes
+upstream's exact `repro.py` from disk through `codegraph_extract::extract_file`
+and runs the PRODUCTION `resolve_and_persist`, then reads persisted `edges`.
+The decoy is present by construction: the only project `join` is nested inside
+`format_fields`, so a bare-name fallback visibly binds `", ".join` to it. On the
+pre-change bytes the nested `join` had **three** callers
+(`["function:37f4985b…", "function:dd8ad4c1…", "function:f41fd935…"]` — itself
+via `"-".join`, its container, and `report_missing`) where exactly one is
+correct.
+
+### Green (minimal)
+
+- `crates/codegraph-extract/src/walker.rs`: new `LITERAL_RECEIVER_KINDS` +
+  `is_literal_receiver`, consulted at BOTH call-extraction receiver sites — the
+  generic member-expression arm in `extract_call` and the Java/Kotlin/PHP
+  `object`/`name` arm in `extract_object_name_call`. A literal receiver returns
+  early, emitting NOTHING. Nested calls in the arguments are visited
+  independently, which is why `sorted(...)` survives.
+  The kind list is upstream's, plus `encapsed_string`: this workspace's
+  `tree-sitter-php` reports a double-quoted literal receiver under that kind,
+  which upstream's set omits. That extra entry was derived by probing the real
+  grammars in this workspace across Python/TS/Java/PHP/Ruby/Kotlin/Swift/Rust/
+  Dart/Scala/C#/Go — testing shapes the fix was NOT designed for, per the Batch B
+  lesson — and every kind in the list was observed in receiver position by that
+  probe or is upstream's verbatim entry.
+- `crates/codegraph-resolve/src/name_matcher.rs`: new `is_lexically_reachable`,
+  applied as a filter on `match_by_exact_name`'s candidate list. A `Function`
+  candidate whose `qualified_name` parent resolves to a same-file
+  `Function`/`Method` that ENCLOSES it by line range survives only when the ref
+  is in that same file AND inside the container's line range. Class members
+  (parent is class-like), top-level symbols (no `::`) and C++ namespace prefixes
+  (no container node) are untouched.
+
+Same discipline as B1 (`1839504`) and C1: when a receiver cannot aid type
+inference, emit NOTHING rather than a bare name, because a bare name falls
+through to exact-name matching and guesses among unrelated same-named symbols.
+
+### Golden row delta
+
+NONE. `git diff --stat 87a46dc..HEAD -- reference/golden/` → **empty output**;
+`git status --porcelain reference/golden/` → empty. All 26 equivalence oracles
+pass unchanged, so no fixture in the corpus contains a literal-receiver call or a
+cross-scope nested-local call. (Upstream measured −27 edges on excalidraw and
+byte-identical output on `requests`; our fixture corpus lands in the
+byte-identical class.)
+
+### Negative control, EXECUTED both ways
+
+1. Extraction guard neutered (`if is_literal_receiver(...) { return; }` →
+   `let _ = is_literal_receiver(...);` at both sites, resolution filter intact):
+   all 5 extraction Reds went RED again with the SAME wrong ref lists, AND the
+   end-to-end resolver test went RED with the nested `join` back to 3 callers.
+   Restored; `sha256sum -c` → both files OK.
+2. Resolution filter neutered (`.filter(|n| is_lexically_reachable(...) || true)`,
+   extraction guard intact): the two nested-local Reds went RED again with the
+   SAME `Some(function:join, 0.9, ExactMatch)`; the end-to-end test stayed GREEN
+   (with literal receivers emitting nothing, `report_missing` no longer reaches
+   the decoy). Restored; `sha256sum -c` → both files OK.
+
+Green hashes: `walker.rs`
+`42834fe71029cbe6977c8a699f995940911fa6432d64707c38677785a57f132c`,
+`name_matcher.rs`
+`47724ae2a13ffdcf103260b1a2f66a426aafc81696c08da7bbfb227a42fefe51`.
+
+Control 2 is the honest reading of the two-defect split: the end-to-end test is
+load-bearing for the EXTRACTION half, and the two unit Reds are load-bearing for
+the RESOLUTION half. Neither half alone covers both, which is why both are
+committed together and both controls were run.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-extract` → exit 0 (382 lib + every
+  integration target green).
+- `cargo test --locked -p codegraph-resolve` → exit 0 (655 lib + integration
+  targets green).
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → exit 0.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26
+  passed, 0 failed** (unchanged 26/26).
+- `cargo test --locked --workspace` → **exit 101 on the first run**, failing ONLY
+  `codegraph-rs formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+  (`assertion failed: dir.join(".config/fish/completions/codegraph.fish").is_file()`
+  at `main.rs:6202`; the printed path shows fish completions written to a
+  DIFFERENT temp home — the known in-process `HOME`/`XDG_DATA_HOME` race). That
+  test is unrelated to resolution or extraction and was NOT weakened, skipped or
+  modified. Re-run in isolation via `-p codegraph-rs --bin codegraph` → exit 0
+  four times in a row (1 passed each). The full `cargo test --locked --workspace`
+  re-run → **exit 0**, 121 `test result: ok` lines, zero failures.
+- `git diff --stat 87a46dc..HEAD -- reference/golden/` → empty.
+
+The first workspace run also left two untracked SQLite byproducts
+(`reference/golden/cpp/colby.db-{wal,shm}`) from the oracle; they are not
+gitignored, so they were deleted before staging. No tracked golden file changed.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
+no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed.

From 29f635b206f6108750c4b221779e47009df2dbd3 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 09:52:16 +0800
Subject: [PATCH 49/91] fix(resolution): key resolved-ref cleanup on the row id
 so sibling call sites survive

---
 crates/codegraph-resolve/src/framework.rs     |   1 +
 .../codegraph-resolve/src/frameworks/godot.rs |   1 +
 .../src/frameworks/godot_project.rs           |   1 +
 .../src/frameworks/godot_resource.rs          |   1 +
 .../src/frameworks/godot_scene.rs             |   1 +
 .../src/frameworks/godot_script.rs            |   1 +
 .../src/frameworks/nestjs.rs                  |   2 +
 .../codegraph-resolve/src/frameworks/react.rs |   2 +
 .../codegraph-resolve/src/frameworks/vue.rs   |   1 +
 .../codegraph-resolve/src/import_resolver.rs  |   1 +
 crates/codegraph-resolve/src/name_matcher.rs  |   2 +
 crates/codegraph-resolve/src/resolver.rs      | 163 ++++++++++++----
 crates/codegraph-resolve/src/types.rs         |  11 ++
 crates/codegraph-resolve/tests/frameworks.rs  |   1 +
 .../tests/snapshot_equivalence.rs             |   1 +
 crates/codegraph-store/src/queries.rs         | 131 +++++--------
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 184 ++++++++++++++++++
 17 files changed, 395 insertions(+), 110 deletions(-)

diff --git a/crates/codegraph-resolve/src/framework.rs b/crates/codegraph-resolve/src/framework.rs
index 1da0059..e850874 100644
--- a/crates/codegraph-resolve/src/framework.rs
+++ b/crates/codegraph-resolve/src/framework.rs
@@ -207,6 +207,7 @@ mod tests {
 
     fn a_ref() -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "from".to_string(),
             reference_name: "X".to_string(),
             reference_kind: EdgeKind::Calls,
diff --git a/crates/codegraph-resolve/src/frameworks/godot.rs b/crates/codegraph-resolve/src/frameworks/godot.rs
index 7dcd628..0831584 100644
--- a/crates/codegraph-resolve/src/frameworks/godot.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot.rs
@@ -584,6 +584,7 @@ mod tests {
 
     fn gd_ref(name: &str, kind: EdgeKind) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "from:caller.gd".to_string(),
             reference_name: name.to_string(),
             reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/frameworks/godot_project.rs b/crates/codegraph-resolve/src/frameworks/godot_project.rs
index b0bb837..9a20a82 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_project.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_project.rs
@@ -425,6 +425,7 @@ fn constant_node(file_path: &str, line_no: i64, name: &str) -> Node {
 /// Build a `References` edge from a synthesized node to a repo-relative path.
 fn reference(from_node_id: String, target: String, line_no: i64, file_path: &str) -> RefView {
     RefView {
+        row_id: None,
         from_node_id,
         reference_name: target,
         reference_kind: EdgeKind::References,
diff --git a/crates/codegraph-resolve/src/frameworks/godot_resource.rs b/crates/codegraph-resolve/src/frameworks/godot_resource.rs
index 64d3fed..870e960 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_resource.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_resource.rs
@@ -331,6 +331,7 @@ fn constant_node(file_path: &str, line_no: i64, name: &str) -> Node {
 /// repo-relative path.
 fn reference(from_node_id: String, target: String, line_no: i64, file_path: &str) -> RefView {
     RefView {
+        row_id: None,
         from_node_id,
         reference_name: target,
         reference_kind: EdgeKind::References,
diff --git a/crates/codegraph-resolve/src/frameworks/godot_scene.rs b/crates/codegraph-resolve/src/frameworks/godot_scene.rs
index 699407d..d0cd6bc 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_scene.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_scene.rs
@@ -537,6 +537,7 @@ fn reference(
     subkind: ReferenceSubkind,
 ) -> RefView {
     RefView {
+        row_id: None,
         from_node_id,
         reference_name: target,
         reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/frameworks/godot_script.rs b/crates/codegraph-resolve/src/frameworks/godot_script.rs
index ce0a3fa..fefd556 100644
--- a/crates/codegraph-resolve/src/frameworks/godot_script.rs
+++ b/crates/codegraph-resolve/src/frameworks/godot_script.rs
@@ -947,6 +947,7 @@ fn reference(
     file_path: &str,
 ) -> RefView {
     RefView {
+        row_id: None,
         from_node_id: from_node_id.to_string(),
         reference_name: name.to_string(),
         reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/frameworks/nestjs.rs b/crates/codegraph-resolve/src/frameworks/nestjs.rs
index 53a0b1a..ce9220a 100644
--- a/crates/codegraph-resolve/src/frameworks/nestjs.rs
+++ b/crates/codegraph-resolve/src/frameworks/nestjs.rs
@@ -378,6 +378,7 @@ fn add_route(
     nodes.push(node);
     if let Some(handler) = handler {
         references.push(RefView {
+            row_id: None,
             from_node_id: node_id,
             reference_name: handler,
             reference_kind: EdgeKind::References,
@@ -1158,6 +1159,7 @@ mod tests {
 
     fn a_ref(name: &str, file: &str) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: format!("from:{file}"),
             reference_name: name.to_string(),
             reference_kind: EdgeKind::References,
diff --git a/crates/codegraph-resolve/src/frameworks/react.rs b/crates/codegraph-resolve/src/frameworks/react.rs
index 10f1f70..1436a7b 100644
--- a/crates/codegraph-resolve/src/frameworks/react.rs
+++ b/crates/codegraph-resolve/src/frameworks/react.rs
@@ -274,6 +274,7 @@ fn route_reference(
     language: Language,
 ) -> RefView {
     RefView {
+        row_id: None,
         from_node_id,
         reference_name: name,
         reference_kind: EdgeKind::References,
@@ -762,6 +763,7 @@ mod tests {
 
     fn a_ref(name: &str, kind: EdgeKind, file: &str, lang: Language) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: format!("from:{file}"),
             reference_name: name.to_string(),
             reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/frameworks/vue.rs b/crates/codegraph-resolve/src/frameworks/vue.rs
index e411082..1c3417a 100644
--- a/crates/codegraph-resolve/src/frameworks/vue.rs
+++ b/crates/codegraph-resolve/src/frameworks/vue.rs
@@ -493,6 +493,7 @@ mod tests {
 
     fn a_ref(name: &str, kind: EdgeKind, file: &str) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: format!("from:{file}"),
             reference_name: name.to_string(),
             reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/import_resolver.rs b/crates/codegraph-resolve/src/import_resolver.rs
index 6f4dbc8..10ac25c 100644
--- a/crates/codegraph-resolve/src/import_resolver.rs
+++ b/crates/codegraph-resolve/src/import_resolver.rs
@@ -2210,6 +2210,7 @@ mod tests {
 
     fn reference(name: &str, kind: EdgeKind, file_path: &str, language: Language) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "function:caller".to_string(),
             reference_name: name.to_string(),
             reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/name_matcher.rs b/crates/codegraph-resolve/src/name_matcher.rs
index 41f140a..9e797a1 100644
--- a/crates/codegraph-resolve/src/name_matcher.rs
+++ b/crates/codegraph-resolve/src/name_matcher.rs
@@ -2253,6 +2253,7 @@ mod ceiling_tests {
 
     fn reference() -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "function:caller".to_string(),
             reference_name: "doThing".to_string(),
             reference_kind: EdgeKind::Calls,
@@ -2445,6 +2446,7 @@ mod tests {
 
     fn refv(name: &str, kind: EdgeKind, path: &str, lang: Language, line: i64) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "function:caller".to_string(),
             reference_name: name.to_string(),
             reference_kind: kind,
diff --git a/crates/codegraph-resolve/src/resolver.rs b/crates/codegraph-resolve/src/resolver.rs
index 1959866..969a96f 100644
--- a/crates/codegraph-resolve/src/resolver.rs
+++ b/crates/codegraph-resolve/src/resolver.rs
@@ -1324,11 +1324,12 @@ impl ReferenceResolver {
     /// instead of materializing the whole graph. Byte-equivalence rests on four
     /// invariants: `warm_caches` runs ONCE over the full node set; the cursor reads
     /// refs in ascending rowid order so edges insert in the same global order with
-    /// identical autoinc ids; resolved-row deletion is DEFERRED to after the loop so
-    /// the tuple-keyed delete never removes a not-yet-read duplicate row from a later
-    /// batch (which would lose its edge — `unresolved_refs` rows have no UNIQUE
-    /// constraint, so the same `(from,name,kind)` tuple recurs across batches); and
-    /// only resolved rows are deleted, leaving the same final `unresolved_refs` table.
+    /// identical autoinc ids; resolved-row deletion is keyed on `unresolved_refs.id`,
+    /// so a batch deletes exactly the rows it resolved and can reach neither a
+    /// not-yet-read row from a later batch nor a sibling call site sharing its
+    /// `(from,name,kind)` tuple (`unresolved_refs` has no UNIQUE constraint, so that
+    /// tuple repeats both within and across batches); and only resolved rows are
+    /// deleted, leaving the same final `unresolved_refs` table.
     ///
     /// Each chunk's refs are resolved IN PARALLEL via an order-preserving
     /// `par_iter().map().collect()` over a `Sync` [`SnapshotResolutionContext`],
@@ -1502,24 +1503,17 @@ impl ReferenceResolver {
                 }
             }
 
-            // Delete THIS batch's resolved rows immediately, bounded by the
-            // batch's max id, instead of accumulating every resolved key for a
-            // single end-of-loop delete (peak-memory bound on large graphs). The
-            // `id <= cursor` guard preserves any duplicate tuple in a later batch
-            // (ascending-id read order ⇒ its id > cursor) — same final table.
-            let batch_keys: Vec<(String, String, EdgeKind)> = result
+            // Per-batch deletion (peak-memory bound on large graphs) is precise
+            // because the key is `row_id`: a batch can only delete rows it read, so
+            // neither a later batch's row nor a sibling call site sharing this
+            // row's (from,name,kind) tuple is reachable from here.
+            let batch_row_ids: Vec<i64> = result
                 .resolved
                 .iter()
-                .map(|reference| {
-                    (
-                        reference.original.from_node_id.clone(),
-                        reference.original.reference_name.clone(),
-                        reference.original.reference_kind,
-                    )
-                })
+                .filter_map(|reference| reference.original.row_id)
                 .collect();
-            if !batch_keys.is_empty() {
-                store.delete_resolved_unresolved_refs_up_to(&batch_keys, cursor)?;
+            if !batch_row_ids.is_empty() {
+                store.delete_resolved_unresolved_refs(&batch_row_ids)?;
             }
 
             // WAL valve in the resolution write loop (#1212 port / resolution-loop
@@ -1913,6 +1907,7 @@ impl ReferenceResolver {
 /// Denormalize a stored [`UnresolvedRef`] into a [`RefView`] (`index.ts:522-531`).
 fn to_ref_view(reference: &UnresolvedRef) -> RefView {
     RefView {
+        row_id: reference.id,
         from_node_id: reference.from_node_id.clone(),
         reference_name: reference.reference_name.clone(),
         reference_kind: reference.reference_kind,
@@ -1929,7 +1924,7 @@ fn to_ref_view(reference: &UnresolvedRef) -> RefView {
 /// for persistence (inverse of [`to_ref_view`]).
 fn ref_view_to_unresolved(reference: &RefView) -> UnresolvedRef {
     UnresolvedRef {
-        id: None,
+        id: reference.row_id,
         from_node_id: reference.from_node_id.clone(),
         reference_name: reference.reference_name.clone(),
         reference_kind: reference.reference_kind,
@@ -2074,17 +2069,8 @@ fn highest_confidence(best: ResolvedRef, curr: ResolvedRef) -> ResolvedRef {
 /// Delete resolved rows from `unresolved_refs`
 /// (`deleteSpecificResolvedReferences`, `index.ts:811-817`).
 fn delete_resolved_rows(store: &mut Store, resolved: &[ResolvedRef]) -> anyhow::Result<()> {
-    let keys: Vec<(String, String, EdgeKind)> = resolved
-        .iter()
-        .map(|r| {
-            (
-                r.original.from_node_id.clone(),
-                r.original.reference_name.clone(),
-                r.original.reference_kind,
-            )
-        })
-        .collect();
-    store.delete_resolved_unresolved_refs(&keys)?;
+    let row_ids: Vec<i64> = resolved.iter().filter_map(|r| r.original.row_id).collect();
+    store.delete_resolved_unresolved_refs(&row_ids)?;
     Ok(())
 }
 
@@ -2213,11 +2199,29 @@ mod tests {
         assert_eq!(view.line, 3);
         assert_eq!(view.column, 4);
         assert!(view.is_function_ref);
+        assert_eq!(view.row_id, Some(7));
         let back = ref_view_to_unresolved(&view);
         assert_eq!(back.reference_name, "X");
         assert_eq!(back.col, 4);
         assert!(back.is_function_ref);
-        assert_eq!(back.id, None);
+        assert_eq!(back.id, Some(7));
+    }
+
+    #[test]
+    fn ref_view_to_unresolved_keeps_framework_ref_row_id_absent() {
+        let synthesized = RefView {
+            row_id: None,
+            from_node_id: "from".to_string(),
+            reference_name: "Autoload.ping".to_string(),
+            reference_kind: EdgeKind::Calls,
+            line: 1,
+            column: 0,
+            file_path: "a.gd".to_string(),
+            language: Language::Gdscript,
+            is_function_ref: false,
+            reference_subkind: None,
+        };
+        assert_eq!(ref_view_to_unresolved(&synthesized).id, None);
     }
 
     #[test]
@@ -2390,6 +2394,7 @@ mod tests {
 
         let extends = ResolvedRef {
             original: RefView {
+                row_id: None,
                 from_node_id: cls.id.clone(),
                 reference_name: "I".to_string(),
                 reference_kind: EdgeKind::Extends,
@@ -2406,6 +2411,7 @@ mod tests {
         };
         let calls = ResolvedRef {
             original: RefView {
+                row_id: None,
                 from_node_id: caller.id.clone(),
                 reference_name: "D".to_string(),
                 reference_kind: EdgeKind::Calls,
@@ -2973,6 +2979,7 @@ mod tests {
         ));
         let ctx = crate::context::StoreResolutionContext::new(&store, "/root");
         let reference = RefView {
+            row_id: None,
             from_node_id: caller.id.clone(),
             reference_name: "this.helper".to_string(),
             reference_kind: EdgeKind::References,
@@ -3016,6 +3023,7 @@ mod tests {
         {
             let ctx = crate::context::StoreResolutionContext::new(&store, "/root");
             let reference = RefView {
+                row_id: None,
                 from_node_id: caller.id.clone(),
                 reference_name: "this.absent".to_string(),
                 reference_kind: EdgeKind::References,
@@ -3064,6 +3072,7 @@ mod tests {
         ));
         let ctx = crate::context::StoreResolutionContext::new(&store, "/root");
         let reference = RefView {
+            row_id: None,
             from_node_id: caller.id.clone(),
             reference_name: "onBlur".to_string(),
             reference_kind: EdgeKind::References,
@@ -3246,6 +3255,7 @@ mod tests {
             "Sub",
             "greet",
             &RefView {
+                row_id: None,
                 from_node_id: run.id.clone(),
                 reference_name: "this.greet".to_string(),
                 reference_kind: EdgeKind::References,
@@ -3279,6 +3289,7 @@ mod tests {
             "C",
             "gone",
             &RefView {
+                row_id: None,
                 from_node_id: "x".to_string(),
                 reference_name: "this.gone".to_string(),
                 reference_kind: EdgeKind::References,
@@ -3368,6 +3379,7 @@ mod tests {
 
     fn mk_ref(name: &str, kind: EdgeKind, lang: Language) -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "from".to_string(),
             reference_name: name.to_string(),
             reference_kind: kind,
@@ -3533,4 +3545,89 @@ mod tests {
         let _ = std::fs::remove_file(&db);
         let _ = std::fs::remove_dir_all(&dir);
     }
+
+    // ----------------------------------------------------------------------
+    // #1269/#1270 PORT: cleanup by row id keeps sibling call sites
+    // ----------------------------------------------------------------------
+
+    /// `run` calls `thing.render()` TWICE (lines 12 and 14) — two
+    /// `unresolved_refs` rows agreeing on `from_node_id`, `reference_name` and
+    /// `reference_kind`, differing only in `line`. Only the line-14 call resolves
+    /// (`thing = Widget()` precedes it), so cleanup must remove exactly that row
+    /// and leave line 12's for the next resolve pass.
+    fn write_sibling_call_sites_fixture(dir: &std::path::Path) -> &'static str {
+        std::fs::write(
+            dir.join("src/siblings.py"),
+            concat!(
+                "class Widget:\n",
+                "    def render(self):\n",
+                "        return 1\n",
+                "\n",
+                "\n",
+                "class Gadget:\n",
+                "    def render(self):\n",
+                "        return 2\n",
+                "\n",
+                "\n",
+                "def run(thing):\n",
+                "    thing.render()\n",
+                "    thing = Widget()\n",
+                "    thing.render()\n",
+            ),
+        )
+        .expect("write siblings.py");
+        "src/siblings.py"
+    }
+
+    #[test]
+    fn resolving_one_call_site_keeps_its_tuple_identical_sibling_row() {
+        let dir = fresh_fixture_dir("sibling-rows");
+        let relative = write_sibling_call_sites_fixture(&dir);
+        let root = dir.to_string_lossy().to_string();
+        let (mut store, db) = index_python_fixture("sibling-rows", &dir, relative);
+
+        let seeded = store.all_unresolved_refs().expect("seeded refs");
+        let seeded_siblings: Vec<&UnresolvedRef> = seeded
+            .iter()
+            .filter(|r| r.reference_name == "thing.render")
+            .collect();
+        assert_eq!(
+            seeded_siblings.len(),
+            2,
+            "fixture must seed TWO tuple-identical rows, got {seeded:?}"
+        );
+
+        let mut resolver = ReferenceResolver::new(root);
+        let result = resolver
+            .resolve_and_persist(&mut store)
+            .expect("resolve_and_persist");
+
+        let resolved_siblings: Vec<&ResolvedRef> = result
+            .resolved
+            .iter()
+            .filter(|r| r.original.reference_name == "thing.render")
+            .collect();
+        assert_eq!(
+            resolved_siblings.len(),
+            1,
+            "exactly ONE of the two call sites resolves"
+        );
+        let resolved_line = resolved_siblings[0].original.line;
+
+        let survivors: Vec<UnresolvedRef> = store
+            .all_unresolved_refs()
+            .expect("remaining refs")
+            .into_iter()
+            .filter(|r| r.reference_name == "thing.render")
+            .collect();
+        assert_eq!(
+            survivors.len(),
+            1,
+            "the UNRESOLVED sibling must survive cleanup of its resolved twin"
+        );
+        assert_ne!(survivors[0].line, resolved_line);
+
+        let _ = std::fs::remove_file(&db);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 }
diff --git a/crates/codegraph-resolve/src/types.rs b/crates/codegraph-resolve/src/types.rs
index 59347f0..87b9ce4 100644
--- a/crates/codegraph-resolve/src/types.rs
+++ b/crates/codegraph-resolve/src/types.rs
@@ -16,6 +16,16 @@ use codegraph_core::types::{EdgeKind, Language, Node, ReferenceSubkind};
 /// node when the row omitted them — `index.ts:522-531`).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RefView {
+    /// `unresolved_refs.id` of the PERSISTED row this view was read from
+    /// (`INTEGER PRIMARY KEY AUTOINCREMENT`, so unique per row), threaded through
+    /// resolution so cleanup can delete EXACTLY the row that resolved (#1269/#1270,
+    /// upstream `e871c49`).
+    ///
+    /// `None` for a view that was never persisted — a `FrameworkResolver`
+    /// synthesizes `RefView`s in memory, and a test may build one by hand. Such a
+    /// view identifies no row, so it must never delete anything; the cleanup path
+    /// skips it.
+    pub row_id: Option<i64>,
     /// ID of the source node containing the reference (`fromNodeId`).
     pub from_node_id: String,
     /// The name being referenced (`referenceName`).
@@ -289,6 +299,7 @@ mod tests {
 
     fn sample_ref() -> RefView {
         RefView {
+            row_id: None,
             from_node_id: "fn:1".to_string(),
             reference_name: "foo".to_string(),
             reference_kind: EdgeKind::Calls,
diff --git a/crates/codegraph-resolve/tests/frameworks.rs b/crates/codegraph-resolve/tests/frameworks.rs
index ed5b220..4a596aa 100644
--- a/crates/codegraph-resolve/tests/frameworks.rs
+++ b/crates/codegraph-resolve/tests/frameworks.rs
@@ -129,6 +129,7 @@ fn node(id: &str, kind: NodeKind, name: &str, file_path: &str, lang: Language) -
 
 fn ref_view(name: &str, kind: EdgeKind, file_path: &str, lang: Language) -> RefView {
     RefView {
+        row_id: None,
         from_node_id: format!("from:{file_path}"),
         reference_name: name.to_string(),
         reference_kind: kind,
diff --git a/crates/codegraph-resolve/tests/snapshot_equivalence.rs b/crates/codegraph-resolve/tests/snapshot_equivalence.rs
index dc41a51..42c962b 100644
--- a/crates/codegraph-resolve/tests/snapshot_equivalence.rs
+++ b/crates/codegraph-resolve/tests/snapshot_equivalence.rs
@@ -117,6 +117,7 @@ fn assert_contexts_equivalent(test_name: &str, root: &Path, relative_files: &[&s
     let mut mismatches: Vec<String> = Vec::new();
     for unresolved in &refs {
         let view = codegraph_resolve::RefView {
+            row_id: unresolved.id,
             from_node_id: unresolved.from_node_id.clone(),
             reference_name: unresolved.reference_name.clone(),
             reference_kind: unresolved.reference_kind,
diff --git a/crates/codegraph-store/src/queries.rs b/crates/codegraph-store/src/queries.rs
index d6377b3..0a71fc8 100644
--- a/crates/codegraph-store/src/queries.rs
+++ b/crates/codegraph-store/src/queries.rs
@@ -739,58 +739,29 @@ impl Store {
             .query_row("SELECT count(*) FROM unresolved_refs", [], |row| row.get(0))
     }
 
-    /// Ports `deleteSpecificResolvedReferences` from `upstream db/queries.ts:1716-1727`.
-    /// Deletes one row per `(from_node_id, reference_name, reference_kind)` tuple in a single
-    /// transaction, matching the upstream precise per-tuple delete so only actually-resolved refs go.
-    pub fn delete_resolved_unresolved_refs(
-        &mut self,
-        keys: &[(String, String, EdgeKind)],
-    ) -> rusqlite::Result<()> {
-        if keys.is_empty() {
-            return Ok(());
-        }
-        let tx = self.conn.transaction()?;
-        {
-            let mut stmt = tx.prepare_cached(
-                "DELETE FROM unresolved_refs WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ?",
-            )?;
-            for (from_node_id, reference_name, reference_kind) in keys {
-                stmt.execute(params![
-                    from_node_id,
-                    reference_name,
-                    reference_kind.as_str()
-                ])?;
-            }
-        }
-        tx.commit()
-    }
-
-    /// Per-batch variant of [`Self::delete_resolved_unresolved_refs`] bounded by
-    /// `max_id`: deletes only rows whose `id <= max_id`. The batched resolver
-    /// reads refs in ascending-`id` order, so a duplicate `(from,name,kind)`
-    /// tuple in a LATER batch has `id > max_id` and is preserved — letting the
-    /// caller drop each batch's keys immediately instead of accumulating every
-    /// resolved key for one final delete (bounds peak memory on large graphs).
-    pub fn delete_resolved_unresolved_refs_up_to(
-        &mut self,
-        keys: &[(String, String, EdgeKind)],
-        max_id: i64,
-    ) -> rusqlite::Result<()> {
-        if keys.is_empty() {
+    /// Ports `deleteSpecificResolvedReferences` from `upstream db/queries.ts:1716-1727`
+    /// (row-id form, #1269/#1270 / upstream `e871c49`).
+    ///
+    /// Deletes EXACTLY the rows named by `row_ids` in a single transaction. `id` is
+    /// the table's `INTEGER PRIMARY KEY AUTOINCREMENT`, so each id addresses one
+    /// row and nothing else.
+    ///
+    /// The previous key — `(from_node_id, reference_name, reference_kind)` — is NOT
+    /// unique: two calls to the same name from the same enclosing node differ only
+    /// in `line`/`col`/`id`, and the tuple-keyed `DELETE` carried no `LIMIT`, so
+    /// resolving ONE of them deleted BOTH and the sibling's edge was silently lost.
+    /// Keying on the row id removes that whole class of loss, and with it the need
+    /// for any `id <= max_id` batch guard: an id from batch N cannot name a row in
+    /// batch N+1, so a per-batch caller is already precise.
+    pub fn delete_resolved_unresolved_refs(&mut self, row_ids: &[i64]) -> rusqlite::Result<()> {
+        if row_ids.is_empty() {
             return Ok(());
         }
         let tx = self.conn.transaction()?;
         {
-            let mut stmt = tx.prepare_cached(
-                "DELETE FROM unresolved_refs WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ? AND id <= ?",
-            )?;
-            for (from_node_id, reference_name, reference_kind) in keys {
-                stmt.execute(params![
-                    from_node_id,
-                    reference_name,
-                    reference_kind.as_str(),
-                    max_id
-                ])?;
+            let mut stmt = tx.prepare_cached("DELETE FROM unresolved_refs WHERE id = ?")?;
+            for row_id in row_ids {
+                stmt.execute(params![row_id])?;
             }
         }
         tx.commit()
@@ -2487,18 +2458,22 @@ mod tests {
         assert_eq!(store.unresolved_refs_count().unwrap(), 0);
     }
 
+    /// Two sibling call sites — SAME `from_node_id`, SAME `reference_name`, SAME
+    /// `reference_kind`, differing only in `line` — must be independently
+    /// deletable. The old `(from,name,kind)` key could not tell them apart and,
+    /// carrying no `LIMIT`, removed both when one resolved (#1269/#1270).
     #[test]
-    fn delete_resolved_refs_precise_and_bounded() {
-        let mut store = store("delete-resolved");
+    fn delete_resolved_refs_by_row_id_removes_only_the_named_row() {
+        let mut store = store("delete-resolved-siblings");
         store
             .upsert_nodes(&[node("function:src", "src", "a.rs")])
             .unwrap();
-        let mk = |name: &str| UnresolvedRef {
+        let mk = |name: &str, line: i64| UnresolvedRef {
             id: None,
             from_node_id: "function:src".to_string(),
             reference_name: name.to_string(),
             reference_kind: EdgeKind::Calls,
-            line: 1,
+            line,
             col: 0,
             candidates: None,
             file_path: "a.rs".to_string(),
@@ -2507,38 +2482,40 @@ mod tests {
             reference_subkind: None,
         };
         store
-            .insert_unresolved_refs(&[mk("Alpha"), mk("Beta"), mk("Gamma")])
+            .insert_unresolved_refs(&[mk("helper", 2), mk("helper", 3), mk("Other", 4)])
             .unwrap();
         assert_eq!(store.unresolved_refs_count().unwrap(), 3);
 
         store.delete_resolved_unresolved_refs(&[]).unwrap();
-        store
-            .delete_resolved_unresolved_refs_up_to(&[], 100)
-            .unwrap();
         assert_eq!(store.unresolved_refs_count().unwrap(), 3);
 
-        store
-            .delete_resolved_unresolved_refs(&[(
-                "function:src".to_string(),
-                "Alpha".to_string(),
-                EdgeKind::Calls,
-            )])
-            .unwrap();
-        assert_eq!(store.unresolved_refs_count().unwrap(), 2);
+        let siblings: Vec<UnresolvedRef> = store
+            .all_unresolved_refs()
+            .unwrap()
+            .into_iter()
+            .filter(|r| r.reference_name == "helper")
+            .collect();
+        assert_eq!(siblings.len(), 2);
+        let first = siblings[0].id.unwrap();
+        let second = siblings[1].id.unwrap();
+        assert_ne!(first, second);
+
+        store.delete_resolved_unresolved_refs(&[first]).unwrap();
+
+        let remaining = store.all_unresolved_refs().unwrap();
+        assert_eq!(remaining.len(), 2);
+        let survivor = remaining
+            .iter()
+            .find(|r| r.reference_name == "helper")
+            .expect("the sibling `helper` row must survive its twin's deletion");
+        assert_eq!(survivor.id, Some(second));
+        assert_eq!(survivor.line, siblings[1].line);
 
-        let rows = store.all_unresolved_refs().unwrap();
-        let max_id = rows.iter().map(|r| r.id.unwrap()).min().unwrap();
-        store
-            .delete_resolved_unresolved_refs_up_to(
-                &[(
-                    "function:src".to_string(),
-                    "Beta".to_string(),
-                    EdgeKind::Calls,
-                )],
-                max_id,
-            )
-            .unwrap();
-        assert!(store.unresolved_refs_count().unwrap() <= 2);
+        store.delete_resolved_unresolved_refs(&[second]).unwrap();
+        assert_eq!(store.unresolved_refs_count().unwrap(), 1);
+
+        store.delete_resolved_unresolved_refs(&[second]).unwrap();
+        assert_eq!(store.unresolved_refs_count().unwrap(), 1);
     }
 
     #[test]
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 3845d82..4b35608 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4385,3 +4385,187 @@ gitignored, so they were deleted before staging. No tracked golden file changed.
 `lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
 must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
 no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed.
+
+## Batch C3 — resolved-ref cleanup keys on the row id, so batch boundaries stop dropping sibling call sites (2026-07-28)
+
+Ports upstream `e871c49` (#1269/#1270). Base for this entry: `285d591`
+(Batch C2). One commit, resolution/store only.
+
+### The old key, quoted verbatim
+
+`crates/codegraph-store/src/queries.rs` held two tuple-keyed deletes:
+
+```sql
+DELETE FROM unresolved_refs WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ?
+```
+
+```sql
+DELETE FROM unresolved_refs WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ? AND id <= ?
+```
+
+`(from_node_id, reference_name, reference_kind)` is NOT unique — the table has no
+UNIQUE constraint, and two calls to the same name from the same enclosing node
+differ only in `line`/`col`/`id`. Neither statement carried a `LIMIT`, so
+resolving ONE call site deleted EVERY row sharing its tuple.
+
+Two further facts made this reachable rather than theoretical. First, the
+`id <= max_id` guard on the batched variant proves the author already knew the
+tuple repeats — its own doc said a duplicate tuple in a LATER batch has
+`id > max_id` and is preserved. That guard protects ACROSS batches and does
+nothing WITHIN one, where every sibling satisfies `id <= max_id`. Second, the
+non-batched variant's doc claimed "Deletes one row per tuple", which was false;
+that sentence is corrected in this commit.
+
+The row id was available the whole time and simply discarded:
+`unresolved_refs.id` is `INTEGER PRIMARY KEY AUTOINCREMENT`,
+`row_to_unresolved_ref` already read it into `UnresolvedRef.id`, and
+`to_ref_view` then dropped it because `RefView` had no field to hold it — leaving
+the resolver able to rebuild only the coarse tuple.
+
+### Red (documented, with the actual observed drop)
+
+A throwaway probe module in `resolver.rs`, driven through the production path
+(`extract_file` → `upsert_nodes`/`insert_edges`/`insert_unresolved_refs` →
+`resolve_and_persist`), on this Python fixture:
+
+```python
+def run(thing):
+    thing.render()      # line 12 — `thing` not yet bound, does NOT resolve
+    thing = Widget()
+    thing.render()      # line 14 — resolves to Widget::render
+```
+
+Observed (`cargo test --locked -p codegraph-resolve --lib scratch_observe_sibling_rows
+-- --nocapture` → exit 0, printing):
+
+```text
+REF from=function:70b72f5… name=thing.render kind=Calls line=12
+REF from=function:70b72f5… name=thing.render kind=Calls line=14
+RESOLVED 2 UNRESOLVED 1
+  OK name=thing.render line=14 -> method:830ab53… by=InstanceMethod
+  NO name=thing.render line=12
+```
+
+and then, decisively, ZERO `REMAIN` lines: the store's `unresolved_refs` table was
+EMPTY. Resolution itself was correct — it reported line 12 unresolved — but
+cleanup of line 14 deleted line 12's row too. The unresolved sibling was
+silently erased from the table that exists to record it, so it can never be
+retried and its edge can never appear. The probe module was reverted
+(`git checkout --` → tree clean) before any fix; its observation is the Red.
+
+### Green (minimal)
+
+Thread the ROW ID from the stored row through resolution to cleanup. No coarse
+fallback key is retained anywhere — keeping one would reintroduce the defect.
+
+- `crates/codegraph-resolve/src/types.rs`: `RefView` gains
+  `row_id: Option<i64>`. `None` means "this view was never persisted" — a
+  `FrameworkResolver` synthesizes `RefView`s in memory and tests build them by
+  hand; such a view names no row and must delete nothing.
+- `crates/codegraph-resolve/src/resolver.rs`: `to_ref_view` populates
+  `row_id: reference.id`; `ref_view_to_unresolved` now carries it back
+  (`id: reference.row_id`) instead of hardcoding `None`, so the round-trip is
+  lossless while a framework-synthesized view still persists with `id: None`.
+  Both delete call sites collect `filter_map(|r| r.original.row_id)`, so an
+  unpersisted view is skipped rather than widened into a tuple.
+- `crates/codegraph-store/src/queries.rs`: `delete_resolved_unresolved_refs`
+  takes `&[i64]` and runs `DELETE FROM unresolved_refs WHERE id = ?`.
+  `delete_resolved_unresolved_refs_up_to` is REMOVED rather than re-signatured:
+  its entire reason for existing was the `id <= max_id` cross-batch guard, and an
+  id from batch N cannot name a row in batch N+1, so the batched caller is
+  already precise with the plain row-id delete. Its doc rationale moved onto the
+  surviving function, and the false "Deletes one row per tuple" sentence is
+  replaced with the actual guarantee plus why the old key was unsafe.
+- 47 `RefView` construction sites across `crates/codegraph-resolve/`
+  (frameworks, `name_matcher`, `import_resolver`, `framework`, both integration
+  tests) updated explicitly. `RefView` gained no `Default`, and no
+  `..Default::default()` was introduced, so the compiler had to see every site.
+  `snapshot_equivalence.rs` threads the real `unresolved.id`.
+
+The batched-resolution doc comment on `resolve_and_persist_batched` is corrected
+in the same commit: its byte-equivalence argument previously rested on the
+tuple-keyed delete being deferred; it now rests on the row-id key, which is
+strictly stronger (a batch can reach neither a later batch's row nor a sibling
+sharing its tuple).
+
+### Load-bearing tests
+
+- `codegraph-store` `delete_resolved_refs_by_row_id_removes_only_the_named_row`
+  SUPERSEDES `delete_resolved_refs_precise_and_bounded`. The old test used three
+  DISTINCT names (`Alpha`/`Beta`/`Gamma`), which is exactly why it never caught
+  this: with no tuple collision in the fixture, the missing `LIMIT` was
+  unobservable. The new test inserts TWO tuple-identical `helper` rows differing
+  only in `line`, deletes the first by id, and asserts the second survives with
+  its own id and line — then asserts a repeat delete of an already-gone id is a
+  no-op.
+- `codegraph-resolve` `resolving_one_call_site_keeps_its_tuple_identical_sibling_row`
+  drives the PRODUCTION path on the Red's fixture (pattern copied from C2's
+  accepted `literal_receiver_and_nested_local_produce_no_fabricated_call_edge`):
+  it asserts the fixture really seeds two tuple-identical rows, that exactly one
+  resolves, and that the UNRESOLVED sibling is still in `unresolved_refs`
+  afterwards at a different line.
+- `to_ref_view_and_back_roundtrip` extended to assert the id survives both
+  directions (`Some(7)`), plus a new
+  `ref_view_to_unresolved_keeps_framework_ref_row_id_absent` pinning the
+  never-persisted case at `None`.
+
+### Golden row delta
+
+NONE. `git diff --stat 285d591..HEAD -- reference/golden/` → **empty output**;
+`git status --porcelain reference/golden/` → empty. Expected: the manifest
+classifies C3 as "exact persisted row IDs; golden-neutral", and the change only
+narrows WHICH rows a delete removes — it never alters extraction, resolution
+decisions, edge construction, or insertion order. All 26 equivalence oracles pass
+unchanged. No golden was regenerated.
+
+### Negative control, EXECUTED
+
+Restored tuple semantics BEHIND the new row-id signature (each id looked up to
+its `(from,name,kind)` tuple, then the old tuple-keyed `DELETE` executed), so
+only the delete's precision changed and nothing else:
+
+- `cargo test --locked -p codegraph-store --lib delete_resolved_refs_by_row_id_removes_only_the_named_row`
+  → **exit 101**, `assertion left == right failed; left: 1, right: 2` at
+  `queries.rs:2522` — both `helper` rows gone, only `Other` left.
+- `cargo test --locked -p codegraph-resolve --lib resolving_one_call_site_keeps_its_tuple_identical_sibling_row`
+  → **exit 101**, `assertion failed: the UNRESOLVED sibling must survive cleanup
+of its resolved twin; left: 0, right: 1` at `resolver.rs:3626`.
+
+Both tests are load-bearing, at both layers. Restored from backup;
+`sha256sum -c` → `queries.rs: OK`, `resolver.rs: OK` (verify exit 0). Green
+hashes: `queries.rs`
+`42deaa32da2a6b0053ec974da5891d2af34386d3c219bdcb63fef54bed71d5f2`,
+`resolver.rs`
+`072c66b36f1b061d06c58809f7306b6358526eda88d6966d7eca62413d01090b`,
+`types.rs`
+`a7084d442d91708073a7e4ec44f72ad96da7e6df914b0cec4bc094b0065fbe8b`.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked --workspace --all-targets` → first attempt exit 101
+  (`delete_resolved_unresolved_refs_up_to` not found — the superseded store test
+  still called it); after replacing that test, clean.
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → exit 0.
+- `cargo test --locked -p codegraph-store --lib delete_resolved_refs_by_row_id_removes_only_the_named_row`
+  → exit 0.
+- `cargo test --locked -p codegraph-resolve --lib resolving_one_call_site_keeps_its_tuple_identical_sibling_row`
+  → exit 0.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26
+  passed, 0 failed** (unchanged 26/26).
+- `cargo test --locked --workspace` → **exit 101 on the first run**, failing ONLY
+  `codegraph-rs formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+  — the KNOWN pre-existing in-process `HOME`/`XDG_DATA_HOME` race documented in
+  the Batch C2 entry, unrelated to resolution or the store. It was NOT weakened,
+  skipped, `#[ignore]`d or modified. Re-run in isolation → exit 0, 1 passed.
+- The first workspace run left two untracked SQLite byproducts
+  (`reference/golden/cfml/colby.db-{wal,shm}`) from the oracle; they are not
+  gitignored, so they were deleted before staging. No tracked golden changed.
+- `git diff --stat 285d591..HEAD -- reference/golden/` → empty.
+
+`lsp_diagnostics` was attempted on `queries.rs` and again refused this worktree
+(`LSP file path must be inside request cwd`); locked Cargo clippy/test is the
+honest fallback and no LSP-clean result is claimed. No dependency, version or
+`Cargo.lock` byte changed. No Windows/MSVC runtime validation is claimed — this
+work ran on Linux only.

From 8c803315a9af6e5da566d7eaf0e51c3330a8cd69 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 10:31:36 +0800
Subject: [PATCH 50/91] fix(retrieval): score non-ASCII query words so their
 definers outrank namesakes

---
 .../codegraph-cli/tests/unicode_search_cli.rs | 295 ++++++++++++++++++
 crates/codegraph-graph/src/query/scoring.rs   |  21 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 151 +++++++++
 3 files changed, 464 insertions(+), 3 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/unicode_search_cli.rs

diff --git a/crates/codegraph-cli/tests/unicode_search_cli.rs b/crates/codegraph-cli/tests/unicode_search_cli.rs
new file mode 100644
index 0000000..a160787
--- /dev/null
+++ b/crates/codegraph-cli/tests/unicode_search_cli.rs
@@ -0,0 +1,295 @@
+//! Upstream #1372 — non-ASCII identifiers must be FINDABLE and RANKED
+//! correctly through the real user-facing surfaces.
+//!
+//! Drives the actual `codegraph` binary (`init` then `query --json`) against a
+//! temp project whose files are named in SEVEN different scripts, each paired
+//! with an ASCII-named DECOY file that defines an identically-named function.
+//! The definer inside the script-named file must outrank its decoy, because the
+//! query names that file. The scripts are deliberately not just the one the fix
+//! was written for: CJK, Cyrillic, Greek, Kana, Hangul, accented Latin, and an
+//! ASCII control that must stay byte-identical in behavior.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-unicode-search-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(cwd: &Path, args: &[&str]) -> Run {
+    let output = Command::new(bin())
+        .args(args)
+        .current_dir(cwd)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+/// `(module-file stem, function name)` pairs. The module stem is what the query
+/// names; the function is defined TWICE — once in `<stem>.py`, once in the
+/// ASCII decoy `zdecoy_<tag>.py`. The decoy is named so it sorts and matches
+/// nothing in the query: only path relevance can separate the two.
+const CASES: &[(&str, &str, &str)] = &[
+    ("示例模块", "handlercjk", "cjk"),
+    ("модуль", "handlercyr", "cyr"),
+    ("μονάδα", "handlergrk", "grk"),
+    ("サンプル", "handlerkana", "kana"),
+    ("모듈", "handlerkor", "kor"),
+    ("café_módulo", "handleracc", "acc"),
+    ("samplemodule", "handlerascii", "ascii"),
+];
+
+/// A two-character CJK module stem — below the 3-char floor ASCII tokens use.
+/// Unsegmented scripts pack a whole word into two characters, so this shape
+/// must rank as well as the four-character one.
+const SHORT_CASE: (&str, &str, &str) = ("模块", "handlershort", "short");
+
+fn write_project(root: &Path) {
+    let body = |func: &str| format!("def {func}():\n    return 1\n");
+    for (stem, func, tag) in CASES.iter().chain(std::iter::once(&SHORT_CASE)) {
+        std::fs::write(root.join(format!("{stem}.py")), body(func)).unwrap();
+        std::fs::write(root.join(format!("zdecoy_{tag}.py")), body(func)).unwrap();
+    }
+}
+
+/// `(filePath, name)` for every hit, in the order the CLI ranked them.
+fn ranked(project: &Path, query: &str) -> Vec<(String, String)> {
+    let p = project.to_str().unwrap();
+    let run = run_in(project, &["query", query, "-p", p, "--json"]);
+    assert!(
+        run.ok,
+        "query {query:?} must succeed: {} {}",
+        run.stdout, run.stderr
+    );
+    let v: serde_json::Value = serde_json::from_str(&run.stdout)
+        .unwrap_or_else(|e| panic!("query {query:?} must emit JSON ({e}): {}", run.stdout));
+    v.as_array()
+        .expect("query --json is an array")
+        .iter()
+        .map(|r| {
+            (
+                r["node"]["filePath"]
+                    .as_str()
+                    .unwrap_or_default()
+                    .to_string(),
+                r["node"]["name"].as_str().unwrap_or_default().to_string(),
+            )
+        })
+        .collect()
+}
+
+fn indexed_project(dir: &TestDir) -> PathBuf {
+    let project = dir.path().join("proj");
+    std::fs::create_dir_all(&project).unwrap();
+    write_project(&project);
+    let run = run_in(dir.path(), &["init", project.to_str().unwrap()]);
+    assert!(run.ok, "init failed: {} {}", run.stdout, run.stderr);
+    project
+}
+
+/// The definer in the file the query NAMES must outrank the same-named decoy in
+/// every script, not just the one the fix was written against.
+#[test]
+fn non_ascii_module_name_outranks_ascii_decoy_in_every_script() {
+    let dir = TestDir::new("rank");
+    let project = indexed_project(&dir);
+
+    let mut failures: Vec<String> = Vec::new();
+    for (stem, func, tag) in CASES.iter().chain(std::iter::once(&SHORT_CASE)) {
+        let hits = ranked(&project, &format!("{stem} {func}"));
+        let want = format!("{stem}.py");
+        let decoy = format!("zdecoy_{tag}.py");
+        let pos = |file: &str| hits.iter().position(|(f, n)| f == file && n == func);
+        match (pos(&want), pos(&decoy)) {
+            (Some(w), Some(d)) if w < d => {}
+            (w, d) => failures.push(format!(
+                "[{tag}] query {stem:?} {func:?}: definer {want} at {w:?}, decoy {decoy} at {d:?}; ranking was {hits:?}"
+            )),
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "the query names the module file, so its definer must rank first:\n{}",
+        failures.join("\n")
+    );
+}
+
+/// A non-ASCII SYMBOL name (not just a file name) stays findable by exact name.
+#[test]
+fn non_ascii_symbol_name_is_findable_by_exact_name() {
+    let dir = TestDir::new("symbol");
+    let project = dir.path().join("proj");
+    std::fs::create_dir_all(&project).unwrap();
+    std::fs::write(
+        project.join("mod.py"),
+        "def 示例函数():\n    return 1\n\n\ndef 데이터조회():\n    return 2\n",
+    )
+    .unwrap();
+    let run = run_in(dir.path(), &["init", project.to_str().unwrap()]);
+    assert!(run.ok, "init failed: {} {}", run.stdout, run.stderr);
+
+    for name in ["示例函数", "데이터조회"] {
+        let hits = ranked(&project, name);
+        assert_eq!(
+            hits.first().map(|(_, n)| n.as_str()),
+            Some(name),
+            "exact non-ASCII symbol {name:?} must rank first, got {hits:?}"
+        );
+    }
+}
+
+/// The same ranking must hold over the MCP `codegraph_search` contract, not
+/// only the CLI: `serve --mcp` against the same index, driven over real stdio.
+#[cfg(unix)]
+#[test]
+fn mcp_search_ranks_the_non_ascii_definer_over_its_decoy() {
+    use std::io::{BufRead, BufReader, Write};
+    use std::process::Stdio;
+    use std::time::{Duration, Instant};
+
+    let dir = TestDir::new("mcp");
+    let project = indexed_project(&dir);
+
+    let mut child = Command::new(bin())
+        .args(["serve", "--mcp", "--path", project.to_str().unwrap()])
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn serve --mcp");
+    let mut stdin = child.stdin.take().expect("child stdin");
+    let mut stdout = BufReader::new(child.stdout.take().expect("child stdout"));
+    let deadline = Instant::now() + Duration::from_secs(30);
+
+    let send = |stdin: &mut std::process::ChildStdin, v: serde_json::Value| {
+        writeln!(stdin, "{v}").unwrap();
+        stdin.flush().unwrap();
+    };
+    let mut recv = |want_id: i64| -> serde_json::Value {
+        loop {
+            assert!(Instant::now() < deadline, "timed out awaiting id {want_id}");
+            let mut line = String::new();
+            match stdout.read_line(&mut line) {
+                Ok(0) => panic!("serve --mcp closed stdout before id {want_id}"),
+                Ok(_) => {
+                    if let Ok(v) = serde_json::from_str::<serde_json::Value>(line.trim())
+                        && v.get("id").and_then(serde_json::Value::as_i64) == Some(want_id)
+                    {
+                        return v;
+                    }
+                }
+                Err(e) => panic!("reading serve --mcp stdout: {e}"),
+            }
+        }
+    };
+
+    send(
+        &mut stdin,
+        serde_json::json!({
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": { "name": "unicode-search-test", "version": "0" }
+            }
+        }),
+    );
+    let _ = recv(1);
+    send(
+        &mut stdin,
+        serde_json::json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }),
+    );
+
+    send(
+        &mut stdin,
+        serde_json::json!({
+            "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+            "params": {
+                "name": "codegraph_search",
+                "arguments": { "query": "示例模块 handlercjk" }
+            }
+        }),
+    );
+    let resp = recv(2);
+    let text = resp["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string();
+    drop(stdin);
+    let _ = child.kill();
+    let _ = child.wait();
+
+    assert_ne!(
+        resp["result"]["isError"],
+        serde_json::json!(true),
+        "MCP search must not error on a non-ASCII query: {text}"
+    );
+    let definer = text
+        .find("示例模块.py")
+        .unwrap_or_else(|| panic!("MCP search must surface the non-ASCII definer file: {text}"));
+    let decoy = text
+        .find("zdecoy_cjk.py")
+        .unwrap_or_else(|| panic!("MCP search must surface the decoy too: {text}"));
+    assert!(
+        definer < decoy,
+        "MCP search must rank the named module's definer above its decoy: {text}"
+    );
+}
+
+/// Ranking must be a pure function of the index, not of incidental row order:
+/// the same query over the same index answers identically every time.
+#[test]
+fn non_ascii_ranking_is_deterministic_across_repeated_queries() {
+    let dir = TestDir::new("determinism");
+    let project = indexed_project(&dir);
+    let first = ranked(&project, "示例模块 handlercjk");
+    for _ in 0..4 {
+        assert_eq!(
+            ranked(&project, "示例模块 handlercjk"),
+            first,
+            "repeated identical queries must return an identical ranking"
+        );
+    }
+}
diff --git a/crates/codegraph-graph/src/query/scoring.rs b/crates/codegraph-graph/src/query/scoring.rs
index 571d0cc..b08ba08 100644
--- a/crates/codegraph-graph/src/query/scoring.rs
+++ b/crates/codegraph-graph/src/query/scoring.rs
@@ -5,10 +5,25 @@ use codegraph_core::types::NodeKind;
 pub fn normalize_name_token(raw: &str) -> String {
     raw.to_lowercase()
         .chars()
-        .filter(|c| c.is_ascii_alphanumeric())
+        .filter(|c| c.is_alphanumeric())
         .collect()
 }
 
+/// Minimum length for a scoring token (#1372).
+///
+/// An ASCII word shorter than three characters carries no retrieval signal
+/// ("of", "is", "at"), which is why the floor exists. An unsegmented script
+/// packs a whole word into two characters — `模块` IS "module" — so a token
+/// holding any non-ASCII character is admitted at two. ASCII tokens keep the
+/// original three-character floor byte-for-byte.
+fn meets_min_token_len(token: &str) -> bool {
+    let len = token.chars().count();
+    if len >= 3 {
+        return true;
+    }
+    len >= 2 && !token.is_ascii()
+}
+
 pub const STOP_WORDS: &[&str] = &[
     "the",
     "a",
@@ -336,12 +351,12 @@ pub fn extract_search_terms(query: &str, include_stems: bool) -> Vec<String> {
         .map(|c| if c == '_' || c == '.' { ' ' } else { c })
         .collect();
 
-    for word in normalised.split(|c: char| !c.is_ascii_alphanumeric()) {
+    for word in normalised.split(|c: char| !c.is_alphanumeric()) {
         if word.is_empty() {
             continue;
         }
         let lower = word.to_lowercase();
-        if lower.chars().count() < 3 {
+        if !meets_min_token_len(&lower) {
             continue;
         }
         if is_stop_word(&lower) {
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 4b35608..38fa3ab 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4569,3 +4569,154 @@ hashes: `queries.rs`
 honest fallback and no LSP-clean result is claimed. No dependency, version or
 `Cargo.lock` byte changed. No Windows/MSVC runtime validation is claimed — this
 work ran on Linux only.
+
+---
+
+## Batch A1 — non-ASCII identifiers reach their definers through the real search surfaces (2026-07-28)
+
+Ports upstream issue #1372. Base for this entry: `29f635b` (Batch C3). One
+commit, scoring + a new CLI/MCP integration test.
+
+### What the current build ACTUALLY did (measured before any edit)
+
+The reported upstream symptom — `explore` returning _no relevant code_ for a
+pure-CJK query while `query` finds the file — does NOT reproduce here. Measured
+on the real binary (`target/debug/codegraph`, built from `29f635b`) against a
+throwaway project holding `示例模块.lua` (defining `M.示例函数`), `cafe.py`
+(`café_lookup`) and `uni.py` (`Ünicode`):
+
+```text
+$ codegraph query "示例模块"      → file 示例模块.lua           (found)
+$ codegraph query "示例函数"      → method 示例函数              (found)
+$ codegraph query "café_lookup"  → function café_lookup        (found)
+$ codegraph query "Ünicode"      → class Ünicode                (found)
+$ codegraph explore "示例模块"    → "## Exploration: 示例模块", 3 symbols,
+                                    the file's verbatim source
+```
+
+FTS5 tokenization is NOT the crux: `nodes_fts` is a `unicode61`-tokenized
+contentless-mirror table (`schema.rs:100`), and `unicode61` already treats CJK,
+Cyrillic, Greek, Kana, Hangul and accented Latin codepoints as token
+characters. Non-ASCII names are indexed and retrievable. So no FTS/schema
+change was made and none is needed — the golden `.schema` is untouched.
+
+The defect that IS present is in RANKING, one layer above FTS: the scoring
+tokenizer in `crates/codegraph-graph/src/query/scoring.rs` is ASCII-only, so a
+non-ASCII query word produces ZERO scoring tokens and therefore contributes
+NOTHING to `score_path_relevance`. Probe (throwaway test, reverted):
+
+```text
+word="示例模块" terms=[] path_relevance=0
+word="модуль"   terms=[] path_relevance=0
+word="μονάδα"   terms=[] path_relevance=0
+word="サンプル"  terms=[] path_relevance=0
+word="모듈"      terms=[] path_relevance=0
+word="café"      terms=["caf"]          path_relevance=13
+word="samplemodule" terms=["samplemodule"] path_relevance=13
+```
+
+`extract_search_terms` split on `!c.is_ascii_alphanumeric()`, so an entire
+non-ASCII word was discarded; `café` survived only as the truncated `caf`
+because `é` acted as a separator; `normalize_name_token` likewise erased
+non-ASCII, making project-name filtering meaningless for such repos.
+
+### Red (documented, with the actual wrong output)
+
+New test `crates/codegraph-cli/tests/unicode_search_cli.rs`, driving the REAL
+binary (`init`, then `query --json`, plus a `serve --mcp` stdio session). Each
+of SEVEN scripts gets a module file named in that script defining a function,
+paired with an ASCII-named DECOY file defining the SAME function name — so only
+path relevance can separate them — plus a two-character CJK case (`模块`, a
+whole word below the ASCII 3-char floor).
+
+`cargo test --locked -p codegraph-rs --test unicode_search_cli` → exit 101,
+2 of 4 failing. Verbatim, the wrong ranking:
+
+```text
+the query names the module file, so its definer must rank first:
+[cjk] query "示例模块" "handlercjk": definer 示例模块.py at Some(1), decoy zdecoy_cjk.py at Some(0)
+[cyr] query "модуль" "handlercyr": definer модуль.py at Some(1), decoy zdecoy_cyr.py at Some(0)
+[grk] query "μονάδα" "handlergrk": definer μονάδα.py at Some(1), decoy zdecoy_grk.py at Some(0)
+[kana] query "サンプル" "handlerkana": definer サンプル.py at Some(1), decoy zdecoy_kana.py at Some(0)
+[kor] query "모듈" "handlerkor": definer 모듈.py at Some(1), decoy zdecoy_kor.py at Some(0)
+[short] query "模块" "handlershort": definer 模块.py at Some(1), decoy zdecoy_short.py at Some(0)
+```
+
+and through the MCP `codegraph_search` contract over real stdio:
+
+```text
+MCP search must rank the named module's definer above its decoy:
+## Search Results (3 found)
+
+### handlercjk (function)
+zdecoy_cjk.py:1
+### handlercjk (function)
+示例模块.py:1
+```
+
+The ASCII control case (`samplemodule handlerascii`) PASSED before the fix —
+that is the point: the wrong answer was specific to non-ASCII input. Measured
+scores on the real binary: definer and decoy tied at exactly `75.8908` for CJK
+(the file name contributed 0), where the ASCII pair separated `88.8908` vs
+`75.8908`. The tie then resolved to whichever row FTS returned first, which is
+why the decoy won.
+
+### Green (minimal)
+
+`crates/codegraph-graph/src/query/scoring.rs`, three edits, no new dependency:
+
+- `extract_search_terms` word split: `!c.is_ascii_alphanumeric()` →
+  `!c.is_alphanumeric()`, so a non-ASCII word survives as one token and
+  `café_módulo` no longer shatters into `caf`/`dulo`.
+- New `meets_min_token_len` replaces the bare `< 3` check: ASCII keeps the
+  three-character floor byte-for-byte; a token containing any non-ASCII
+  character is admitted at two, because an unsegmented script packs a whole word
+  into two characters (`模块` IS "module").
+- `normalize_name_token`: `is_ascii_alphanumeric` → `is_alphanumeric`, so
+  project-name-token filtering sees non-ASCII repo names.
+
+The camel/acronym/compound/snake helpers were deliberately left ASCII-only —
+case humps are not a concept in unsegmented scripts, and widening them would
+change ASCII tokenization. No FTS query string, BM25 weight, tie-break or SQL
+was touched, so ranking stays a pure function of the index (proven by the
+repeat-query determinism test).
+
+### Golden row delta
+
+None. `git diff --stat 29f635b..HEAD -- reference/golden/` → EMPTY, and
+`git status --short reference/golden/` → empty.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed** (unchanged 26/26).
+
+### Negative control, EXECUTED
+
+`git stash push -- crates/codegraph-graph/src/query/scoring.rs` (production
+change only; the new test kept) → `cargo test --locked -p codegraph-rs --test
+unicode_search_cli` → exit 101, exactly the two Red failures above. `git stash
+pop` restored it; restored-file SHA-256 of `scoring.rs`
+`2fcaaef957f8d20bcc530df7e50382dd8b451c105e8ea769e87532126b5ce34c` (before the
+clippy follow-up below), and with the fix re-applied the same command → exit 0,
+4 passed.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → **first
+  attempt exit 101**: `needless_character_iteration` on
+  `token.chars().any(|c| !c.is_ascii())`. Rewritten to `!token.is_ascii()`
+  (identical semantics); re-run → exit 0.
+- `cargo test --locked -p codegraph-rs --test unicode_search_cli` → exit 0,
+  4 passed.
+- `cargo test --locked -p codegraph-graph` → exit 0 (all targets green,
+  including the pre-existing `extract_search_terms` / `score_path_relevance` /
+  `normalize_name_token` unit tests, which were NOT modified).
+- `cargo test --locked -p codegraph-mcp` → exit 0, including
+  `rmcp_parity` (15 golden MCP fixtures) and `golden_mcp`.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+
+`lsp_diagnostics` was attempted on `scoring.rs` and again refused this worktree
+(`LSP file path must be inside request cwd`); locked Cargo clippy/test is the
+honest fallback and no LSP-clean result is claimed. No dependency, version or
+`Cargo.lock` byte changed. No Windows/MSVC runtime validation is claimed — this
+work ran on Linux only.

From b20260aed65cbcdea99b82dd720f69a268d18f63 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 10:48:08 +0800
Subject: [PATCH 51/91] fix(retrieval): seed multi-segment field-name queries
 with their segment-boundary definers

---
 .../tests/multi_hump_query_cli.rs             | 247 ++++++++++++++++++
 crates/codegraph-graph/src/query/mod.rs       |  73 ++++++
 crates/codegraph-graph/src/query/scoring.rs   | 111 ++++++++
 crates/codegraph-store/src/queries.rs         |  83 ++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 157 +++++++++++
 5 files changed, 671 insertions(+)
 create mode 100644 crates/codegraph-cli/tests/multi_hump_query_cli.rs

diff --git a/crates/codegraph-cli/tests/multi_hump_query_cli.rs b/crates/codegraph-cli/tests/multi_hump_query_cli.rs
new file mode 100644
index 0000000..589b45c
--- /dev/null
+++ b/crates/codegraph-cli/tests/multi_hump_query_cli.rs
@@ -0,0 +1,247 @@
+//! Upstream `1de7e8f` (#1319) — a multi-hump field-name query must reach the
+//! symbol that DEFINES it, even when the stored name segments differently from
+//! the query's humps.
+//!
+//! Drives the real `codegraph` binary against a temp project holding, for each
+//! query shape, three files:
+//!   * the DEFINER — a callable whose name embeds the query at a hump boundary
+//!     (`profileInfo` → `getProfileInfoV2`);
+//!   * a PROSE decoy — a constant whose signature/docstring merely MENTIONS the
+//!     query words, which is what today's FTS actually returns;
+//!   * a NAME decoy — a callable whose lowercase name CONTAINS the query's run
+//!     but at no hump boundary (`xxprofileinfoxx`), which a naive `LIKE
+//!     %needle%` would bind to.
+//!
+//! The definer must be returned and must outrank both decoys; the name decoy
+//! must not be returned at all.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-multi-hump-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(cwd: &Path, args: &[&str]) -> Run {
+    let output = Command::new(bin())
+        .args(args)
+        .current_dir(cwd)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+fn write_project(root: &Path) {
+    let src = root.join("src");
+    std::fs::create_dir_all(&src).unwrap();
+
+    std::fs::write(
+        src.join("profileController.js"),
+        "function getProfileInfoV2(userId) {\n  return { userId };\n}\n\n\
+         function updateUserProfileIdMapping(a, b) {\n  return [a, b];\n}\n\n\
+         function loadOrderStateSnapshot() {\n  return 0;\n}\n\n\
+         module.exports = {\n  getProfileInfoV2,\n  updateUserProfileIdMapping,\n  loadOrderStateSnapshot,\n};\n",
+    )
+    .unwrap();
+
+    std::fs::write(
+        src.join("prose_decoy.js"),
+        "const NOTES = \"profileInfo userProfileId orderState profile info user order state\";\n\
+         function auditLog(msg) {\n  return NOTES + msg;\n}\n\
+         module.exports = { auditLog };\n",
+    )
+    .unwrap();
+
+    std::fs::write(
+        src.join("name_decoy.js"),
+        "function xxprofileinfoxx() {\n  return 0;\n}\n\n\
+         function xxuserprofileidxx() {\n  return 1;\n}\n\n\
+         function xxorderstatexx() {\n  return 2;\n}\n\n\
+         module.exports = { xxprofileinfoxx, xxuserprofileidxx, xxorderstatexx };\n",
+    )
+    .unwrap();
+}
+
+fn indexed_project(dir: &TestDir) -> PathBuf {
+    let project = dir.path().join("proj");
+    std::fs::create_dir_all(&project).unwrap();
+    write_project(&project);
+    let run = run_in(dir.path(), &["init", project.to_str().unwrap()]);
+    assert!(run.ok, "init failed: {} {}", run.stdout, run.stderr);
+    project
+}
+
+/// `(name, filePath)` for every hit, in the order the CLI ranked them.
+fn ranked(project: &Path, query: &str) -> Vec<(String, String)> {
+    let p = project.to_str().unwrap();
+    let run = run_in(project, &["query", query, "-p", p, "--json"]);
+    assert!(
+        run.ok,
+        "query {query:?} must succeed: {} {}",
+        run.stdout, run.stderr
+    );
+    let v: serde_json::Value = serde_json::from_str(&run.stdout)
+        .unwrap_or_else(|e| panic!("query {query:?} must emit JSON ({e}): {}", run.stdout));
+    v.as_array()
+        .expect("query --json is an array")
+        .iter()
+        .map(|r| {
+            (
+                r["node"]["name"].as_str().unwrap_or_default().to_string(),
+                r["node"]["filePath"]
+                    .as_str()
+                    .unwrap_or_default()
+                    .to_string(),
+            )
+        })
+        .collect()
+}
+
+/// `(query, definer, name-decoy)` — camelCase, snake_case and PascalCase forms of
+/// the same field names, so the fix cannot pass by handling only the one shape
+/// it was written for.
+const CASES: &[(&str, &str, &str)] = &[
+    ("profileInfo", "getProfileInfoV2", "xxprofileinfoxx"),
+    ("profile_info", "getProfileInfoV2", "xxprofileinfoxx"),
+    ("ProfileInfo", "getProfileInfoV2", "xxprofileinfoxx"),
+    (
+        "userProfileId",
+        "updateUserProfileIdMapping",
+        "xxuserprofileidxx",
+    ),
+    (
+        "user_profile_id",
+        "updateUserProfileIdMapping",
+        "xxuserprofileidxx",
+    ),
+    ("orderState", "loadOrderStateSnapshot", "xxorderstatexx"),
+];
+
+#[test]
+fn multi_hump_field_name_query_reaches_its_definer_not_a_prose_or_name_decoy() {
+    let dir = TestDir::new("definer");
+    let project = indexed_project(&dir);
+
+    let mut failures: Vec<String> = Vec::new();
+    for (query, definer, name_decoy) in CASES {
+        let hits = ranked(&project, query);
+        let pos = |name: &str| hits.iter().position(|(n, _)| n == name);
+        match pos(definer) {
+            None => failures.push(format!(
+                "query {query:?}: definer {definer} ABSENT; ranking was {hits:?}"
+            )),
+            Some(d) => {
+                if let Some(other) = hits
+                    .iter()
+                    .position(|(n, _)| n != definer)
+                    .filter(|other| *other < d)
+                {
+                    failures.push(format!(
+                        "query {query:?}: {} outranked definer {definer}; ranking was {hits:?}",
+                        hits[other].0
+                    ));
+                }
+            }
+        }
+        if let Some(bad) = pos(name_decoy) {
+            failures.push(format!(
+                "query {query:?}: non-hump-boundary namesake {name_decoy} must not be returned (at {bad}); ranking was {hits:?}"
+            ));
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "multi-hump field-name queries must reach their definers:\n{}",
+        failures.join("\n")
+    );
+}
+
+/// A query that IS an exact symbol name keeps binding to that symbol — the
+/// infix fallback must never displace an exact definition.
+#[test]
+fn exact_symbol_query_is_unaffected_by_the_infix_fallback() {
+    let dir = TestDir::new("exact");
+    let project = indexed_project(&dir);
+
+    for name in ["getProfileInfoV2", "updateUserProfileIdMapping", "auditLog"] {
+        let hits = ranked(&project, name);
+        assert_eq!(
+            hits.first().map(|(n, _)| n.as_str()),
+            Some(name),
+            "exact symbol {name:?} must still rank first, got {hits:?}"
+        );
+    }
+}
+
+/// A bare single-word query must NOT trigger the multi-hump fallback: it has no
+/// humps, so widening it would resurrect the natural-language false positives
+/// the stop-word guard exists to prevent.
+#[test]
+fn single_word_query_does_not_pull_in_infix_namesakes() {
+    let dir = TestDir::new("single");
+    let project = indexed_project(&dir);
+
+    for word in ["profile", "state"] {
+        let hits = ranked(&project, word);
+        assert!(
+            !hits.iter().any(|(n, _)| n.starts_with("xx")),
+            "single-word query {word:?} must not reach infix namesakes, got {hits:?}"
+        );
+    }
+}
+
+/// Ranking must be a pure function of the index: repeated identical queries
+/// answer identically.
+#[test]
+fn multi_hump_ranking_is_deterministic_across_repeated_queries() {
+    let dir = TestDir::new("determinism");
+    let project = indexed_project(&dir);
+    let first = ranked(&project, "userProfileId");
+    for _ in 0..4 {
+        assert_eq!(
+            ranked(&project, "userProfileId"),
+            first,
+            "repeated identical queries must return an identical ranking"
+        );
+    }
+}
diff --git a/crates/codegraph-graph/src/query/mod.rs b/crates/codegraph-graph/src/query/mod.rs
index e18859f..7d678f7 100644
--- a/crates/codegraph-graph/src/query/mod.rs
+++ b/crates/codegraph-graph/src/query/mod.rs
@@ -9,6 +9,17 @@ use codegraph_store::queries::SearchResult;
 
 pub use parser::{ParsedQuery, bounded_edit_distance, parse_query};
 
+/// #1319 infix-seeding bounds: how many callable candidates the store returns
+/// per token, and how many survive the segment-boundary filter into the result
+/// set. Both are hard caps so a hot substring can never flood the ranking.
+const INFIX_CANDIDATE_CAP: i64 = 50;
+const INFIX_SEED_CAP: usize = 3;
+
+/// Base score for an infix-seeded definer. Deliberately small: the definer earns
+/// its rank from the `kind_bonus` + `name_match_bonus` pass that follows, so it
+/// can never outrank a genuine exact-name hit.
+const INFIX_SEED_SCORE: f64 = 1.0;
+
 #[derive(Debug, Clone, Default)]
 pub struct SearchOptions {
     pub kinds: Vec<NodeKind>,
@@ -92,6 +103,8 @@ pub fn search_nodes(
         }
     }
 
+    seed_multi_segment_definers(store, query, &kinds, &mut results)?;
+
     if !results.is_empty() && (!text.is_empty() || !query.is_empty()) {
         let scoring_query = if !text.is_empty() { &text } else { query };
         for result in &mut results {
@@ -135,6 +148,66 @@ fn sort_by_score_desc(results: &mut [SearchResult]) {
     });
 }
 
+/// Multi-hump field-name seeding (upstream `1de7e8f` #1319).
+///
+/// A query token that names a multi-SEGMENT field (`userProfileId`,
+/// `user_profile_id`, `ProfileInfo`) but matches no symbol EXACTLY is seeded
+/// with the callables that DEFINE it — the ones whose own segments contain the
+/// query's segment run contiguously. Scoped to multi-segment tokens so the
+/// natural-language guard on bare words is untouched, and applied only when the
+/// token is not already an exact symbol name so exact matches always win.
+///
+/// A candidate whose name merely CONTAINS the lowercase run without a segment
+/// boundary (`xxprofileinfoxx`) is rejected: a silent miss beats a wrong answer.
+fn seed_multi_segment_definers(
+    store: &Store,
+    query: &str,
+    kinds: &[NodeKind],
+    results: &mut Vec<SearchResult>,
+) -> rusqlite::Result<()> {
+    let mut existing: HashSet<String> = results.iter().map(|r| r.node.id.clone()).collect();
+    for token in query.split_whitespace() {
+        if !scoring::is_multi_segment_identifier(token) {
+            continue;
+        }
+        if results.iter().any(|r| r.node.name == token) {
+            continue;
+        }
+        if !store.nodes_by_lower_name(&token.to_lowercase())?.is_empty() {
+            continue;
+        }
+        let needle: String = token
+            .chars()
+            .filter(|c| c.is_alphanumeric())
+            .collect::<String>()
+            .to_lowercase();
+        if needle.is_empty() {
+            continue;
+        }
+        let mut seeded = 0usize;
+        for node in store.callable_nodes_by_name_infix(&needle, INFIX_CANDIDATE_CAP)? {
+            if seeded >= INFIX_SEED_CAP {
+                break;
+            }
+            if !kinds.is_empty() && !kinds.contains(&node.kind) {
+                continue;
+            }
+            if !scoring::name_segments_contain_run(&node.name, token) {
+                continue;
+            }
+            if !existing.insert(node.id.clone()) {
+                continue;
+            }
+            results.push(SearchResult {
+                node,
+                score: INFIX_SEED_SCORE,
+            });
+            seeded += 1;
+        }
+    }
+    Ok(())
+}
+
 fn search_nodes_fuzzy(
     store: &Store,
     text: &str,
diff --git a/crates/codegraph-graph/src/query/scoring.rs b/crates/codegraph-graph/src/query/scoring.rs
index b08ba08..ca1cab1 100644
--- a/crates/codegraph-graph/src/query/scoring.rs
+++ b/crates/codegraph-graph/src/query/scoring.rs
@@ -660,6 +660,62 @@ pub fn kind_bonus(kind: NodeKind) -> f64 {
     }
 }
 
+/// Split an identifier into its lowercase word segments (#1319).
+///
+/// Non-alphanumerics separate runs (`user_profile_id`, `order-state`,
+/// `file.name`); inside a run, a lowercase/digit→uppercase transition is a
+/// camelCase hump (`orderState` → order|state) and an uppercase followed by
+/// uppercase+lowercase closes an acronym (`HTMLParser` → html|parser). Digits
+/// stay glued to their word (`getInfoV2` → get|info|v2).
+pub fn identifier_segments(raw: &str) -> Vec<String> {
+    let mut out: Vec<String> = Vec::new();
+    for run in raw.split(|c: char| !c.is_alphanumeric()) {
+        if run.is_empty() {
+            continue;
+        }
+        let chars: Vec<char> = run.chars().collect();
+        let mut current = String::new();
+        for i in 0..chars.len() {
+            if i > 0 {
+                let prev = chars[i - 1];
+                let cur = chars[i];
+                let hump = (prev.is_lowercase() || prev.is_numeric()) && cur.is_uppercase();
+                let acronym = prev.is_uppercase()
+                    && cur.is_uppercase()
+                    && chars.get(i + 1).is_some_and(|n| n.is_lowercase());
+                if (hump || acronym) && !current.is_empty() {
+                    out.push(std::mem::take(&mut current).to_lowercase());
+                }
+            }
+            current.push(chars[i]);
+        }
+        if !current.is_empty() {
+            out.push(current.to_lowercase());
+        }
+    }
+    out
+}
+
+/// Whether a query token names a MULTI-SEGMENT field (#1319): `userProfileId`,
+/// `user_profile_id`, `ProfileInfo` — but not a bare word like `profile`, which
+/// must keep its natural-language stop-word guard.
+pub fn is_multi_segment_identifier(token: &str) -> bool {
+    identifier_segments(token).len() >= 2
+}
+
+/// Whether `name`'s segments CONTAIN the query's segment run contiguously
+/// (#1319) — the hump-boundary filter that separates a real definer
+/// (`getProfileInfoV2` for `profileInfo`) from an incidental namesake
+/// (`xxprofileinfoxx`, one unsegmented word).
+pub fn name_segments_contain_run(name: &str, query: &str) -> bool {
+    let want = identifier_segments(query);
+    if want.is_empty() {
+        return false;
+    }
+    let have = identifier_segments(name);
+    have.windows(want.len()).any(|w| w == want.as_slice())
+}
+
 pub fn is_distinctive_identifier(token: &str) -> bool {
     if token.is_empty() {
         return false;
@@ -892,6 +948,61 @@ mod tests {
         assert_eq!(kind_bonus(NodeKind::Interface), 9.0);
     }
 
+    #[test]
+    fn identifier_segments_splits_humps_snake_and_acronyms() {
+        assert_eq!(
+            identifier_segments("userProfileId"),
+            ["user", "profile", "id"]
+        );
+        assert_eq!(
+            identifier_segments("user_profile_id"),
+            ["user", "profile", "id"]
+        );
+        assert_eq!(identifier_segments("order-state"), ["order", "state"]);
+        assert_eq!(identifier_segments("HTMLParser"), ["html", "parser"]);
+        assert_eq!(identifier_segments("getInfoV2"), ["get", "info", "v2"]);
+        assert_eq!(identifier_segments("plain"), ["plain"]);
+        assert!(identifier_segments("").is_empty());
+        assert!(identifier_segments("__").is_empty());
+    }
+
+    #[test]
+    fn is_multi_segment_identifier_only_for_multi_segment_tokens() {
+        assert!(is_multi_segment_identifier("userProfileId"));
+        assert!(is_multi_segment_identifier("user_profile_id"));
+        assert!(is_multi_segment_identifier("ProfileInfo"));
+        assert!(!is_multi_segment_identifier("profile"));
+        assert!(!is_multi_segment_identifier("PROFILE"));
+        assert!(!is_multi_segment_identifier(""));
+    }
+
+    #[test]
+    fn name_segments_contain_run_requires_a_segment_boundary() {
+        // A real definer: the query's segment run appears contiguously.
+        assert!(name_segments_contain_run("getProfileInfoV2", "profileInfo"));
+        assert!(name_segments_contain_run(
+            "getProfileInfoV2",
+            "profile_info"
+        ));
+        assert!(name_segments_contain_run(
+            "updateUserProfileIdMapping",
+            "userProfileId"
+        ));
+        assert!(name_segments_contain_run("load_order_state", "orderState"));
+        // An incidental namesake: the lowercase run is there, the boundary is not.
+        assert!(!name_segments_contain_run("xxprofileinfoxx", "profileInfo"));
+        assert!(!name_segments_contain_run(
+            "xxuserprofileidxx",
+            "userProfileId"
+        ));
+        // Non-contiguous segments are not a match either.
+        assert!(!name_segments_contain_run(
+            "profileOtherInfo",
+            "profileInfo"
+        ));
+        assert!(!name_segments_contain_run("anything", ""));
+    }
+
     #[test]
     fn is_distinctive_identifier_rules() {
         assert!(!is_distinctive_identifier(""));
diff --git a/crates/codegraph-store/src/queries.rs b/crates/codegraph-store/src/queries.rs
index 0a71fc8..341bf26 100644
--- a/crates/codegraph-store/src/queries.rs
+++ b/crates/codegraph-store/src/queries.rs
@@ -450,6 +450,41 @@ impl Store {
         rows.collect()
     }
 
+    /// Callable definitions whose name CONTAINS `needle` as a substring, fetched
+    /// as a SEPARATE batch from the FTS/LIKE ladder (upstream `1de7e8f` #1319
+    /// "kind whitelist" — hot single-word terms must not crowd definers out of
+    /// the length-ordered batch).
+    ///
+    /// `needle` is matched lowercase against both `lower(name)` and its
+    /// separator-stripped form, so a `user_profile_id` query reaches a
+    /// `userProfileId`-humped name and a `userProfileId` query reaches a
+    /// `user_profile_id`-separated one. Substring containment is only the
+    /// CANDIDATE gate; the caller still applies the segment-boundary filter, so
+    /// an incidental namesake never becomes a match. `ORDER BY` is fully
+    /// specified — shortest name first, then name/path/line — so the candidate
+    /// order never depends on SQLite's incidental row order.
+    pub fn callable_nodes_by_name_infix(
+        &self,
+        needle: &str,
+        limit: i64,
+    ) -> rusqlite::Result<Vec<Node>> {
+        let pattern = format!("%{}%", needle.to_lowercase());
+        let mut stmt = self.conn.prepare(
+            r#"
+            SELECT * FROM nodes
+            WHERE kind IN ('function', 'method', 'component')
+              AND (
+                lower(name) LIKE ?
+                OR replace(replace(replace(lower(name), '_', ''), '-', ''), '.', '') LIKE ?
+              )
+            ORDER BY length(name) ASC, name ASC, file_path ASC, start_line ASC
+            LIMIT ?
+            "#,
+        )?;
+        let rows = stmt.query_map(params![pattern, pattern, limit], row_to_node)?;
+        rows.collect()
+    }
+
     /// Ports `getAllNodeNames` from `upstream db/queries.ts:1655-1661`.
     /// `SELECT DISTINCT name FROM nodes` — the candidate name set for fuzzy fallback.
     pub fn all_node_names(&self) -> rusqlite::Result<Vec<String>> {
@@ -2124,6 +2159,54 @@ mod tests {
         assert_eq!(names, vec!["shared".to_string(), "unique".to_string()]);
     }
 
+    #[test]
+    fn callable_infix_returns_callables_only_shortest_first_and_folds_separators() {
+        let mut store = store("callable-infix");
+        let mut cls = node("class:holder", "UserProfileIdHolder", "src/holder.rs");
+        cls.kind = NodeKind::Class;
+        let mut var = node("variable:v", "userProfileId", "src/var.rs");
+        var.kind = NodeKind::Variable;
+        store
+            .upsert_nodes(&[
+                node("function:long", "updateUserProfileIdMapping", "src/b.rs"),
+                node("function:short", "userProfileId2", "src/a.rs"),
+                node("function:snake", "read_user_profile_id", "src/c.rs"),
+                node("function:other", "unrelated", "src/d.rs"),
+                cls,
+                var,
+            ])
+            .unwrap();
+
+        let hits = store
+            .callable_nodes_by_name_infix("userprofileid", 50)
+            .unwrap();
+        let names: Vec<&str> = hits.iter().map(|n| n.name.as_str()).collect();
+        assert_eq!(
+            names,
+            vec![
+                "userProfileId2",
+                "read_user_profile_id",
+                "updateUserProfileIdMapping"
+            ],
+            "callables only, shortest name first; the separator-stripped form matches snake_case"
+        );
+
+        assert!(
+            store
+                .callable_nodes_by_name_infix("userprofileid", 1)
+                .unwrap()
+                .len()
+                == 1,
+            "the limit is honoured"
+        );
+        assert!(
+            store
+                .callable_nodes_by_name_infix("nosuchneedle", 50)
+                .unwrap()
+                .is_empty()
+        );
+    }
+
     #[test]
     fn distinct_non_file_node_names_omits_file_and_import() {
         let mut store = store("distinct-non-file");
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 38fa3ab..cdd708f 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4720,3 +4720,160 @@ clippy follow-up below), and with the fix re-applied the same command → exit 0
 honest fallback and no LSP-clean result is claimed. No dependency, version or
 `Cargo.lock` byte changed. No Windows/MSVC runtime validation is claimed — this
 work ran on Linux only.
+
+---
+
+## Batch A2 — multi-hump field-name queries reach their definers (2026-07-28)
+
+Ports upstream `1de7e8f` (#1319). Base for this entry: `8c80331` (Batch A1). One
+commit: a new store query, the query-layer seeding pass that consumes it, and a
+CLI integration test.
+
+### Red (documented, with the actual wrong output)
+
+New test `crates/codegraph-cli/tests/multi_hump_query_cli.rs`, driving the REAL
+binary (`init`, then `query --json`). The fixture holds, per query shape, three
+files:
+
+- the DEFINER `src/profileController.js` — `getProfileInfoV2`,
+  `updateUserProfileIdMapping`, `loadOrderStateSnapshot`;
+- a PROSE decoy `src/prose_decoy.js` — a constant whose signature/docstring
+  merely MENTIONS the words (`const NOTES = "profileInfo userProfileId …"`);
+- a NAME decoy `src/name_decoy.js` — callables whose lowercase names CONTAIN the
+  query run at NO segment boundary (`xxprofileinfoxx`, `xxuserprofileidxx`,
+  `xxorderstatexx`). This is the required decoy: a naive `LIKE %needle%` binds
+  to it, and would do so with a SHORTER name, i.e. it would win.
+
+`cargo test --locked -p codegraph-rs --test multi_hump_query_cli` → exit 101.
+Verbatim:
+
+```text
+multi-hump field-name queries must reach their definers:
+query "profileInfo": definer getProfileInfoV2 ABSENT; ranking was [("NOTES", "src/prose_decoy.js")]
+query "profile_info": definer getProfileInfoV2 ABSENT; ranking was [("NOTES", "src/prose_decoy.js")]
+query "ProfileInfo": definer getProfileInfoV2 ABSENT; ranking was [("NOTES", "src/prose_decoy.js")]
+query "userProfileId": definer updateUserProfileIdMapping ABSENT; ranking was [("NOTES", "src/prose_decoy.js")]
+query "user_profile_id": definer updateUserProfileIdMapping ABSENT; ranking was []
+query "orderState": definer loadOrderStateSnapshot ABSENT; ranking was [("NOTES", "src/prose_decoy.js")]
+```
+
+The definer was not merely mis-ranked, it was ABSENT: FTS5 matches whole tokens
+with a trailing prefix, so `"userProfileId"*` matches the STRING inside `NOTES`
+but never the INFIX inside `updateUserProfileIdMapping`. `user_profile_id`
+returned nothing at all. Ground truth from `sqlite3`, confirming the definers
+were in the index the whole time:
+
+```text
+sqlite> select nodes.name, nodes.file_path from nodes_fts join nodes
+        on nodes_fts.id=nodes.id where nodes_fts match '"profileInfo"*';
+NOTES|src/unrelated.js
+
+sqlite> select kind,name,file_path from nodes where lower(name) like '%userprofileid%';
+function|xxuserprofileidxx|src/name_decoy.js
+function|updateUserProfileIdMapping|src/profileController.js
+```
+
+That second row pair is exactly why substring containment alone is NOT the fix.
+
+### Green (minimal)
+
+Three pieces, no new dependency, no schema change:
+
+1. `crates/codegraph-store/src/queries.rs` — new
+   `callable_nodes_by_name_infix(needle, limit)`: callables only
+   (`function`/`method`/`component`, upstream's "kind whitelist" so hot
+   single-word terms can't crowd definers out of the length-ordered batch),
+   matching `lower(name) LIKE %needle%` OR the separator-stripped form (so
+   `user_profile_id` reaches `userProfileId` and vice-versa), ordered
+   `length(name), name, file_path, start_line` — fully specified, never
+   SQLite's incidental row order.
+2. `crates/codegraph-graph/src/query/scoring.rs` — `identifier_segments`,
+   `is_multi_segment_identifier`, `name_segments_contain_run`: the hump/acronym/
+   separator splitter and the CONTIGUOUS-segment-run filter.
+3. `crates/codegraph-graph/src/query/mod.rs` — `seed_multi_segment_definers`,
+   called after the exact-name supplement and before rescoring. It fires ONLY
+   for a multi-segment token that is not already an exact symbol name
+   (`nodes_by_lower_name` empty), caps candidates at 50 and seeds at most 3 per
+   token, and admits a candidate only when its own segments contain the query's
+   segment run contiguously.
+
+The boundary filter is what rejects `xxprofileinfoxx`: following the accepted
+Batch C precedent, when a candidate cannot be shown to DEFINE the queried field,
+nothing is emitted rather than a guess. A silent miss beats a wrong answer.
+
+### A rejected first attempt, recorded
+
+The first Green also added `.then_with(|| a.node.id.cmp(&b.node.id))` as a
+tie-break in `sort_by_score_desc`. That made
+`cargo test --locked -p codegraph-graph` fail (exit 101) on the pre-existing
+golden search oracle:
+
+```text
+case `filter_only_kind_method` query `kind:method`: id ordering mismatch
+ got:  [3c01f33…, 89ae38f0…, d9785bc2…, f501ba98…]
+ want: [d9785bc2…, 3c01f33…, f501ba98…, 89ae38f0…]
+```
+
+All four score exactly `11`, and the golden order is the upstream's
+`ORDER BY name` (`__init__`, `greet`, `increment`, `value`) preserved by Rust's
+STABLE sort. An id tie-break would have replaced a meaningful order with a hash
+order. The tie-break was REVERTED; determinism is instead guaranteed by the
+fully-specified `ORDER BY` in the new store query plus the existing stable sort,
+and is asserted by `multi_hump_ranking_is_deterministic_across_repeated_queries`.
+The golden was NOT touched.
+
+### Golden row delta
+
+None. `git diff --stat 29f635b..HEAD -- reference/golden/` → EMPTY;
+`git status --short reference/golden/` → empty.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed**.
+
+### Negative control, EXECUTED
+
+`git stash push` of the three production files (test kept) →
+`cargo test --locked -p codegraph-rs --test multi_hump_query_cli` → exit 101,
+exactly the six Red lines above. `git stash pop` restored them; restored SHA-256:
+
+- `crates/codegraph-graph/src/query/mod.rs`
+  `fed17893c2ea1f1ff6c7778bf06f0742c08a1bb82cb0002742e3f213ba5dcadd`
+- `crates/codegraph-graph/src/query/scoring.rs`
+  `af689c1df8224cb11909bd33048a798bdf34345e438d9e75b89ce424314e32bb`
+- `crates/codegraph-store/src/queries.rs`
+  `2b499860f476cdb1cb7245504928b4c78790aa7a2bf8cdd4bb5e63f18b39d2d2`
+
+With the fix re-applied the same command → exit 0, 4 passed.
+
+### Post-fix behaviour on the real binary
+
+```text
+$ codegraph query "profileInfo" --json
+  39.000 function getProfileInfoV2           src/profileController.js
+   4.736 constant NOTES                      src/unrelated.js
+$ codegraph query "user_profile_id" --json
+  39.000 function updateUserProfileIdMapping src/profileController.js
+```
+
+The name decoys are absent from both.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → **first
+  attempt exit 101** (`doc_lazy_continuation` on the new test's module doc list);
+  a blank `//!` line was added and re-run → exit 0.
+- `cargo test --locked -p codegraph-rs --test multi_hump_query_cli` → exit 0,
+  4 passed.
+- `cargo test --locked -p codegraph-store --lib callable_infix…` → exit 0.
+- `cargo test --locked -p codegraph-graph --lib identifier_segments…` → exit 0.
+- `cargo test --locked -p codegraph-graph -p codegraph-store -p codegraph-mcp`
+  → exit 0 (after the tie-break revert above).
+- `cargo test --locked -p codegraph-rs --test multi_hump_query_cli --test
+unicode_search_cli --test explore_node_cli --test cli_commands` → exit 0.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+
+`lsp_diagnostics` again refused this worktree (`LSP file path must be inside
+request cwd`); locked Cargo clippy/test is the honest fallback and no LSP-clean
+result is claimed. No dependency, version or `Cargo.lock` byte changed. No
+Windows/MSVC runtime validation is claimed — this work ran on Linux only.

From efc6fcd7f25f4cc6d7ecb938ff00ef0e74aab48e Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 10:56:20 +0800
Subject: [PATCH 52/91] fix(graph): guard find_path with an enqueue-once set
 and expose its queue stats

---
 crates/codegraph-graph/src/graph/mod.rs      |  51 +++-
 crates/codegraph-graph/tests/enqueue_once.rs | 237 +++++++++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md    | 118 +++++++++
 3 files changed, 401 insertions(+), 5 deletions(-)
 create mode 100644 crates/codegraph-graph/tests/enqueue_once.rs

diff --git a/crates/codegraph-graph/src/graph/mod.rs b/crates/codegraph-graph/src/graph/mod.rs
index 5a1d0ec..b49cb0c 100644
--- a/crates/codegraph-graph/src/graph/mod.rs
+++ b/crates/codegraph-graph/src/graph/mod.rs
@@ -100,6 +100,18 @@ pub struct PathStep {
     pub edge: Option<Edge>,
 }
 
+/// Queue accounting for one [`GraphTraverser::find_path_instrumented`] BFS
+/// (#1359). `enqueued` counts pushes, so a work item enqueued more than once is
+/// directly observable from a test; `duplicate_dequeues` counts items that were
+/// already `visited` when popped, i.e. wasted pushes that survived to the front
+/// of the queue.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
+pub struct PathSearchStats {
+    pub enqueued: usize,
+    pub dequeued: usize,
+    pub duplicate_dequeues: usize,
+}
+
 /// Sentinel-prefix that L3's `godot_script` resolver stamps onto the
 /// `reference_name` of a computed (statically-unconfirmable) Godot call-site.
 /// Mirrors `codegraph_resolve::frameworks::godot_script::DYNAMIC_PREFIX`;
@@ -775,14 +787,37 @@ impl<'store> GraphTraverser<'store> {
         to_id: &str,
         edge_kinds: &[EdgeKind],
     ) -> rusqlite::Result<Option<Vec<PathStep>>> {
+        Ok(self.find_path_instrumented(from_id, to_id, edge_kinds)?.0)
+    }
+
+    /// [`GraphTraverser::find_path`] plus the [`PathSearchStats`] its BFS
+    /// accumulated (#1359).
+    ///
+    /// Enqueue counts are not observable from the returned path, so the
+    /// enqueue-once guard cannot be regression-tested through `find_path`
+    /// alone; this is the seam that makes it assertable instead of a log line
+    /// someone has to read.
+    pub fn find_path_instrumented(
+        &self,
+        from_id: &str,
+        to_id: &str,
+        edge_kinds: &[EdgeKind],
+    ) -> rusqlite::Result<(Option<Vec<PathStep>>, PathSearchStats)> {
+        let mut stats = PathSearchStats::default();
         let Some(from_node) = self.store.node_by_id(from_id)? else {
-            return Ok(None);
+            return Ok((None, stats));
         };
         if self.store.node_by_id(to_id)?.is_none() {
-            return Ok(None);
+            return Ok((None, stats));
         }
 
         let mut visited = HashSet::new();
+        // #1359: `visited` is set at DEQUEUE, so it cannot stop a fan-in layer
+        // from pushing the same target once per predecessor — up to k² entries
+        // (each carrying a cloned path) for a k-wide layer into k shared
+        // targets. `enqueued` is the separate enqueue-once guard, mirroring
+        // `traverse_bfs`'s #1090 fix, and is seeded with the start node.
+        let mut enqueued: HashSet<String> = HashSet::from([from_id.to_string()]);
         let mut queue: VecDeque<(String, Vec<PathStep>)> = VecDeque::new();
         queue.push_back((
             from_id.to_string(),
@@ -791,12 +826,15 @@ impl<'store> GraphTraverser<'store> {
                 edge: None,
             }],
         ));
+        stats.enqueued += 1;
 
         while let Some((node_id, path)) = queue.pop_front() {
+            stats.dequeued += 1;
             if node_id == to_id {
-                return Ok(Some(path));
+                return Ok((Some(path), stats));
             }
             if visited.contains(&node_id) {
+                stats.duplicate_dequeues += 1;
                 continue;
             }
             visited.insert(node_id.clone());
@@ -808,12 +846,13 @@ impl<'store> GraphTraverser<'store> {
             let want_ids: Vec<String> = outgoing
                 .iter()
                 .map(|e| e.target.clone())
-                .filter(|id| !visited.contains(id))
+                .filter(|id| !visited.contains(id) && !enqueued.contains(id))
                 .collect();
             let next_nodes = self.store.nodes_by_ids(&want_ids)?;
 
             for edge in outgoing {
                 if !visited.contains(&edge.target)
+                    && !enqueued.contains(&edge.target)
                     && let Some(next_node) = next_nodes.get(&edge.target)
                 {
                     let mut next_path = path.clone();
@@ -821,12 +860,14 @@ impl<'store> GraphTraverser<'store> {
                         node: next_node.clone(),
                         edge: Some(edge.clone()),
                     });
+                    enqueued.insert(edge.target.clone());
                     queue.push_back((edge.target.clone(), next_path));
+                    stats.enqueued += 1;
                 }
             }
         }
 
-        Ok(None)
+        Ok((None, stats))
     }
 
     /// Ports `getAncestors` from `upstream graph/traversal.ts:615-645`.
diff --git a/crates/codegraph-graph/tests/enqueue_once.rs b/crates/codegraph-graph/tests/enqueue_once.rs
new file mode 100644
index 0000000..fdb18bb
--- /dev/null
+++ b/crates/codegraph-graph/tests/enqueue_once.rs
@@ -0,0 +1,237 @@
+//! Upstream #1359 — `find_path`'s BFS must enqueue each work item EXACTLY once.
+//!
+//! `traverse_bfs` got a separate `enqueued` guard in #1090; `find_path` did not.
+//! Its `visited` set is populated at DEQUEUE, so on a fan-in layer (k nodes all
+//! pointing into the same k targets — a shared-helper hub, common in real call
+//! graphs) the same target is pushed once per predecessor, up to k² pushes for
+//! that transition, each carrying a cloned path array.
+//!
+//! The shortest path itself stays correct, so the defect is invisible from
+//! `find_path`'s return value. These tests assert on
+//! `find_path_instrumented`'s queue accounting instead, which is why the
+//! instrumentation is part of the fix rather than a log line.
+
+use codegraph_core::types::{Edge, EdgeKind, Language, Node, NodeKind};
+use codegraph_graph::graph::GraphTraverser;
+use codegraph_store::Store;
+
+fn temp_db_path(label: &str) -> std::path::PathBuf {
+    let mut path = std::env::temp_dir();
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_nanos();
+    path.push(format!(
+        "codegraph-enqueue-once-{label}-{}-{nanos}.db",
+        std::process::id()
+    ));
+    path
+}
+
+fn node(id: &str, name: &str) -> Node {
+    Node {
+        id: id.to_string(),
+        kind: NodeKind::Function,
+        name: name.to_string(),
+        qualified_name: name.to_string(),
+        file_path: "src/hub.ts".to_string(),
+        language: Language::TypeScript,
+        start_line: 1,
+        end_line: 2,
+        start_column: 0,
+        end_column: 0,
+        docstring: None,
+        signature: None,
+        visibility: None,
+        is_exported: false,
+        is_async: false,
+        is_static: false,
+        is_abstract: false,
+        decorators: Vec::new(),
+        type_parameters: Vec::new(),
+        return_type: None,
+        updated_at: 1,
+    }
+}
+
+fn edge(source: &str, target: &str) -> Edge {
+    Edge {
+        id: None,
+        source: source.to_string(),
+        target: target.to_string(),
+        kind: EdgeKind::Calls,
+        metadata: None,
+        line: Some(3),
+        col: Some(0),
+        provenance: None,
+    }
+}
+
+/// A fan-in graph: `root` → `mid0..mid{k-1}`, and EVERY mid → EVERY
+/// `sink0..sink{k-1}`. `target` hangs off `sink0` so the search must traverse
+/// the whole fan-in layer before finding it.
+fn fan_in_store(label: &str, k: usize) -> (Store, usize) {
+    let mut store = Store::open(&temp_db_path(label)).expect("open store");
+    let mut nodes = vec![
+        node("function:root", "root"),
+        node("function:target", "target"),
+    ];
+    for i in 0..k {
+        nodes.push(node(&format!("function:mid{i}"), &format!("mid{i}")));
+        nodes.push(node(&format!("function:sink{i}"), &format!("sink{i}")));
+    }
+    let reachable = nodes.len();
+    store.upsert_nodes(&nodes).expect("insert nodes");
+
+    let mut edges = Vec::new();
+    for i in 0..k {
+        edges.push(edge("function:root", &format!("function:mid{i}")));
+        for j in 0..k {
+            edges.push(edge(
+                &format!("function:mid{i}"),
+                &format!("function:sink{j}"),
+            ));
+        }
+    }
+    edges.push(edge("function:sink0", "function:target"));
+    store.insert_edges(&edges).expect("insert edges");
+    (store, reachable)
+}
+
+/// The enqueue-once contract: over a fan-in hub, the number of pushes must be
+/// bounded by the number of distinct nodes reached — never by the edge count.
+#[test]
+fn find_path_enqueues_each_work_item_exactly_once_over_a_fan_in_hub() {
+    let k = 8;
+    let (store, reachable) = fan_in_store("fanin", k);
+    let traverser = GraphTraverser::new(&store);
+
+    let (path, stats) = traverser
+        .find_path_instrumented("function:root", "function:target", &[EdgeKind::Calls])
+        .expect("find_path_instrumented");
+
+    assert!(path.is_some(), "the fan-in graph does contain a path");
+    assert!(
+        stats.enqueued <= reachable,
+        "each work item must be enqueued at most once: enqueued {} for {reachable} reachable nodes (fan-in edges: {}) — stats {stats:?}",
+        stats.enqueued,
+        k * k + k + 1
+    );
+    assert_eq!(
+        stats.duplicate_dequeues, 0,
+        "a correctly guarded queue never dequeues an already-visited item: {stats:?}"
+    );
+}
+
+/// The same contract on a diamond — the smallest shape that double-enqueues.
+#[test]
+fn find_path_does_not_re_enqueue_a_shared_successor_in_a_diamond() {
+    let mut store = Store::open(&temp_db_path("diamond")).expect("open store");
+    store
+        .upsert_nodes(&[
+            node("function:a", "a"),
+            node("function:b", "b"),
+            node("function:c", "c"),
+            node("function:d", "d"),
+            node("function:e", "e"),
+        ])
+        .expect("insert nodes");
+    store
+        .insert_edges(&[
+            edge("function:a", "function:b"),
+            edge("function:a", "function:c"),
+            edge("function:b", "function:d"),
+            edge("function:c", "function:d"),
+            edge("function:d", "function:e"),
+        ])
+        .expect("insert edges");
+
+    let traverser = GraphTraverser::new(&store);
+    let (path, stats) = traverser
+        .find_path_instrumented("function:a", "function:e", &[EdgeKind::Calls])
+        .expect("find_path_instrumented");
+
+    assert!(path.is_some(), "a→b→d→e exists");
+    assert_eq!(
+        stats.enqueued, 5,
+        "a, b, c, d, e — `d` is reachable from both b and c but must be enqueued ONCE: {stats:?}"
+    );
+    assert_eq!(stats.duplicate_dequeues, 0, "{stats:?}");
+}
+
+/// The guard must not change the ANSWER: the shortest path is still the shortest
+/// path, and an unreachable target is still unreachable.
+#[test]
+fn enqueue_once_guard_preserves_the_shortest_path_and_the_no_path_answer() {
+    let mut store = Store::open(&temp_db_path("shortest")).expect("open store");
+    store
+        .upsert_nodes(&[
+            node("function:a", "a"),
+            node("function:short", "short"),
+            node("function:long1", "long1"),
+            node("function:long2", "long2"),
+            node("function:z", "z"),
+            node("function:island", "island"),
+        ])
+        .expect("insert nodes");
+    store
+        .insert_edges(&[
+            edge("function:a", "function:long1"),
+            edge("function:long1", "function:long2"),
+            edge("function:long2", "function:z"),
+            edge("function:a", "function:short"),
+            edge("function:short", "function:z"),
+        ])
+        .expect("insert edges");
+
+    let traverser = GraphTraverser::new(&store);
+    let path = traverser
+        .find_path("function:a", "function:z", &[EdgeKind::Calls])
+        .expect("find_path")
+        .expect("a path exists");
+    let names: Vec<&str> = path.iter().map(|s| s.node.name.as_str()).collect();
+    assert_eq!(
+        names,
+        vec!["a", "short", "z"],
+        "the shortest of two routes must still win"
+    );
+
+    assert!(
+        traverser
+            .find_path("function:a", "function:island", &[EdgeKind::Calls])
+            .expect("find_path")
+            .is_none(),
+        "an unreachable target must still report no path"
+    );
+}
+
+/// A cycle must still terminate with the guard in place.
+#[test]
+fn enqueue_once_guard_still_terminates_on_a_cycle() {
+    let mut store = Store::open(&temp_db_path("cycle")).expect("open store");
+    store
+        .upsert_nodes(&[
+            node("function:a", "a"),
+            node("function:b", "b"),
+            node("function:c", "c"),
+            node("function:unreached", "unreached"),
+        ])
+        .expect("insert nodes");
+    store
+        .insert_edges(&[
+            edge("function:a", "function:b"),
+            edge("function:b", "function:c"),
+            edge("function:c", "function:a"),
+        ])
+        .expect("insert edges");
+
+    let traverser = GraphTraverser::new(&store);
+    let (path, stats) = traverser
+        .find_path_instrumented("function:a", "function:unreached", &[EdgeKind::Calls])
+        .expect("find_path_instrumented");
+    assert!(path.is_none(), "`unreached` has no incoming edge");
+    assert_eq!(
+        stats.enqueued, 3,
+        "a, b, c each enqueued once despite the cycle: {stats:?}"
+    );
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index cdd708f..5dabaf1 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4877,3 +4877,121 @@ unicode_search_cli --test explore_node_cli --test cli_commands` → exit 0.
 request cwd`); locked Cargo clippy/test is the honest fallback and no LSP-clean
 result is claimed. No dependency, version or `Cargo.lock` byte changed. No
 Windows/MSVC runtime validation is claimed — this work ran on Linux only.
+
+---
+
+## Batch A3 — `find_path` enqueues each work item exactly once, and a test can prove it (2026-07-28)
+
+Ports upstream issue #1359. Base for this entry: `b20260ae` (Batch A2). One
+commit, `codegraph-graph` traversal only.
+
+### The defect, quoted verbatim from the pre-fix source
+
+`crates/codegraph-graph/src/graph/mod.rs`, `find_path`:
+
+```rust
+let mut visited = HashSet::new();
+...
+    if visited.contains(&node_id) { continue; }
+    visited.insert(node_id.clone());
+...
+    for edge in outgoing {
+        if !visited.contains(&edge.target)
+            && let Some(next_node) = next_nodes.get(&edge.target)
+        {
+            let mut next_path = path.clone();
+            ...
+            queue.push_back((edge.target.clone(), next_path));
+        }
+    }
+```
+
+`visited` is inserted at DEQUEUE, so it cannot stop a fan-in layer from pushing
+the same target once per predecessor. `traverse_bfs` in the same file already
+carries the separate enqueue-once guard from #1090 (`unvisited_neighbor_ids` +
+the per-insertion check); `find_path` never got it. Each redundant push also
+clones the whole `Vec<PathStep>`, so wasted work and peak memory scale with EDGE
+count rather than node count.
+
+The shortest path stays correct — duplicates are dropped at dequeue — so the
+defect is INVISIBLE from `find_path`'s return value. That is why the
+instrumentation is part of the fix.
+
+### Green (minimal)
+
+- New `PathSearchStats { enqueued, dequeued, duplicate_dequeues }` and
+  `find_path_instrumented`, which returns the path AND the queue accounting.
+  `find_path` is now a thin wrapper over it, so its signature and behaviour for
+  every existing caller are unchanged.
+- An `enqueued: HashSet<String>` seeded with `from_id`, consulted in BOTH the
+  `want_ids` prefilter and the per-edge push condition, and inserted at push
+  time — mirroring `traverse_bfs`'s #1090 shape.
+
+Counters live in the instrumented function only; no logging was added, so the
+contract is assertable from a test rather than eyeballed in output.
+
+### Red (documented, with the actual wrong output)
+
+New test `crates/codegraph-graph/tests/enqueue_once.rs` (4 tests). Red was
+produced by stripping ONLY the guard (seeding `enqueued` empty, dropping both
+checks and the insert) while KEEPING the instrumentation seam, so the failure is
+a real assertion on real counts, not a compile error:
+
+```text
+running 4 tests
+test find_path_does_not_re_enqueue_a_shared_successor_in_a_diamond ... FAILED
+test find_path_enqueues_each_work_item_exactly_once_over_a_fan_in_hub ... FAILED
+
+assertion `left == right` failed: a, b, c, d, e — `d` is reachable from both b
+and c but must be enqueued ONCE: PathSearchStats { enqueued: 6, dequeued: 6,
+duplicate_dequeues: 1 }
+  left: 6
+ right: 5
+
+each work item must be enqueued at most once: enqueued 74 for 18 reachable
+nodes (fan-in edges: 73) — stats PathSearchStats { enqueued: 74, dequeued: 74,
+duplicate_dequeues: 56 }
+```
+
+`74` pushes for `18` reachable nodes — the count tracked the 73 fan-in edges, exactly
+the quadratic the issue describes. With the guard restored: `18` pushes,
+`0` duplicate dequeues (`cargo test --locked -p codegraph-graph --test
+enqueue_once` → exit 0, 4 passed).
+
+The other two tests pin what must NOT change and passed both ways: the shortest
+of two routes still wins, an unreachable target still reports no path, and a
+3-cycle still terminates with exactly 3 pushes.
+
+### Golden row delta
+
+None. `git diff --stat 29f635b..HEAD -- reference/golden/` → EMPTY.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed**. The oracle run left two untracked SQLite byproducts
+(`reference/golden/metal/colby.db-{wal,shm}`), not gitignored; deleted before
+staging. No tracked golden changed.
+
+### Negative control, EXECUTED
+
+The guard-strip above IS the negative control, run in both directions: guard
+removed → exit 101 with the two assertions quoted verbatim; guard restored from
+the saved copy → exit 0, 4 passed. Restored-file SHA-256 of
+`crates/codegraph-graph/src/graph/mod.rs`:
+`0a0a1d93dd1c5dd39f305c0c37ef66327791e547d5fbae46763ac06495c87c57`
+(measured with `sha256sum` after the restore).
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo build --locked -p codegraph-graph --all-targets` → exit 0.
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → exit 0.
+- `cargo test --locked -p codegraph-graph --test enqueue_once` → exit 0,
+  4 passed.
+- `cargo test --locked -p codegraph-graph -p codegraph-mcp -p codegraph-rs`
+  → exit 0 (63 `test result: ok` lines, no FAILED).
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+
+`lsp_diagnostics` again refused this worktree (`LSP file path must be inside
+request cwd`); locked Cargo clippy/test is the honest fallback and no LSP-clean
+result is claimed. No dependency, version or `Cargo.lock` byte changed. No
+Windows/MSVC runtime validation is claimed — this work ran on Linux only.

From 7d0253bf2f90af3a56e56f578200d4d5921eeea1 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 11:16:39 +0800
Subject: [PATCH 53/91] fix(cli): node <symbol> --file pins one overload and
 returns its source body

---
 crates/codegraph-cli/src/main.rs              |  15 +-
 .../codegraph-cli/tests/node_file_pin_cli.rs  | 279 ++++++++++++++++++
 crates/codegraph-mcp/src/engine.rs            | 129 ++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 163 ++++++++++
 4 files changed, 584 insertions(+), 2 deletions(-)
 create mode 100644 crates/codegraph-cli/tests/node_file_pin_cli.rs

diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index 00ebca0..be2c406 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -319,6 +319,10 @@ enum Command {
         target: String,
         #[arg(short, long)]
         path: Option<PathBuf>,
+        /// Pin an overloaded SYMBOL to the definition in this file (path or
+        /// basename). Its source body is returned, like the unpinned form.
+        #[arg(short = 'f', long = "file")]
+        file: Option<String>,
         /// Symbol mode: return just the file's symbol map instead of source.
         #[arg(long = "symbols-only")]
         symbols_only: bool,
@@ -575,10 +579,11 @@ fn run(cli: Cli) -> Result<()> {
         Command::Node {
             target,
             path,
+            file,
             symbols_only,
             json,
             strict,
-        } => cmd_node(target, path, symbols_only, json, strict),
+        } => cmd_node(target, path, file, symbols_only, json, strict),
         Command::Install {
             target,
             location,
@@ -3114,13 +3119,19 @@ fn cmd_explore(
 fn cmd_node(
     target: String,
     path: Option<PathBuf>,
+    file: Option<String>,
     symbols_only: bool,
     json_output: bool,
     strict: bool,
 ) -> Result<()> {
     let project = resolve_required_project(path)?;
     let engine = codegraph_mcp::CodeGraphEngine::open(&project)?;
-    let args = if node_target_is_file(&engine, &target) {
+    // #1314: `-f/--file` PINS an overloaded symbol to one file and must still
+    // carry `includeCode`, exactly like the bare-symbol branch below — the
+    // pinned definition's source body is the whole point of the pin.
+    let args = if let Some(file) = &file {
+        json!({ "symbol": target, "file": file, "includeCode": true })
+    } else if node_target_is_file(&engine, &target) {
         json!({ "file": target, "symbolsOnly": symbols_only })
     } else {
         json!({ "symbol": target, "includeCode": true })
diff --git a/crates/codegraph-cli/tests/node_file_pin_cli.rs b/crates/codegraph-cli/tests/node_file_pin_cli.rs
new file mode 100644
index 0000000..9db426f
--- /dev/null
+++ b/crates/codegraph-cli/tests/node_file_pin_cli.rs
@@ -0,0 +1,279 @@
+//! Upstream `ce983a0` (#1314) — `codegraph node <symbol> -f <file>` must return
+//! the symbol's SOURCE BODY, not just its location.
+//!
+//! `codegraph node setState` prints every overload's body. `-f <file>` is the
+//! tool's own suggestion for picking ONE of them, so it must print that one's
+//! body — the whole point of the disambiguation. These tests drive the REAL
+//! binary against a temp project with two same-named definitions and assert on
+//! the process's stdout.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_codegraph"))
+}
+
+struct TestDir {
+    path: PathBuf,
+}
+
+impl TestDir {
+    fn new(label: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "codegraph-node-file-pin-{label}-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        std::fs::create_dir_all(&path).unwrap();
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+struct Run {
+    stdout: String,
+    stderr: String,
+    ok: bool,
+}
+
+fn run_in(cwd: &Path, args: &[&str]) -> Run {
+    let output = Command::new(bin())
+        .args(args)
+        .current_dir(cwd)
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .output()
+        .expect("run codegraph binary");
+    Run {
+        stdout: String::from_utf8_lossy(&output.stdout).into_owned(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+        ok: output.status.success(),
+    }
+}
+
+/// Two `setState` definitions, each carrying a marker only its own body holds.
+fn indexed_project(dir: &TestDir) -> PathBuf {
+    let project = dir.path().join("proj");
+    let src = project.join("src");
+    std::fs::create_dir_all(&src).unwrap();
+    std::fs::write(
+        src.join("alpha.ts"),
+        "export function setState(next: number): number {\n  \
+         const ALPHA_MARKER = next + 1;\n  return ALPHA_MARKER;\n}\n",
+    )
+    .unwrap();
+    std::fs::write(
+        src.join("beta.ts"),
+        "export function setState(next: string): string {\n  \
+         const BETA_MARKER = next + \"!\";\n  return BETA_MARKER;\n}\n",
+    )
+    .unwrap();
+    let run = run_in(dir.path(), &["init", project.to_str().unwrap()]);
+    assert!(run.ok, "init failed: {} {}", run.stdout, run.stderr);
+    project
+}
+
+#[test]
+fn node_symbol_pinned_to_a_file_prints_that_definitions_body_only() {
+    let dir = TestDir::new("pin");
+    let project = indexed_project(&dir);
+    let p = project.to_str().unwrap();
+
+    let run = run_in(
+        project.as_path(),
+        &["node", "setState", "-f", "src/beta.ts", "-p", p],
+    );
+    assert!(
+        run.ok,
+        "node <symbol> -f <file> must succeed: {} {}",
+        run.stdout, run.stderr
+    );
+    assert!(
+        run.stdout.contains("BETA_MARKER"),
+        "the pinned definition's SOURCE BODY must be printed: {}",
+        run.stdout
+    );
+    assert!(
+        !run.stdout.contains("ALPHA_MARKER"),
+        "the other overload's body must NOT be printed: {}",
+        run.stdout
+    );
+    assert!(
+        run.stdout.contains("src/beta.ts"),
+        "the pinned location must be named: {}",
+        run.stdout
+    );
+}
+
+/// A basename pins as well as a repo-relative path.
+#[test]
+fn node_symbol_pinned_by_basename_prints_that_definitions_body() {
+    let dir = TestDir::new("basename");
+    let project = indexed_project(&dir);
+    let p = project.to_str().unwrap();
+
+    let run = run_in(
+        project.as_path(),
+        &["node", "setState", "-f", "alpha.ts", "-p", p],
+    );
+    assert!(run.ok, "basename pin must succeed: {}", run.stderr);
+    assert!(
+        run.stdout.contains("ALPHA_MARKER"),
+        "the basename-pinned body must be printed: {}",
+        run.stdout
+    );
+    assert!(
+        !run.stdout.contains("BETA_MARKER"),
+        "the other overload's body must NOT be printed: {}",
+        run.stdout
+    );
+}
+
+/// A `--file` that matches no definition of the symbol must say so rather than
+/// silently falling back to an arbitrary overload.
+#[test]
+fn node_symbol_pinned_to_a_non_matching_file_reports_not_found() {
+    let dir = TestDir::new("nomatch");
+    let project = indexed_project(&dir);
+    let p = project.to_str().unwrap();
+
+    let run = run_in(
+        project.as_path(),
+        &["node", "setState", "-f", "src/nowhere.ts", "-p", p],
+    );
+    assert!(
+        !run.stdout.contains("ALPHA_MARKER") && !run.stdout.contains("BETA_MARKER"),
+        "a non-matching pin must not fall back to an arbitrary overload: {}",
+        run.stdout
+    );
+    assert!(
+        run.stdout.contains("not found") || run.stdout.contains("No "),
+        "a non-matching pin must report not-found: {}",
+        run.stdout
+    );
+}
+
+/// The bare (unpinned) form is unchanged: every overload's body, as before.
+#[test]
+fn bare_node_symbol_still_returns_every_overload_body() {
+    let dir = TestDir::new("bare");
+    let project = indexed_project(&dir);
+    let p = project.to_str().unwrap();
+
+    let run = run_in(project.as_path(), &["node", "setState", "-p", p]);
+    assert!(run.ok, "bare node <symbol> must succeed: {}", run.stderr);
+    assert!(
+        run.stdout.contains("ALPHA_MARKER") && run.stdout.contains("BETA_MARKER"),
+        "the unpinned form must still return every overload in full: {}",
+        run.stdout
+    );
+}
+
+/// The MCP `codegraph_node` contract: `symbol` + `file` must pin to that file's
+/// definition and return its body, over real stdio.
+#[cfg(unix)]
+#[test]
+fn mcp_node_symbol_plus_file_pins_and_returns_the_body() {
+    use std::io::{BufRead, BufReader, Write};
+    use std::process::Stdio;
+    use std::time::{Duration, Instant};
+
+    let dir = TestDir::new("mcp");
+    let project = indexed_project(&dir);
+
+    let mut child = Command::new(bin())
+        .args(["serve", "--mcp", "--path", project.to_str().unwrap()])
+        .env("CODEGRAPH_NO_DAEMON", "1")
+        .env("CODEGRAPH_NO_WATCH", "1")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .expect("spawn serve --mcp");
+    let mut stdin = child.stdin.take().expect("child stdin");
+    let mut stdout = BufReader::new(child.stdout.take().expect("child stdout"));
+    let deadline = Instant::now() + Duration::from_secs(30);
+
+    let send = |stdin: &mut std::process::ChildStdin, v: serde_json::Value| {
+        writeln!(stdin, "{v}").unwrap();
+        stdin.flush().unwrap();
+    };
+    let mut recv = |want_id: i64| -> serde_json::Value {
+        loop {
+            assert!(Instant::now() < deadline, "timed out awaiting id {want_id}");
+            let mut line = String::new();
+            match stdout.read_line(&mut line) {
+                Ok(0) => panic!("serve --mcp closed stdout before id {want_id}"),
+                Ok(_) => {
+                    if let Ok(v) = serde_json::from_str::<serde_json::Value>(line.trim())
+                        && v.get("id").and_then(serde_json::Value::as_i64) == Some(want_id)
+                    {
+                        return v;
+                    }
+                }
+                Err(e) => panic!("reading serve --mcp stdout: {e}"),
+            }
+        }
+    };
+
+    send(
+        &mut stdin,
+        serde_json::json!({
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": { "name": "node-file-pin-test", "version": "0" }
+            }
+        }),
+    );
+    let _ = recv(1);
+    send(
+        &mut stdin,
+        serde_json::json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }),
+    );
+    send(
+        &mut stdin,
+        serde_json::json!({
+            "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+            "params": {
+                "name": "codegraph_node",
+                "arguments": { "symbol": "setState", "file": "src/beta.ts", "includeCode": true }
+            }
+        }),
+    );
+    let resp = recv(2);
+    let text = resp["result"]["content"][0]["text"]
+        .as_str()
+        .unwrap_or_default()
+        .to_string();
+    drop(stdin);
+    let _ = child.kill();
+    let _ = child.wait();
+
+    assert_ne!(
+        resp["result"]["isError"],
+        serde_json::json!(true),
+        "MCP node with symbol+file must not error: {text}"
+    );
+    assert!(
+        text.contains("BETA_MARKER"),
+        "MCP node symbol+file must return the pinned body: {text}"
+    );
+    assert!(
+        !text.contains("ALPHA_MARKER"),
+        "MCP node symbol+file must not return the other overload: {text}"
+    );
+}
diff --git a/crates/codegraph-mcp/src/engine.rs b/crates/codegraph-mcp/src/engine.rs
index 2bd0173..c3382b0 100644
--- a/crates/codegraph-mcp/src/engine.rs
+++ b/crates/codegraph-mcp/src/engine.rs
@@ -397,6 +397,29 @@ impl CodeGraphEngine {
                 "Symbol \"{symbol}\" not found in the codebase"
             )));
         }
+        // `symbol` + `file` (#1314): the schema promises `file` PINS an
+        // overloaded name to the definition in that file. A pin that matches
+        // nothing reports not-found rather than falling back to an arbitrary
+        // overload — a silent miss beats a wrong answer.
+        if let Some(file_hint) = file_hint {
+            let pinned: Vec<Node> = matches
+                .iter()
+                .filter(|n| file_path_matches_hint(&n.file_path, file_hint))
+                .cloned()
+                .collect();
+            if pinned.is_empty() {
+                return Ok(ToolResult::not_found_text(format!(
+                    "Symbol \"{symbol}\" not found in \"{file_hint}\""
+                )));
+            }
+            if pinned.len() == 1 {
+                let rendered = self.render_node_section(&pinned[0], include_code)?;
+                return Ok(ToolResult::text(truncate_output(&rendered)));
+            }
+            return Ok(ToolResult::text(truncate_output(
+                &self.render_ambiguous_node(symbol, &pinned, include_code)?,
+            )));
+        }
         if matches.len() == 1 {
             let rendered = self.render_node_section(&matches[0], include_code)?;
             return Ok(ToolResult::text(truncate_output(&rendered)));
@@ -2368,6 +2391,28 @@ fn basename(path: &str) -> &str {
     path.rsplit('/').next().unwrap_or(path)
 }
 
+/// Whether an indexed `file_path` is the file a `codegraph_node` `file` hint
+/// names (#1314). Accepts the exact repo-relative path, a path suffix on a
+/// segment boundary (`auth/session.ts` for `src/auth/session.ts`), or a bare
+/// basename (`session.ts`). Separators are normalized so a Windows-style hint
+/// pins the same node as its POSIX form.
+fn file_path_matches_hint(file_path: &str, hint: &str) -> bool {
+    let normalize = |s: &str| s.replace('\\', "/").trim_start_matches("./").to_string();
+    let path = normalize(file_path);
+    let hint = normalize(hint);
+    if hint.is_empty() {
+        return false;
+    }
+    if path == hint {
+        return true;
+    }
+    if !hint.contains('/') {
+        return path.rsplit('/').next() == Some(hint.as_str());
+    }
+    path.strip_suffix(hint.as_str())
+        .is_some_and(|prefix| prefix.ends_with('/'))
+}
+
 /// `matchesSymbol` (`tools.ts:3175-3210`).
 fn matches_symbol(node: &Node, symbol: &str) -> bool {
     if node.name == symbol {
@@ -3145,6 +3190,90 @@ mod tests {
         assert_eq!(tr.is_error, Some(true));
     }
 
+    #[test]
+    fn file_path_matches_hint_accepts_exact_suffix_and_basename_only() {
+        assert!(file_path_matches_hint(
+            "src/auth/session.ts",
+            "src/auth/session.ts"
+        ));
+        assert!(file_path_matches_hint(
+            "src/auth/session.ts",
+            "auth/session.ts"
+        ));
+        assert!(file_path_matches_hint("src/auth/session.ts", "session.ts"));
+        assert!(file_path_matches_hint(
+            "src/auth/session.ts",
+            "./src/auth/session.ts"
+        ));
+        // Windows-style hint pins the same node as its POSIX form.
+        assert!(file_path_matches_hint(
+            "src/auth/session.ts",
+            "auth\\session.ts"
+        ));
+        // A suffix that does not land on a segment boundary is NOT a match.
+        assert!(!file_path_matches_hint(
+            "src/myauth/session.ts",
+            "auth/session.ts"
+        ));
+        // A basename hint must match the basename, not a substring of it.
+        assert!(!file_path_matches_hint(
+            "src/auth/mysession.ts",
+            "session.ts"
+        ));
+        assert!(!file_path_matches_hint("src/auth/session.ts", "other.ts"));
+        assert!(!file_path_matches_hint("src/auth/session.ts", ""));
+    }
+
+    #[test]
+    fn ext_node_symbol_plus_file_pins_to_that_definition_and_reports_a_bad_pin() {
+        let mut engine = test_engine();
+        let alpha = node_lang(
+            "setState",
+            "setState",
+            "src/alpha.ts",
+            1,
+            4,
+            NodeKind::Function,
+            Language::TypeScript,
+        );
+        let beta = node_lang(
+            "setState",
+            "setState",
+            "src/beta.ts",
+            1,
+            4,
+            NodeKind::Function,
+            Language::TypeScript,
+        );
+        put_nodes(&mut engine, &[alpha, beta]);
+
+        let pinned = engine.execute(
+            "codegraph_node",
+            &serde_json::json!({"symbol": "setState", "file": "src/beta.ts", "includeCode": true}),
+        );
+        let txt = text_of(&pinned);
+        assert!(txt.contains("src/beta.ts"), "got: {txt}");
+        assert!(
+            !txt.contains("src/alpha.ts"),
+            "the pin must exclude the other overload: {txt}"
+        );
+        assert!(
+            !txt.contains("definitions named"),
+            "a resolved pin renders one definition, not the ambiguity list: {txt}"
+        );
+
+        let bad = engine.execute(
+            "codegraph_node",
+            &serde_json::json!({"symbol": "setState", "file": "src/nowhere.ts"}),
+        );
+        assert_eq!(bad.not_found, Some(true));
+        assert!(
+            text_of(&bad).contains("not found in \"src/nowhere.ts\""),
+            "got: {}",
+            text_of(&bad)
+        );
+    }
+
     #[test]
     fn ext_node_missing_symbol_errors() {
         let engine = test_engine();
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 5dabaf1..8bbdf7d 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -4995,3 +4995,166 @@ the saved copy → exit 0, 4 passed. Restored-file SHA-256 of
 request cwd`); locked Cargo clippy/test is the honest fallback and no LSP-clean
 result is claimed. No dependency, version or `Cargo.lock` byte changed. No
 Windows/MSVC runtime validation is claimed — this work ran on Linux only.
+
+---
+
+## Batch A4 — `node <symbol> -f <file>` returns the pinned definition's source body (2026-07-28)
+
+Ports upstream `ce983a0` (#1314). Base for this entry: `efc6fcd7` (Batch A3).
+One commit: the CLI flag, the engine's symbol+file pin, and tests.
+
+### Red (documented, with the actual wrong output)
+
+Two distinct defects, both measured on the real binary built from `efc6fcd7`
+against a temp project with TWO `setState` definitions (`src/alpha.ts` holding
+`ALPHA_MARKER`, `src/beta.ts` holding `BETA_MARKER`):
+
+1. **The CLI had no `-f` at all.** `codegraph node setState -f src/beta.ts`:
+
+```text
+error: unexpected argument '-f' found
+  tip: to pass '-f' as a value, use '-- -f'
+Usage: codegraph node [OPTIONS] <TARGET>
+```
+
+The tool's own `codegraph_node` schema says "pass `file`/`line` to pin one", and
+the ambiguity render tells the agent to pick one — but the shell had no way to.
+
+2. **The MCP tool IGNORED `file` when `symbol` was present.** `handle_node` only
+   consulted `file_hint` when `symbol` was ABSENT (`if symbol_raw.is_none() &&
+let Some(file_hint)`), so a pinned request fell through to the unpinned path.
+   Driven over real stdio with
+   `{"symbol":"setState","file":"src/beta.ts","includeCode":true}`:
+
+```text
+**2 definitions named "setState"**
+Returning 2 in full — pick the one you need (no Read required).
+
+## setState (function)
+**Location:** src/alpha.ts:1
+...  const ALPHA_MARKER = next + 1;
+---
+## setState (function)
+**Location:** src/beta.ts:1
+...  const BETA_MARKER = next + "!";
+```
+
+Both overloads, i.e. the pin did nothing. `cargo test --locked -p codegraph-rs
+--test node_file_pin_cli` → exit 101, 4 of 5 failing (the 5th pins the UNPINNED
+behaviour and passed both before and after).
+
+### Green (minimal)
+
+- `crates/codegraph-cli/src/main.rs`: new `-f/--file` on `Command::Node`, wired
+  through `cmd_node`. When present it sends
+  `{"symbol": target, "file": file, "includeCode": true}` — carrying
+  `includeCode` exactly like the bare-symbol branch, which is the upstream's
+  named root cause. File-view mode and the bare-symbol path are untouched.
+- `crates/codegraph-mcp/src/engine.rs`: `handle_node` now filters its matches by
+  the `file` hint when both `symbol` and `file` are given. One survivor renders
+  as a single definition (body + trail); several survivors render the ambiguity
+  view over the SURVIVORS only; zero survivors returns a not-found
+  `Symbol "X" not found in "<hint>"` rather than falling back to an arbitrary
+  overload — the same "silent miss beats a wrong answer" rule as Batch C.
+- New `file_path_matches_hint`: exact repo-relative path, a path suffix on a
+  SEGMENT boundary, or a bare basename; `\` normalized to `/` so a
+  Windows-style hint pins the same node. `src/myauth/session.ts` is NOT matched
+  by `auth/session.ts`, and `mysession.ts` is NOT matched by `session.ts`.
+
+### Proof through the REAL user-facing surface
+
+    $ codegraph node setState -f src/beta.ts
+    ## setState (function)
+    **Location:** src/beta.ts:1
+    **Signature:** `(next: string): string`
+    1	export function setState(next: string): string {
+    2	  const BETA_MARKER = next + "!";
+    3	  return BETA_MARKER;
+    4	}
+
+    $ codegraph node setState -f alpha.ts        # basename pin
+    ## setState (function)
+    **Location:** src/alpha.ts:1
+    1	export function setState(next: number): number {
+    2	  const ALPHA_MARKER = next + 1;
+    3	  return ALPHA_MARKER;
+    4	}
+
+    $ codegraph node setState -f src/nowhere.ts
+    Symbol "setState" not found in "src/nowhere.ts"
+
+The source body appears in stdout, and only the pinned overload's.
+
+### Golden row delta
+
+None. `git diff --stat 29f635b..HEAD -- reference/golden/` → EMPTY;
+`git status --short reference/golden/` → empty.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed**. The 15 golden MCP fixtures still reach parity
+(`rmcp_parity`, `golden_mcp` green): none of them passes `symbol`+`file`, so the
+new branch is unreachable for them.
+
+### Negative control, EXECUTED
+
+`git stash push -- crates/codegraph-mcp/src/engine.rs
+crates/codegraph-cli/src/main.rs` (tests kept) →
+`cargo test --locked -p codegraph-rs --test node_file_pin_cli` → exit 101 with 4
+of 5 RED (the unpinned-behaviour test still ok). `git stash pop` restored both;
+restored SHA-256:
+
+- `crates/codegraph-mcp/src/engine.rs`
+  `ad925f79c47c3660b2a0406cf173018cf91560d046fb54f3a2282e1c82e0747a`
+- `crates/codegraph-cli/src/main.rs`
+  `aa580663f7c1ee8a7dc4f5cf41676a8c33946929ff89353c4ecee2c15b936231`
+
+Re-run with the fix restored → exit 0, 5 passed.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo clippy --locked --workspace --all-targets -- -D warnings` → exit 0.
+- `cargo test --locked -p codegraph-rs --test node_file_pin_cli` → exit 0,
+  5 passed.
+- `cargo test --locked -p codegraph-mcp --lib file_path_matches_hint…` → exit 0.
+- `cargo test --locked -p codegraph-mcp --lib ext_node_symbol_plus_file…` →
+  exit 0.
+- `cargo test --locked -p codegraph-mcp -p codegraph-rs` → **exit 101**, failing
+  ONLY `codegraph-rs formatter_and_env_tests::install_completions_writes_zsh_
+fish_elvish_into_home` — the KNOWN pre-existing in-process `HOME`/
+  `XDG_DATA_HOME` race documented in the Batch C2/C3 entries, unrelated to the
+  `node` command. NOT weakened, skipped, `#[ignore]`d or modified. Re-run in
+  isolation (`--bin codegraph <that test>`) → exit 0, 1 passed.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+- `make ci CARGO='cargo --locked'` was run repeatedly as the final Batch A gate.
+  The LAST run, executed after the last byte of this commit (code, tests and this
+  prose, then `make fmt`), exited **0** with `✅ All CI checks passed!`. Earlier
+  runs in the same session hit two KNOWN pre-existing flakes, both reported here
+  rather than hidden:
+  - `codegraph-rs formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+    — the in-process `HOME`/`XDG_DATA_HOME` race documented in the Batch C2/C3
+    entries (2 of 6 runs). Passes in isolation: exit 0, 1 passed.
+  - `codegraph-rs batch_m_legacy_extension_override::verify_legacy_binary_rejects_a_wrong_executable_version`
+    — fails with `run configured legacy binary …/stub-legacy --version: Text
+file busy (os error 26)` (2 of 6 runs). The test writes a stub executable
+    and immediately execs it; under a loaded multi-threaded workspace run the
+    write handle can still be open. Run in isolation SIX consecutive times: exit
+    0 every time, zero `Text file busy` hits. This test file is NOT in Batch A's
+    diff (`git diff --name-only 29f635b..HEAD` does not list it); its last commit
+    is `25b78a8`, before this batch.
+    Neither test was weakened, skipped, `#[ignore]`d, given a sleep, or modified in
+    any way. Gate runs left untracked SQLite byproducts under `reference/golden/`
+    (`metal/`, `solidity/` `colby.db-{wal,shm}`), which are not gitignored; they
+    were deleted before staging and no tracked golden changed.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+`lsp_diagnostics` again refused this worktree (`LSP file path must be inside
+request cwd`); locked Cargo clippy/test is the honest fallback and no LSP-clean
+result is claimed. No dependency, version or `Cargo.lock` byte changed. No
+Windows/MSVC runtime validation is claimed — the `\`-normalization is asserted
+by a unit test on Linux only.
+
+```
+
+```

From b7ff1f8b3a0ee5f99912e8a426d6af810eec3b9c Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 12:57:41 +0800
Subject: [PATCH 54/91] fix(resolve): bound the React Route opening-tag scan to
 the tag itself

---
 .../codegraph-resolve/src/frameworks/react.rs |  69 ++++++-
 crates/codegraph-resolve/tests/frameworks.rs  | 133 +++++++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 180 ++++++++++++++++++
 3 files changed, 381 insertions(+), 1 deletion(-)

diff --git a/crates/codegraph-resolve/src/frameworks/react.rs b/crates/codegraph-resolve/src/frameworks/react.rs
index 1436a7b..5fc64bc 100644
--- a/crates/codegraph-resolve/src/frameworks/react.rs
+++ b/crates/codegraph-resolve/src/frameworks/react.rs
@@ -151,7 +151,7 @@ impl FrameworkResolver for ReactResolver {
 
         // React Router <Route .../> (v5/v6) (react.ts:158-198).
         for tag in route_tag_regex().find_iter(content) {
-            let window = byte_window(content, tag.start(), 400);
+            let window = route_opening_tag_window(content, tag.start());
             let Some(path_match) = route_path_attr().captures(window) else {
                 continue;
             };
@@ -520,6 +520,73 @@ fn byte_window(content: &str, start: usize, max_bytes: usize) -> &str {
     &content[start..end]
 }
 
+/// Hard byte bound on how far the `<Route …>` opening-tag scan may look forward
+/// from the `<` (upstream issue #1348).
+///
+/// The scan normally stops at the tag's own `>` (see [`opening_tag_end`]), but a
+/// malformed or unterminated tag has no `>` to find, so the search itself must be
+/// capped: without a cap one stray `<Route` would drag the scan to end-of-file,
+/// and a file carrying many such tags would turn this pass quadratic.
+///
+/// 2048 bytes is the cap, sized off the longest opening tags actually measured
+/// rather than a guess. Measured reference points, each the true tag length up to
+/// its brace-aware terminator: a lazy, error-bounded v6 data route spread over
+/// six attribute lines is 278 bytes; the same route with `hydrateFallbackElement`,
+/// `shouldRevalidate` and a `handle={{…}}` object is 525 bytes; a prettier-wrapped
+/// tag carrying twelve extra `data-*` attributes is 700 bytes. 2048 is ~3x that
+/// widest measured tag, so a legitimate tag is never truncated, while the work per
+/// tag stays constant. It is also strictly wider than the fixed 400-byte window it
+/// replaces (`react.ts:114-123`), so no attribute the old window could reach is
+/// lost.
+const ROUTE_OPENING_TAG_SCAN_LIMIT: usize = 2048;
+
+/// The `<Route …>` opening tag's own text, starting at `start` (its `<`).
+///
+/// Replaces the upstream fixed 400-byte window (`react.ts:114-123`), which never
+/// cut at the tag's end and therefore let a parent or pathless route match a
+/// *sibling's* `path`/`element` (upstream issue #1348). The window is bounded
+/// twice over: by the tag terminator when the tag is well formed, and by
+/// [`ROUTE_OPENING_TAG_SCAN_LIMIT`] always — so an unterminated tag can never
+/// scan unboundedly. A malformed tag additionally stops at the next `<Route`, so
+/// even then it cannot borrow a sibling's attributes.
+fn route_opening_tag_window(content: &str, start: usize) -> &str {
+    let bounded = byte_window(content, start, ROUTE_OPENING_TAG_SCAN_LIMIT);
+    if let Some(end) = opening_tag_end(bounded) {
+        return &bounded[..end];
+    }
+    match bounded.get(1..).and_then(|rest| rest.find("<Route")) {
+        Some(idx) => &bounded[..idx + 1],
+        None => bounded,
+    }
+}
+
+/// Byte index just past the `>` closing the opening tag that starts at byte 0 of
+/// `text`, or `None` when the tag does not terminate inside `text`.
+///
+/// `{…}` expression containers and quoted attribute values are skipped, so the
+/// `>` inside `element={<Comp/>}` or `path="a>b"` does not end the tag early.
+fn opening_tag_end(text: &str) -> Option<usize> {
+    let mut brace_depth = 0usize;
+    let mut quote: Option<u8> = None;
+    for (index, byte) in text.as_bytes().iter().enumerate() {
+        match quote {
+            Some(open) => {
+                if *byte == open {
+                    quote = None;
+                }
+            }
+            None => match byte {
+                b'"' | b'\'' | b'`' => quote = Some(*byte),
+                b'{' => brace_depth += 1,
+                b'}' => brace_depth = brace_depth.saturating_sub(1),
+                b'>' if brace_depth == 0 => return Some(index + 1),
+                _ => {}
+            },
+        }
+    }
+    None
+}
+
 fn component_patterns() -> &'static [Regex] {
     static RE: OnceLock<Vec<Regex>> = OnceLock::new();
     RE.get_or_init(|| {
diff --git a/crates/codegraph-resolve/tests/frameworks.rs b/crates/codegraph-resolve/tests/frameworks.rs
index 4a596aa..6b5290f 100644
--- a/crates/codegraph-resolve/tests/frameworks.rs
+++ b/crates/codegraph-resolve/tests/frameworks.rs
@@ -298,6 +298,139 @@ fn react_extract_component_and_route_reference() {
     );
 }
 
+/// Nested v6 shape from upstream #1348: the parent route has a `path` but renders
+/// `<Outlet/>`, and the pathless `index` child must stay skipped. The unbounded
+/// 400-byte window let the parent borrow the child's `element` and let the `index`
+/// route borrow its sibling's `path`, producing `/dashboard -> DashboardHome`,
+/// a duplicate `settings` node, and `settings -> DashboardHome`.
+#[test]
+fn react_route_window_stops_at_tag_end_not_at_sibling_routes() {
+    let content = concat!(
+        "function DashboardHome() { return null; }\n",
+        "function Settings() { return null; }\n",
+        "export function App() {\n",
+        "  return (\n",
+        "    <Routes>\n",
+        "      <Route path=\"/dashboard\">\n",
+        "        <Route index element={<DashboardHome/>} />\n",
+        "        <Route path=\"settings\" element={<Settings/>} />\n",
+        "      </Route>\n",
+        "    </Routes>\n",
+        "  );\n",
+        "}\n",
+    );
+    let result = react::ReactResolver
+        .extract("src/App.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<(String, i64)> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| (n.name.clone(), n.start_line))
+        .collect();
+    assert_eq!(
+        routes,
+        vec![("/dashboard".to_string(), 6), ("settings".to_string(), 8)],
+        "the pathless index route must not borrow its sibling's path"
+    );
+
+    let refs: Vec<(String, i64)> = result
+        .references
+        .iter()
+        .map(|r| (r.reference_name.clone(), r.line))
+        .collect();
+    assert_eq!(
+        refs,
+        vec![("Settings".to_string(), 8)],
+        "only the settings route owns an element; the parent renders <Outlet/>"
+    );
+}
+
+/// An unterminated `<Route path=…` followed by a long run of `<` must not let the
+/// scan run to end-of-file, and must not reach the well-formed route far below it.
+#[test]
+fn react_route_window_is_bounded_for_unterminated_tag_and_bare_angle_run() {
+    let mut content = String::from("function Comp() { return null; }\n<Route path=\"/a\"\n");
+    content.push_str(&"<".repeat(200_000));
+    content.push_str("\n<Route path=\"/b\" element={<Comp/>} />\n");
+
+    let result = react::ReactResolver
+        .extract("src/Patho.tsx", &content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<String> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| n.name.clone())
+        .collect();
+    assert_eq!(routes, vec!["/a".to_string(), "/b".to_string()]);
+
+    let refs: Vec<(String, i64)> = result
+        .references
+        .iter()
+        .map(|r| (r.reference_name.clone(), r.line))
+        .collect();
+    assert_eq!(
+        refs,
+        vec![("Comp".to_string(), 4)],
+        "the unterminated /a tag must not reach the /b element 200KB later"
+    );
+}
+
+/// Pins `ROUTE_OPENING_TAG_SCAN_LIMIT` from the outside: a 700-byte prettier-wrapped
+/// opening tag — wider than both the old 400-byte window and any tag measured while
+/// sizing the bound — still yields its `path` and its `element`, so the bound cannot
+/// be tightened to a value that truncates legitimate input.
+#[test]
+fn react_route_window_keeps_long_multiline_opening_tag_intact() {
+    let filler: String = (0..12)
+        .map(|i| format!("        data-attribute-number-{i:02}=\"filler-value-{i:02}\"\n"))
+        .collect();
+    let content = format!(
+        concat!(
+            "function DeepSettingsPage() {{ return null; }}\n",
+            "export function Router() {{\n",
+            "  return (\n",
+            "    <Routes>\n",
+            "      <Route\n",
+            "        path=\"/dashboard/settings\"\n",
+            "{filler}",
+            "        element={{<DeepSettingsPage/>}}\n",
+            "      />\n",
+            "    </Routes>\n",
+            "  );\n",
+            "}}\n",
+        ),
+        filler = filler
+    );
+    let tag_start = content.find("<Route").expect("route tag");
+    let tag_len = content[tag_start..].find("/>").expect("tag end") + 2;
+    assert!(
+        tag_len > 400,
+        "fixture must exceed the old 400-byte window, got {tag_len}"
+    );
+
+    let result = react::ReactResolver
+        .extract("src/Router.tsx", &content, &no_project_config())
+        .expect("extract result");
+
+    let route = result
+        .nodes
+        .iter()
+        .find(|n| n.kind == NodeKind::Route)
+        .expect("route node");
+    assert_eq!(route.name, "/dashboard/settings");
+    assert!(
+        result
+            .references
+            .iter()
+            .any(|r| r.reference_name == "DeepSettingsPage"),
+        "the element of a {tag_len}-byte opening tag must still be seen"
+    );
+}
+
 // ---------------------------------------------------------------------------
 // Vue
 // ---------------------------------------------------------------------------
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 8bbdf7d..75b9b0a 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -5158,3 +5158,183 @@ by a unit test on Linux only.
 ```
 
 ```
+
+## Batch D1 — the `<Route>` opening-tag scan is bounded by the tag itself, not by 400 fixed bytes (2026-07-28)
+
+Ports upstream issue **#1348**. Investigated first, and the located scan was
+**NOT** already bounded in the sense the issue means: it had a fixed 400-byte
+forward window that never stopped at the tag's own end.
+
+### The located scan, quoted
+
+Not in `crates/codegraph-extract/src/embedded/` and not in the `lang/{jsx,tsx}.rs`
+specs (those only delegate to the JavaScript spec) — the scan is in the React
+framework resolver, `crates/codegraph-resolve/src/frameworks/react.rs:152-155`
+(pre-change):
+
+```rust
+// React Router <Route .../> (v5/v6) (react.ts:158-198).
+for tag in route_tag_regex().find_iter(content) {
+    let window = byte_window(content, tag.start(), 400);
+    let Some(path_match) = route_path_attr().captures(window) else {
+```
+
+with `byte_window` at `react.rs:515-521`:
+
+```rust
+fn byte_window(content: &str, start: usize, max_bytes: usize) -> &str {
+    let mut end = start.saturating_add(max_bytes).min(content.len());
+    while !content.is_char_boundary(end) {
+        end -= 1;
+    }
+    &content[start..end]
+}
+```
+
+So the scan was byte-capped (no unbounded read, no quadratic blow-up) but
+**never cut at the opening tag's terminator**. That is the #1348 defect: the cap
+was the _only_ bound, so one tag's window bled into its siblings' attributes.
+The call site reached is real: `ReferenceResolver::extract_and_persist_frameworks_with`
+(`resolver.rs:836-845`) → `ReactResolver::extract`, driven from
+`codegraph-cli/src/main.rs:4081` and `codegraph-watch/src/sync.rs:453`.
+
+### Measured Red — real indexed project, ground truth read from SQLite
+
+Scratch project `/tmp/d1-red` (`package.json` with a `react` dep, `src/App.js`
+carrying the standard v6 nested shape from the issue: a parent `path="/dashboard"`
+that renders `<Outlet/>`, a pathless `index` child, and a `path="settings"`
+sibling). `target/debug/codegraph init .`, then
+`sqlite3 .codegraph-v2/codegraph.db`:
+
+    $ sqlite3 … "select kind,name,start_line from nodes where kind='route' order by start_line;"
+    route|/dashboard|9
+    route|settings|10        <- WRONG: this is the pathless index route; it borrowed
+    route|settings|11           its sibling's path, so `settings` is duplicated
+
+    $ sqlite3 … "select (select name from nodes where id=e.source),
+                        (select name from nodes where id=e.target), e.line
+                 from edges e where e.source like 'route:%';"
+    /dashboard|DashboardHome|9   <- WRONG: /dashboard has no element of its own
+    settings|DashboardHome|10    <- WRONG pair: index route mislabeled `settings`
+    settings|Settings|11         <- correct
+
+3 route nodes where 2 are right, and **2 of 3 route→component edges wrong**,
+matching the upstream report edge for edge. This is observed database state, not
+a compile or setup failure.
+
+Pathological input measured too: `/tmp/d1-path/src/patho.js` — an unterminated
+`<Route path="/a"` (no `>`), then a 200 000-character run of `<`, then a
+well-formed `<Route path="/b" element={<Comp/>} />` (200 129 bytes total). The
+byte cap meant the old code did NOT hang (0.317 s wall clock, `Indexed 1 files`),
+so the honest finding is: **no unbounded scan, but wrong attribution** — the `/a`
+tag reached `Comp` in the unit-level reproduction (see the negative control
+below, where lifting the cap yields `[("Comp", 2), ("Comp", 4)]` instead of
+`[("Comp", 4)]`).
+
+### Green
+
+`route_opening_tag_window` replaces the raw 400-byte window. It bounds the scan
+twice: `opening_tag_end` walks to the tag's own `>` (skipping `{…}` expression
+containers and quoted values, so `element={<Comp/>}` and `path="a>b"` do not end
+the tag early), and `ROUTE_OPENING_TAG_SCAN_LIMIT` caps the search itself so an
+unterminated tag can never scan to end-of-file. A malformed tag additionally
+stops at the next `<Route`, so even then it cannot borrow a sibling's attributes.
+
+Same project re-indexed with the rebuilt binary:
+
+    route|/dashboard|9
+    route|settings|11
+    settings|Settings|11
+
+Exactly the single correct edge the issue asks for.
+
+### The bound and why that number
+
+`ROUTE_OPENING_TAG_SCAN_LIMIT = 2048`, justified in its doc comment from tag
+lengths actually measured on this branch (true length to the brace-aware
+terminator, computed with a Python walker over each fixture):
+
+| Opening tag shape                                                           | Bytes |
+| --------------------------------------------------------------------------- | ----- |
+| lazy, error-bounded v6 data route over six attribute lines (`/tmp/d1-long`) | 278   |
+| the same plus `hydrateFallbackElement`, `shouldRevalidate`, `handle={{…}}`  | 525   |
+| prettier-wrapped tag with twelve extra `data-*` attributes (`/tmp/d1-wide`) | 700   |
+
+2048 is ~3x the widest measured tag, and strictly wider than the 400-byte window
+it replaces, so nothing the old code could reach is lost. The first draft used
+512; the 700-byte measurement showed 512 would truncate a legitimate tag, so the
+constant was raised before commit rather than after.
+
+### Tests
+
+Three new tests in `crates/codegraph-resolve/tests/frameworks.rs`, all driving
+the real `ReactResolver::extract`:
+
+- `react_route_window_stops_at_tag_end_not_at_sibling_routes` — the #1348 nested
+  shape; asserts the exact route-node list AND the exact reference list.
+- `react_route_window_is_bounded_for_unterminated_tag_and_bare_angle_run` — the
+  pathological input: unterminated `<Route path="/a"`, a 200 000-char run of `<`,
+  then a well-formed route; asserts `/a` does not reach the far-away element.
+- `react_route_window_keeps_long_multiline_opening_tag_intact` — a 705-byte
+  prettier-wrapped tag with twelve props; asserts the fixture exceeds 400 bytes
+  and that both its `path` and its `element` still extract. This pins the bound
+  from the outside: tightening the constant below the tag length reddens it.
+
+### Golden row delta
+
+None. `git diff --stat 7d0253b..HEAD -- reference/golden/` → EMPTY.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed**. No golden fixture contains a `<Route`/`createBrowserRouter`
+construct (`grep -rn '<Route\|createBrowserRouter' reference/golden/ crates/codegraph-bench/fixtures/`
+→ no matches), so the new branch is unreachable for them. The equivalence run left
+untracked `reference/golden/godot/colby.db-{wal,shm}`; both were deleted before
+staging and no tracked golden changed.
+
+### Negative control, EXECUTED (three mutants)
+
+1. Production line reverted to `byte_window(content, tag.start(), 400)`, tests
+   untouched → `cargo test --locked -p codegraph-resolve --test frameworks` →
+   **exit 101**, 2 failed. Actual assertion output:
+
+       assertion `left == right` failed: the pathless index route must not borrow its sibling's path
+         left: [("/dashboard", 6), ("settings", 7), ("settings", 8)]
+        right: [("/dashboard", 6), ("settings", 8)]
+
+   plus `react_route_window_keeps_long_multiline_opening_tag_intact` FAILED.
+
+2. Cap lifted to `usize::MAX` (terminator logic kept) → **exit 101**, 1 failed:
+
+       assertion `left == right` failed: the unterminated /a tag must not reach the /b element 200KB later
+         left: [("Comp", 2), ("Comp", 4)]
+        right: [("Comp", 4)]
+
+   — proof the cap itself is load-bearing, not decoration.
+
+3. Cap tightened to `400` → **exit 101**, 1 failed:
+   `the element of a 705-byte opening tag must still be seen` — proof the bound
+   cannot be shrunk without truncating legitimate input.
+
+Restored after each mutant by copying back the green file; restored SHA-256 of
+`crates/codegraph-resolve/src/frameworks/react.rs`:
+`a4bbc7a36305bc8bd901b15daf867a3546b94ea76dc854afa86e90f263f8bb7d`.
+Re-run with the fix restored → exit 0, 31 passed.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, run before every Cargo
+  batch; every Cargo command used `--locked`.
+- `cargo build --locked -p codegraph-rs` → exit 0 (binary used for the SQLite
+  ground-truth measurements above).
+- `cargo test --locked -p codegraph-resolve --test frameworks` → exit 0,
+  31 passed.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, this prose, then `make fmt`); result recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
+no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
+changed. No native Windows/MSVC runtime validation is claimed — everything above
+ran on Linux.

From 1e1d259d7dec74163da9579d13c1980d92b2fd58 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 13:17:57 +0800
Subject: [PATCH 55/91] fix(extract): close each DFM object at its own matching
 end line

---
 crates/codegraph-extract/src/embedded/dfm.rs  |  31 ++-
 .../tests/fixtures/markup_risk/BrokenForm.dfm |   7 +
 .../tests/fixtures/markup_risk/DeepForm.dfm   |  33 +++
 .../tests/markup_risk_languages.rs            | 109 ++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 262 ++++++++++++++++++
 5 files changed, 437 insertions(+), 5 deletions(-)
 create mode 100644 crates/codegraph-extract/tests/fixtures/markup_risk/BrokenForm.dfm
 create mode 100644 crates/codegraph-extract/tests/fixtures/markup_risk/DeepForm.dfm

diff --git a/crates/codegraph-extract/src/embedded/dfm.rs b/crates/codegraph-extract/src/embedded/dfm.rs
index 03065cd..1fd2152 100644
--- a/crates/codegraph-extract/src/embedded/dfm.rs
+++ b/crates/codegraph-extract/src/embedded/dfm.rs
@@ -15,6 +15,17 @@ pub struct DfmExtractor<'a> {
     source: &'a str,
 }
 
+/// One entry of the `object … end` stack.
+///
+/// `id` is the node id used as the parent of the next `contains` edge. For the
+/// synthetic file root `node_index` is `None`; for a real `object`/`inherited`/
+/// `inline` block it is that node's index in `ExtractionResult::nodes`, so the
+/// matching `end` line can close the block's span (upstream issue #1350).
+struct OpenBlock {
+    id: String,
+    node_index: Option<usize>,
+}
+
 impl<'a> DfmExtractor<'a> {
     pub fn new(file_path: &'a str, source: &'a str) -> Self {
         Self { file_path, source }
@@ -63,7 +74,10 @@ impl<'a> DfmExtractor<'a> {
         let multiline_start_re = Regex::new(r"=\s*\(\s*$").unwrap();
         let multiline_item_start_re = Regex::new(r"=\s*<\s*$").unwrap();
 
-        let mut stack = vec![file_id.to_string()];
+        let mut stack = vec![OpenBlock {
+            id: file_id.to_string(),
+            node_index: None,
+        }];
         let mut in_multiline = false;
         let mut multiline_end = ')';
 
@@ -103,18 +117,22 @@ impl<'a> DfmExtractor<'a> {
                 );
                 node.signature = Some(type_name);
                 let node_id = node.id.clone();
+                let node_index = result.nodes.len();
                 result.nodes.push(node);
                 result
                     .edges
-                    .push(contains_edge(stack.last().unwrap(), &node_id));
-                stack.push(node_id);
+                    .push(contains_edge(&stack.last().unwrap().id, &node_id));
+                stack.push(OpenBlock {
+                    id: node_id,
+                    node_index: Some(node_index),
+                });
                 continue;
             }
 
             if let Some(captures) = event_re.captures(line) {
                 let method_name = captures.get(2).unwrap().as_str().to_string();
                 result.unresolved_references.push(unresolved_ref(
-                    stack.last().unwrap(),
+                    &stack.last().unwrap().id,
                     method_name,
                     EdgeKind::References,
                     line_num,
@@ -126,7 +144,10 @@ impl<'a> DfmExtractor<'a> {
             }
 
             if end_re.is_match(line) && stack.len() > 1 {
-                stack.pop();
+                let closed = stack.pop().unwrap();
+                if let Some(index) = closed.node_index {
+                    result.nodes[index].end_line = line_num;
+                }
             }
         }
     }
diff --git a/crates/codegraph-extract/tests/fixtures/markup_risk/BrokenForm.dfm b/crates/codegraph-extract/tests/fixtures/markup_risk/BrokenForm.dfm
new file mode 100644
index 0000000..f0a9cfe
--- /dev/null
+++ b/crates/codegraph-extract/tests/fixtures/markup_risk/BrokenForm.dfm
@@ -0,0 +1,7 @@
+object BrokenForm: TBrokenForm
+  Caption = 'Broken'
+  object OrphanPanel: TPanel
+    Caption = 'Orphan'
+    object LostButton: TButton
+      Caption = 'Lost'
+      OnClick = LostButtonClick
diff --git a/crates/codegraph-extract/tests/fixtures/markup_risk/DeepForm.dfm b/crates/codegraph-extract/tests/fixtures/markup_risk/DeepForm.dfm
new file mode 100644
index 0000000..b799af6
--- /dev/null
+++ b/crates/codegraph-extract/tests/fixtures/markup_risk/DeepForm.dfm
@@ -0,0 +1,33 @@
+object DeepForm: TDeepForm
+  Caption = 'Deep'
+  OnCreate = DeepFormCreate
+  object TopPanel: TPanel
+    Caption = 'Top'
+    object InnerPanel: TPanel
+      Caption = 'Inner'
+      object DeepButton: TButton
+        Caption = 'Deep'
+        OnClick = DeepButtonClick
+      end
+      object DeepLabel: TLabel
+        Caption = 'Label'
+      end
+    end
+    object SiblingButton: TButton
+      Caption = 'Sibling'
+    end
+  end
+  object BottomPanel: TPanel
+    Caption = 'Bottom'
+    object Items: TListView
+      Columns = <
+        item
+          Caption = 'Name'
+        end
+        item
+          Caption = 'Size'
+        end>
+      OnDblClick = ItemsDblClick
+    end
+  end
+end
diff --git a/crates/codegraph-extract/tests/markup_risk_languages.rs b/crates/codegraph-extract/tests/markup_risk_languages.rs
index a749b6d..ca3627e 100644
--- a/crates/codegraph-extract/tests/markup_risk_languages.rs
+++ b/crates/codegraph-extract/tests/markup_risk_languages.rs
@@ -69,6 +69,115 @@ fn lang_markup_risk_dfm_uses_custom_component_extractor() {
     );
 }
 
+#[test]
+fn lang_markup_risk_dfm_spans_close_at_their_own_matching_end() {
+    // Upstream issue #1350: every DFM object must report the line of ITS OWN
+    // matching `end`, so a container's span covers its children and a sibling
+    // never inherits the neighbour's terminator. DeepForm.dfm nests four deep
+    // (DeepForm > TopPanel > InnerPanel > DeepButton) and puts sibling pairs at
+    // two different depths.
+    let result = extract_fixture("DeepForm.dfm", None);
+    assert!(result.errors.is_empty(), "{:?}", result.errors);
+
+    let mut spans: Vec<(&str, i64, i64)> = result
+        .nodes
+        .iter()
+        .filter(|node| node.kind == NodeKind::Component)
+        .map(|node| (node.name.as_str(), node.start_line, node.end_line))
+        .collect();
+    spans.sort();
+    assert_eq!(
+        spans,
+        vec![
+            ("BottomPanel", 20, 32),
+            ("DeepButton", 8, 11),
+            ("DeepForm", 1, 33),
+            ("DeepLabel", 12, 14),
+            ("InnerPanel", 6, 15),
+            ("Items", 22, 31),
+            ("SiblingButton", 16, 18),
+            ("TopPanel", 4, 19),
+        ],
+        "each object must span from its own header line to its own matching end"
+    );
+
+    // Depth >= 2 exact spans, stated separately so a regression that only
+    // breaks deep nesting cannot hide behind the aggregate above.
+    let inner = assert_node(&result, NodeKind::Component, "InnerPanel");
+    assert_eq!((inner.start_line, inner.end_line), (6, 15));
+    let deep_button = assert_node(&result, NodeKind::Component, "DeepButton");
+    assert_eq!((deep_button.start_line, deep_button.end_line), (8, 11));
+
+    // Sibling pair at the same depth: an off-by-one that hands DeepButton's
+    // `end` (11) to DeepLabel, or DeepLabel's (14) to DeepButton, reddens here.
+    let deep_label = assert_node(&result, NodeKind::Component, "DeepLabel");
+    assert_eq!((deep_label.start_line, deep_label.end_line), (12, 14));
+    assert!(
+        deep_button.end_line < deep_label.start_line,
+        "siblings must not overlap: {:?} vs {:?}",
+        (deep_button.start_line, deep_button.end_line),
+        (deep_label.start_line, deep_label.end_line)
+    );
+
+    // The multiline `Columns = <...>` block ends with `end>` and `end` lines
+    // that must NOT close the enclosing objects (dfm-extractor.ts:95-109).
+    let items = assert_node(&result, NodeKind::Component, "Items");
+    assert_eq!((items.start_line, items.end_line), (22, 31));
+
+    // Nesting is unchanged by the span fix: parents still contain their children.
+    let file = assert_node(&result, NodeKind::File, "DeepForm.dfm");
+    let form = assert_node(&result, NodeKind::Component, "DeepForm");
+    let top = assert_node(&result, NodeKind::Component, "TopPanel");
+    let sibling = assert_node(&result, NodeKind::Component, "SiblingButton");
+    let bottom = assert_node(&result, NodeKind::Component, "BottomPanel");
+    assert_contains(&result, &file.id, &form.id);
+    assert_contains(&result, &form.id, &top.id);
+    assert_contains(&result, &top.id, &inner.id);
+    assert_contains(&result, &inner.id, &deep_button.id);
+    assert_contains(&result, &inner.id, &deep_label.id);
+    assert_contains(&result, &top.id, &sibling.id);
+    assert_contains(&result, &form.id, &bottom.id);
+    assert_contains(&result, &bottom.id, &items.id);
+    assert_ref_at(&result, EdgeKind::References, "DeepButtonClick", 10);
+    assert_ref_at(&result, EdgeKind::References, "ItemsDblClick", 30);
+}
+
+#[test]
+fn lang_markup_risk_dfm_unterminated_object_keeps_its_header_span() {
+    // Upstream issue #1350, malformed half: a truncated DFM leaves objects with
+    // no matching `end`. The extractor must neither panic nor invent a span it
+    // did not see, so an unclosed object keeps its header line as end_line
+    // rather than borrowing the file end (7) or a sibling's terminator.
+    let result = extract_fixture("BrokenForm.dfm", None);
+    assert!(result.errors.is_empty(), "{:?}", result.errors);
+
+    let mut spans: Vec<(&str, i64, i64)> = result
+        .nodes
+        .iter()
+        .filter(|node| node.kind == NodeKind::Component)
+        .map(|node| (node.name.as_str(), node.start_line, node.end_line))
+        .collect();
+    spans.sort();
+    assert_eq!(
+        spans,
+        vec![
+            ("BrokenForm", 1, 1),
+            ("LostButton", 5, 5),
+            ("OrphanPanel", 3, 3),
+        ],
+        "an unterminated object must not fabricate a span"
+    );
+
+    let file = assert_node(&result, NodeKind::File, "BrokenForm.dfm");
+    let form = assert_node(&result, NodeKind::Component, "BrokenForm");
+    let panel = assert_node(&result, NodeKind::Component, "OrphanPanel");
+    let button = assert_node(&result, NodeKind::Component, "LostButton");
+    assert_contains(&result, &file.id, &form.id);
+    assert_contains(&result, &form.id, &panel.id);
+    assert_contains(&result, &panel.id, &button.id);
+    assert_ref_at(&result, EdgeKind::References, "LostButtonClick", 7);
+}
+
 #[test]
 fn lang_markup_risk_kotlin_extracts_upstream_symbol_set() {
     // Golden run: upstream extractFromSource on this exact fixture (kotlin.ts:71-308).
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 75b9b0a..e41725b 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -5338,3 +5338,265 @@ must be inside request cwd`); locked Cargo clippy/test is the honest fallback an
 no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
 changed. No native Windows/MSVC runtime validation is claimed — everything above
 ran on Linux.
+
+## Batch D2 — every DFM object closes at its own matching `end` (2026-07-28)
+
+Ports upstream issue **#1350**. Investigated first, then MEASURED against real
+indexed database state. Finding, split honestly in two halves:
+
+- **Nesting was ALREADY correct.** The extractor already keeps an `object … end`
+  stack and parents each new object to `stack.last()`, so a nested object never
+  attached to the file root. Measured to four levels deep with siblings at two
+  depths — every `contains` edge was already right. This half is a
+  **reclassification: no defect, pinned by a new regression test.**
+- **`end_line` was WRONG for every object.** Each component reported
+  `end_line == start_line`, i.e. a one-line span, so no container's span covered
+  its children and no object reached its own `end`. This half is a **real
+  defect, fixed.**
+
+### The located logic, quoted
+
+`crates/codegraph-extract/src/embedded/dfm.rs:59-131` (pre-change). The stack
+held bare id strings, so once an object was pushed there was no way back to its
+node to close it — the `end` branch popped and discarded:
+
+```rust
+let mut stack = vec![file_id.to_string()];
+…
+if let Some(captures) = object_re.captures(line) {
+    let name = captures.get(2).unwrap().as_str().to_string();
+    let type_name = captures.get(3).unwrap().as_str().to_string();
+    let mut node = default_node(
+        self.file_path,
+        Language::Pascal,
+        NodeKind::Component,
+        name.clone(),
+        format!("{}#{name}", self.file_path),
+        line_num,
+        line_num,   // <- end_line seeded to the HEADER line and never updated
+        0,
+        line.len() as i64,
+    );
+    node.signature = Some(type_name);
+    let node_id = node.id.clone();
+    result.nodes.push(node);
+    result
+        .edges
+        .push(contains_edge(stack.last().unwrap(), &node_id));
+    stack.push(node_id);
+    continue;
+}
+…
+if end_re.is_match(line) && stack.len() > 1 {
+    stack.pop();   // <- the matching `end` line is discarded
+}
+```
+
+### Measured Red — real indexed project, ground truth read from SQLite
+
+Scratch project `/tmp/d2-red` with two fixtures: `src/Deep.dfm` (four levels —
+`MainForm` > `TopPanel` > `InnerPanel` > `DeepButton` — plus sibling pairs at two
+depths and a multiline `Columns = <…>` block whose `end` / `end>` lines must not
+close anything) and `src/Broken.dfm` (truncated: three objects, zero `end`).
+Indexed with the pre-change `target/debug/codegraph`, then:
+
+    sqlite3 .codegraph-v2/codegraph.db \
+      "select kind, name, qualified_name, start_line, end_line, file_path \
+       from nodes order by file_path, start_line;"
+
+Observed (pre-change), verbatim:
+
+    file|Broken.dfm|src/Broken.dfm|1|7|src/Broken.dfm
+    component|BrokenForm|src/Broken.dfm#BrokenForm|1|1|src/Broken.dfm
+    component|OrphanPanel|src/Broken.dfm#OrphanPanel|3|3|src/Broken.dfm
+    component|LostButton|src/Broken.dfm#LostButton|5|5|src/Broken.dfm
+    file|Deep.dfm|src/Deep.dfm|1|34|src/Deep.dfm
+    component|MainForm|src/Deep.dfm#MainForm|1|1|src/Deep.dfm
+    component|TopPanel|src/Deep.dfm#TopPanel|4|4|src/Deep.dfm
+    component|InnerPanel|src/Deep.dfm#InnerPanel|6|6|src/Deep.dfm
+    component|DeepButton|src/Deep.dfm#DeepButton|8|8|src/Deep.dfm
+    component|DeepLabel|src/Deep.dfm#DeepLabel|12|12|src/Deep.dfm
+    component|SiblingButton|src/Deep.dfm#SiblingButton|16|16|src/Deep.dfm
+    component|BottomPanel|src/Deep.dfm#BottomPanel|20|20|src/Deep.dfm
+    component|Items|src/Deep.dfm#Items|22|22|src/Deep.dfm
+
+**Wrong rows: all 8 `Deep.dfm` components.** Every one reports
+`end_line == start_line`. Ground truth from `cat -n src/Deep.dfm`: `MainForm`
+ends at 33, `TopPanel` at 19, `InnerPanel` at 15, `DeepButton` at 11,
+`DeepLabel` at 14, `SiblingButton` at 18, `BottomPanel` at 32, `Items` at 31.
+So a caller asking "what lines is `TopPanel`?" was told line 4 only, and no
+container's span contained its children. This is observed database state, not a
+compile or setup failure.
+
+`qualified_name` was NOT flattened — it is `{file}#{name}` by upstream design
+(`dfm-extractor.ts`), and the existing test already pins that form, so it is not
+touched here.
+
+Nesting, measured in the same run:
+
+    contains|Broken.dfm@1|BrokenForm@1
+    contains|BrokenForm@1|OrphanPanel@3
+    contains|OrphanPanel@3|LostButton@5
+    contains|Deep.dfm@1|MainForm@1
+    contains|MainForm@1|TopPanel@4
+    contains|TopPanel@4|InnerPanel@6
+    contains|InnerPanel@6|DeepButton@8
+    contains|InnerPanel@6|DeepLabel@12
+    contains|TopPanel@4|SiblingButton@16
+    contains|MainForm@1|BottomPanel@20
+    contains|BottomPanel@20|Items@22
+
+Every edge correct, including at depth 3 and across the multiline block —
+**already right**, hence the reclassification above. Reported as measured rather
+than restated as a defect.
+
+### Green
+
+`OpenBlock { id, node_index }` replaces the bare id on the stack: the file root
+carries `node_index: None`, each real object carries its index in
+`result.nodes`. The `end` branch now closes the block it actually popped:
+
+```rust
+if end_re.is_match(line) && stack.len() > 1 {
+    let closed = stack.pop().unwrap();
+    if let Some(index) = closed.node_index {
+        result.nodes[index].end_line = line_num;
+    }
+}
+```
+
+Because the `end_line` is written from the popped frame, the value can only ever
+come from that object's own matching `end` — a sibling's terminator is
+structurally unreachable. Same project re-indexed with the rebuilt binary:
+
+    file|Broken.dfm|src/Broken.dfm|1|7|src/Broken.dfm
+    component|BrokenForm|src/Broken.dfm#BrokenForm|1|1|src/Broken.dfm
+    component|OrphanPanel|src/Broken.dfm#OrphanPanel|3|3|src/Broken.dfm
+    component|LostButton|src/Broken.dfm#LostButton|5|5|src/Broken.dfm
+    file|Deep.dfm|src/Deep.dfm|1|34|src/Deep.dfm
+    component|MainForm|src/Deep.dfm#MainForm|1|33|src/Deep.dfm
+    component|TopPanel|src/Deep.dfm#TopPanel|4|19|src/Deep.dfm
+    component|InnerPanel|src/Deep.dfm#InnerPanel|6|15|src/Deep.dfm
+    component|DeepButton|src/Deep.dfm#DeepButton|8|11|src/Deep.dfm
+    component|DeepLabel|src/Deep.dfm#DeepLabel|12|14|src/Deep.dfm
+    component|SiblingButton|src/Deep.dfm#SiblingButton|16|18|src/Deep.dfm
+    component|BottomPanel|src/Deep.dfm#BottomPanel|20|32|src/Deep.dfm
+    component|Items|src/Deep.dfm#Items|22|31|src/Deep.dfm
+
+All 8 spans now match `cat -n` exactly. The `contains` edge list is byte-identical
+to the Red run (re-queried and compared) — nesting was not disturbed.
+
+### Unterminated objects: honest omission, not a fabricated span
+
+`Broken.dfm`'s three objects never reach an `end`, so nothing pops them and their
+`end_line` stays at the header line. That is deliberate, following the precedent
+that an undeterminable target emits nothing rather than a guess: the extractor
+does not claim a span it never observed, does not borrow the file end (7), and
+does not panic. `result.errors` stays empty and the `contains` chain is still
+built, so the structure is still usable.
+
+### `start_line` invariance — node-ID safety
+
+Node IDs are `{kind}:{sha256("{filePath}:{kind}:{name}:{line}").hex[:32]}` where
+`line` is `start_line` (`shared::default_node` → `generate_node_id(file_path,
+kind, &name, start_line.max(1) as u32)`). **This change writes only `end_line`.**
+The `default_node(…)` call — including both line arguments and therefore the id —
+is untouched; the single new write is `result.nodes[index].end_line = line_num;`
+after the node already exists. No `start_line`, `name`, `kind`, `file_path` or
+`qualified_name` value changes, so **no node ID shifts**. Confirmed against the
+measured tables above: every `start_line` in the Green table equals the Red one.
+An earlier draft also updated `end_column`; that was reverted before commit to
+keep the diff to the one field the issue is about.
+
+### Tests
+
+Two new tests in `crates/codegraph-extract/tests/markup_risk_languages.rs`,
+driving the real `extract_source` through `extract_fixture`, plus two new
+fixtures (`DeepForm.dfm`, `BrokenForm.dfm`; no existing fixture reflowed, so no
+existing `start_line` moved):
+
+- `lang_markup_risk_dfm_spans_close_at_their_own_matching_end` — asserts the
+  EXACT `(name, start_line, end_line)` triple for all 8 objects, then repeats the
+  depth-2 (`InnerPanel` 6..15) and depth-3 (`DeepButton` 8..11) spans separately,
+  asserts the same-depth sibling pair (`DeepButton` 8..11 vs `DeepLabel` 12..14)
+  plus a non-overlap assertion so an off-by-one that swaps their terminators is
+  caught, pins `Items` 22..31 across the multiline `Columns = <…>` block, and
+  re-asserts all 8 `contains` edges and two handler reference lines.
+- `lang_markup_risk_dfm_unterminated_object_keeps_its_header_span` — the
+  truncated fixture; asserts the exact three spans (`1..1`, `3..3`, `5..5`), that
+  `errors` is empty (no panic, no error node), and that the `contains` chain is
+  still complete.
+
+The existing `lang_markup_risk_dfm_uses_custom_component_extractor` is unchanged
+and still green, so the ported behavior did not disturb `MainForm.dfm`.
+
+### Golden row delta
+
+None. `git diff --stat b7ff1f8..HEAD -- reference/golden/` → **EMPTY** (exit 0).
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**26 passed, 0 failed**. No golden corpus or bench fixture contains a `.dfm` or
+`.fmx` file (`find reference/golden crates/codegraph-bench/fixtures -iname '*.dfm'
+-o -iname '*.fmx'` → no matches), so the DFM extractor is unreachable for them,
+matching the frozen manifest's `#1350 → golden effect: none`. The equivalence run
+left untracked `reference/golden/ruby/colby.db-{wal,shm}`; both were deleted
+before staging and no tracked golden changed.
+
+### Negative control, EXECUTED (three mutants)
+
+Each mutant is a change to `dfm.rs` ONLY; the tests were never touched.
+
+1. `end_line` write removed (exact pre-#1350 behavior: pop and discard) →
+   `cargo test --locked -p codegraph-extract --test markup_risk_languages` →
+   **exit 101**, 1 failed:
+
+       assertion `left == right` failed: each object must span from its own header line to its own matching end
+         left: [("BottomPanel", 20, 20), ("DeepButton", 8, 8), ("DeepForm", 1, 1), ("DeepLabel", 12, 12), ("InnerPanel", 6, 6), ("Items", 22, 22), ("SiblingButton", 16, 16), ("TopPanel", 4, 4)]
+        right: [("BottomPanel", 20, 32), ("DeepButton", 8, 11), ("DeepForm", 1, 33), ("DeepLabel", 12, 14), ("InnerPanel", 6, 15), ("Items", 22, 31), ("SiblingButton", 16, 18), ("TopPanel", 4, 19)]
+
+2. `end_line = line_num - 1` (off-by-one at the terminator) → **exit 101**,
+   1 failed — proof the exact terminator line is pinned, not merely "some larger
+   number":
+
+       assertion `left == right` failed: each object must span from its own header line to its own matching end
+         left: [("BottomPanel", 20, 31), ("DeepButton", 8, 10), ("DeepForm", 1, 32), ("DeepLabel", 12, 13), ("InnerPanel", 6, 14), ("Items", 22, 30), ("SiblingButton", 16, 17), ("TopPanel", 4, 18)]
+        right: [("BottomPanel", 20, 32), ("DeepButton", 8, 11), ("DeepForm", 1, 33), ("DeepLabel", 12, 14), ("InnerPanel", 6, 15), ("Items", 22, 31), ("SiblingButton", 16, 18), ("TopPanel", 4, 19)]
+
+3. Unterminated objects post-patched to reach the file end (the tempting
+   "fill in a plausible span" design) → **exit 101**, and it reddens a
+   DIFFERENT test, so a partial regression cannot hide:
+
+       assertion `left == right` failed: an unterminated object must not fabricate a span
+         left: [("BrokenForm", 1, 8), ("LostButton", 5, 8), ("OrphanPanel", 3, 8)]
+        right: [("BrokenForm", 1, 1), ("LostButton", 5, 5), ("OrphanPanel", 3, 3)]
+
+Restored after each mutant by copying back the green file; restored SHA-256 of
+`crates/codegraph-extract/src/embedded/dfm.rs`:
+`a8c3db6949c395071b5ecabc7c74a80515927d23c84cd2d0b59afbaa4c1a86ab`.
+Re-run with the fix restored → exit 0, 9 passed.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, run before every Cargo
+  batch; every Cargo command used `--locked`.
+- `cargo build --locked -p codegraph-rs` → exit 0 (binary used for the SQLite
+  ground-truth measurements above, pre- and post-change).
+- `cargo test --locked -p codegraph-extract --test markup_risk_languages` →
+  exit 0, 9 passed.
+- `cargo test --locked -p codegraph-extract` (whole crate) → exit 0, all suites
+  green (382 lib tests + integration suites).
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, fixtures, this prose, then `make fmt`); result recorded
+  below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+Determinism: the fix adds no map iteration and no new sort — objects are still
+emitted in source-line order and the `end_line` write targets an already-fixed
+index, so output ordering is unchanged.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
+no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
+changed. No native Windows/MSVC runtime validation is claimed — everything above
+ran on Linux.

From 063604d6eab3742827edd87bfae4c7ffbd3f70ca Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 13:44:50 +0800
Subject: [PATCH 56/91] fix(extract): recognize both mapper dialects and
 resolve qualified refids

---
 .../codegraph-extract/src/embedded/mybatis.rs |  50 ++-
 .../tests/embedded_languages.rs               |  99 ++++++
 .../tests/fixtures/legacy_sqlmap.xml          |  13 +
 .../tests/fixtures/qualified_mapper.xml       |  16 +
 .../tests/golden_resolution.rs                | 102 ++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 311 ++++++++++++++++++
 6 files changed, 578 insertions(+), 13 deletions(-)
 create mode 100644 crates/codegraph-extract/tests/fixtures/legacy_sqlmap.xml
 create mode 100644 crates/codegraph-extract/tests/fixtures/qualified_mapper.xml

diff --git a/crates/codegraph-extract/src/embedded/mybatis.rs b/crates/codegraph-extract/src/embedded/mybatis.rs
index a5fe067..8911759 100644
--- a/crates/codegraph-extract/src/embedded/mybatis.rs
+++ b/crates/codegraph-extract/src/embedded/mybatis.rs
@@ -35,19 +35,28 @@ impl<'a> MyBatisExtractor<'a> {
         result
     }
 
+    /// Locates the mapper root element and its namespace.
+    ///
+    /// Both dialect forms are accepted: the MyBatis `<mapper namespace="…">`
+    /// root and the older iBatis 2 `<sqlMap namespace="…">` root (upstream
+    /// #1182). `\b` keeps `<sqlMapConfig>` — the iBatis *config* file, which
+    /// holds no statements — from being mistaken for a statement map. The
+    /// closing tag is derived from whichever root matched, so the body window
+    /// ends at the real root close instead of a hard-coded `</mapper>`.
     fn find_mapper_root(&self) -> Option<(String, usize, usize)> {
-        let open_re = Regex::new(r#"<mapper\b([^>]*)>"#).unwrap();
+        let open_re = Regex::new(r#"<(mapper|sqlMap)\b([^>]*)>"#).unwrap();
         let ns_re = Regex::new(r#"\bnamespace\s*=\s*"([^"]+)""#).unwrap();
-        let open = open_re.find(self.source)?;
-        let attrs = open_re
-            .captures(open.as_str())
-            .and_then(|cap| cap.get(1).map(|m| m.as_str().to_string()))?;
+        let open = open_re.captures(self.source)?;
+        let matched = open.get(0)?;
+        let root_tag = open.get(1)?.as_str();
+        let attrs = open.get(2).map_or("", |m| m.as_str());
         let namespace = ns_re
-            .captures(&attrs)
+            .captures(attrs)
             .and_then(|cap| cap.get(1).map(|m| m.as_str().to_string()))?;
-        let body_start = open.end();
+        let body_start = matched.end();
+        let close_tag = format!("</{root_tag}>");
         let body_end = self.source[body_start..]
-            .find("</mapper>")
+            .find(&close_tag)
             .map_or(self.source.len(), |idx| body_start + idx);
         Some((namespace, body_start, body_end))
     }
@@ -132,11 +141,7 @@ impl<'a> MyBatisExtractor<'a> {
         for cap in include_re.captures_iter(elem_body) {
             let full = cap.get(0).unwrap();
             let refid = cap.get(1).unwrap().as_str();
-            let ref_qualified = if refid.contains('.') {
-                refid.replace('.', "::")
-            } else {
-                format!("{namespace}::{refid}")
-            };
+            let ref_qualified = qualify_refid(namespace, refid);
             let line = line_number_for_offset(&self.line_starts, elem_body_abs + full.start());
             result.unresolved_references.push(unresolved_ref(
                 node_id,
@@ -151,6 +156,25 @@ impl<'a> MyBatisExtractor<'a> {
     }
 }
 
+/// Builds the `{namespace}::{id}` reference name a `<sql>` fragment node
+/// carries, from an `<include refid="…">` value (upstream #1209).
+///
+/// A bare `refid` is local to the enclosing mapper. A QUALIFIED `refid` names
+/// the owning namespace, and only its LAST dotted segment is the fragment id —
+/// the rest is the namespace, whose own dots are preserved, because that is
+/// exactly the `qualified_name` the fragment node stores
+/// (`com.example.UserMapper` + `::` + `baseColumns`). Rewriting every dot to
+/// `::` would produce a name no node carries, and dropping the namespace would
+/// let a same-`id` fragment in another namespace answer the include.
+fn qualify_refid(namespace: &str, refid: &str) -> String {
+    match refid.rsplit_once('.') {
+        Some((owner, fragment)) if !owner.is_empty() && !fragment.is_empty() => {
+            format!("{owner}::{fragment}")
+        }
+        _ => format!("{namespace}::{refid}"),
+    }
+}
+
 fn build_signature(elem_type: &str, attrs: &str) -> String {
     if elem_type == "sql" {
         return "<sql>".to_string();
diff --git a/crates/codegraph-extract/tests/embedded_languages.rs b/crates/codegraph-extract/tests/embedded_languages.rs
index b2326fa..df5d336 100644
--- a/crates/codegraph-extract/tests/embedded_languages.rs
+++ b/crates/codegraph-extract/tests/embedded_languages.rs
@@ -118,6 +118,105 @@ fn mybatis_extracts_mapper_methods_and_include_refs_on_original_lines() {
     println!("mybatis original-line assertions passed");
 }
 
+#[test]
+fn mybatis_accepts_the_ibatis_sqlmap_root_form() {
+    // Upstream #1182: the iBatis 2 `<sqlMap namespace="…">` root carries the same
+    // statement elements as MyBatis `<mapper>`; before this port the root regex
+    // only matched `<mapper`, so a `.xml` sqlMap produced ONLY a file node.
+    let result = extract_fixture("legacy_sqlmap.xml", Some(Language::Xml));
+    assert_no_errors(&result);
+
+    assert_node(&result, NodeKind::File, "legacy_sqlmap.xml", 1);
+    assert_node(&result, NodeKind::Method, "legacyColumns", 4);
+    assert_node(&result, NodeKind::Method, "legacySelect", 7);
+    assert_node(&result, NodeKind::Method, "legacyUpdate", 10);
+
+    let select = result
+        .nodes
+        .iter()
+        .find(|node| node.name == "legacySelect")
+        .expect("legacySelect node");
+    assert_eq!(select.qualified_name, "Legacy.AccountMap::legacySelect");
+    assert_ref(
+        &result,
+        EdgeKind::References,
+        "Legacy.AccountMap::legacyColumns",
+        8,
+    );
+}
+
+#[test]
+fn mybatis_ignores_the_ibatis_sqlmapconfig_root() {
+    // `<sqlMapConfig>` is the iBatis *config* file: it only points at the real
+    // statement maps, so the `\b` in the root regex must keep the `sqlMap` prefix
+    // of its name from being read as a statement-map root. The stray `<select>`
+    // is the hostile part: without the word boundary the config becomes a root
+    // whose body runs to EOF and that statement gets attributed to it.
+    let source = concat!(
+        "<sqlMapConfig namespace=\"Config\">\n",
+        "  <sqlMap resource=\"Legacy.xml\" />\n",
+        "  <select id=\"strayStatement\">SELECT 1</select>\n",
+        "</sqlMapConfig>\n",
+    );
+    let result = extract_source("sqlMapConfig.xml", source, Some(Language::Xml));
+    assert_no_errors(&result);
+    assert_eq!(
+        result.nodes.len(),
+        1,
+        "sqlMapConfig keeps only the file node; nodes={:#?}",
+        result.nodes
+    );
+    assert_eq!(result.nodes[0].kind, NodeKind::File);
+}
+
+#[test]
+fn mybatis_qualified_refid_keeps_its_namespace_and_only_splits_the_fragment_id() {
+    // Upstream #1209: a namespace-qualified `refid` must become the exact
+    // `{namespace}::{id}` the `<sql>` node carries — every dot BEFORE the last one
+    // belongs to the namespace. Rewriting them all to `::` produced
+    // `com::example::UserMapper::baseColumns`, a name no node has, so the include
+    // stayed unresolved.
+    let result = extract_fixture("qualified_mapper.xml", Some(Language::Xml));
+    assert_no_errors(&result);
+
+    assert_node(&result, NodeKind::Method, "baseColumns", 4);
+    assert_ref(
+        &result,
+        EdgeKind::References,
+        "com.example.UserMapper::baseColumns",
+        8,
+    );
+    assert_ref(
+        &result,
+        EdgeKind::References,
+        "com.example.OrderMapper::orderColumns",
+        14,
+    );
+
+    let bare = result
+        .unresolved_references
+        .iter()
+        .find(|reference| reference.line == 8)
+        .expect("bare refid on line 8");
+    let qualified = result
+        .unresolved_references
+        .iter()
+        .find(|reference| reference.line == 11)
+        .expect("qualified refid on line 11");
+    assert_eq!(
+        bare.reference_name, qualified.reference_name,
+        "a bare refid and the same fragment written out in full must name one node"
+    );
+    assert!(
+        !result
+            .unresolved_references
+            .iter()
+            .any(|reference| reference.reference_name.starts_with("com::example")),
+        "namespace dots must survive; refs={:#?}",
+        result.unresolved_references
+    );
+}
+
 #[test]
 fn astro_extracts_frontmatter_scripts_and_template_refs_on_original_lines() {
     // Mirrors upstream extraction/astro-extractor.ts:48-69,123-235.
diff --git a/crates/codegraph-extract/tests/fixtures/legacy_sqlmap.xml b/crates/codegraph-extract/tests/fixtures/legacy_sqlmap.xml
new file mode 100644
index 0000000..c099b94
--- /dev/null
+++ b/crates/codegraph-extract/tests/fixtures/legacy_sqlmap.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sqlMap PUBLIC "-//iBATIS.com//DTD SQL Map 2.0//EN" "http://ibatis.apache.org/dtd/sql-map-2.dtd">
+<sqlMap namespace="Legacy.AccountMap">
+  <sql id="legacyColumns">
+    account_id, balance
+  </sql>
+  <select id="legacySelect" parameterType="int" resultType="Account">
+    SELECT <include refid="legacyColumns"/> FROM accounts WHERE account_id = #{id}
+  </select>
+  <update id="legacyUpdate">
+    UPDATE accounts SET balance = #{balance} WHERE account_id = #{id}
+  </update>
+</sqlMap>
diff --git a/crates/codegraph-extract/tests/fixtures/qualified_mapper.xml b/crates/codegraph-extract/tests/fixtures/qualified_mapper.xml
new file mode 100644
index 0000000..55d63ff
--- /dev/null
+++ b/crates/codegraph-extract/tests/fixtures/qualified_mapper.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.example.UserMapper">
+  <sql id="baseColumns">
+    id, name
+  </sql>
+  <select id="findLocal" resultType="User">
+    SELECT <include refid="baseColumns"/> FROM users
+  </select>
+  <select id="findSelfQualified" resultType="User">
+    SELECT <include refid="com.example.UserMapper.baseColumns"/> FROM users
+  </select>
+  <select id="findForeign" resultType="User">
+    SELECT <include refid="com.example.OrderMapper.orderColumns"/> FROM users
+  </select>
+</mapper>
diff --git a/crates/codegraph-resolve/tests/golden_resolution.rs b/crates/codegraph-resolve/tests/golden_resolution.rs
index f987e75..59be0e6 100644
--- a/crates/codegraph-resolve/tests/golden_resolution.rs
+++ b/crates/codegraph-resolve/tests/golden_resolution.rs
@@ -124,6 +124,7 @@ fn resolve_fixture(test_name: &str, root: &Path, relative_files: &[&str]) -> Vec
             Some("java") => Language::Java,
             Some("cpp") => Language::Cpp,
             Some("php") => Language::Php,
+            Some("xml") => Language::Xml,
             other => panic!("unexpected fixture extension {other:?}"),
         };
         store
@@ -667,3 +668,104 @@ fn php_this_prop_interface_typed_resolves_via_conformance() {
         "expected run→Handler::handle conformance edge, got: {resolved:#?}"
     );
 }
+
+#[test]
+fn mybatis_qualified_refid_resolves_across_namespaces_and_rejects_the_decoy() {
+    // #1209 end-to-end: an `<include refid="com.example.OrderMapper.orderColumns">`
+    // must reach the `<sql>` fragment in THAT namespace. The decoy is a second
+    // `baseColumns` fragment in OrderMapper carrying the same `id` as UserMapper's:
+    // a match on the bare id alone can pick either one, so the include that names
+    // OrderMapper explicitly must land on OrderMapper's node and the bare one must
+    // stay inside its own mapper.
+    let dir = fresh_fixture_dir("mybatis-qualified-refid");
+    std::fs::write(
+        dir.join("src/UserMapper.xml"),
+        concat!(
+            "<mapper namespace=\"com.example.UserMapper\">\n",
+            "  <sql id=\"baseColumns\">id, name</sql>\n",
+            "  <select id=\"findLocal\" resultType=\"User\">\n",
+            "    SELECT <include refid=\"baseColumns\"/> FROM users\n",
+            "  </select>\n",
+            "  <select id=\"findForeign\" resultType=\"User\">\n",
+            "    SELECT <include refid=\"com.example.OrderMapper.orderColumns\"/> FROM users\n",
+            "  </select>\n",
+            "  <select id=\"findDecoy\" resultType=\"User\">\n",
+            "    SELECT <include refid=\"com.example.OrderMapper.baseColumns\"/> FROM users\n",
+            "  </select>\n",
+            "  <select id=\"findMissing\" resultType=\"User\">\n",
+            "    SELECT <include refid=\"com.example.NopeMapper.baseColumns\"/> FROM users\n",
+            "  </select>\n",
+            "</mapper>\n",
+        ),
+    )
+    .expect("write UserMapper.xml");
+    std::fs::write(
+        dir.join("src/OrderMapper.xml"),
+        concat!(
+            "<mapper namespace=\"com.example.OrderMapper\">\n",
+            "  <sql id=\"baseColumns\">order_id, total</sql>\n",
+            "  <sql id=\"orderColumns\">order_id</sql>\n",
+            "</mapper>\n",
+        ),
+    )
+    .expect("write OrderMapper.xml");
+
+    let user = codegraph_extract::extract_file(&dir, "src/UserMapper.xml").expect("extract user");
+    let order =
+        codegraph_extract::extract_file(&dir, "src/OrderMapper.xml").expect("extract order");
+    let resolved = resolve_fixture(
+        "mybatis-qualified-refid",
+        &dir,
+        &["src/OrderMapper.xml", "src/UserMapper.xml"],
+    );
+    let _ = std::fs::remove_dir_all(&dir);
+
+    let node_id = |result: &codegraph_core::types::ExtractionResult, qualified: &str| -> String {
+        result
+            .nodes
+            .iter()
+            .find(|n| n.qualified_name == qualified)
+            .unwrap_or_else(|| panic!("missing node {qualified}; nodes={:#?}", result.nodes))
+            .id
+            .clone()
+    };
+    let user_base = node_id(&user, "com.example.UserMapper::baseColumns");
+    let order_base = node_id(&order, "com.example.OrderMapper::baseColumns");
+    let order_columns = node_id(&order, "com.example.OrderMapper::orderColumns");
+    let find_local = node_id(&user, "com.example.UserMapper::findLocal");
+    let find_foreign = node_id(&user, "com.example.UserMapper::findForeign");
+    let find_decoy = node_id(&user, "com.example.UserMapper::findDecoy");
+    let find_missing = node_id(&user, "com.example.UserMapper::findMissing");
+    assert_ne!(
+        user_base, order_base,
+        "the decoy must be a genuinely different node than UserMapper's fragment"
+    );
+
+    let target_of = |source: &str| -> Option<String> {
+        resolved
+            .iter()
+            .find(|e| e.kind == codegraph_core::types::EdgeKind::References && e.source == source)
+            .map(|e| e.target.clone())
+    };
+
+    assert_eq!(
+        target_of(&find_local).as_deref(),
+        Some(user_base.as_str()),
+        "a bare refid stays inside its own mapper, not the same-id decoy; edges={resolved:#?}"
+    );
+    assert_eq!(
+        target_of(&find_foreign).as_deref(),
+        Some(order_columns.as_str()),
+        "a qualified refid must cross into the named namespace; edges={resolved:#?}"
+    );
+    assert_eq!(
+        target_of(&find_decoy).as_deref(),
+        Some(order_base.as_str()),
+        "the qualified refid names OrderMapper, so the OrderMapper fragment wins over the same-id UserMapper one; edges={resolved:#?}"
+    );
+    assert_eq!(
+        target_of(&find_missing),
+        None,
+        "a refid naming a namespace that does not exist must emit NO edge rather than binding an arbitrary same-named fragment; edges={resolved:#?}"
+    );
+}
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e41725b..57db9fb 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -5600,3 +5600,314 @@ must be inside request cwd`); locked Cargo clippy/test is the honest fallback an
 no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
 changed. No native Windows/MSVC runtime validation is claimed — everything above
 ran on Linux.
+
+## Batch D3 — both mapper dialects are recognized and a qualified `refid` keeps its namespace (2026-07-28)
+
+Ports upstream issues **#1182** (MyBatis/iBatis mapper forms) and **#1209**
+(qualified `<include refid>` resolution) as ONE commit: they share the single
+extractor `crates/codegraph-extract/src/embedded/mybatis.rs`, and the frozen
+manifest lists them as one row (`| #1182/#1209 | PORT | Batch D3 MyBatis/iBatis
+forms and qualified refids | none |`).
+
+Investigated first, then MEASURED against real indexed database state. BOTH
+halves were real defects — neither was already correct.
+
+### The located logic, quoted
+
+**Dialect detection** — `mybatis.rs:38-53` (pre-change). One literal root tag,
+and a hard-coded closing tag independent of it:
+
+```rust
+fn find_mapper_root(&self) -> Option<(String, usize, usize)> {
+    let open_re = Regex::new(r#"<mapper\b([^>]*)>"#).unwrap();
+    let ns_re = Regex::new(r#"\bnamespace\s*=\s*"([^"]+)""#).unwrap();
+    let open = open_re.find(self.source)?;
+    …
+    let body_end = self.source[body_start..]
+        .find("</mapper>")
+        .map_or(self.source.len(), |idx| body_start + idx);
+```
+
+`extract` calls it with `if let Some(…) = self.find_mapper_root()`, so a root
+that is not literally `<mapper` yields `None` and the whole mapper body is
+skipped — the file node is the only output.
+
+**`refid` matching** — `mybatis.rs:131-150` (pre-change). Any dot at all meant
+"rewrite every dot to `::`":
+
+```rust
+let ref_qualified = if refid.contains('.') {
+    refid.replace('.', "::")
+} else {
+    format!("{namespace}::{refid}")
+};
+```
+
+The nodes it must match are built at `mybatis.rs:95` as
+`let qualified = format!("{namespace}::{id}");` — the namespace keeps its OWN
+dots. So `com.example.UserMapper.baseColumns` became
+`com::example::UserMapper::baseColumns`, which no node carries.
+
+### The measured Red (SQLite ground truth, pre-change binary)
+
+Scratch project `/tmp/d3pre` — a MyBatis mapper with five statements (bare
+refid, self-qualified refid, foreign-namespace refid, a DECOY refid naming
+another namespace's same-`id` fragment, and an unresolvable refid), a second
+mapper owning the decoy, and an iBatis `<sqlMap>` file. Built from
+`crates/codegraph-extract/src/embedded/mybatis.rs` SHA-256
+`725e83497536a315463da4318dbd8417a50a0fde27d9117d32f7549e2fc9f0a4`.
+
+`select kind, name, qualified_name, start_line, end_line, file_path from nodes
+order by file_path, start_line;`
+
+```
+file|LegacySqlMap.xml|src/LegacySqlMap.xml|1|11|src/LegacySqlMap.xml
+file|OrderMapper.xml|src/OrderMapper.xml|1|10|src/OrderMapper.xml
+method|baseColumns|com.example.OrderMapper::baseColumns|3|5|src/OrderMapper.xml
+method|orderColumns|com.example.OrderMapper::orderColumns|6|8|src/OrderMapper.xml
+file|UserMapper.xml|src/UserMapper.xml|1|22|src/UserMapper.xml
+method|baseColumns|com.example.UserMapper::baseColumns|3|5|src/UserMapper.xml
+method|findLocal|com.example.UserMapper::findLocal|6|8|src/UserMapper.xml
+method|findQualified|com.example.UserMapper::findQualified|9|11|src/UserMapper.xml
+method|findCross|com.example.UserMapper::findCross|12|14|src/UserMapper.xml
+method|findDecoy|com.example.UserMapper::findDecoy|15|17|src/UserMapper.xml
+method|findMissing|com.example.UserMapper::findMissing|18|20|src/UserMapper.xml
+```
+
+RED #1 (#1182): `src/LegacySqlMap.xml` contributes ONLY a file node. Its
+`<sql id="legacyColumns">` and `<select id="legacySelect">` produce nothing —
+the iBatis form is invisible.
+
+`select kind, source, target, line from edges where kind!='contains' order by
+source;`
+
+```
+references|method:bf6ee95a109cb69fa818daa03aa4122e|method:828b1d45f6bc1f7b0562a33ab633f28a|7
+```
+
+RED #2 (#1209): exactly ONE include edge — the bare `refid` on line 7. All three
+namespace-qualified includes produce no edge at all.
+
+`select reference_name, line, file_path from unresolved_refs order by file_path,
+line;`
+
+```
+com::example::UserMapper::baseColumns|10|src/UserMapper.xml
+com::example::OrderMapper::orderColumns|13|src/UserMapper.xml
+com::example::OrderMapper::baseColumns|16|src/UserMapper.xml
+com::example::NopeMapper::baseColumns|19|src/UserMapper.xml
+```
+
+This is the direct proof of the mechanism: every qualified refid was rewritten to
+`com::example::…`, a name that matches no `qualified_name` in the graph, so all
+four stayed unresolved — including line 10, which names the fragment sitting three
+lines above it in the SAME file.
+
+### The Green (same fixtures, post-change binary)
+
+`crates/codegraph-extract/src/embedded/mybatis.rs` SHA-256
+`1550b1da1eaa6476c5b451e0f8b30aa2abe693eeccad70e08b4efa7d96f7f7ae`, scratch
+project `/tmp/d3post`, same sources.
+
+```
+file|LegacySqlMap.xml|src/LegacySqlMap.xml|1|11|src/LegacySqlMap.xml
+method|legacyColumns|Legacy::legacyColumns|4|6|src/LegacySqlMap.xml
+method|legacySelect|Legacy::legacySelect|7|9|src/LegacySqlMap.xml
+file|OrderMapper.xml|src/OrderMapper.xml|1|10|src/OrderMapper.xml
+method|baseColumns|com.example.OrderMapper::baseColumns|3|5|src/OrderMapper.xml
+method|orderColumns|com.example.OrderMapper::orderColumns|6|8|src/OrderMapper.xml
+file|UserMapper.xml|src/UserMapper.xml|1|22|src/UserMapper.xml
+method|baseColumns|com.example.UserMapper::baseColumns|3|5|src/UserMapper.xml
+method|findLocal|com.example.UserMapper::findLocal|6|8|src/UserMapper.xml
+method|findQualified|com.example.UserMapper::findQualified|9|11|src/UserMapper.xml
+method|findCross|com.example.UserMapper::findCross|12|14|src/UserMapper.xml
+method|findDecoy|com.example.UserMapper::findDecoy|15|17|src/UserMapper.xml
+method|findMissing|com.example.UserMapper::findMissing|18|20|src/UserMapper.xml
+```
+
+```
+references|method:45d8eacff46c2aeb1379cee54963b101|method:0b3a72ef37c2e01cfe46e661ff8f8df6|13
+references|method:bf6ee95a109cb69fa818daa03aa4122e|method:828b1d45f6bc1f7b0562a33ab633f28a|7
+references|method:c2ed2a8d2c281cada1850566cff7b94d|method:148f6dfc5ea8f4cef10862224874d23f|16
+references|method:d8364a506d91720a65866d24e14d1d03|method:376bcb423ecbaeef2d07eda51acfeb42|8
+references|method:d9d21bd0b97b87d2c1eff47088ee900a|method:828b1d45f6bc1f7b0562a33ab633f28a|10
+```
+
+```
+com.example.NopeMapper::baseColumns|19|src/UserMapper.xml
+```
+
+Read against the node table, each edge lands where it must:
+
+- line 7, bare `refid` → `method:828b1d45…` = `com.example.UserMapper::baseColumns`,
+  its OWN mapper's fragment, NOT the same-`id` decoy in OrderMapper.
+- line 10, self-qualified `refid` → the same `method:828b1d45…`. A bare refid and
+  the same fragment spelled out in full now name one node.
+- line 13, foreign `refid` → `method:0b3a72ef…` = `com.example.OrderMapper::orderColumns`,
+  crossing namespaces correctly.
+- line 16, the DECOY → `method:148f6dfc…` = `com.example.OrderMapper::baseColumns`.
+  The refid names OrderMapper, so OrderMapper's fragment wins over UserMapper's
+  identically-`id`'d one. A naive unqualified match cannot distinguish these two.
+- line 19, the unresolvable `refid` → **no edge**, and it stays in
+  `unresolved_refs`. It does NOT bind to either existing `baseColumns`. This
+  upholds the precedent already set by B1, C2 and A4: when the target cannot be
+  determined, emit NOTHING rather than guess among same-named candidates. A wrong
+  `include` edge is worse than a missing one.
+- `src/LegacySqlMap.xml` line 8 → `method:d8364a…` → `method:376bcb…`, the
+  iBatis fragment. The `<sqlMap>` file now contributes two method nodes
+  (`Legacy::legacyColumns`, `Legacy::legacySelect`) plus a working include.
+
+### Node-ID safety — explicit statement
+
+Node IDs are `{kind}:{sha256("{filePath}:{kind}:{name}:{line}").hex[:32]}` with
+`line` = `start_line`.
+
+**No `start_line` and no `name` changes for any node that existed before.** Diff
+the pre and post node tables above: every MyBatis node keeps its exact
+`start_line` and `name`, and the IDs are byte-identical across the two runs —
+`method:828b1d45f6bc1f7b0562a33ab633f28a`, `method:148f6dfc5ea8f4cef10862224874d23f`,
+`method:0b3a72ef37c2e01cfe46e661ff8f8df6`, `method:bf6ee95a109cb69fa818daa03aa4122e`,
+`method:45d8eacff46c2aeb1379cee54963b101`, `method:c2ed2a8d2c281cada1850566cff7b94d`,
+`method:9eb467f1b674a36bdd30b4585a09f0a9` all appear in BOTH runs.
+
+The dialect change only ADDS nodes, for `<sqlMap>` files that previously produced
+none, at their own real source lines. The refid change touches
+`unresolved_ref.reference_name` only — never a node's `name`, `start_line`, or
+kind. So this port is NOT golden-affecting, matching the frozen manifest's
+`none`.
+
+### Golden delta
+
+`GIT_MASTER=1 git diff --stat 1e1d259..HEAD -- reference/golden/` → **EMPTY**, as
+the manifest requires. No golden fixture was regenerated, and none needed to be:
+no golden corpus contains any `.xml` file (`find crates/codegraph-bench/fixtures
+-type f` yields extensions `c cfc cfm cfs cpp cu erl ets gd godot h hpp metal nix
+py rb sol tf ts tscn uid` — no `xml`), so the MyBatis extractor is not exercised
+by the equivalence oracle at all.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26/26**.
+
+### Tests added
+
+`crates/codegraph-extract/tests/embedded_languages.rs` (extraction shape):
+
+- `mybatis_accepts_the_ibatis_sqlmap_root_form` — the `<sqlMap>` fixture yields
+  its `<sql>`/`<select>`/`<update>` nodes on their real lines with
+  `Legacy.AccountMap::…` qualified names, plus a working bare-refid reference.
+- `mybatis_ignores_the_ibatis_sqlmapconfig_root` — `<sqlMapConfig>` (the iBatis
+  _config_ file, which declares no statements) must stay a file node only. The
+  fixture plants a stray `<select id="strayStatement">` inside it, so a root regex
+  without the word boundary would swallow the config as a statement map and
+  attribute that statement to it.
+- `mybatis_qualified_refid_keeps_its_namespace_and_only_splits_the_fragment_id` —
+  a qualified refid produces exactly the `{namespace}::{id}` a node carries; a
+  bare and a fully-written refid for the same fragment produce the SAME reference
+  name; no reference name starts with `com::example`.
+
+`crates/codegraph-resolve/tests/golden_resolution.rs` (end-to-end resolution
+through the real resolver):
+
+- `mybatis_qualified_refid_resolves_across_namespaces_and_rejects_the_decoy` —
+  asserts the resolved edge target node ID for each of the four cases: bare stays
+  home, foreign crosses over, the DECOY (a second `baseColumns` in another
+  namespace, asserted `assert_ne!` to be a genuinely different node) is picked by
+  namespace, and the unresolvable refid yields `None`.
+
+The resolve-side test needed `Some("xml") => Language::Xml` added to
+`resolve_fixture`'s extension map, which previously panicked on any non-listed
+extension.
+
+### Negative control, EXECUTED (three mutants, each reddening a DIFFERENT test)
+
+Each mutant is a change to `mybatis.rs` ONLY; no test was touched.
+
+1. **Dialect recognition reverted** (`<(mapper|sqlMap)\b…>` → `<(mapper)\b…>`,
+   i.e. the exact pre-#1182 root) →
+   `cargo test --locked -p codegraph-extract --test embedded_languages` →
+   **exit 101**, 1 failed —
+   `mybatis_accepts_the_ibatis_sqlmap_root_form`, and ONLY it:
+
+       panicked at crates/codegraph-extract/tests/embedded_languages.rs:264:13:
+       missing node kind=method name=legacyColumns; nodes=[
+           Node {
+               id: "file:a591d82f2d7e057a4033c2f6e60926d4",
+               kind: File,
+               name: "legacy_sqlmap.xml",
+               …
+           },
+       ]
+
+   (a single file node — the iBatis body is skipped entirely, reproducing RED #1).
+
+2. **Qualified-refid matching reverted** to the unqualified whole-string rewrite
+   (`refid.replace('.', "::")`, the exact pre-#1209 body) → reddens a DIFFERENT
+   test in each of the two suites:
+
+       panicked at crates/codegraph-extract/tests/embedded_languages.rs:278:13:
+       missing ref kind=references name=com.example.OrderMapper::orderColumns; refs=[
+           …
+           reference_name: "com::example::UserMapper::baseColumns",
+           line: 11,
+           …
+
+       panicked at crates/codegraph-resolve/tests/golden_resolution.rs:757:5:
+       assertion `left == right` failed: a qualified refid must cross into the named namespace; edges=[…]
+         left: None
+        right: Some("method:3165c21458b287c3528cdae44cbc71d4")
+
+   Both suites exit 101 with exactly 1 failure each, and neither is the test that
+   mutant 1 reddens — so a partial regression in either half cannot hide behind
+   the other.
+
+3. **Word boundary dropped** (`<(mapper|sqlMap)\b…>` → `<(mapper|sqlMap)…>`, the
+   tempting "looser is safer" design) → the two tests above still PASS, and it
+   reddens a THIRD test instead:
+
+       panicked at crates/codegraph-extract/tests/embedded_languages.rs:163:5:
+       assertion `left == right` failed: sqlMapConfig keeps only the file node; nodes=[…]
+         left: 2
+        right: 1
+
+   The extra node is the stray `<select>` inside `<sqlMapConfig>` — proof the
+   boundary is load-bearing, not decoration.
+
+Restored after each mutant by copying back the green file; restored SHA-256 of
+`crates/codegraph-extract/src/embedded/mybatis.rs`:
+`1550b1da1eaa6476c5b451e0f8b30aa2abe693eeccad70e08b4efa7d96f7f7ae`.
+Re-run with the fix restored → `embedded_languages` exit 0, 8 passed;
+`golden_resolution` exit 0, 13 passed.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, run before every Cargo
+  batch; every Cargo command used `--locked`.
+- `cargo build --locked -p codegraph-rs` → exit 0 (the binary used for the
+  SQLite ground-truth measurements above, pre- and post-change; note the package
+  is `codegraph-rs`, not `codegraph-cli`).
+- `cargo test --locked -p codegraph-extract --test embedded_languages` → exit 0,
+  8 passed.
+- `cargo test --locked -p codegraph-resolve --test golden_resolution` → exit 0,
+  13 passed.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 26/26.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, fixtures, this prose, then `make fmt`); result recorded
+  below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+Determinism: the change adds no map, no `HashMap` iteration and no new sort.
+Root detection is a single leftmost regex match; statement extraction still walks
+the body forward by byte offset; `qualify_refid` is a pure string split on the
+LAST dot. Cross-file fragment lookup is not performed in the extractor at all —
+it is the existing resolver's `match_by_qualified_name`, which already has a
+deterministic ordering rule, and the reference name this port hands it is
+identical for every run.
+
+The untracked `reference/golden/*/colby.db-{wal,shm}` files the equivalence
+oracle leaves behind were removed before staging; they are not gitignored and
+must never be committed.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); locked Cargo clippy/test is the honest fallback and
+no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
+changed. No native Windows/MSVC runtime validation is claimed — everything above
+ran on Linux.

From ecd3641eb6d23097090b6dedcf131125674d6362 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 14:34:30 +0800
Subject: [PATCH 57/91] feat(release): publish SHA256SUMS and verify it in both
 installers

---
 .github/workflows/release-please.yml      |  25 ++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 262 +++++++++++++++++
 scripts/install.ps1                       |  63 +++-
 scripts/install.sh                        |  70 ++++-
 scripts/tests/install-checksum.test.sh    | 337 ++++++++++++++++++++++
 5 files changed, 754 insertions(+), 3 deletions(-)
 create mode 100755 scripts/tests/install-checksum.test.sh

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index 421f383..0f358a9 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -302,6 +302,30 @@ jobs:
           path: dist
           merge-multiple: true
 
+      # Checksums are computed HERE, from the very same merged `dist/` that the
+      # attach step below uploads, so the sums provably describe the uploaded
+      # bytes. Determinism: `LC_ALL=C sort` on basenames gives a byte-order,
+      # locale-independent ordering; sha256sum is run with cwd=dist so each line
+      # carries the bare asset name (no `dist/` prefix); output is LF-only.
+      - name: Generate SHA256SUMS
+        shell: bash
+        working-directory: dist
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          archives=(*.tar.gz *.zip)
+          if [ "${#archives[@]}" -eq 0 ]; then
+            echo "::error::no release archives found in dist/" >&2
+            exit 1
+          fi
+          mapfile -t sorted < <(printf '%s\n' "${archives[@]}" | LC_ALL=C sort)
+          : > SHA256SUMS
+          for archive in "${sorted[@]}"; do
+            sha256sum "$archive" >> SHA256SUMS
+          done
+          echo "--- SHA256SUMS ---"
+          cat SHA256SUMS
+
       - name: Generate release notes
         uses: orhun/git-cliff-action@v4
         with:
@@ -321,6 +345,7 @@ jobs:
           files: |
             dist/*.tar.gz
             dist/*.zip
+            dist/SHA256SUMS
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 57db9fb..57fd217 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -5911,3 +5911,265 @@ must be inside request cwd`); locked Cargo clippy/test is the honest fallback an
 no LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte
 changed. No native Windows/MSVC runtime validation is claimed — everything above
 ran on Linux.
+
+## Batch E3 — release artifacts carry a checksum authority and the installers refuse unverified binaries (2026-07-28)
+
+### The defect, confirmed not assumed
+
+Release artifacts shipped with **no checksums at all**, and both one-liner
+installers downloaded an archive and immediately executed the binary out of it.
+
+```
+$ grep -rniE 'sha256|checksum|shasum|Get-FileHash' \
+    .github/workflows/release-please.yml scripts/install.sh scripts/install.ps1
+$ echo $?
+1
+```
+
+Zero matches across all three files — the workflow published nothing to verify
+against, and neither installer had anything to verify with. Read against the
+code: `upload-assets` merged every `dist-*` artifact into `dist/` and attached
+`dist/*.tar.gz` + `dist/*.zip`, nothing else. `scripts/install.sh` went
+`download "$url" "$tmp/$asset"` → `tar -xzf` → `mv` → `chmod +x` →
+`"$install_dir/$BIN" --version`, executing whatever bytes arrived. `install.ps1`
+went `Invoke-WebRequest -OutFile $zipPath` → `Expand-Archive` → `& $exePath
+--version`. A corrupted download, a truncated transfer, or a substituted asset
+was indistinguishable from a good one, and the failure mode was _executing it_.
+
+### The fix
+
+Three coordinated changes, one commit:
+
+1. **`.github/workflows/release-please.yml` — a new `Generate SHA256SUMS` step**
+   inside `upload-assets`, placed after `Download artifacts` and before the
+   attach step, with `working-directory: dist`. It hashes the archives of that
+   very merged `dist/` and writes `dist/SHA256SUMS`; the same step's output is
+   echoed into the job log. `dist/SHA256SUMS` is then added to the existing
+   `softprops/action-gh-release@v2` step's `files:` list, so it lands on the SAME
+   still-draft Release as the archives it describes. No new job, no second
+   artifact download — the sums provably describe the uploaded bytes because they
+   are computed from them.
+
+2. **`scripts/install.sh` — an integrity gate before extraction.** It resolves a
+   hashing tool once (`sha256sum`, else `shasum -a 256`), derives
+   `sums_url="${release_base}/SHA256SUMS"` from the SAME `release_base` the
+   archive URL is built from (so the sums always come from the same tag), matches
+   its own asset's line, and compares. The gate sits between `download` and
+   `tar -xzf`: an unverified archive is never unpacked and its binary is never
+   executed.
+
+3. **`scripts/install.ps1` — the same gate** via `Get-FileHash -Algorithm
+SHA256`, placed between `Invoke-WebRequest` and `Expand-Archive`, with a
+   `Assert-CanSkipVerification` helper mirroring the shell `cannot_verify`.
+
+### Determinism of `SHA256SUMS` — how it is guaranteed
+
+- **Ordering**: the filename list is piped through **`LC_ALL=C sort`**. `LC_ALL=C`
+  forces byte-order collation, so the ordering does not depend on the runner's
+  locale (a `en_US.UTF-8` runner and a `C` runner produce the same sequence).
+  Shell glob order alone was not trusted for this.
+- **Names**: `sha256sum` is invoked with `working-directory: dist`, so every line
+  carries the bare asset basename. There is no `dist/` prefix and no absolute
+  path, which is exactly what a client that downloaded a single asset can match
+  against.
+- **Format**: plain `sha256sum` output — `<64-hex><two spaces><name>` — so the
+  file is directly consumable by `sha256sum -c SHA256SUMS`.
+- **Line endings**: LF only. The file is produced by `sha256sum` on an
+  `ubuntu-latest` runner and never round-tripped through a Windows tool.
+- **Empty input is an error, not an empty file**: `nullglob` plus an explicit
+  `${#archives[@]} -eq 0` check makes a missing-artifacts situation fail the job
+  with `::error::no release archives found in dist/`, instead of quietly
+  publishing an empty authority that every client would then treat as
+  "unverifiable".
+
+Proven locally by replaying the exact step body against a six-archive fake
+`dist/` (`/tmp/e3-dist`):
+
+```
+e06c0482dc6da332be84c68951e1756bac63cffedc12f5c1b31c6a533d35a386  codegraph-9.9.9-aarch64-apple-darwin.tar.gz
+1ff30088da0b1a6741a52e564af76c5bd670ade89785126af08210e4f94f1d81  codegraph-9.9.9-aarch64-pc-windows-msvc.zip
+5d8ed155c442b58ab95e0fb2f4bfa136ed1b13b077363a7ff3ae8989780e4e27  codegraph-9.9.9-aarch64-unknown-linux-musl.tar.gz
+929d1ee5ff7c3309238ce8c62b39d41bd3f5aad6132fad860a8454ced2949da8  codegraph-9.9.9-x86_64-apple-darwin.tar.gz
+d4db99a2ab23ae7a094367d227c56edfde05211e1d52f2295ef0098bfa949bd6  codegraph-9.9.9-x86_64-pc-windows-msvc.zip
+b88c456b823f476789e8fa7a8938314872cad3cc7131d4d1efd12021f88e7aa0  codegraph-9.9.9-x86_64-unknown-linux-musl.tar.gz
+```
+
+- run under `LC_ALL=C` and again under `LC_ALL=en_US.UTF-8` → `diff` **IDENTICAL**,
+  both files hashing to `5488b0cd60d0a592183bbd43f20ad0663a935addbdcd02eafb6353cd8f8d3e8f`.
+- `grep -c '/'` → **0** (no path prefix). `od -c | grep -c '\r'` → **0** (LF only).
+- `sha256sum -c SHA256SUMS` → 6× `OK`, **exit 0**.
+- the same body in an empty directory → **exit 1** with the `::error::` line.
+
+### Fail closed, and what that costs
+
+The gate is **fail-closed on every unverifiable condition**, not just on a
+mismatch:
+
+| condition                                                            | behaviour                                           |
+| -------------------------------------------------------------------- | --------------------------------------------------- |
+| digest matches                                                       | install proceeds                                    |
+| digest **differs**                                                   | **hard abort**, always — the opt-out does NOT apply |
+| no `sha256sum` and no `shasum` (POSIX) / no `Get-FileHash` (Windows) | refuse, unless opt-out                              |
+| `SHA256SUMS` absent (404)                                            | refuse, unless opt-out                              |
+| `SHA256SUMS` present but has no line for this asset                  | refuse, unless opt-out                              |
+
+The opt-out is **`CODEGRAPH_SKIP_CHECKSUM`** (any non-empty value), documented in
+the header comment of both scripts. It covers only "I cannot verify"; it never
+covers "verification failed". A mismatch aborts with the expected and actual
+digests printed, whatever the environment says.
+
+**The deliberate compatibility cost**: a release cut BEFORE this change has no
+`SHA256SUMS`, so the plain one-liner will now REFUSE to install it and print the
+opt-out instruction. That is a real regression in convenience for old tags, and
+it is the intended trade. Silently skipping verification when the authority is
+missing would mean an attacker who can suppress one small file downgrades every
+client back to the pre-E3 behaviour — the check would protect nobody. This
+upholds the precedent already set on this branch by B1, C2, A4 and D3: when
+correctness cannot be established, refuse rather than guess. Refusing to install
+is recoverable in one command; executing a tampered binary is not.
+
+### Tests added — `scripts/tests/install-checksum.test.sh`
+
+An executable, **network-free** harness in the shape of
+`scripts/tests/check-workspace-versions.test.sh` (same `PASS`/`FAIL`/`ok`/`bad`
+counters, same `mktemp -d` + `trap cleanup EXIT`, same "assert the business
+diagnostic, not just the exit code" style). It runs the REAL
+`scripts/install.sh` under `env -i` with:
+
+- a **`curl` shim** first on a sandboxed `PATH` that maps any URL to
+  `$CG_TEST_RELEASE_DIR/<basename>` and exits **22** (curl's HTTP-error code)
+  when the file is absent — so no scenario touches the network, and the script's
+  own `download`/`fetch` plumbing is exercised unchanged;
+- a **sandboxed `PATH`** built from symlinks to a fixed tool list, so the
+  "no hashing tool" scenario is a _genuine absence_ rather than a stubbed
+  failure;
+- a fake release holding a real `tar.gz` (with an executable `codegraph` stub)
+  plus a decoy Windows asset, so `SHA256SUMS` is never a one-line file and
+  picking the right line actually matters.
+
+Ten assertions across eight scenarios:
+
+- **A_match** — correct digest ⇒ exit 0, binary present at the install dir,
+  `sha256: OK` reported.
+- **B_mismatch** — one digest zeroed ⇒ nonzero exit, `checksum MISMATCH`, and
+  **the binary is NOT installed**.
+- **C_mismatch_optout** — same mismatch WITH `CODEGRAPH_SKIP_CHECKSUM=1` ⇒ still
+  aborts, still nothing installed. Proves the opt-out cannot launder a mismatch.
+- **D_truncated** — `SHA256SUMS` correct, archive truncated to 64 bytes (the
+  real-world corrupt-download shape, a form NOT designed for) ⇒ abort before
+  extraction.
+- **E_notool_refuse / E_notool_optout** — no `sha256sum` on PATH ⇒ explicit
+  refusal naming `CODEGRAPH_SKIP_CHECKSUM` and no install; with the opt-out set,
+  exit 0 with an `UNVERIFIED binary` warning.
+- **F_nosums_refuse / F_nosums_optout** — no `SHA256SUMS` published at all (the
+  pre-E3 release shape) ⇒ refusal; installable only under the opt-out.
+- **G_no_entry** — `SHA256SUMS` present and well-formed but with our asset's line
+  removed ⇒ refusal. A sums file that simply omits your asset must not read as a
+  pass.
+- **H_crlf** — correct digests with CRLF line endings ⇒ accepted. Line endings
+  must not silently turn a good release into an unverifiable one.
+
+D, G and H are deliberately shapes the implementation was not designed around,
+per the lesson that got an earlier commit on this branch rejected: a fixture
+holding only the author's intended shape proves nothing.
+
+### Negative control, EXECUTED — four mutants, each reddening a DIFFERENT scenario
+
+Each mutant edits `scripts/install.sh` only; no test file was touched.
+
+1. **Whole verification block deleted** (the exact pre-E3 flow: download then
+   `tar -xzf`) → **21 failures**, including the ones that matter most:
+
+       FAIL: B_mismatch: expected a NONZERO exit, got 0
+       FAIL: B_mismatch: binary WAS installed despite a failed verification
+       FAIL: G_no_entry: binary WAS installed despite a failed verification
+       FAIL: E_notool_refuse: binary WAS installed despite a failed verification
+       === harness result: 0 passed, 21 failed ===
+
+   `A_match` also loses its `sha256: OK` assertion. This is the defect itself,
+   reproduced.
+
+2. **`cannot_verify` downgraded to a silent `return 0`** — i.e. the FORBIDDEN
+   "just skip it if you can't check" design → the mismatch tests still pass, and
+   it reddens the three _unverifiable_ scenarios instead:
+
+       FAIL: E_notool_refuse: expected a NONZERO exit, got 0
+       FAIL: F_nosums_refuse: expected a NONZERO exit, got 0
+       FAIL: G_no_entry: expected a NONZERO exit, got 0
+       FAIL: G_no_entry: binary WAS installed despite a failed verification
+       === harness result: 7 passed, 10 failed ===
+
+3. **Mismatch routed through the opt-out** (a plausible "be lenient" change) →
+   the unverifiable scenarios stay green and it reddens a different trio:
+
+       FAIL: B_mismatch: expected diagnostic /checksum MISMATCH/ on stderr
+       FAIL: C_mismatch_optout: expected diagnostic /checksum MISMATCH/ on stderr
+       FAIL: D_truncated: expected diagnostic /checksum MISMATCH/ on stderr
+       === harness result: 7 passed, 3 failed ===
+
+4. **CRLF tolerance dropped** (`tr -d '\r'` removed — the "obviously
+   unnecessary" guard) → everything else stays green and exactly one scenario
+   goes red:
+
+       FAIL: H_crlf: expected exit 0, got 1
+         stderr: … error: cannot verify the download: SHA256SUMS has no entry for
+                 codegraph-9.9.9-x86_64-unknown-linux-musl.tar.gz | error: refusing
+                 to install an unverified binary. …
+       FAIL: H_crlf: expected the binary at …/H_crlf.dest/codegraph, it is absent
+       === harness result: 9 passed, 3 failed ===
+
+   Note the failure mode: a CRLF sums file would make a PERFECTLY GOOD release
+   look unverifiable and block every install. The `tr -d '\r'` is load-bearing.
+
+Four mutants, four disjoint red sets — no partial regression in this gate can
+hide behind another part of it. Restored by copying back the green file; restored
+`scripts/install.sh` SHA-256
+`5f35d096b95a2f2824cad06f8057b98a397a477988b421cd6a319722672e6418`, and the
+harness re-run green: **10 passed, 0 failed, exit 0**.
+
+### Windows — UNVERIFIED AT RUNTIME
+
+`scripts/install.ps1` was changed by **code inspection only**. This host is
+Linux; no PowerShell is available, so the `Get-FileHash` path, the
+`Invoke-WebRequest` 404 `catch`, and `Assert-CanSkipVerification` were NOT
+executed. No native Windows/MSVC runtime validation is claimed. What was checked
+by reading: the gate sits between `Invoke-WebRequest` and `Expand-Archive`;
+`$ErrorActionPreference = 'Stop'` plus `throw` gives the hard abort;
+`-ine` compares the hex case-insensitively (`Get-FileHash` returns UPPERCASE,
+`sha256sum` writes lowercase — a case-sensitive `-ne` here would have been a
+false mismatch on every single install); `Get-Content` drops the line ending so
+CRLF is handled, and `.TrimStart('*')` covers the BSD marker, mirroring the shell
+side. Runtime confirmation on Windows is deferred to the next real release run.
+
+### Golden delta
+
+`GIT_MASTER=1 git diff --stat 063604d..HEAD -- reference/golden/` → **EMPTY**.
+Nothing in this commit touches extraction, resolution, or any fixture: the diff
+is two shell/PowerShell installers, one workflow job step, one new test harness,
+and this prose. No golden was regenerated and none needed to be.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0, **26/26**.
+
+### Verification (actual exit statuses)
+
+- `grep -rniE 'sha256|checksum|shasum|Get-FileHash' <workflow> <install.sh> <install.ps1>`
+  on the pre-change tree → exit **1**, zero matches (the defect proof above).
+- `bash scripts/tests/install-checksum.test.sh` → exit **0**, 10 passed, 0 failed.
+- `python3 -c "yaml.safe_load(...)"` on `release-please.yml` → parses; the
+  `upload-assets` step list is `Checkout code, Download artifacts, Generate
+SHA256SUMS, Generate release notes, Attach assets to GitHub Release` and
+  `files:` is `dist/*.tar.gz\ndist/*.zip\ndist/SHA256SUMS\n`.
+- `sha256sum -c SHA256SUMS` on the replayed six-archive `dist/` → exit **0**.
+- `bash scripts/check-workspace-versions.sh` → run before every Cargo batch;
+  result recorded below. Every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-bench --test equivalence` → recorded below.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, this prose, then `make fmt`); recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+  No dependency and no version byte changed; release-please still owns versions.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path
+must be inside request cwd`); no LSP-clean result is claimed. The changed files
+are shell, PowerShell and YAML, which the Rust toolchain does not lint anyway —
+the honest checks for them are the executable harness, the YAML parse, and the
+replayed workflow step above.
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index fba0553..00ec2f2 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -6,9 +6,18 @@
 .DESCRIPTION
     irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex
 
-    Env overrides:
+      Env overrides:
       CODEGRAPH_VERSION      pin a release (e.g. 0.4.0 or v0.4.0); default: latest
       CODEGRAPH_INSTALL_DIR  install destination; default: %LOCALAPPDATA%\Programs\codegraph
+      CODEGRAPH_SKIP_CHECKSUM
+                             set to any non-empty value to proceed when the
+                             download CANNOT be verified — i.e. Get-FileHash is
+                             unavailable, or the release has no usable
+                             SHA256SUMS (releases cut before checksums were
+                             published). Without it the installer REFUSES to
+                             install rather than run an unverified binary. It
+                             never bypasses a checksum MISMATCH — a mismatch
+                             always aborts.
 #>
 
 $ErrorActionPreference = 'Stop'
@@ -59,8 +68,22 @@ if ($env:CODEGRAPH_VERSION) {
     $version = $tag -replace '^v', ''
 }
 
+$sums = 'SHA256SUMS'
 $asset = "$Bin-$version-$target.$ext"
-$url = "https://github.com/$Repo/releases/download/v$version/$asset"
+$releaseBase = "https://github.com/$Repo/releases/download/v$version"
+$url = "$releaseBase/$asset"
+$sumsUrl = "$releaseBase/$sums"
+
+# Fail closed unless the operator explicitly opted out.
+function Assert-CanSkipVerification([string]$Reason) {
+    if ($env:CODEGRAPH_SKIP_CHECKSUM) {
+        Write-Warning "Cannot verify download ($Reason)."
+        Write-Warning 'CODEGRAPH_SKIP_CHECKSUM is set — installing an UNVERIFIED binary.'
+        return
+    }
+    throw ("Cannot verify the download: $Reason. Refusing to install an unverified " +
+        'binary. To proceed anyway, set CODEGRAPH_SKIP_CHECKSUM=1.')
+}
 
 if ($env:CODEGRAPH_INSTALL_DIR) {
     $installDir = $env:CODEGRAPH_INSTALL_DIR
@@ -80,6 +103,42 @@ try {
     $headers = @{ 'User-Agent' = 'codegraph-installer' }
     Invoke-WebRequest -Uri $url -OutFile $zipPath -Headers $headers
 
+    # Integrity gate — runs BEFORE Expand-Archive, so an unverified archive is
+    # never unpacked and its binary is never executed.
+    if (-not (Get-Command Get-FileHash -ErrorAction SilentlyContinue)) {
+        Assert-CanSkipVerification 'Get-FileHash is unavailable'
+    } else {
+        $sumsPath = Join-Path $tmp $sums
+        $sumsOk = $true
+        try {
+            Invoke-WebRequest -Uri $sumsUrl -OutFile $sumsPath -Headers $headers
+        } catch {
+            $sumsOk = $false
+        }
+        if (-not $sumsOk) {
+            Assert-CanSkipVerification "could not download $sumsUrl"
+        } else {
+            # Each line is `<hex><sep><name>`; tolerate CRLF (Get-Content strips
+            # the line ending) and the BSD `*name` marker.
+            $expected = $null
+            foreach ($line in (Get-Content -LiteralPath $sumsPath)) {
+                $parts = $line.Trim() -split '\s+', 2
+                if ($parts.Count -ne 2) { continue }
+                if ($parts[1].TrimStart('*') -eq $asset) { $expected = $parts[0]; break }
+            }
+            if (-not $expected) {
+                Assert-CanSkipVerification "$sums has no entry for $asset"
+            } else {
+                $actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $zipPath).Hash
+                if ($actual -ine $expected) {
+                    throw ("Checksum MISMATCH for ${asset}: expected $expected, actual $actual. " +
+                        'Refusing to install a corrupted or tampered archive.')
+                }
+                Write-Host "  sha256: OK ($actual)"
+            }
+        }
+    }
+
     Expand-Archive -Path $zipPath -DestinationPath $tmp -Force
 
     $exeSrc = Join-Path $tmp "$Bin.exe"
diff --git a/scripts/install.sh b/scripts/install.sh
index 606c307..3d51362 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -6,6 +6,15 @@
 # Env overrides:
 #   CODEGRAPH_VERSION      pin a release (e.g. 0.4.0 or v0.4.0); default: latest
 #   CODEGRAPH_INSTALL_DIR  install destination; default: $HOME/.local/bin
+#   CODEGRAPH_SKIP_CHECKSUM
+#                          set to any non-empty value to proceed when the
+#                          download CANNOT be verified — i.e. no sha256 tool is
+#                          available, or the release has no usable SHA256SUMS
+#                          (releases cut before checksums were published).
+#                          This is an explicit opt-out: without it the installer
+#                          REFUSES to install rather than run an unverified
+#                          binary. It never bypasses a checksum MISMATCH — a
+#                          mismatch always aborts.
 set -eu
 
 REPO="sunerpy/codegraph-rust"
@@ -33,6 +42,34 @@ fi
 
 command -v tar >/dev/null 2>&1 || err "need tar to extract the release archive"
 
+# Pick a SHA-256 tool once, expose `sha256_of <file>` printing the bare lowercase
+# hex digest. `sha256sum` is coreutils (Linux); `shasum -a 256` is the macOS/perl
+# fallback. If neither exists, sha256_tool stays empty and verification is
+# impossible — handled explicitly at verify time, never silently skipped.
+if command -v sha256sum >/dev/null 2>&1; then
+	sha256_tool="sha256sum"
+	sha256_of() { sha256sum "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then
+	sha256_tool="shasum"
+	sha256_of() { shasum -a 256 "$1" | cut -d' ' -f1; }
+else
+	sha256_tool=""
+	sha256_of() { err "internal: sha256_of called with no hashing tool"; }
+fi
+
+# cannot_verify REASON — fail closed unless the operator explicitly opted out.
+cannot_verify() {
+	if [ "${CODEGRAPH_SKIP_CHECKSUM:-}" != "" ]; then
+		info "WARNING: cannot verify download ($1)."
+		info "WARNING: CODEGRAPH_SKIP_CHECKSUM is set — installing an UNVERIFIED binary."
+		return 0
+	fi
+	printf 'error: cannot verify the download: %s\n' "$1" >&2
+	printf 'error: refusing to install an unverified binary.\n' >&2
+	printf 'error: to proceed anyway, re-run with CODEGRAPH_SKIP_CHECKSUM=1\n' >&2
+	exit 1
+}
+
 # Detect OS.
 os=$(uname -s)
 case "$os" in
@@ -63,8 +100,11 @@ else
 	version=$(printf '%s' "$tag" | sed 's/^v//')
 fi
 
+SUMS="SHA256SUMS"
 asset="${BIN}-${version}-${target}.${ext}"
-url="https://github.com/${REPO}/releases/download/v${version}/${asset}"
+release_base="https://github.com/${REPO}/releases/download/v${version}"
+url="${release_base}/${asset}"
+sums_url="${release_base}/${SUMS}"
 
 install_dir="${CODEGRAPH_INSTALL_DIR:-$HOME/.local/bin}"
 
@@ -77,6 +117,34 @@ tmp=$(mktemp -d 2>/dev/null || mktemp -d -t codegraph)
 trap 'rm -rf "$tmp"' EXIT INT TERM
 
 download "$url" "$tmp/$asset" || err "download failed: $url"
+
+# Integrity gate — runs BEFORE extraction, so an unverified archive is never
+# unpacked and its binary is never executed.
+if [ "$sha256_tool" = "" ]; then
+	cannot_verify "no sha256sum or shasum on PATH"
+elif ! download "$sums_url" "$tmp/$SUMS" 2>/dev/null; then
+	cannot_verify "could not download $sums_url"
+else
+	# Match the asset's own line. Tolerate CRLF (a SHA256SUMS that travelled
+	# through a Windows editor) and both the `sha256sum` two-space and the
+	# `shasum`/BSD single-space-star separators.
+	expected=$(tr -d '\r' < "$tmp/$SUMS" | awk -v want="$asset" '
+		{ name = $2; sub(/^\*/, "", name); if (name == want) { print $1; exit } }')
+	if [ "${expected:-}" = "" ]; then
+		cannot_verify "$SUMS has no entry for $asset"
+	else
+		actual=$(sha256_of "$tmp/$asset")
+		if [ "$actual" != "$expected" ]; then
+			printf 'error: checksum MISMATCH for %s\n' "$asset" >&2
+			printf 'error:   expected %s\n' "$expected" >&2
+			printf 'error:   actual   %s\n' "$actual" >&2
+			printf 'error: refusing to install a corrupted or tampered archive.\n' >&2
+			exit 1
+		fi
+		info "  sha256: OK (${actual})"
+	fi
+fi
+
 tar -xzf "$tmp/$asset" -C "$tmp" || err "failed to extract $asset"
 
 [ -f "$tmp/$BIN" ] || err "archive did not contain expected binary '$BIN'"
diff --git a/scripts/tests/install-checksum.test.sh b/scripts/tests/install-checksum.test.sh
new file mode 100755
index 0000000..a7f1d8a
--- /dev/null
+++ b/scripts/tests/install-checksum.test.sh
@@ -0,0 +1,337 @@
+#!/usr/bin/env bash
+# install-checksum.test.sh — fixture harness for the installer's SHA-256 gate.
+#
+# Drives scripts/install.sh against a LOCAL fake release directory. NO network
+# access: a `curl` shim first on PATH resolves every requested URL to a file in
+# the fixture release dir (and exits 22, curl's HTTP-error code, when the file is
+# absent), so the script's own download/fetch plumbing is exercised unchanged.
+#
+# It proves the gate:
+#   * matching checksum          -> install proceeds (exit 0, binary present),
+#   * MISMATCHING checksum       -> abort (nonzero, binary ABSENT),
+#   * mismatch + opt-out set     -> STILL aborts (opt-out never bypasses a mismatch),
+#   * truncated archive          -> abort (real-world corrupt download),
+#   * no sha256 tool             -> explicit refusal; installs only with opt-out,
+#   * missing SHA256SUMS         -> explicit refusal; installs only with opt-out,
+#   * SHA256SUMS without our line-> explicit refusal,
+#   * CRLF SHA256SUMS            -> accepted (line endings must not break matching).
+#
+# Runs no Cargo and touches no repository file.
+#
+# Usage: scripts/tests/install-checksum.test.sh
+
+set -euo pipefail
+
+HARNESS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$HARNESS_DIR/../.." && pwd -P)"
+INSTALLER="$REPO_ROOT/scripts/install.sh"
+VERSION="9.9.9"
+
+[ -f "$INSTALLER" ] || {
+	printf 'harness: installer not found: %s\n' "$INSTALLER" >&2
+	exit 2
+}
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+note() { printf '  %s\n' "$1"; }
+ok() {
+	printf 'PASS: %s\n' "$1"
+	PASS=$((PASS + 1))
+}
+bad() {
+	printf 'FAIL: %s\n' "$1" >&2
+	FAIL=$((FAIL + 1))
+}
+
+# The asset name install.sh will compute on this host.
+case "$(uname -s)" in
+Linux) OS_PART="unknown-linux-musl" ;;
+Darwin) OS_PART="apple-darwin" ;;
+*)
+	printf 'harness: unsupported host OS %s\n' "$(uname -s)" >&2
+	exit 2
+	;;
+esac
+case "$(uname -m)" in
+x86_64 | amd64) ARCH_PART="x86_64" ;;
+arm64 | aarch64) ARCH_PART="aarch64" ;;
+*)
+	printf 'harness: unsupported host arch %s\n' "$(uname -m)" >&2
+	exit 2
+	;;
+esac
+ASSET="codegraph-${VERSION}-${ARCH_PART}-${OS_PART}.tar.gz"
+
+# ---------------------------------------------------------------------------
+# Sandbox PATH. install.sh must find ONLY the tools we hand it, so the
+# "no hashing tool" scenario is a genuine absence rather than a stubbed failure.
+# ---------------------------------------------------------------------------
+BASE_TOOLS=(sh tar gzip uname sed grep head mktemp cut awk tr rm mkdir mv chmod cat ls)
+make_sandbox_bin() {
+	local dir="$1" with_hash="$2" tool src
+	mkdir -p "$dir"
+	for tool in "${BASE_TOOLS[@]}"; do
+		src="$(command -v "$tool")" || {
+			printf 'harness: missing host tool %s\n' "$tool" >&2
+			exit 2
+		}
+		ln -sf "$src" "$dir/$tool"
+	done
+	if [ "$with_hash" = "with_hash" ]; then
+		src="$(command -v sha256sum)" || {
+			printf 'harness: host has no sha256sum\n' >&2
+			exit 2
+		}
+		ln -sf "$src" "$dir/sha256sum"
+	fi
+}
+
+# ---------------------------------------------------------------------------
+# curl shim: URL -> $RELEASE_DIR/<basename>. Absent file => exit 22.
+# ---------------------------------------------------------------------------
+write_curl_shim() {
+	local dir="$1"
+	mkdir -p "$dir"
+	cat > "$dir/curl" <<'SHIM'
+#!/bin/sh
+# Offline stand-in for curl: resolves URLs to files in $CG_TEST_RELEASE_DIR.
+# Deliberately depends on nothing beyond /bin/sh builtins so the sandboxed PATH
+# (which omits a hashing tool in some scenarios) cannot accidentally help it.
+set -u
+url=""
+out=""
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+	-o)
+		out="$2"
+		shift 2
+		;;
+	http://* | https://*)
+		url="$1"
+		shift
+		;;
+	*) shift ;;
+	esac
+done
+[ -n "$url" ] || exit 2
+src="$CG_TEST_RELEASE_DIR/${url##*/}"
+[ -f "$src" ] || exit 22
+if [ -n "$out" ]; then cat "$src" > "$out"; else cat "$src"; fi
+SHIM
+	chmod +x "$dir/curl"
+}
+
+# ---------------------------------------------------------------------------
+# make_release DIR — a fake release: one tar.gz holding an executable stub
+# `codegraph`, plus a decoy asset so SHA256SUMS is never a single-line file.
+# ---------------------------------------------------------------------------
+make_release() {
+	local dir="$1" stage
+	mkdir -p "$dir"
+	stage="$dir/.stage"
+	mkdir -p "$stage"
+	cat > "$stage/codegraph" <<'STUB'
+#!/bin/sh
+printf 'codegraph 9.9.9 (test stub)\n'
+STUB
+	chmod +x "$stage/codegraph"
+	tar -czf "$dir/$ASSET" -C "$stage" codegraph
+	printf 'decoy\n' > "$dir/codegraph-${VERSION}-x86_64-pc-windows-msvc.zip"
+	rm -rf "$stage"
+}
+
+sums_for() {
+	local dir="$1" f
+	(
+		cd "$dir" || exit 1
+		for f in $(printf '%s\n' *.tar.gz *.zip | LC_ALL=C sort); do
+			sha256sum "$f"
+		done
+	)
+}
+
+# ---------------------------------------------------------------------------
+# run_install NAME RELEASE_DIR WITH_HASH SKIP_ENV -> rc / out / err / installed
+# ---------------------------------------------------------------------------
+RC=0
+OUT=""
+ERR=""
+INSTALLED_PATH=""
+run_install() {
+	local name="$1" release_dir="$2" with_hash="$3" skip_env="$4"
+	local sandbox="$WORK/$name.bin" install_dir="$WORK/$name.dest"
+	OUT="$WORK/$name.out"
+	ERR="$WORK/$name.err"
+	INSTALLED_PATH="$install_dir/codegraph"
+	make_sandbox_bin "$sandbox" "$with_hash"
+	write_curl_shim "$sandbox"
+	mkdir -p "$install_dir"
+	rm -f "$INSTALLED_PATH"
+	set +e
+	env -i \
+		PATH="$sandbox" \
+		HOME="$WORK/$name.home" \
+		CG_TEST_RELEASE_DIR="$release_dir" \
+		CODEGRAPH_VERSION="$VERSION" \
+		CODEGRAPH_INSTALL_DIR="$install_dir" \
+		CODEGRAPH_SKIP_CHECKSUM="$skip_env" \
+		/bin/sh "$INSTALLER" > "$OUT" 2> "$ERR"
+	RC=$?
+	set -e
+}
+
+assert_installed() {
+	local name="$1"
+	[ -f "$INSTALLED_PATH" ] || {
+		bad "$name: expected the binary at $INSTALLED_PATH, it is absent"
+		return 1
+	}
+}
+assert_not_installed() {
+	local name="$1"
+	if [ -e "$INSTALLED_PATH" ]; then
+		bad "$name: binary WAS installed despite a failed verification"
+		return 1
+	fi
+}
+assert_rc() {
+	local name="$1" want="$2"
+	if [ "$RC" != "$want" ]; then
+		bad "$name: expected exit $want, got $RC"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+assert_rc_nonzero() {
+	local name="$1"
+	if [ "$RC" -eq 0 ]; then
+		bad "$name: expected a NONZERO exit, got 0"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+assert_stderr() {
+	local name="$1" re="$2"
+	if ! grep -Eq "$re" "$ERR"; then
+		bad "$name: expected diagnostic /$re/ on stderr"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+
+printf '=== installer checksum-gate fixture harness ===\n'
+printf 'asset under test: %s\n' "$ASSET"
+
+# --- Scenario A — matching checksum: install proceeds. --------------------
+REL_A="$WORK/rel_a"
+make_release "$REL_A"
+sums_for "$REL_A" > "$REL_A/SHA256SUMS"
+a_ok=1
+run_install "A_match" "$REL_A" with_hash ""
+assert_rc "A_match" 0 || a_ok=0
+assert_installed "A_match" || a_ok=0
+assert_stderr "A_match" 'sha256: OK' || a_ok=0
+[ "$a_ok" -eq 1 ] && ok "A_match (exit=0, binary installed, checksum reported OK)"
+
+# --- Scenario B — mismatching checksum: abort, nothing installed. ---------
+REL_B="$WORK/rel_b"
+make_release "$REL_B"
+sums_for "$REL_B" | sed "s|^[0-9a-f]\{64\}\(  ${ASSET}\)$|$(printf '0%.0s' $(seq 64))\1|" > "$REL_B/SHA256SUMS"
+b_ok=1
+run_install "B_mismatch" "$REL_B" with_hash ""
+assert_rc_nonzero "B_mismatch" || b_ok=0
+assert_stderr "B_mismatch" 'checksum MISMATCH' || b_ok=0
+assert_not_installed "B_mismatch" || b_ok=0
+[ "$b_ok" -eq 1 ] && ok "B_mismatch (exit=$RC, MISMATCH reported, binary NOT installed)"
+
+# --- Scenario C — mismatch + opt-out: STILL aborts. ----------------------
+c_ok=1
+run_install "C_mismatch_optout" "$REL_B" with_hash "1"
+assert_rc_nonzero "C_mismatch_optout" || c_ok=0
+assert_stderr "C_mismatch_optout" 'checksum MISMATCH' || c_ok=0
+assert_not_installed "C_mismatch_optout" || c_ok=0
+[ "$c_ok" -eq 1 ] && ok "C_mismatch_optout (exit=$RC, opt-out does NOT bypass a mismatch)"
+
+# --- Scenario D — truncated archive against a good SHA256SUMS. -----------
+REL_D="$WORK/rel_d"
+make_release "$REL_D"
+sums_for "$REL_D" > "$REL_D/SHA256SUMS"
+head -c 64 "$REL_D/$ASSET" > "$REL_D/$ASSET.trunc"
+mv "$REL_D/$ASSET.trunc" "$REL_D/$ASSET"
+d_ok=1
+run_install "D_truncated" "$REL_D" with_hash ""
+assert_rc_nonzero "D_truncated" || d_ok=0
+assert_stderr "D_truncated" 'checksum MISMATCH' || d_ok=0
+assert_not_installed "D_truncated" || d_ok=0
+[ "$d_ok" -eq 1 ] && ok "D_truncated (exit=$RC, corrupt download caught BEFORE extraction)"
+
+# --- Scenario E — no sha256 tool: refuse, then allow with opt-out. --------
+e_ok=1
+run_install "E_notool_refuse" "$REL_A" without_hash ""
+assert_rc_nonzero "E_notool_refuse" || e_ok=0
+assert_stderr "E_notool_refuse" 'cannot verify the download: no sha256sum or shasum' || e_ok=0
+assert_stderr "E_notool_refuse" 'CODEGRAPH_SKIP_CHECKSUM' || e_ok=0
+assert_not_installed "E_notool_refuse" || e_ok=0
+[ "$e_ok" -eq 1 ] && ok "E_notool_refuse (exit=$RC, explicit refusal, binary NOT installed)"
+
+e2_ok=1
+run_install "E_notool_optout" "$REL_A" without_hash "1"
+assert_rc "E_notool_optout" 0 || e2_ok=0
+assert_stderr "E_notool_optout" 'UNVERIFIED binary' || e2_ok=0
+assert_installed "E_notool_optout" || e2_ok=0
+[ "$e2_ok" -eq 1 ] && ok "E_notool_optout (exit=0, installs only under the explicit opt-out)"
+
+# --- Scenario F — no SHA256SUMS at all (pre-checksum release). ------------
+REL_F="$WORK/rel_f"
+make_release "$REL_F"
+f_ok=1
+run_install "F_nosums_refuse" "$REL_F" with_hash ""
+assert_rc_nonzero "F_nosums_refuse" || f_ok=0
+assert_stderr "F_nosums_refuse" 'cannot verify the download: could not download' || f_ok=0
+assert_not_installed "F_nosums_refuse" || f_ok=0
+[ "$f_ok" -eq 1 ] && ok "F_nosums_refuse (exit=$RC, missing SHA256SUMS fails CLOSED)"
+
+f2_ok=1
+run_install "F_nosums_optout" "$REL_F" with_hash "1"
+assert_rc "F_nosums_optout" 0 || f2_ok=0
+assert_stderr "F_nosums_optout" 'UNVERIFIED binary' || f2_ok=0
+assert_installed "F_nosums_optout" || f2_ok=0
+[ "$f2_ok" -eq 1 ] && ok "F_nosums_optout (exit=0, legacy release installable only via opt-out)"
+
+# --- Scenario G — SHA256SUMS present but with no line for OUR asset. -----
+REL_G="$WORK/rel_g"
+make_release "$REL_G"
+sums_for "$REL_G" | grep -v -- "$ASSET" > "$REL_G/SHA256SUMS"
+g_ok=1
+[ -s "$REL_G/SHA256SUMS" ] || {
+	bad "G_no_entry: fixture SHA256SUMS ended up empty"
+	g_ok=0
+}
+run_install "G_no_entry" "$REL_G" with_hash ""
+assert_rc_nonzero "G_no_entry" || g_ok=0
+assert_stderr "G_no_entry" "SHA256SUMS has no entry for ${ASSET}" || g_ok=0
+assert_not_installed "G_no_entry" || g_ok=0
+[ "$g_ok" -eq 1 ] && ok "G_no_entry (exit=$RC, a sums file that omits our asset is NOT a pass)"
+
+# --- Scenario H — CRLF SHA256SUMS with the correct digest. ----------------
+REL_H="$WORK/rel_h"
+make_release "$REL_H"
+sums_for "$REL_H" | sed 's/$/\r/' > "$REL_H/SHA256SUMS"
+h_ok=1
+grep -q $'\r' "$REL_H/SHA256SUMS" || {
+	bad "H_crlf: fixture is not actually CRLF"
+	h_ok=0
+}
+run_install "H_crlf" "$REL_H" with_hash ""
+assert_rc "H_crlf" 0 || h_ok=0
+assert_stderr "H_crlf" 'sha256: OK' || h_ok=0
+assert_installed "H_crlf" || h_ok=0
+[ "$h_ok" -eq 1 ] && ok "H_crlf (exit=0, CRLF line endings do not defeat the match)"
+
+printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

From 5c585ecaeed10f7551948d01b204d2aaebe605b1 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 17:10:20 +0800
Subject: [PATCH 58/91] test(bench): parse KNOWN_DIFFS.md fail-closed and wire
 it into the golden oracle

---
 crates/codegraph-bench/src/oracle/diff.rs   | 355 +++++++++++++++++++-
 crates/codegraph-bench/src/oracle/mod.rs    |  14 +-
 crates/codegraph-bench/tests/equivalence.rs |  33 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md   | 260 ++++++++++++++
 4 files changed, 648 insertions(+), 14 deletions(-)

diff --git a/crates/codegraph-bench/src/oracle/diff.rs b/crates/codegraph-bench/src/oracle/diff.rs
index 3750999..44afecd 100644
--- a/crates/codegraph-bench/src/oracle/diff.rs
+++ b/crates/codegraph-bench/src/oracle/diff.rs
@@ -1,13 +1,31 @@
 use std::collections::{BTreeMap, BTreeSet};
 use std::fmt;
 use std::fs;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 
 use super::canonicalize::{CanonicalDb, CanonicalRow};
 
+/// Every surface name `diff_canonical` can put on a `DiffEntry`, enumerated from
+/// its `compare_*` call sites (nodes/files via `compare_tier1_rows`, schema via
+/// `compare_schema`, edges/unresolved_refs via `compare_tier2_rows`). A RULE that
+/// names anything else can never match a real diff, so it is rejected at parse
+/// time: a typo'd `surface=` would otherwise sit in the document forever looking
+/// like an active decision while silently allowing nothing — a LOUD error is
+/// strictly better than an inert rule nobody notices is inert.
+const DIFF_SURFACES: [&str; 5] = ["nodes", "files", "schema", "edges", "unresolved_refs"];
+
+/// The field names a RULE line may carry. Anything else is a typo.
+const RULE_FIELDS: [&str; 4] = ["tier", "surface", "key", "justification"];
+
+/// A `DiffEntry` legitimately carries ANY tier — `diff_canonical` mints Tier-1
+/// (nodes/files/schema) and Tier-2 (edges/unresolved_refs) entries today, and
+/// Tier-3 exists for behavioral surfaces. The asymmetry lives on the allowlist
+/// side, not here: only Tier-3 may appear on a `RULE` line (`parse_rule`) and
+/// only a Tier-3 entry can ever be allowed (`KnownDiffs::allows`). So all three
+/// variants stay.
 #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub enum Tier {
     Tier1,
@@ -120,17 +138,52 @@ impl KnownDiffs {
         Self::parse(&text)
     }
 
+    pub fn repo_doc_path() -> PathBuf {
+        Path::new(env!("CARGO_MANIFEST_DIR"))
+            .parent()
+            .and_then(Path::parent)
+            .expect("codegraph-bench lives under crates/")
+            .join("docs/upstream-sync/KNOWN_DIFFS.md")
+    }
+
+    /// The committed allowlist, parsed. A syntactically invalid `KNOWN_DIFFS.md`
+    /// therefore FAILS every equivalence assertion instead of being silently
+    /// ignored, which is what made the document decorative before this wiring.
+    pub fn load_repo_doc() -> Result<Self> {
+        Self::load(&Self::repo_doc_path())
+    }
+
+    pub fn rule_count(&self) -> usize {
+        self.rules.len()
+    }
+
+    /// Lines inside a fenced code block are DOCUMENTATION, not rules: the "Rule
+    /// format" section of `KNOWN_DIFFS.md` shows the template
+    /// `RULE tier=3 surface=<surface> …` inside a ```text fence, and the
+    /// pre-fail-closed parser accepted it as an ACTIVE rule (tier=3, surface
+    /// `<surface>`) — an allowlist entry nobody wrote on purpose, inert only
+    /// because that placeholder surface never matches a real diff.
     pub fn parse(text: &str) -> Result<Self> {
         let mut rules = Vec::new();
+        let mut in_fence = false;
         for (line_number, line) in text.lines().enumerate() {
             let line = line.trim();
-            if line.is_empty() || line.starts_with('#') || !line.starts_with("RULE ") {
+            if line.starts_with("```") {
+                in_fence = !in_fence;
+                continue;
+            }
+            if in_fence || line.is_empty() || line.starts_with('#') || !line.starts_with("RULE ") {
                 continue;
             }
             rules.push(parse_rule(line).with_context(|| {
                 format!("parsing KNOWN_DIFFS.md line {}: {line}", line_number + 1)
             })?);
         }
+        if in_fence {
+            anyhow::bail!(
+                "unterminated code fence: every RULE line after it would be silently skipped"
+            );
+        }
         Ok(Self { rules })
     }
 
@@ -146,25 +199,54 @@ impl KnownDiffs {
     }
 }
 
+/// Fail-closed RULE parser. Every rejection below exists because the permissive
+/// version accepted a line that LOOKED like an active allowlist entry and then
+/// silently did nothing (or, for `tier=1|2`, looked like it waved through a
+/// Tier-1 golden difference):
+///
+/// - a token without `=` was dropped, so `RULE garbage tier=3 …` parsed clean;
+/// - an unknown field name (`surfce=nodes`) was dropped, so the rule silently
+///   fell back to "missing surface" or to a stale value;
+/// - a duplicate field silently kept the last occurrence, so two contradictory
+///   `key=` values resolved by position alone;
+/// - `tier=1` / `tier=2` parsed fine and were discarded only later by `allows`,
+///   so the document's promise that Tier-1/Tier-2 are never allowlisted held by
+///   downstream accident rather than at parse time;
+/// - a `surface=` outside `DIFF_SURFACES` can never match a real diff.
 fn parse_rule(line: &str) -> Result<KnownDiffRule> {
-    let mut fields = BTreeMap::new();
+    let mut fields: BTreeMap<&str, &str> = BTreeMap::new();
     for token in line.trim_start_matches("RULE ").split_whitespace() {
-        if let Some((key, value)) = token.split_once('=') {
-            fields.insert(key, value);
+        let (key, value) = token
+            .split_once('=')
+            .with_context(|| format!("token {token} is not key=value"))?;
+        if key.is_empty() || value.is_empty() {
+            anyhow::bail!("token {token} has an empty key or value");
+        }
+        if !RULE_FIELDS.contains(&key) {
+            anyhow::bail!("unknown field {key}; allowed fields are {RULE_FIELDS:?}");
+        }
+        if fields.insert(key, value).is_some() {
+            anyhow::bail!("duplicate field {key}");
         }
     }
-    let tier = match *fields.get("tier").context("missing tier")? {
+
+    let tier_token = *fields.get("tier").context("missing tier")?;
+    let tier = match tier_token {
         "3" | "Tier3" | "tier3" => Tier::Tier3,
-        "2" | "Tier2" | "tier2" => Tier::Tier2,
-        "1" | "Tier1" | "tier1" => Tier::Tier1,
+        "1" | "Tier1" | "tier1" | "2" | "Tier2" | "tier2" => anyhow::bail!(
+            "tier={tier_token} may not be allowlisted; only Tier-3 differences can be allowed"
+        ),
         value => anyhow::bail!("unknown tier {value}"),
     };
+
+    let surface = *fields.get("surface").context("missing surface")?;
+    if !DIFF_SURFACES.contains(&surface) {
+        anyhow::bail!("unknown surface {surface}; the differ reports {DIFF_SURFACES:?}");
+    }
+
     Ok(KnownDiffRule {
         tier,
-        surface: fields
-            .get("surface")
-            .context("missing surface")?
-            .to_string(),
+        surface: surface.to_string(),
         key_pattern: fields
             .get("key")
             .context("missing key")?
@@ -336,3 +418,252 @@ fn truncate(value: &str) -> String {
         format!("{}…<truncated {} bytes>", &value[..MAX], value.len() - MAX)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const TIER3_RULE: &str =
+        "RULE tier=3 surface=nodes key=alpha justification=documented-behavioral-drift";
+
+    fn tier3_entry(surface: &str, key: &str) -> DiffEntry {
+        entry(
+            Tier::Tier3,
+            surface,
+            key,
+            "expected".to_string(),
+            "actual".to_string(),
+        )
+    }
+
+    fn parsed(text: &str) -> KnownDiffs {
+        KnownDiffs::parse(text).expect("rule parses")
+    }
+
+    fn parse_error(text: &str) -> String {
+        let error = KnownDiffs::parse(text).expect_err("rule must be rejected");
+        format!("{error:#}")
+    }
+
+    #[test]
+    fn tier3_rule_allows_its_matching_tier3_diff() {
+        let known = parsed(TIER3_RULE);
+        assert_eq!(known.rule_count(), 1);
+        assert!(known.allows(&tier3_entry("nodes", "function:alpha")));
+    }
+
+    #[test]
+    fn tier3_rule_does_not_allow_a_different_surface() {
+        let known = parsed(TIER3_RULE);
+        assert!(!known.allows(&tier3_entry("edges", "function:alpha")));
+    }
+
+    #[test]
+    fn tier3_rule_does_not_allow_a_non_matching_key() {
+        let known = parsed(TIER3_RULE);
+        assert!(!known.allows(&tier3_entry("nodes", "function:beta")));
+    }
+
+    #[test]
+    fn tier3_rule_does_not_allow_the_same_key_at_tier1() {
+        let known = parsed(TIER3_RULE);
+        let tier1 = entry(
+            Tier::Tier1,
+            "nodes",
+            "function:alpha",
+            "expected".to_string(),
+            "actual".to_string(),
+        );
+        assert!(!known.allows(&tier1));
+    }
+
+    #[test]
+    fn tier3_rule_does_not_allow_the_same_key_at_tier2() {
+        let known = parsed(TIER3_RULE);
+        let tier2 = entry(
+            Tier::Tier2,
+            "nodes",
+            "function:alpha",
+            "expected".to_string(),
+            "actual".to_string(),
+        );
+        assert!(!known.allows(&tier2));
+    }
+
+    #[test]
+    fn wildcard_rule_never_allows_a_tier1_golden_difference() {
+        let known = parsed("RULE tier=3 surface=nodes key=* justification=wildcard");
+        let tier1 = entry(
+            Tier::Tier1,
+            "nodes",
+            "function:anything",
+            "expected".to_string(),
+            "actual".to_string(),
+        );
+        assert!(!known.allows(&tier1));
+        assert!(known.allows(&tier3_entry("nodes", "function:anything")));
+    }
+
+    #[test]
+    fn tier1_and_tier2_rules_are_rejected_at_parse_time() {
+        for token in ["1", "Tier1", "tier1", "2", "Tier2", "tier2"] {
+            let line =
+                format!("RULE tier={token} surface=nodes key=* justification=must-not-be-allowed");
+            let message = parse_error(&line);
+            assert!(
+                message.contains("may not be allowlisted"),
+                "tier={token} must be rejected at parse time, got: {message}"
+            );
+            assert!(
+                message.contains(&line),
+                "the error must name the offending line, got: {message}"
+            );
+        }
+    }
+
+    #[test]
+    fn token_without_equals_is_rejected() {
+        let message = parse_error("RULE garbage tier=3 surface=nodes key=* justification=x");
+        assert!(
+            message.contains("token garbage is not key=value"),
+            "got: {message}"
+        );
+    }
+
+    #[test]
+    fn unknown_field_name_is_rejected() {
+        let message = parse_error("RULE tier=3 surfce=nodes key=* justification=x");
+        assert!(message.contains("unknown field surfce"), "got: {message}");
+    }
+
+    #[test]
+    fn duplicate_field_is_rejected() {
+        let message = parse_error("RULE tier=3 surface=nodes key=a key=b justification=x");
+        assert!(message.contains("duplicate field key"), "got: {message}");
+    }
+
+    #[test]
+    fn unknown_surface_is_rejected() {
+        let message = parse_error("RULE tier=3 surface=noodes key=* justification=x");
+        assert!(message.contains("unknown surface noodes"), "got: {message}");
+        for surface in DIFF_SURFACES {
+            let line = format!("RULE tier=3 surface={surface} key=* justification=x");
+            assert_eq!(parsed(&line).rule_count(), 1, "{surface} must be accepted");
+        }
+    }
+
+    #[test]
+    fn missing_field_is_rejected() {
+        for line in [
+            "RULE surface=nodes key=* justification=x",
+            "RULE tier=3 key=* justification=x",
+            "RULE tier=3 surface=nodes justification=x",
+            "RULE tier=3 surface=nodes key=*",
+        ] {
+            let message = parse_error(line);
+            assert!(message.contains("missing"), "{line} -> {message}");
+        }
+    }
+
+    #[test]
+    fn fenced_template_and_prose_lines_are_not_rules() {
+        let known = parsed(
+            "# Known CodeGraph Equivalence Differences\n\nNo Tier-3 rules are active yet.\n\n\
+             ```text\nRULE tier=3 surface=<surface> key=<substring-or-*> \
+             justification=<short-token>\n```\n",
+        );
+        assert_eq!(known.rule_count(), 0);
+    }
+
+    #[test]
+    fn a_rule_after_a_closed_fence_is_still_active() {
+        let known = parsed(&format!(
+            "```text\nRULE tier=3 surface=<x> key=* j=1\n```\n\n{TIER3_RULE}\n"
+        ));
+        assert_eq!(known.rule_count(), 1);
+        assert!(known.allows(&tier3_entry("nodes", "function:alpha")));
+    }
+
+    #[test]
+    fn unterminated_fence_is_rejected() {
+        let message = parse_error(&format!("```text\n{TIER3_RULE}\n"));
+        assert!(
+            message.contains("unterminated code fence"),
+            "got: {message}"
+        );
+    }
+
+    #[test]
+    fn committed_known_diffs_doc_parses_and_has_zero_active_rules() {
+        let path = KnownDiffs::repo_doc_path();
+        let known = KnownDiffs::load(&path).unwrap_or_else(|error| {
+            panic!("{} must parse: {error:#}", path.display());
+        });
+        assert_eq!(
+            known.rule_count(),
+            0,
+            "{} must have zero active Tier-3 rules; adding one silently widens \
+             golden adjudication",
+            path.display()
+        );
+    }
+
+    #[test]
+    fn invalid_known_diffs_file_fails_to_load() {
+        let dir = std::env::temp_dir().join(format!(
+            "codegraph-bench-known-diffs-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("clock after epoch")
+                .as_nanos()
+        ));
+        fs::create_dir(&dir).expect("temp dir");
+        let path = dir.join("KNOWN_DIFFS.md");
+        fs::write(
+            &path,
+            "RULE tier=1 surface=nodes key=* justification=sneaky\n",
+        )
+        .expect("write fixture");
+
+        let message = format!("{:#}", KnownDiffs::load(&path).expect_err("must fail"));
+        let _ = fs::remove_dir_all(&dir);
+
+        assert!(message.contains("may not be allowlisted"), "got: {message}");
+    }
+
+    #[test]
+    fn tier1_entries_survive_the_allowlist_in_diff_canonical() {
+        let expected = CanonicalDb {
+            nodes: vec![row(&[("id", "function:alpha"), ("name", "alpha")])],
+            edges: Vec::new(),
+            unresolved_refs: Vec::new(),
+            files: Vec::new(),
+            schema: String::new(),
+        };
+        let mut actual = expected.clone();
+        actual.nodes = vec![row(&[("id", "function:alpha"), ("name", "DRIFTED")])];
+
+        let known = parsed("RULE tier=3 surface=nodes key=* justification=wildcard");
+        let error = diff_canonical(&expected, &actual, Some(&known))
+            .expect_err("a Tier-1 node drift is never allowlisted");
+        assert!(
+            error
+                .entries()
+                .iter()
+                .any(|entry| entry.tier == Tier::Tier1 && entry.surface == "nodes")
+        );
+    }
+
+    fn row(pairs: &[(&str, &str)]) -> CanonicalRow {
+        pairs
+            .iter()
+            .map(|(key, value)| {
+                (
+                    (*key).to_string(),
+                    serde_json::Value::String((*value).to_string()),
+                )
+            })
+            .collect()
+    }
+}
diff --git a/crates/codegraph-bench/src/oracle/mod.rs b/crates/codegraph-bench/src/oracle/mod.rs
index a6da34a..16f0e23 100644
--- a/crates/codegraph-bench/src/oracle/mod.rs
+++ b/crates/codegraph-bench/src/oracle/mod.rs
@@ -7,12 +7,24 @@ use std::path::Path;
 use anyhow::Result;
 
 pub use canonicalize::{CanonicalDb, CanonicalRow, canonicalize_db};
+
 pub use diff::{DiffEntry, DiffError, KnownDiffs, Tier, diff_canonical};
 pub use golden::{load_golden, write_golden};
 
 pub fn assert_equivalent(rust_db: &Path, golden_dir: &Path) -> Result<()> {
+    assert_equivalent_with_known_diffs(rust_db, golden_dir, &KnownDiffs::repo_doc_path())
+}
+
+/// The allowlist is loaded from `known_diffs_path` BEFORE any comparison, so an
+/// unparseable `KNOWN_DIFFS.md` fails the assertion instead of being ignored.
+pub fn assert_equivalent_with_known_diffs(
+    rust_db: &Path,
+    golden_dir: &Path,
+    known_diffs_path: &Path,
+) -> Result<()> {
+    let known_diffs = KnownDiffs::load(known_diffs_path)?;
     let expected = load_golden(golden_dir)?;
     let actual = canonicalize_db(rust_db)?;
-    diff_canonical(&expected, &actual, None)?;
+    diff_canonical(&expected, &actual, Some(&known_diffs))?;
     Ok(())
 }
diff --git a/crates/codegraph-bench/tests/equivalence.rs b/crates/codegraph-bench/tests/equivalence.rs
index e499c82..74cf2a9 100644
--- a/crates/codegraph-bench/tests/equivalence.rs
+++ b/crates/codegraph-bench/tests/equivalence.rs
@@ -1,10 +1,41 @@
 use std::path::{Path, PathBuf};
 
 use codegraph_bench::oracle::{
-    Tier, assert_equivalent, canonicalize_db, diff_canonical, load_golden, write_golden,
+    KnownDiffs, Tier, assert_equivalent, assert_equivalent_with_known_diffs, canonicalize_db,
+    diff_canonical, load_golden, write_golden,
 };
 use serde_json::json;
 
+#[test]
+fn committed_known_diffs_doc_is_parsed_and_allowlists_nothing() {
+    // Every `assert_equivalent` in this file now adjudicates through the
+    // committed KNOWN_DIFFS.md, so it must parse AND stay empty: one active
+    // Tier-3 rule would silently widen every golden comparison below.
+    let path = KnownDiffs::repo_doc_path();
+    assert!(path.is_file(), "{} must exist", path.display());
+    let known = KnownDiffs::load(&path).unwrap_or_else(|error| {
+        panic!("{} must parse: {error:#}", path.display());
+    });
+    assert_eq!(known.rule_count(), 0, "{} must stay empty", path.display());
+}
+
+#[test]
+fn an_unparseable_known_diffs_file_fails_the_equivalence_assertion() {
+    let tempdir = TestDir::new("known-diffs-invalid");
+    let path = tempdir.path().join("KNOWN_DIFFS.md");
+    std::fs::write(
+        &path,
+        "RULE tier=1 surface=nodes key=* justification=sneaky\n",
+    )
+    .unwrap();
+
+    let error = assert_equivalent_with_known_diffs(&mini_db(), &mini_golden_dir(), &path)
+        .expect_err("an invalid allowlist must fail, not be ignored");
+    let message = format!("{error:#}");
+    println!("invalid KNOWN_DIFFS.md failure:\n{message}");
+    assert!(message.contains("may not be allowlisted"), "got: {message}");
+}
+
 #[test]
 fn generated_golden_matches_committed_mini_fixture() {
     let tempdir = TestDir::new("generated-golden");
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 57fd217..c5146a8 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -6173,3 +6173,263 @@ must be inside request cwd`); no LSP-clean result is claimed. The changed files
 are shell, PowerShell and YAML, which the Rust toolchain does not lint anyway —
 the honest checks for them are the executable harness, the YAML parse, and the
 replayed workflow step above.
+
+## Batch E1 — `KNOWN_DIFFS.md` becomes an executable, fail-closed oracle (2026-07-28)
+
+### The defect, in three layers
+
+`docs/upstream-sync/KNOWN_DIFFS.md` opened by claiming it "is parsed by
+`codegraph-bench::oracle::diff::KnownDiffs`". It was not. Three independent
+layers, each confirmed by reading the code at `ecd3641`:
+
+1. **The oracle was never wired.** `grep -rn "KnownDiffs::load" crates/` → exit
+   **1**, ZERO hits. The only `KNOWN_DIFFS` mention in the crate was a string
+   literal in an error message (`diff.rs:131`). `diff_canonical` applies the
+   allowlist (`entries.retain(|entry| !known_diffs.allows(entry))`), but EVERY
+   call site passed `None`: 18 in `crates/codegraph-bench/tests/equivalence.rs`,
+   one in `oracle/mod.rs::assert_equivalent`, plus the sites in
+   `crates/codegraph-cli/tests/{batch_m_outdated_migration,sync_incremental,
+parallel_index,godot_idfields_determinism}.rs`. The document had never
+   influenced a single decision.
+2. **`parse_rule` was not fail-closed.** `tier=1` / `tier=2` PARSED fine and were
+   discarded only later by `allows()` (`if entry.tier != Tier::Tier3 { return
+false }`), so the document's promise that Tier-1/Tier-2 are "never
+   allowlisted" held by downstream accident, not at parse time. A token lacking
+   `=` was silently dropped, so `RULE garbage tier=3 surface=nodes key=*
+justification=x` parsed clean. An unknown field name (`surfce=nodes`) was
+   dropped the same way. `fields` is a `BTreeMap`, so a duplicate field silently
+   kept the last occurrence.
+3. **`diff.rs` had NO `mod tests`.** `grep -c "mod tests"
+crates/codegraph-bench/src/oracle/diff.rs` → **0**. Nothing pinned "No Tier-3
+   rules are active yet."
+
+### A fourth layer the fail-closed parser exposed
+
+Wiring the parser to the REAL document immediately reddened, before any mutation:
+
+```text
+/…/docs/upstream-sync/KNOWN_DIFFS.md must parse: parsing KNOWN_DIFFS.md line 12:
+RULE tier=3 surface=<surface> key=<substring-or-*> justification=<short-token>:
+unknown surface <surface>; the differ reports ["nodes", "files", "schema", "edges",
+"unresolved_refs"]
+```
+
+Line 12 is the `RULE` TEMPLATE inside the "Rule format" ``text fence. The old
+parser accepted it as an ACTIVE Tier-3 rule with surface `<surface>` — an
+allowlist entry nobody wrote on purpose, inert only because that placeholder
+surface never matches a real diff. Had anyone ever passed `Some(&known_diffs)`,
+the committed document would have carried one bogus rule. Fix: `parse` now
+tracks ``-fences and skips their contents, and BAILS on an unterminated fence
+(otherwise every RULE after it would be silently skipped — the same
+silent-inertness failure in the other direction). A test pins that a rule AFTER
+a closed fence is still active, so fence tracking cannot degrade into "ignore
+everything".
+
+### What was wired, and where
+
+- `KnownDiffs::repo_doc_path()` resolves `docs/upstream-sync/KNOWN_DIFFS.md` from
+  `CARGO_MANIFEST_DIR`; `KnownDiffs::load_repo_doc()` parses it;
+  `KnownDiffs::rule_count()` exposes the active-rule count for pinning.
+- `oracle::mod::assert_equivalent` now loads the committed document and passes
+  `Some(&known_diffs)`. The load happens BEFORE any comparison, so an
+  unparseable file FAILS the assertion instead of being ignored. All 14
+  `assert_equivalent` golden tests therefore now adjudicate through the real
+  document.
+- `assert_equivalent_with_known_diffs(rust_db, golden_dir, known_diffs_path)` is
+  the injectable seam, used by the negative test that feeds a deliberately
+  invalid allowlist.
+- The `diff_canonical(..., None)` call sites were left alone on purpose: those
+  compare two RUST runs against each other (sync vs `index --force`, run-to-run
+  determinism, migration vs rebuild). An upstream-difference allowlist has no
+  business softening a self-consistency check, so they stay strict.
+
+### Fail-closed decisions, each justified
+
+| Rejection                                      | Silently-broken rule it prevents                                                                                                                                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tier=1` / `tier=2` rejected **at parse time** | The promise that Tier-1/Tier-2 are never allowlisted was enforced only downstream in `allows()`; a reader of a `tier=1` line had no way to know it was inert.                                                                  |
+| token without `=`                              | `RULE garbage tier=3 …` parsed clean; the garbage token was dropped.                                                                                                                                                           |
+| unknown field name                             | `surfce=nodes` was dropped, so the rule fell through to "missing surface" or a stale value.                                                                                                                                    |
+| duplicate field                                | Two contradictory `key=` values resolved by `BTreeMap` insertion position alone.                                                                                                                                               |
+| empty key or value                             | `=nodes` / `surface=` produced a rule with an empty component.                                                                                                                                                                 |
+| `surface=` outside the differ's surfaces       | An inert typo'd rule is worse than a loud error: it sits in the document looking like an active, reviewed decision while allowing nothing. A loud error is fixed in one commit; an inert rule can mislead for a release cycle. |
+| unterminated ```-fence                         | Every RULE after it would be silently skipped.                                                                                                                                                                                 |
+
+The `DIFF_SURFACES` whitelist `["nodes", "files", "schema", "edges",
+"unresolved_refs"]` was ENUMERATED from the actual `compare_*` call sites in
+`diff_canonical` (`compare_tier1_rows` for nodes/files, `compare_schema` for
+schema, `compare_tier2_rows` for edges/unresolved_refs) — not guessed. A test
+asserts every one of the five is accepted, so the whitelist cannot drift out of
+sync with the differ without reddening.
+
+`Tier` keeps all three variants: a `DiffEntry` genuinely carries any tier
+(`diff_canonical` mints Tier-1 and Tier-2 entries today). The asymmetry — only
+Tier-3 may appear on a RULE line, only a Tier-3 entry can be allowed — is now
+documented on the enum and enforced in both `parse_rule` and `allows`.
+
+### Two-direction proof
+
+The entire risk of E1 is that wiring a previously-inert allowlist into golden
+adjudication waves a real difference through. Both directions are pinned:
+
+- ALLOWS: `tier3_rule_allows_its_matching_tier3_diff` — the Tier-3 rule
+  (`surface=nodes key=alpha`) allows a Tier-3 `nodes` entry with key
+  `function:alpha`.
+- DOES NOT ALLOW, four ways: `..._does_not_allow_a_different_surface` (`edges`),
+  `..._does_not_allow_a_non_matching_key` (`function:beta`),
+  `..._does_not_allow_the_same_key_at_tier1`, `..._does_not_allow_the_same_key_at_tier2`.
+- `wildcard_rule_never_allows_a_tier1_golden_difference` — even `key=*` allows
+  only the Tier-3 entry and never the Tier-1 one.
+- `tier1_entries_survive_the_allowlist_in_diff_canonical` — end-to-end through
+  `diff_canonical` with a `key=*` rule loaded: an injected Tier-1 node drift is
+  still reported. This is the assertion that matters most, since it exercises the
+  exact retain() the wiring turned on.
+
+### The zero-rules pin
+
+Two tests pin that the committed document has ZERO active Tier-3 rules:
+`oracle::diff::tests::committed_known_diffs_doc_parses_and_has_zero_active_rules`
+(unit) and `committed_known_diffs_doc_is_parsed_and_allowlists_nothing`
+(integration, next to the golden tests it protects). No Tier-3 rule was added to
+the document to exercise the mechanism — every rule in this commit lives in test
+strings. A future silent allowlist addition now fails CI in both places.
+
+### Unasserted prose — stated plainly
+
+`KNOWN_DIFFS.md` is mostly PROSE, and this commit does NOT make it executable.
+The deferred-colby-resolver list, the canonicalized-timestamp note
+(`nodes.updated_at`, `files.modified_at`, `files.indexed_at` — stripped in
+`canonicalize.rs`, never compared), the Dart/Pascal function_ref notes, and the
+Task-22 MCP text-formatting section remain unasserted documentation. That is
+acceptable and intentional: they are not allowlist rules and were never claimed
+to be. They describe behavior OUTSIDE the five SQLite surfaces the oracle
+compares (deferred resolution paths that no golden fixture exercises, timestamps
+removed before comparison, MCP text output the oracle does not read). Turning
+them into machine-checked assertions would require new fixtures and new
+comparison surfaces — out of scope for E1. What E1 makes executable is exactly
+the RULE grammar and the active-rule set; the prose is still prose.
+
+### Negative control — three mutants, three disjoint red sets
+
+Green baseline: lib **29 passed**, `--test equivalence` **28 passed**.
+
+1. **Restore `tier=1|2` acceptance** (`parse_rule` maps them back to
+   `Tier::Tier1` / `Tier::Tier2` instead of bailing):
+
+   ```text
+   ---- oracle::diff::tests::invalid_known_diffs_file_fails_to_load stdout ----
+   panicked at crates/codegraph-bench/src/oracle/diff.rs:626:63:
+   must fail: KnownDiffs { rules: [KnownDiffRule { tier: Tier1, surface: "nodes",
+   key_pattern: "*", justification: "sneaky" }] }
+
+   ---- oracle::diff::tests::tier1_and_tier2_rules_are_rejected_at_parse_time stdout ----
+   panicked at crates/codegraph-bench/src/oracle/diff.rs:443:45:
+   rule must be rejected: KnownDiffs { rules: [KnownDiffRule { tier: Tier1,
+   surface: "nodes", key_pattern: "*", justification: "must-not-be-allowed" }] }
+
+   test result: FAILED. 27 passed; 2 failed        (lib)
+   ```
+
+   and in the integration test:
+
+   ```text
+   ---- an_unparseable_known_diffs_file_fails_the_equivalence_assertion stdout ----
+   panicked at crates/codegraph-bench/tests/equivalence.rs:29:10:
+   an invalid allowlist must fail, not be ignored: ()
+
+   test result: FAILED. 27 passed; 1 failed        (equivalence)
+   ```
+
+2. **Make `allows()` ignore `surface`** (drop `rule.surface == entry.surface`):
+
+   ```text
+   ---- oracle::diff::tests::tier3_rule_does_not_allow_a_different_surface stdout ----
+   panicked at crates/codegraph-bench/src/oracle/diff.rs:457:9:
+   assertion failed: !known.allows(&tier3_entry("edges", "function:alpha"))
+
+   test result: FAILED. 28 passed; 1 failed        (lib)
+   test result: ok. 28 passed                       (equivalence — untouched)
+   ```
+
+3. **Remove the load wiring** (`assert_equivalent_with_known_diffs` uses
+   `KnownDiffs::default()` and ignores the path):
+
+   ```text
+   ---- an_unparseable_known_diffs_file_fails_the_equivalence_assertion stdout ----
+   panicked at crates/codegraph-bench/tests/equivalence.rs:29:10:
+   an invalid allowlist must fail, not be ignored: ()
+
+   test result: FAILED. 27 passed; 1 failed        (equivalence)
+   test result: ok. 29 passed                       (lib — untouched)
+   ```
+
+4. **Add a Tier-3 rule to the committed document** (`RULE tier=3 surface=nodes
+key=* justification=silently-added` appended to `KNOWN_DIFFS.md`) — the
+   scenario the pin exists for:
+
+   ```text
+   ---- oracle::diff::tests::committed_known_diffs_doc_parses_and_has_zero_active_rules stdout ----
+   panicked at crates/codegraph-bench/src/oracle/diff.rs:600:9:
+   assertion `left == right` failed: /…/KNOWN_DIFFS.md must have zero active
+   Tier-3 rules; adding one silently widens golden adjudication
+     left: 1
+    right: 0
+
+   ---- committed_known_diffs_doc_is_parsed_and_allowlists_nothing stdout ----
+   panicked at crates/codegraph-bench/tests/equivalence.rs:19:5:
+   assertion `left == right` failed: /…/KNOWN_DIFFS.md must stay empty
+     left: 1
+    right: 0
+   ```
+
+Mutant 2 reddens ONLY the lib surface-discrimination test; mutant 3 reddens ONLY
+the integration wiring test; mutant 1 reddens the parse-time gate in both; mutant
+4 reddens both zero-rules pins. No partial regression in this gate can hide
+behind another part of it.
+
+Each mutant was restored by copying back the green file. Restored SHA-256:
+`crates/codegraph-bench/src/oracle/diff.rs`
+`2b525ddca8af6c26cddc0b01d285b36fa2ca4472bc157fcd3ac5b2765e4a6089`,
+`crates/codegraph-bench/src/oracle/mod.rs`
+`fd560ea19fdb574b12268ce31d45790e7e07f8f638ff72f441c5da4d76d482f3`,
+`crates/codegraph-bench/tests/equivalence.rs`
+`a69bd5c0e7d0d207ec3ff92d97ac0a43305d9985cfc2b5780532c3d4d837b2f2`,
+`docs/upstream-sync/KNOWN_DIFFS.md`
+`2c973b6f1407b409131c20849de44f15dc9989c1b47bb278e836daf3c682c07d` (byte-identical
+to `ecd3641` — the document is NOT modified by this commit). Green re-confirmed
+after every restore.
+
+### Golden delta
+
+`GIT_MASTER=1 git diff --stat ecd3641..HEAD -- reference/golden/` → **EMPTY**. No
+golden was regenerated and none needed to be: this commit changes only the
+oracle's rule parser, its wiring, and tests. No extraction, resolution, or
+canonicalization byte changed. `KNOWN_DIFFS.md` itself is untouched.
+
+### Verification (actual exit statuses)
+
+- `grep -rn "KnownDiffs::load" crates/` on the pre-change tree → exit **1**, zero
+  hits (defect layer 1). `grep -c "mod tests" …/oracle/diff.rs` → **0** (layer 3).
+- `bash scripts/check-workspace-versions.sh` → exit **0** (`OK`, workspace
+  0.40.4), run before every Cargo batch. Every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-bench --lib` → exit 0, **29 passed, 0 failed**
+  (was 14 before; +15 new oracle tests).
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+  **28 passed, 0 failed** — the required floor is 26; the two added tests are
+  `committed_known_diffs_doc_is_parsed_and_allowlists_nothing` and
+  `an_unparseable_known_diffs_file_fails_the_equivalence_assertion`. All 26
+  pre-existing tests still pass, now adjudicating through the real document.
+- `cargo clippy --locked -p codegraph-bench --all-targets -- -D warnings` →
+  exit **0**.
+- `cargo test --locked -p codegraph-rs --test parallel_index` → exit 0,
+  **5 passed** (the other `assert_equivalent` consumer).
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  prose; result recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+  No dependency, version, or lockfile byte changed.
+
+`lsp_diagnostics` was attempted on `crates/codegraph-bench/src/oracle/diff.rs`
+and refused this worktree again (`LSP file path must be inside request cwd`); no
+LSP-clean result is claimed. The equivalent evidence is the locked `clippy -D
+warnings` run above plus `make ci`.

From fc23a4a2394d065e776d6e7484d9efc0dc2a1009 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 17:40:52 +0800
Subject: [PATCH 59/91] ci(release): gate release asset-name drift across
 workflow and installers

---
 .githooks/pre-push                        |  10 +-
 .github/workflows/ci.yml                  |  13 +-
 Makefile                                  |   3 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 226 +++++++++
 scripts/check-asset-names.sh              | 540 ++++++++++++++++++++++
 scripts/guardrail.sh                      |  15 +-
 scripts/tests/asset-name-drift.test.sh    | 256 ++++++++++
 7 files changed, 1056 insertions(+), 7 deletions(-)
 create mode 100755 scripts/check-asset-names.sh
 create mode 100755 scripts/tests/asset-name-drift.test.sh

diff --git a/.githooks/pre-push b/.githooks/pre-push
index 516e648..1685657 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -10,7 +10,8 @@
 #   1. cargo fmt --all --check        (rustfmt)
 #   2. cargo clippy ... -D warnings    (lint, warnings are errors)
 #   3. cargo test --workspace          (incl. golden oracle + sync equivalence)
-#   4. scripts/guardrail.sh            (no AI / vector / LLM crates)
+#   4. scripts/guardrail.sh            (no AI/vector/LLM crates + no release
+#                                       asset-name drift)
 #
 # Enable once per clone:
 #   make hooks            # == git config core.hooksPath .githooks
@@ -45,11 +46,12 @@ if ! cargo test --workspace; then
     exit 1
 fi
 
-echo "==> [4/4] scripts/guardrail.sh (no AI/vector/LLM crates)"
+echo "==> [4/4] scripts/guardrail.sh (no AI/vector/LLM crates + asset-name drift)"
 if ! bash scripts/guardrail.sh; then
     echo "" >&2
-    echo "❌ Scope guardrail failed: a forbidden AI/vector/LLM crate was detected." >&2
-    echo "   This project is deterministic and ML-free by design. Push aborted." >&2
+    echo "❌ Scope guardrail failed: a forbidden AI/vector/LLM crate was detected," >&2
+    echo "   or the release workflow and the installers disagree on asset names." >&2
+    echo "   Read the diagnostics above; push aborted." >&2
     exit 1
 fi
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 582eb58..04e2c5b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -54,7 +54,18 @@ jobs:
       # (tree-sitter/libsqlite3-sys/ring) require MSVC tooling. Runtime
       # correctness is gated by the native windows-latest job below.
 
-      - name: Scope guardrail (no AI / vector / LLM crates)
+      # The guardrail's asset-name drift gate parses release-please.yml with
+      # yaml.safe_load, so PyYAML must be importable. Idempotent: installs only
+      # when the runner image does not already ship it. A missing PyYAML must
+      # never degrade the gate into a silent skip — the gate itself exits nonzero
+      # in that case, and this step fails loudly first.
+      - name: Ensure PyYAML (asset-name drift gate)
+        run: |
+          python3 -c 'import yaml' \
+            || python3 -m pip install --break-system-packages PyYAML \
+            || python3 -m pip install PyYAML
+
+      - name: Scope guardrail (no AI/vector/LLM crates + release asset-name drift)
         run: bash scripts/guardrail.sh
 
   windows:
diff --git a/Makefile b/Makefile
index 6ee40c6..16103d9 100644
--- a/Makefile
+++ b/Makefile
@@ -126,7 +126,8 @@ test:
 	@echo "🧪 Running tests..."
 	$(CARGO) test --workspace
 
-# Scope guardrail: no AI / vector / LLM crates allowed in the workspace
+# Scope guardrail: no AI / vector / LLM crates in the workspace, and no drift
+# between the release workflow's asset names and what the installers download.
 guardrail:
 	@echo "🛡️  Running scope guardrail..."
 	bash scripts/guardrail.sh
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index c5146a8..794a55b 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -6433,3 +6433,229 @@ canonicalization byte changed. `KNOWN_DIFFS.md` itself is untouched.
 and refused this worktree again (`LSP file path must be inside request cwd`); no
 LSP-clean result is claimed. The equivalent evidence is the locked `clippy -D
 warnings` run above plus `make ci`.
+
+## Batch E2 — the asset-name contract becomes machine-checked (2026-07-28)
+
+### The three-way verification came back CLEAN
+
+Before writing a line of code the three producers of the release archive name were
+read side by side and compared literally. They agree today:
+
+| surface                   | name expression                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------- |
+| workflow tar.gz packaging | `dist/${BINARY_NAME}-${{ needs.release-please.outputs.version }}-${{ matrix.target }}.tar.gz`  |
+| workflow zip packaging    | `dist/${env:BINARY_NAME}-${{ needs.release-please.outputs.version }}-${{ matrix.target }}.zip` |
+| artifact upload           | `name: dist-${{ matrix.target }}`, `path: dist/*`                                              |
+| `upload-assets` download  | `pattern: dist-*`, `merge-multiple: true`                                                      |
+| `scripts/install.sh`      | `BIN="codegraph"`, `asset="${BIN}-${version}-${target}.${ext}"`                                |
+| `scripts/install.ps1`     | `$Bin = 'codegraph'`, `$asset = "$Bin-$version-$target.$ext"`                                  |
+
+`env.BINARY_NAME` is `codegraph`, identical to `install.sh`'s `BIN` and
+`install.ps1`'s `$Bin`. `install.sh` builds `target="${arch_part}-${os_part}"`
+from `{x86_64, aarch64} x {unknown-linux-musl, apple-darwin}`, and `install.ps1`
+builds `"$archPart-pc-windows-msvc"` from `{x86_64, aarch64}` — together exactly
+the six matrix triples, no orphan on either side. The `aarch64-pc-windows-msvc`
+question was checked specifically, because it is the one target whose installer
+path is easy to get wrong: `install.ps1` matches `^(ARM64|aarch64)$` against
+`PROCESSOR_ARCHITEW6432` (falling back to `PROCESSOR_ARCHITECTURE`, then
+`RuntimeInformation.OSArchitecture`), so a Windows-on-ARM host does yield
+`aarch64-pc-windows-msvc`. **No defect was found there**; nothing in either
+installer needed changing, and neither installer's checksum logic was touched.
+
+So this commit fixes no bug. It closes a hole in the _process_.
+
+### The gap: agreement with no mechanism to keep it
+
+The agreement above is a property of the current bytes, not an enforced invariant.
+`tar -czf "dist/…"` in the workflow and `asset="…"` in `install.sh` are two
+independent string concatenations with nothing linking them. Change either one and
+`cargo test`, `clippy`, `fmt`, the guardrail, and all six cross-compiles still
+pass — CI has no opinion about it. The failure surfaces only _after_ a release: the
+archives are already public, `SHA256SUMS` is already generated over the
+differently-named files, `publish-release` has already flipped the Release to
+`draft=false`, and the one-liner installers 404. That is a real, foreseeable
+failure path with, until now, zero protection. E3 made the _contents_ of a release
+verifiable; E2 makes the _names_ verifiable.
+
+### What was added
+
+`scripts/check-asset-names.sh` — a standalone gate that re-derives all three names
+**from the real files** on every run (`.github/workflows/release-please.yml` via
+`yaml.safe_load`, `scripts/install.sh` and `scripts/install.ps1` via anchored
+regexes over their actual source). It hard-codes no expected asset name: the only
+literal it owns is the canonical skeleton `<bin>-<version>-<target>.<ext>`, which
+is a _shape_, not a copy of any side's value. A hard-coded duplicate of the
+expected names would itself drift and turn the gate into decoration.
+
+Seven assertions, each naming the side at fault when it trips:
+
+1. `binary-name` — `env.BINARY_NAME` == `BIN` == `$Bin`.
+2. asset skeleton — all four name expressions (workflow tar.gz, workflow zip,
+   `install.sh`, `install.ps1`) normalize to the same skeleton.
+3. `extension(unix|windows)` — the workflow's packaged extension per family
+   equals the extension the matching installer downloads.
+4. `target-coverage` — every matrix target is producible by **exactly one**
+   installer's platform detection, with that installer's extension; and no
+   installer can ask for a target the matrix never builds (both directions).
+5. `artifact-plumbing` — the rendered `upload-artifact` `name:` matches the
+   `download-artifact` `pattern:`, `merge-multiple` is `true`, and `path:` covers
+   the packaged archives.
+6. `release-files` — every rendered archive, plus the `SHA256SUMS` name both
+   installers fetch, is covered by a release `files:` glob.
+7. `archive-member` — the workflow tars/zips the same in-archive binary name the
+   installers extract (`codegraph` / `codegraph.exe`).
+
+### Granularity — the deliberate trade-off
+
+Comparison is on the **normalized skeleton**, not on raw source bytes. Each side's
+expression is parsed and its interpolations are replaced by canonical placeholders
+(`${BINARY_NAME}`/`${env:BINARY_NAME}`/`$Bin`/`${BIN}` → `<bin>`,
+`${{ needs.*.outputs.version }}`/`$version`/`${version}` → `<version>`, and so on),
+then all four must reduce to `<bin>-<version>-<target>.<ext>`.
+
+- Too strict (exact source-string comparison) would redden on YAML re-indentation,
+  a renamed shell variable, or routing the version through a different workflow
+  expression — none of which change a single published byte. False alarms train
+  people to weaken the gate.
+- Too loose (e.g. "does the name contain the version somewhere") would miss field
+  reordering, a changed separator, or a stray prefix — the exact mutations that
+  break the installers.
+
+The skeleton sits between the two: blind to how a value is spelled, sensitive to
+field order, separators, affixes, and extension. Scenario C in the harness pins
+the loose end (a comment plus requoting `path: dist/*` → `path: "dist/*"` stays
+green); scenarios D and G pin the strict end (a `-` → `_` separator change and a
+`<version>`/`<target>` swap both go red). The globs (`pattern:`, `path:`,
+`files:`) are additionally matched against _concrete_ rendered names using
+`fnmatch`, so the plumbing that moves the archives is checked, not just the
+archives' names.
+
+Where the gate cannot parse a side, it **fails** (exit 2) rather than passing —
+an unverifiable contract is exactly when drift hides. Scenario J proves it.
+
+### Negative control, EXECUTED — four mutants, each blamed correctly
+
+Each mutant was applied to a throwaway copy of the three real files (the real
+repository tree was never modified) and the gate run against that fixture root.
+Real output:
+
+```text
+##### MUTANT m1 — workflow tar.gz separator `-` → `_` #####
+check-asset-names: MISMATCH [workflow(tar.gz)]: asset skeleton is '<bin>_<version>-<target>.<ext>' but the other sides use '<bin>-<version>-<target>.<ext>'
+check-asset-names: FAIL: 1 asset-name disagreement(s) between the release workflow and the installers
+EXIT=1
+
+##### MUTANT m2 — install.sh BIN="codegraph" → "codegraf" #####
+check-asset-names: MISMATCH [binary-name]: workflow env.BINARY_NAME='codegraph' vs install.sh BIN='codegraf' vs install.ps1 $Bin='codegraph'
+check-asset-names: FAIL: 1 asset-name disagreement(s) between the release workflow and the installers
+EXIT=1
+
+##### MUTANT m3 — upload-assets `pattern: dist-*` → `bins-*` #####
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-x86_64-unknown-linux-musl' does not match upload-assets pattern 'bins-*'
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-aarch64-unknown-linux-musl' does not match upload-assets pattern 'bins-*'
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-x86_64-apple-darwin' does not match upload-assets pattern 'bins-*'
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-aarch64-apple-darwin' does not match upload-assets pattern 'bins-*'
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-x86_64-pc-windows-msvc' does not match upload-assets pattern 'bins-*'
+check-asset-names: MISMATCH [artifact-plumbing]: upload-artifact name 'dist-aarch64-pc-windows-msvc' does not match upload-assets pattern 'bins-*'
+check-asset-names: FAIL: 6 asset-name disagreement(s) between the release workflow and the installers
+EXIT=1
+
+##### MUTANT m4 — install.ps1 loses the `^(ARM64|aarch64)$` arm #####
+check-asset-names: MISMATCH [target-coverage]: matrix target 'aarch64-pc-windows-msvc' cannot be produced by either installer's platform detection (install.sh yields ['aarch64-apple-darwin', 'aarch64-unknown-linux-musl', 'x86_64-apple-darwin', 'x86_64-unknown-linux-musl']; install.ps1 yields ['x86_64-pc-windows-msvc'])
+check-asset-names: FAIL: 1 asset-name disagreement(s) between the release workflow and the installers
+EXIT=1
+```
+
+Each mutant names a **different** category — `workflow(tar.gz)`, `binary-name`,
+`artifact-plumbing`, `target-coverage` — and the harness additionally asserts the
+_absence_ of the other categories, so a mutant cannot pass by reddening something
+unrelated. The `m4` shape is the ARM64-coverage question from the audit above,
+inverted into a test: were the ARM64 arm ever dropped, the gate now says so by
+name.
+
+### Tests added — `scripts/tests/asset-name-drift.test.sh`
+
+Ten scenarios, no Cargo, no network, no repository file touched (each copies the
+three real files into a `mktemp -d` fixture and mutates one). Mutation anchors are
+asserted present before substitution, so a future refactor that moves an anchor
+makes the harness fail loudly instead of silently neutering a mutant into a no-op:
+
+| scenario              | mutation                                  | expect                                             |
+| --------------------- | ----------------------------------------- | -------------------------------------------------- |
+| A `pristine`          | none (verbatim copies)                    | `0`, all six targets listed with their owner       |
+| B `repository`        | none, run on the real repo root           | `0`, `check-asset-names: OK`                       |
+| C `cosmetic`          | comment + requote `path:`/`pattern:`      | `0` — churn is not drift                           |
+| D `workflow_tar_name` | tar.gz separator `-` → `_`                | `1`, blames `workflow(tar.gz)` only                |
+| E `install_sh_bin`    | `BIN="codegraf"`                          | `1`, blames `binary-name`, prints all three values |
+| F `download_pattern`  | `pattern: bins-*`                         | `1`, blames `artifact-plumbing`                    |
+| G `ps1_field_order`   | `$Bin-$target-$version.$ext`              | `1`, blames `install.ps1` only                     |
+| H `ps1_drops_arm64`   | delete the `^(ARM64\|aarch64)$` arm       | `1`, names `aarch64-pc-windows-msvc`               |
+| I `sums_unpublished`  | drop `dist/SHA256SUMS` from `files:`      | `1`, blames `release-files`                        |
+| J `unparsable`        | replace `tar -czf` with `bsdtar --create` | nonzero — fails CLOSED, never a silent pass        |
+
+Scenario I is the E2/E3 seam: E3's `SHA256SUMS` is only useful if it is actually
+published under the name both installers fetch, so an unpublished sums file is
+asset-name drift and reddens here. E3's own harness and the workflow's
+`Generate SHA256SUMS` step were not modified.
+
+### CI wiring — inside `scripts/guardrail.sh`, not a new `make ci` step
+
+The gate runs as a second block of `scripts/guardrail.sh` rather than as its own
+Makefile target. Reason: `guardrail` is the single step already invoked by **all
+four** enforcement paths — `make ci`, the `.githooks/pre-push` hook, the CI `test`
+job, and (transitively) the release workflow's `verify-ci` wait on `CI Success`. A
+new `make ci` target would be missed by the pre-push hook and by CI unless three
+more files were edited, and a check that only some paths run is not a gate. The
+guardrail is also the right conceptual home: both blocks assert repository-level
+invariants that no Rust test can express. `ci.yml` gains one idempotent step that
+ensures PyYAML is importable, so a missing parser can never degrade the gate into
+a skip (and the gate itself exits nonzero if the import fails anyway). The
+guardrail resolves the gate by `dirname "$0"`, so it works from any cwd —
+verified by running it from `/tmp`.
+
+### Windows — runtime-UNVERIFIED
+
+`install.ps1` is read, not executed: this host is Linux with no PowerShell. The
+`aarch64-pc-windows-msvc` conclusion above is a **code-reading argument** about
+`PROCESSOR_ARCHITEW6432` / `PROCESSOR_ARCHITECTURE` / `RuntimeInformation`, and the
+gate's knowledge of `install.ps1` is likewise static parsing of its source. No
+native Windows/MSVC runtime verification was performed or is claimed. The file's
+bytes are unchanged by this commit, so no new Windows risk is introduced.
+
+### Golden delta
+
+`GIT_MASTER=1 git diff --stat 5c585ec..HEAD -- reference/golden/` → **EMPTY**. This
+commit adds two shell scripts and edits `guardrail.sh`, `Makefile`, `ci.yml`,
+`.githooks/pre-push`, and this ledger. No extraction, resolution, or
+canonicalization code was touched, so no golden could change and none was
+regenerated.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-asset-names.sh` → exit **0** (`check-asset-names: OK`, six
+  matrix targets, each owned by exactly one installer).
+- `bash scripts/tests/asset-name-drift.test.sh` → exit **0**, **10 passed, 0
+  failed**.
+- Four standalone mutants → exit **1**, **1**, **1**, **1** with the diagnostics
+  quoted verbatim above.
+- `bash scripts/guardrail.sh` → exit **0** from the repo root and exit **0** from
+  `/tmp` (cwd independence).
+- `python3 -c 'import yaml'` → exit **0** (PyYAML 6.0.3 on this host);
+  `yaml.safe_load` on the mutated `ci.yml` parses and lists the new step between
+  `Run tests …` and `Scope guardrail …`.
+- `bash scripts/check-workspace-versions.sh` → recorded below; run before the
+  Cargo-invoking gates. Every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-bench --test equivalence` → recorded below
+  (floor: 28 after E1).
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  prose and `make fmt`; recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+  No dependency was added, no version byte moved; release-please still owns
+  versions.
+
+`lsp_diagnostics` was attempted and refused this worktree again (`LSP file path
+must be inside request cwd`); no LSP-clean result is claimed. The changed files are
+shell, YAML and Markdown, which the Rust toolchain does not lint — the honest
+checks for them are the executable harness, the four mutants, the YAML parse, and
+`make ci`.
diff --git a/scripts/check-asset-names.sh b/scripts/check-asset-names.sh
new file mode 100755
index 0000000..84dec52
--- /dev/null
+++ b/scripts/check-asset-names.sh
@@ -0,0 +1,540 @@
+#!/usr/bin/env bash
+# check-asset-names.sh — release asset-name drift gate.
+#
+# Purpose
+#   The release archive name is assembled INDEPENDENTLY in three places:
+#
+#     1. .github/workflows/release-please.yml — the packaging steps
+#        (`tar -czf "dist/..."`, `Compress-Archive -DestinationPath "dist/..."`),
+#        the artifact `name:`/`path:`, the `download-artifact` `pattern:`, and the
+#        `files:` list attached to the GitHub Release,
+#     2. scripts/install.sh   — `asset="${BIN}-${version}-${target}.${ext}"`,
+#     3. scripts/install.ps1  — `$asset = "$Bin-$version-$target.$ext"`.
+#
+#   Nothing in CI links those three strings. Change any ONE of them and every
+#   test, lint, and build still passes; the failure only appears AFTER a release
+#   is cut, when the installers 404 on an asset that was published under a
+#   different name — by which point the archives are public and SHA256SUMS is
+#   already generated over them. This gate closes that window by re-deriving all
+#   three names FROM THE REAL FILES on every CI run and asserting they agree.
+#
+# Comparison granularity (deliberate trade-off)
+#   Comparison is on the NORMALIZED SKELETON, not on raw source bytes. Each side's
+#   name expression is parsed and its interpolations are replaced by canonical
+#   placeholders (`<bin>`, `<version>`, `<target>`, `<ext>`), so all three must
+#   reduce to exactly `<bin>-<version>-<target>.<ext>`.
+#     * Immune to harmless edits: YAML re-indentation, renaming a shell variable,
+#       moving the version through a different workflow expression, comment churn.
+#     * Sensitive to every edit that actually changes the published name: field
+#       order, separators, prefixes/suffixes, extension, and the binary name.
+#   Concrete names (rendered with a probe version) are additionally matched
+#   against the artifact `pattern:` and Release `files:` globs, so the plumbing
+#   that MOVES the archives is checked too, not just the archives' names.
+#
+#   Anything this gate cannot parse is a FAILURE, never a silent pass: an
+#   unparsable side means the contract is no longer verifiable, which is exactly
+#   when drift hides.
+#
+# Runs no Cargo, makes no network request, writes nothing.
+#
+# Usage
+#   scripts/check-asset-names.sh [REPO_ROOT]
+#   REPO_ROOT defaults to the repository root (the script's parent dir).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="${1:-"$(cd -- "$SCRIPT_DIR/.." && pwd -P)"}"
+
+command -v python3 > /dev/null 2>&1 || {
+	printf 'check-asset-names: ERROR: python3 not found (needed to parse the release workflow YAML)\n' >&2
+	exit 2
+}
+
+CG_ASSET_ROOT="$REPO_ROOT" python3 <<'PY'
+import fnmatch
+import os
+import re
+import sys
+
+ROOT = os.environ["CG_ASSET_ROOT"]
+WORKFLOW = os.path.join(ROOT, ".github", "workflows", "release-please.yml")
+INSTALL_SH = os.path.join(ROOT, "scripts", "install.sh")
+INSTALL_PS1 = os.path.join(ROOT, "scripts", "install.ps1")
+
+# A version that could never be confused with a placeholder, used to render
+# concrete asset names for the glob/pattern checks.
+PROBE_VERSION = "9.9.9"
+CANONICAL_SKELETON = "<bin>-<version>-<target>.<ext>"
+
+failures = []
+
+
+def fail(side, msg):
+    failures.append((side, msg))
+
+
+def die(msg, code=2):
+    print("check-asset-names: ERROR: %s" % msg, file=sys.stderr)
+    sys.exit(code)
+
+
+def read(path, label):
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        die("cannot read %s (%s): %s" % (label, path, exc))
+
+
+try:
+    import yaml
+except ImportError:
+    die(
+        "PyYAML is required to parse the release workflow "
+        "(pip install PyYAML / apt install python3-yaml)"
+    )
+
+# ---------------------------------------------------------------------------
+# Normalization: collapse each side's interpolations to canonical placeholders.
+# ---------------------------------------------------------------------------
+WF_SUBS = [
+    (re.compile(r"\$\{\{\s*needs\.[A-Za-z0-9_.-]+\.outputs\.version\s*\}\}"), "<version>"),
+    (re.compile(r"\$\{\{\s*matrix\.target\s*\}\}"), "<target>"),
+    (re.compile(r"\$\{BINARY_NAME\}"), "<bin>"),
+    (re.compile(r"\$\{env:BINARY_NAME\}"), "<bin>"),
+]
+
+SH_SUBS = [
+    (re.compile(r"\$\{BIN\}"), "<bin>"),
+    (re.compile(r"\$\{version\}"), "<version>"),
+    (re.compile(r"\$\{target\}"), "<target>"),
+    (re.compile(r"\$\{ext\}"), "<ext>"),
+]
+
+PS_SUBS = [
+    (re.compile(r"\$Bin\b"), "<bin>"),
+    (re.compile(r"\$version\b"), "<version>"),
+    (re.compile(r"\$target\b"), "<target>"),
+    (re.compile(r"\$ext\b"), "<ext>"),
+]
+
+
+def normalize(text, subs):
+    for pattern, replacement in subs:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def split_ext(side, template, want_ext):
+    """`<bin>-<version>-<target>.tar.gz` -> (`<bin>-...-<target>.<ext>`, 'tar.gz')."""
+    suffix = "." + want_ext
+    if not template.endswith(suffix):
+        fail(side, "asset template %r does not end in the expected %r" % (template, suffix))
+        return None, None
+    return template[: -len(want_ext)] + "<ext>", want_ext
+
+
+def strip_dist(side, path):
+    if not path.startswith("dist/"):
+        fail(side, "packaged archive path %r is not under dist/ (the uploaded directory)" % path)
+        return None
+    return path[len("dist/") :]
+
+
+# ---------------------------------------------------------------------------
+# Side 1 — the release workflow.
+# ---------------------------------------------------------------------------
+wf_text = read(WORKFLOW, "release workflow")
+try:
+    wf = yaml.safe_load(wf_text)
+except yaml.YAMLError as exc:
+    die("release workflow is not valid YAML: %s" % exc)
+if not isinstance(wf, dict):
+    die("release workflow did not parse to a mapping")
+
+wf_bin = (wf.get("env") or {}).get("BINARY_NAME")
+if not isinstance(wf_bin, str) or not wf_bin:
+    die("could not read env.BINARY_NAME from the release workflow")
+
+jobs = wf.get("jobs")
+if not isinstance(jobs, dict):
+    die("release workflow has no jobs mapping")
+
+
+def job(name):
+    j = jobs.get(name)
+    if not isinstance(j, dict):
+        die("release workflow has no `%s` job" % name)
+    return j
+
+
+build = job("build-binaries")
+upload = job("upload-assets")
+
+matrix = (((build.get("strategy") or {}).get("matrix") or {})).get("include")
+if not isinstance(matrix, list) or not matrix:
+    die("could not read the build-binaries matrix `include` list")
+
+matrix_targets = []
+for entry in matrix:
+    if not isinstance(entry, dict) or "target" not in entry or "archive" not in entry:
+        die("matrix entry %r lacks `target` and/or `archive`" % (entry,))
+    matrix_targets.append((str(entry["target"]), str(entry["archive"])))
+
+build_steps = build.get("steps")
+if not isinstance(build_steps, list):
+    die("build-binaries job has no steps")
+
+
+def run_scripts(steps):
+    return [s.get("run") for s in steps if isinstance(s, dict) and isinstance(s.get("run"), str)]
+
+
+TAR_RE = re.compile(r'tar\s+-czf\s+"([^"]+)"', re.S)
+TAR_MEMBER_RE = re.compile(r'-C\s+"[^"]*"\s+"([^"]+)"', re.S)
+ZIP_DEST_RE = re.compile(r'-DestinationPath\s+"([^"]+)"', re.S)
+ZIP_SRC_RE = re.compile(r'-Path\s+"([^"]+)"', re.S)
+
+tar_path = tar_member = zip_path = zip_member = None
+for script in run_scripts(build_steps):
+    norm = normalize(script, WF_SUBS)
+    m = TAR_RE.search(norm)
+    if m and tar_path is None:
+        tar_path = m.group(1)
+        mm = TAR_MEMBER_RE.search(norm)
+        if mm:
+            tar_member = mm.group(1)
+    m = ZIP_DEST_RE.search(norm)
+    if m and zip_path is None:
+        zip_path = m.group(1)
+        ms = ZIP_SRC_RE.search(norm)
+        if ms:
+            zip_member = os.path.basename(ms.group(1))
+
+if tar_path is None:
+    die("could not find the `tar -czf \"dist/...\"` packaging step in build-binaries")
+if zip_path is None:
+    die("could not find the `Compress-Archive -DestinationPath \"dist/...\"` step in build-binaries")
+if tar_member is None or zip_member is None:
+    die("could not read the archived binary name from the packaging steps")
+
+artifact_name = artifact_path = None
+for step in build_steps:
+    uses = step.get("uses") if isinstance(step, dict) else None
+    if isinstance(uses, str) and uses.startswith("actions/upload-artifact"):
+        with_ = step.get("with") or {}
+        artifact_name = normalize(str(with_.get("name", "")), WF_SUBS)
+        artifact_path = str(with_.get("path", ""))
+        break
+if not artifact_name or not artifact_path:
+    die("could not read the upload-artifact `name:`/`path:` from build-binaries")
+
+upload_steps = upload.get("steps")
+if not isinstance(upload_steps, list):
+    die("upload-assets job has no steps")
+
+download_pattern = None
+download_merge = None
+release_files = None
+for step in upload_steps:
+    uses = step.get("uses") if isinstance(step, dict) else None
+    if not isinstance(uses, str):
+        continue
+    with_ = step.get("with") or {}
+    if uses.startswith("actions/download-artifact"):
+        download_pattern = with_.get("pattern")
+        download_merge = with_.get("merge-multiple")
+    elif uses.startswith("softprops/action-gh-release"):
+        files = with_.get("files")
+        if isinstance(files, str):
+            release_files = [ln.strip() for ln in files.splitlines() if ln.strip()]
+if not isinstance(download_pattern, str) or not download_pattern:
+    die("could not read the download-artifact `pattern:` from upload-assets")
+if not release_files:
+    die("could not read the release `files:` list from upload-assets")
+
+wf_tar_template = strip_dist("workflow(tar.gz)", tar_path)
+wf_zip_template = strip_dist("workflow(zip)", zip_path)
+wf_tar_skeleton = wf_tar_ext = wf_zip_skeleton = wf_zip_ext = None
+if wf_tar_template is not None:
+    wf_tar_skeleton, wf_tar_ext = split_ext("workflow(tar.gz)", wf_tar_template, "tar.gz")
+if wf_zip_template is not None:
+    wf_zip_skeleton, wf_zip_ext = split_ext("workflow(zip)", wf_zip_template, "zip")
+
+# ---------------------------------------------------------------------------
+# Side 2 — scripts/install.sh.
+# ---------------------------------------------------------------------------
+sh_text = read(INSTALL_SH, "install.sh")
+
+
+def sh_assign(name):
+    m = re.search(r'^%s="([^"]*)"' % re.escape(name), sh_text, re.M)
+    return m.group(1) if m else None
+
+
+sh_bin = sh_assign("BIN")
+sh_ext = sh_assign("ext")
+sh_asset_raw = sh_assign("asset")
+sh_target_raw = sh_assign("target")
+sh_sums = sh_assign("SUMS")
+for label, value in (
+    ("BIN", sh_bin),
+    ("ext", sh_ext),
+    ("asset", sh_asset_raw),
+    ("target", sh_target_raw),
+    ("SUMS", sh_sums),
+):
+    if value is None:
+        die("could not parse %s= from scripts/install.sh" % label)
+
+sh_os_parts = re.findall(r'os_part="([^"]+)"', sh_text)
+sh_arch_parts = re.findall(r'arch_part="([^"]+)"', sh_text)
+if not sh_os_parts or not sh_arch_parts:
+    die("could not parse the os_part/arch_part detection tables from scripts/install.sh")
+
+if sh_target_raw != "${arch_part}-${os_part}":
+    fail(
+        "install.sh",
+        "target is built as %r; this gate understands only \"${arch_part}-${os_part}\""
+        % sh_target_raw,
+    )
+sh_targets = sorted({"%s-%s" % (a, o) for a in sh_arch_parts for o in sh_os_parts})
+
+sh_asset_template = normalize(sh_asset_raw, SH_SUBS)
+sh_skeleton = sh_asset_template if "<ext>" in sh_asset_template else None
+if sh_skeleton is None:
+    fail("install.sh", "asset template %r does not interpolate ${ext}" % sh_asset_raw)
+
+sh_member = "<bin>" if re.search(r'\[ -f "\$tmp/\$BIN" \]', sh_text) else None
+if sh_member is None:
+    fail("install.sh", "could not confirm the expected in-archive binary name ($tmp/$BIN)")
+
+# ---------------------------------------------------------------------------
+# Side 3 — scripts/install.ps1.
+# ---------------------------------------------------------------------------
+ps_text = read(INSTALL_PS1, "install.ps1")
+
+
+def ps_assign(name):
+    m = re.search(r"^\$%s\s*=\s*'([^']*)'" % re.escape(name), ps_text, re.M)
+    if m:
+        return m.group(1)
+    m = re.search(r'^\$%s\s*=\s*"([^"]*)"' % re.escape(name), ps_text, re.M)
+    return m.group(1) if m else None
+
+
+ps_bin = ps_assign("Bin")
+ps_ext = ps_assign("ext")
+ps_asset_raw = ps_assign("asset")
+ps_target_raw = ps_assign("target")
+ps_sums = ps_assign("sums")
+for label, value in (
+    ("Bin", ps_bin),
+    ("ext", ps_ext),
+    ("asset", ps_asset_raw),
+    ("target", ps_target_raw),
+    ("sums", ps_sums),
+):
+    if value is None:
+        die("could not parse $%s = from scripts/install.ps1" % label)
+
+ps_arch_parts = re.findall(r"\$archPart\s*=\s*'([^']+)'", ps_text)
+if not ps_arch_parts:
+    die("could not parse the $archPart detection table from scripts/install.ps1")
+
+ps_target_template = normalize(ps_target_raw, PS_SUBS)
+# `$archPart-pc-windows-msvc` -> the fixed windows suffix each arch is joined to.
+ps_suffix_match = re.match(r"^\$archPart(-[A-Za-z0-9_.-]+)$", ps_target_raw)
+if not ps_suffix_match:
+    fail(
+        "install.ps1",
+        "target is built as %r; this gate understands only \"$archPart-<suffix>\"" % ps_target_raw,
+    )
+    ps_targets = []
+else:
+    ps_targets = sorted({a + ps_suffix_match.group(1) for a in ps_arch_parts})
+
+ps_asset_template = normalize(ps_asset_raw, PS_SUBS)
+ps_skeleton = ps_asset_template if "<ext>" in ps_asset_template else None
+if ps_skeleton is None:
+    fail("install.ps1", "asset template %r does not interpolate $ext" % ps_asset_raw)
+
+ps_member = "<bin>.exe" if re.search(r'Join-Path \$tmp "\$Bin\.exe"', ps_text) else None
+if ps_member is None:
+    fail("install.ps1", 'could not confirm the expected in-archive binary name ($tmp/"$Bin.exe")')
+
+# ---------------------------------------------------------------------------
+# A1 — the binary name must be identical on all three sides.
+# ---------------------------------------------------------------------------
+if not (wf_bin == sh_bin == ps_bin):
+    fail(
+        "binary-name",
+        "workflow env.BINARY_NAME=%r vs install.sh BIN=%r vs install.ps1 $Bin=%r"
+        % (wf_bin, sh_bin, ps_bin),
+    )
+
+# ---------------------------------------------------------------------------
+# A2 — every side must reduce to the SAME canonical skeleton.
+# ---------------------------------------------------------------------------
+for side, skeleton in (
+    ("workflow(tar.gz)", wf_tar_skeleton),
+    ("workflow(zip)", wf_zip_skeleton),
+    ("install.sh", sh_skeleton),
+    ("install.ps1", ps_skeleton),
+):
+    if skeleton is None:
+        continue
+    if skeleton != CANONICAL_SKELETON:
+        fail(
+            side,
+            "asset skeleton is %r but the other sides use %r" % (skeleton, CANONICAL_SKELETON),
+        )
+
+# ---------------------------------------------------------------------------
+# A3 — per-family extension agreement.
+# ---------------------------------------------------------------------------
+if wf_tar_ext is not None and sh_ext != wf_tar_ext:
+    fail(
+        "extension(unix)",
+        "workflow packages %r but install.sh downloads %r" % (wf_tar_ext, sh_ext),
+    )
+if wf_zip_ext is not None and ps_ext != wf_zip_ext:
+    fail(
+        "extension(windows)",
+        "workflow packages %r but install.ps1 downloads %r" % (wf_zip_ext, ps_ext),
+    )
+
+# ---------------------------------------------------------------------------
+# A4 — every matrix target must be producible by exactly one installer, with the
+# extension that installer expects.
+# ---------------------------------------------------------------------------
+for target, archive in matrix_targets:
+    in_sh = target in sh_targets
+    in_ps = target in ps_targets
+    if not in_sh and not in_ps:
+        fail(
+            "target-coverage",
+            "matrix target %r cannot be produced by either installer's platform "
+            "detection (install.sh yields %s; install.ps1 yields %s)"
+            % (target, sh_targets, ps_targets),
+        )
+        continue
+    if in_sh and in_ps:
+        fail(
+            "target-coverage",
+            "matrix target %r is claimed by BOTH installers (ambiguous)" % target,
+        )
+        continue
+    owner, owner_ext = ("install.sh", sh_ext) if in_sh else ("install.ps1", ps_ext)
+    if owner_ext != archive:
+        fail(
+            "target-coverage",
+            "matrix target %r is packaged as %r but %s downloads %r"
+            % (target, archive, owner, owner_ext),
+        )
+
+for target in sh_targets + ps_targets:
+    if target not in [t for t, _ in matrix_targets]:
+        fail(
+            "target-coverage",
+            "installer platform detection can ask for target %r, which the release "
+            "matrix never builds" % target,
+        )
+
+# ---------------------------------------------------------------------------
+# A5 — artifact plumbing: the download pattern must match every rendered
+# artifact name, the merge must be enabled, and the upload path must include the
+# packaged archives.
+# ---------------------------------------------------------------------------
+for target, _archive in matrix_targets:
+    rendered_artifact = artifact_name.replace("<target>", target)
+    if not fnmatch.fnmatchcase(rendered_artifact, download_pattern):
+        fail(
+            "artifact-plumbing",
+            "upload-artifact name %r does not match upload-assets pattern %r"
+            % (rendered_artifact, download_pattern),
+        )
+if download_merge is not True:
+    fail(
+        "artifact-plumbing",
+        "download-artifact `merge-multiple` is %r; per-target artifacts would land in "
+        "separate subdirectories and the release globs would miss them" % (download_merge,),
+    )
+
+# ---------------------------------------------------------------------------
+# A6 — the Release `files:` globs must cover every rendered archive plus the
+# checksum file the installers fetch by name.
+# ---------------------------------------------------------------------------
+rendered_assets = []
+for target, archive in matrix_targets:
+    rendered_assets.append(
+        CANONICAL_SKELETON.replace("<bin>", wf_bin)
+        .replace("<version>", PROBE_VERSION)
+        .replace("<target>", target)
+        .replace("<ext>", archive)
+    )
+
+for asset in rendered_assets:
+    in_dist = "dist/" + asset
+    if not any(fnmatch.fnmatchcase(in_dist, glob) for glob in release_files):
+        fail(
+            "release-files",
+            "archive %r is not covered by any release `files:` glob %s" % (in_dist, release_files),
+        )
+    if not fnmatch.fnmatchcase(in_dist, artifact_path):
+        fail(
+            "artifact-plumbing",
+            "archive %r is not covered by the upload-artifact path %r" % (in_dist, artifact_path),
+        )
+
+if sh_sums != ps_sums:
+    fail("checksums", "install.sh SUMS=%r != install.ps1 $sums=%r" % (sh_sums, ps_sums))
+else:
+    sums_in_dist = "dist/" + sh_sums
+    if not any(fnmatch.fnmatchcase(sums_in_dist, glob) for glob in release_files):
+        fail(
+            "release-files",
+            "the installers fetch %r but no release `files:` glob %s publishes it"
+            % (sh_sums, release_files),
+        )
+
+# ---------------------------------------------------------------------------
+# A7 — the archived binary name must be what the installers look for.
+# ---------------------------------------------------------------------------
+if sh_member is not None and tar_member != sh_member:
+    fail(
+        "archive-member",
+        "workflow tars member %r but install.sh extracts %r" % (tar_member, sh_member),
+    )
+if ps_member is not None and zip_member != ps_member:
+    fail(
+        "archive-member",
+        "workflow zips member %r but install.ps1 extracts %r" % (zip_member, ps_member),
+    )
+
+# ---------------------------------------------------------------------------
+# Report.
+# ---------------------------------------------------------------------------
+if failures:
+    for side, msg in failures:
+        print("check-asset-names: MISMATCH [%s]: %s" % (side, msg), file=sys.stderr)
+    print(
+        "check-asset-names: FAIL: %d asset-name disagreement(s) between the release "
+        "workflow and the installers" % len(failures),
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+print("check-asset-names: OK")
+print("  binary name        : %s (workflow == install.sh == install.ps1)" % wf_bin)
+print("  asset skeleton     : %s" % CANONICAL_SKELETON)
+print("  unix  ext          : %s (workflow tar.gz step == install.sh)" % sh_ext)
+print("  windows ext        : %s (workflow zip step == install.ps1)" % ps_ext)
+print("  checksum file      : %s (published and fetched by both installers)" % sh_sums)
+print("  artifact plumbing  : %s -> pattern %s (merge-multiple: true)" % (artifact_name, download_pattern))
+print("  matrix targets     : %d, each produced by exactly one installer" % len(matrix_targets))
+for target, archive in matrix_targets:
+    owner = "install.sh" if target in sh_targets else "install.ps1"
+    print("    %-28s %-7s %s" % (target, archive, owner))
+PY
diff --git a/scripts/guardrail.sh b/scripts/guardrail.sh
index 2f01f5f..8f6d0be 100755
--- a/scripts/guardrail.sh
+++ b/scripts/guardrail.sh
@@ -1,6 +1,8 @@
 #!/bin/sh
-# Scope guardrail: forbid AI/vector/LLM crates from being added to the workspace
+# Scope guardrail: forbid AI/vector/LLM crates from being added to the workspace,
+# and hold the release asset-name contract (see the second block below).
 
+SCRIPT_DIR=$(dirname "$0")
 FORBIDDEN='surrealdb|rig-|qdrant|lancedb|candle|onnx|\bort\b'
 EXIT_CODE=0
 
@@ -15,4 +17,15 @@ for toml in $(find . -name 'Cargo.toml' -not -path '*/reference/*' -not -path '*
     fi
 done
 
+# Release asset-name contract: the archive name is assembled independently in the
+# release workflow and in both installers, and nothing else in CI links those
+# strings — drift there is invisible until AFTER a release is published. This gate
+# lives here rather than in a Cargo test because it parses CI/shell/PowerShell
+# files, not Rust, and `guardrail` is the one step run by make ci, the pre-push
+# hook, AND both CI jobs.
+if ! bash "$SCRIPT_DIR/check-asset-names.sh"; then
+    echo "❌ RELEASE ASSET-NAME DRIFT: the release workflow and the installers disagree."
+    EXIT_CODE=1
+fi
+
 exit $EXIT_CODE
diff --git a/scripts/tests/asset-name-drift.test.sh b/scripts/tests/asset-name-drift.test.sh
new file mode 100755
index 0000000..5b2536e
--- /dev/null
+++ b/scripts/tests/asset-name-drift.test.sh
@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# asset-name-drift.test.sh — fixture harness for the asset-name drift gate.
+#
+# Copies the three REAL files the gate parses
+#   .github/workflows/release-please.yml, scripts/install.sh, scripts/install.ps1
+# into a throwaway repo-shaped fixture, mutates ONE of them per scenario, and runs
+# scripts/check-asset-names.sh against that fixture root. Nothing under the real
+# repository is touched, no Cargo runs, no network request is made.
+#
+# It proves the gate:
+#   * pristine copy of the real files            -> exit 0,
+#   * the real repository root                   -> exit 0,
+#   * cosmetic YAML churn (comment + requoting)  -> STILL exit 0 (no false alarm),
+#   * workflow tar.gz name separator changed     -> red, names workflow(tar.gz),
+#   * install.sh BIN renamed                     -> red, names binary-name,
+#   * upload-assets download `pattern:` changed  -> red, names artifact-plumbing,
+#   * install.ps1 asset field order swapped      -> red, names install.ps1,
+#   * install.ps1 loses ARM64 detection          -> red, names the uncovered target,
+#   * SHA256SUMS dropped from release `files:`   -> red, names release-files,
+#   * an unparsable workflow                     -> red (fails CLOSED, never passes).
+#
+# Usage: scripts/tests/asset-name-drift.test.sh
+
+set -euo pipefail
+
+HARNESS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$HARNESS_DIR/../.." && pwd -P)"
+GATE="$REPO_ROOT/scripts/check-asset-names.sh"
+
+WORKFLOW_REL=".github/workflows/release-please.yml"
+SH_REL="scripts/install.sh"
+PS_REL="scripts/install.ps1"
+
+for f in "$GATE" "$REPO_ROOT/$WORKFLOW_REL" "$REPO_ROOT/$SH_REL" "$REPO_ROOT/$PS_REL"; do
+	[ -f "$f" ] || {
+		printf 'harness: required file not found: %s\n' "$f" >&2
+		exit 2
+	}
+done
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+note() { printf '  %s\n' "$1"; }
+ok() {
+	printf 'PASS: %s\n' "$1"
+	PASS=$((PASS + 1))
+}
+bad() {
+	printf 'FAIL: %s\n' "$1" >&2
+	FAIL=$((FAIL + 1))
+}
+
+# make_fixture NAME -> echoes a fresh fixture root holding verbatim copies.
+make_fixture() {
+	local name="$1"
+	local root="$WORK/$name"
+	mkdir -p "$root/.github/workflows" "$root/scripts"
+	cp "$REPO_ROOT/$WORKFLOW_REL" "$root/$WORKFLOW_REL"
+	cp "$REPO_ROOT/$SH_REL" "$root/$SH_REL"
+	cp "$REPO_ROOT/$PS_REL" "$root/$PS_REL"
+	printf '%s' "$root"
+}
+
+RC=0
+OUT=""
+ERR=""
+run_gate() {
+	local name="$1" root="$2"
+	OUT="$WORK/$name.out"
+	ERR="$WORK/$name.err"
+	set +e
+	bash "$GATE" "$root" > "$OUT" 2> "$ERR"
+	RC=$?
+	set -e
+}
+
+assert_rc() {
+	local name="$1" want="$2"
+	if [ "$RC" != "$want" ]; then
+		bad "$name: expected exit $want, got $RC"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+assert_rc_nonzero() {
+	local name="$1"
+	if [ "$RC" -eq 0 ]; then
+		bad "$name: expected a NONZERO exit, got 0"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		return 1
+	fi
+}
+assert_stdout() {
+	local name="$1" re="$2"
+	if ! grep -Eq "$re" "$OUT"; then
+		bad "$name: expected /$re/ on stdout"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		return 1
+	fi
+}
+assert_stderr() {
+	local name="$1" re="$2"
+	if ! grep -Eq -- "$re" "$ERR"; then
+		bad "$name: expected diagnostic /$re/ on stderr"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+assert_not_stderr() {
+	local name="$1" re="$2"
+	if grep -Eq -- "$re" "$ERR"; then
+		bad "$name: did NOT expect /$re/ on stderr (over-broad diagnosis)"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+
+# Replace the FIRST literal occurrence of OLD with NEW in FILE; fail loudly when
+# OLD is absent, so a refactor that moves the anchor cannot silently neuter a
+# mutant into a no-op.
+mutate() {
+	local file="$1" old="$2" new="$3"
+	CG_MUT_FILE="$file" CG_MUT_OLD="$old" CG_MUT_NEW="$new" python3 - <<'PY'
+import os
+import sys
+
+path = os.environ["CG_MUT_FILE"]
+old = os.environ["CG_MUT_OLD"]
+new = os.environ["CG_MUT_NEW"]
+with open(path, "r", encoding="utf-8") as fh:
+    text = fh.read()
+if old not in text:
+    print("harness: mutation anchor not found in %s: %r" % (path, old), file=sys.stderr)
+    sys.exit(2)
+with open(path, "w", encoding="utf-8") as fh:
+    fh.write(text.replace(old, new, 1))
+PY
+}
+
+printf '=== asset-name drift-gate fixture harness ===\n'
+
+# --- Scenario A — pristine copies of the real files: green. ----------------
+A="$(make_fixture A_pristine)"
+a_ok=1
+run_gate "A_pristine" "$A"
+assert_rc "A_pristine" 0 || a_ok=0
+assert_stdout "A_pristine" 'check-asset-names: OK' || a_ok=0
+assert_stdout "A_pristine" 'matrix targets     : 6' || a_ok=0
+for t in x86_64-unknown-linux-musl aarch64-unknown-linux-musl x86_64-apple-darwin \
+	aarch64-apple-darwin x86_64-pc-windows-msvc aarch64-pc-windows-msvc; do
+	assert_stdout "A_pristine" "$t" || a_ok=0
+done
+[ "$a_ok" -eq 1 ] && ok "A_pristine (exit=0, all six matrix targets owned by an installer)"
+
+# --- Scenario B — the real repository root: green. -------------------------
+b_ok=1
+run_gate "B_repository" "$REPO_ROOT"
+assert_rc "B_repository" 0 || b_ok=0
+assert_stdout "B_repository" 'check-asset-names: OK' || b_ok=0
+[ "$b_ok" -eq 1 ] && ok "B_repository (exit=0, the shipped tree agrees three ways)"
+
+# --- Scenario C — cosmetic churn must NOT trip the gate. -------------------
+C="$(make_fixture C_cosmetic)"
+mutate "$C/$WORKFLOW_REL" '          path: dist/*' \
+	'          # cosmetic: requoted + commented, same value
+          path: "dist/*"'
+mutate "$C/$WORKFLOW_REL" '          pattern: dist-*' '          pattern: "dist-*"'
+c_ok=1
+run_gate "C_cosmetic" "$C"
+assert_rc "C_cosmetic" 0 || c_ok=0
+assert_stdout "C_cosmetic" 'check-asset-names: OK' || c_ok=0
+[ "$c_ok" -eq 1 ] && ok "C_cosmetic (exit=0, comments/quoting are not drift)"
+
+# --- Scenario D — MUTANT: workflow tar.gz separator drifts. ----------------
+D="$(make_fixture D_workflow_tar_name)"
+mutate "$D/$WORKFLOW_REL" 'tar -czf "dist/${BINARY_NAME}-${{' 'tar -czf "dist/${BINARY_NAME}_${{'
+d_ok=1
+run_gate "D_workflow_tar_name" "$D"
+assert_rc_nonzero "D_workflow_tar_name" || d_ok=0
+assert_stderr "D_workflow_tar_name" 'MISMATCH \[workflow\(tar\.gz\)\]' || d_ok=0
+assert_stderr "D_workflow_tar_name" '<bin>_<version>-<target>\.<ext>' || d_ok=0
+assert_not_stderr "D_workflow_tar_name" 'MISMATCH \[install\.(sh|ps1)\]' || d_ok=0
+[ "$d_ok" -eq 1 ] && ok "D_workflow_tar_name (exit=$RC, blames workflow(tar.gz) only)"
+
+# --- Scenario E — MUTANT: install.sh binary name drifts. ------------------
+E="$(make_fixture E_install_sh_bin)"
+mutate "$E/$SH_REL" 'BIN="codegraph"' 'BIN="codegraf"'
+e_ok=1
+run_gate "E_install_sh_bin" "$E"
+assert_rc_nonzero "E_install_sh_bin" || e_ok=0
+assert_stderr "E_install_sh_bin" 'MISMATCH \[binary-name\]' || e_ok=0
+assert_stderr "E_install_sh_bin" "install\\.sh BIN='codegraf'" || e_ok=0
+assert_not_stderr "E_install_sh_bin" 'MISMATCH \[artifact-plumbing\]' || e_ok=0
+[ "$e_ok" -eq 1 ] && ok "E_install_sh_bin (exit=$RC, blames binary-name and prints both values)"
+
+# --- Scenario F — MUTANT: upload-assets download pattern drifts. -----------
+F="$(make_fixture F_download_pattern)"
+mutate "$F/$WORKFLOW_REL" 'pattern: dist-*' 'pattern: bins-*'
+f_ok=1
+run_gate "F_download_pattern" "$F"
+assert_rc_nonzero "F_download_pattern" || f_ok=0
+assert_stderr "F_download_pattern" 'MISMATCH \[artifact-plumbing\]' || f_ok=0
+assert_stderr "F_download_pattern" "name 'dist-x86_64-unknown-linux-musl' does not match upload-assets pattern 'bins-\*'" || f_ok=0
+assert_not_stderr "F_download_pattern" 'MISMATCH \[binary-name\]' || f_ok=0
+[ "$f_ok" -eq 1 ] && ok "F_download_pattern (exit=$RC, blames artifact-plumbing with both strings)"
+
+# --- Scenario G — MUTANT: install.ps1 asset field order swapped. -----------
+G="$(make_fixture G_ps1_field_order)"
+mutate "$G/$PS_REL" '$asset = "$Bin-$version-$target.$ext"' '$asset = "$Bin-$target-$version.$ext"'
+g_ok=1
+run_gate "G_ps1_field_order" "$G"
+assert_rc_nonzero "G_ps1_field_order" || g_ok=0
+assert_stderr "G_ps1_field_order" 'MISMATCH \[install\.ps1\]' || g_ok=0
+assert_stderr "G_ps1_field_order" '<bin>-<target>-<version>\.<ext>' || g_ok=0
+assert_not_stderr "G_ps1_field_order" 'MISMATCH \[workflow' || g_ok=0
+[ "$g_ok" -eq 1 ] && ok "G_ps1_field_order (exit=$RC, blames install.ps1 only)"
+
+# --- Scenario H — MUTANT: install.ps1 loses ARM64 detection. ---------------
+H="$(make_fixture H_ps1_drops_arm64)"
+mutate "$H/$PS_REL" "    '^(ARM64|aarch64)\$'    { \$archPart = 'aarch64' }
+" ""
+h_ok=1
+run_gate "H_ps1_drops_arm64" "$H"
+assert_rc_nonzero "H_ps1_drops_arm64" || h_ok=0
+assert_stderr "H_ps1_drops_arm64" 'MISMATCH \[target-coverage\]' || h_ok=0
+assert_stderr "H_ps1_drops_arm64" "matrix target 'aarch64-pc-windows-msvc' cannot be produced" || h_ok=0
+[ "$h_ok" -eq 1 ] && ok "H_ps1_drops_arm64 (exit=$RC, names the orphaned matrix target)"
+
+# --- Scenario I — MUTANT: SHA256SUMS dropped from the release files. -------
+I="$(make_fixture I_sums_unpublished)"
+mutate "$I/$WORKFLOW_REL" '            dist/SHA256SUMS
+' ""
+i_ok=1
+run_gate "I_sums_unpublished" "$I"
+assert_rc_nonzero "I_sums_unpublished" || i_ok=0
+assert_stderr "I_sums_unpublished" 'MISMATCH \[release-files\]' || i_ok=0
+assert_stderr "I_sums_unpublished" "installers fetch 'SHA256SUMS' but no release" || i_ok=0
+[ "$i_ok" -eq 1 ] && ok "I_sums_unpublished (exit=$RC, an unpublished sums file is drift too)"
+
+# --- Scenario J — an unparsable workflow must FAIL CLOSED. -----------------
+J="$(make_fixture J_unparsable)"
+mutate "$J/$WORKFLOW_REL" '      - name: Package (unix tar.gz)' '      - name: Package (unix TARBALL)'
+mutate "$J/$WORKFLOW_REL" 'tar -czf "dist/${BINARY_NAME}' 'bsdtar --create --gzip --file "dist/${BINARY_NAME}'
+j_ok=1
+run_gate "J_unparsable" "$J"
+assert_rc_nonzero "J_unparsable" || j_ok=0
+assert_stderr "J_unparsable" 'check-asset-names: ERROR' || j_ok=0
+[ "$j_ok" -eq 1 ] && ok "J_unparsable (exit=$RC, an unreadable contract is a failure, not a pass)"
+
+printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

From f80ee4f91e4d4d1a2921a28532728bfac9517081 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 21:12:58 +0800
Subject: [PATCH 60/91] docs(godot): record the gdext rejection and engine-free
 alternatives

---
 README.md                    |   3 +
 docs/godot-gdext-decision.md | 147 +++++++++++++++++++++++++++++++++++
 docs/godot.md                |   3 +
 3 files changed, 153 insertions(+)
 create mode 100644 docs/godot-gdext-decision.md

diff --git a/README.md b/README.md
index 1bb9b14..edf9205 100644
--- a/README.md
+++ b/README.md
@@ -476,6 +476,9 @@ Full list with extensions and per-language notes: [`docs/languages.md`](docs/lan
 - [`docs/godot.md`](docs/godot.md) — Godot static analysis: what CodeGraph
   extracts from `.tscn`/`.tres`/`project.godot`/`.gd`, the static-vs-runtime
   boundary, and honesty signals for dynamic reachability.
+- [`docs/godot-gdext-decision.md`](docs/godot-gdext-decision.md) — why `gdext`
+  (godot-rust GDExtension bindings) is rejected for Godot analysis, and the
+  engine-free alternatives.
 - [`docs/grammar-manifest.md`](docs/grammar-manifest.md) /
   [`docs/embedded-extraction.md`](docs/embedded-extraction.md) — language support
   and extraction tiers (engineering ABI detail).
diff --git a/docs/godot-gdext-decision.md b/docs/godot-gdext-decision.md
new file mode 100644
index 0000000..7c4dc5f
--- /dev/null
+++ b/docs/godot-gdext-decision.md
@@ -0,0 +1,147 @@
+# Decision: gdext is not used for Godot analysis
+
+## The question
+
+A user asked whether CodeGraph could or should use
+[`gdext`](https://github.com/godot-rust/gdext) — the godot-rust GDExtension
+bindings — to improve Godot/GDScript analysis.
+
+## Verdict
+
+**Rejected, and unnecessary.** `gdext` is a binding for Rust code running inside
+a live Godot engine, so adopting it would add an engine dependency to a
+standalone binary and make output depend on the engine version, while solving
+none of the gaps recorded in [`docs/godot.md`](godot.md#limitations) — those are
+either genuinely runtime-only or solvable with better static parsing.
+
+## What gdext actually is
+
+`gdext` compiles Rust into a GDExtension shared library that Godot loads at
+startup. Its type surface (`Node`, `Callable`, `NodePath`, …) is generated from
+`extension_api.json`, which ships with a specific Godot build, and those types
+are only meaningful once the engine has initialized. It is not a GDScript
+parser, not a `.tscn`/`.tres` reader, and offers no offline API for inspecting
+project files. Anything CodeGraph wanted from it would require launching Godot.
+
+## Why it disqualifies itself
+
+**1. It requires the engine; CodeGraph deliberately does not.**
+`docs/godot.md` opens by stating that CodeGraph parses Godot project files
+"— no engine required, no compilation, no runtime". Releases are standalone
+binaries, and README.md notes that "Linux builds are statically linked (musl) —
+no glibc or SQLite system dependency". Users indexing a Godot repo on CI, on a
+server, or on a machine without the editor installed are a supported case.
+`gdext` would make Godot analysis conditional on having a matching Godot binary
+and its `extension_api.json` present at build time.
+
+**2. It breaks byte-stable determinism.**
+`AGENTS.md` lists as a hard invariant: "**Golden `.schema` byte-stability** —
+verified by `crates/codegraph-bench/tests/equivalence.rs` against the fixed
+golden artifacts under `reference/golden/`", with `reference/golden/godot/`
+guarding the autoload-call edges, signal-handler edges, and UID-form autoloads
+"byte-for-byte". `AGENTS.md` also requires "**Deterministic** extraction +
+resolution". Bindings generated from a specific engine version make output a
+function of that version, so the same corpus could produce different goldens on
+different release runners. That is not reconcilable with a fixed golden checked
+into the repository.
+
+**3. It solves none of the recorded gaps.**
+The limitations in [`docs/godot.md`](godot.md#limitations) split cleanly, and
+neither half needs an engine binding:
+
+- Runtime-only by nature — `get_node(var)` / `call(method_var)` computed
+  targets, `NodePath`s built by string concatenation, and "No runtime
+  verification". An in-engine binding does not make a static analyser able to
+  know a value that only exists while the game runs; it would only let CodeGraph
+  _run_ the project, which is a different tool (`docs/godot.md` already assigns
+  runtime load-verification to Godot MCP Pro).
+- Statically solvable — scene-backed autoloads not binding the attached script's
+  methods, `.tscn` `[connection]` handlers matched by name only, binary `.res`
+  files unparsed. Each is a parsing/resolution improvement in existing crates.
+
+## Alternatives worth pursuing instead
+
+Ranked by value against risk. None adds a dependency on the engine.
+
+**1. Bind scene-backed autoload methods (highest value, lowest risk).**
+`docs/godot.md` records: "**Scene-backed autoloads are registration-only.** A
+`uid://…` autoload that resolves to a `.tscn` (scene autoload) emits the
+`project.godot → .tscn` registration reference but no F1 `Autoload.method()`
+binding to the scene's attached script." The missing hop is one the resolver
+already knows how to make: the `.tscn` extraction already emits `script =
+ExtResource(…)` scene-node → `.gd` references, and F1 already binds
+`Autoload.method()` to a uniquely-named `func` in a bound script. Following the
+scene's root-node script and reusing F1's existing determinism rule (edge only
+when exactly one matching `func` exists) closes a concrete, user-visible gap
+inside one resolver, with a new golden fixture to pin it. Purely additive.
+
+**2. Move the `.gd` dynamic scanner onto tree-sitter queries (high value,
+moderate risk).** `crates/codegraph-resolve/src/frameworks/godot_script.rs` is
+today a defensive line/string/paren scanner — `scan_line`, `scan_connect`,
+`scan_dollar_node`, `first_arg`, `top_level_comma`, `ident_before` and friends
+walk raw bytes per line. It is deliberately tolerant (malformed input is
+skipped, never panics), but hand-rolled text windows are exactly the bug class
+commit `b7ff1f8b3a0ee5f99912e8a426d6af810eec3b9c` ("fix(resolve): bound the
+React Route opening-tag scan to the tag itself") fixed on this branch: a fixed
+byte window that never cut at the element's own `>` let a parent route borrow a
+sibling's `path`/`element`, producing 2 wrong edges out of 3. The Godot scanner
+carries the same shape of risk — multi-line call arguments, comments and strings
+containing `connect(`, and nested parens are all handled by ad-hoc byte logic.
+Running tree-sitter queries over the parse tree the GDScript grammar already
+produces removes that class of error at the root. Moderate risk because the
+resolver's output is golden-protected via `reference/golden/godot/`, so the port
+must be output-preserving: every existing sentinel and edge has to come out
+byte-identical, and the change is only worth making with the current unit tests
+plus the golden fixture as the gate.
+
+**3. Upgrade the GDScript grammar (conditional value, low risk).**
+The pinned version is `tree-sitter-gdscript = "6.1.0"`
+(`crates/codegraph-extract/Cargo.toml`, checksum
+`b7a37fe8c0a10c0c39ecd5b2f7db53933f691488f5572409a4d3c0dfeb3f6108` in
+`Cargo.lock`, also recorded in [`docs/grammar-manifest.md`](grammar-manifest.md)).
+Whether a newer release exists is **unverified** — nothing in this repository
+records the upstream crate's latest version, and no network lookup was performed
+for this decision. What would settle it: `cargo search tree-sitter-gdscript` or
+the crate's registry page, plus the grammar's changelog. Ranked below (2) because
+its value is unknown until that check happens: a grammar bump only helps if it
+fixes parse gaps CodeGraph actually hits, and any bump is a golden-affecting
+change that must be re-verified against `reference/golden/godot/`.
+
+**4. Parse binary `.res` (lowest value).** Recorded as a limitation, but it
+means implementing Godot's binary resource format against no specification in
+this repository, for files that are usually a compiled form of a `.tres` the
+project also has in text form. Not worth the surface area.
+
+Not worth pursuing at all: computed `get_node`/`call` targets and
+runtime-constructed `NodePath`s. `docs/godot.md` states the position —
+"**Computed targets are unresolved, not fabricated.** … They appear as
+`godot:dynamic:<kind>` sentinels, never as concrete edges." The sentinel _is_
+the correct answer; replacing it with a guess would be a regression in honesty.
+
+## What remains uncertain
+
+- Whether a newer `tree-sitter-gdscript` release exists, and whether it fixes
+  anything CodeGraph hits. Unverified, as above.
+- Whether the tree-sitter-query port of `godot_script.rs` can be made exactly
+  output-preserving. Unknown until attempted; the golden fixture decides it, and
+  a diff there is a stop signal, not something to regenerate around.
+- No throughput, latency, or memory benchmark exists for the GDScript path, so
+  no performance claim is made here in either direction. If a future argument
+  for a different parsing strategy rests on speed, it needs a measurement first.
+
+Evidence that would reopen the gdext question: an offline, engine-free,
+version-stable API for reading Godot project files. `gdext` is not that, and is
+not trying to be.
+
+`scripts/guardrail.sh` is **not** extended to ban Godot-engine crates as part of
+this decision — its forbidden list targets AI/vector/LLM crates, and widening a
+CI gate is a separate call. If a hard block is wanted, adding `gdext`/`godot` to
+that list is the mechanism; it is recommended here, not done here.
+
+## See also
+
+- [`docs/godot.md`](godot.md) — what CodeGraph extracts from Godot projects, the
+  static-vs-runtime boundary, and the limitations argued against above.
+- [`AGENTS.md`](../AGENTS.md) — the hard invariants quoted here.
+- [`docs/grammar-manifest.md`](grammar-manifest.md) — the pinned GDScript
+  grammar and its ABI status.
diff --git a/docs/godot.md b/docs/godot.md
index 8a74d36..70b6ba3 100644
--- a/docs/godot.md
+++ b/docs/godot.md
@@ -392,6 +392,9 @@ sync` that touches only a `.gd.uid`, a `.tscn` uid header, or a file rename does
 
 ## See also
 
+- [`docs/godot-gdext-decision.md`](godot-gdext-decision.md) — why CodeGraph does
+  NOT use `gdext` (the godot-rust GDExtension bindings), and the engine-free
+  alternatives for the limitations above.
 - [`docs/languages.md`](languages.md) — GDScript (Tier 1), GodotScene,
   GodotResource, GodotProject file types.
 - [`docs/mcp.md`](mcp.md) — `codegraph_callers` and `codegraph_impact` tools

From d897fdc05088bac338584566faaac07a32798252 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 22:45:45 +0800
Subject: [PATCH 61/91] fix(ci): require every gated job to conclude success
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`CI Success` rejected only a `failure` result, so a required job that was
`cancelled` or `skipped` still passed the gate. With `cancel-in-progress: true`
a run cancelled by a newer push therefore concluded `CI Success` successfully,
and release-please.yml's `verify-ci` gates the release on exactly that job — so
a release could be cut on a run whose tests never finished.

Read every result from `toJSON(needs)` and accept only `success`; `cancelled`,
`skipped`, and any undocumented future value now fail, and a degenerate needs
context fails closed. The failure output names each job and its actual result.

GitHub Actions cannot express "require every job" — the needs context holds only
what `needs:` lists — so scripts/check-ci-gate.sh asserts from outside the
workflow that the gated set is every job minus an explicitly justified
informational allow-list, and that `coverage` may stay excluded only while
codecov.yml keeps it informational. It also executes the shipped gate body over
a synthetic needs context and pins verify-ci's strict conclusion check, wired
through scripts/guardrail.sh so it runs in make ci, pre-push, and CI.
scripts/tests/ci-gate.test.sh adds a 12-scenario mutation harness including a
negative control showing the old expression admits cancelled/skipped.
---
 .github/workflows/ci.yml                  |  86 ++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 355 +++++++++++++++++-
 scripts/check-ci-gate.sh                  | 428 ++++++++++++++++++++++
 scripts/guardrail.sh                      |  12 +
 scripts/tests/ci-gate.test.sh             | 349 ++++++++++++++++++
 5 files changed, 1224 insertions(+), 6 deletions(-)
 create mode 100755 scripts/check-ci-gate.sh
 create mode 100755 scripts/tests/ci-gate.test.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 04e2c5b..a33ee88 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -65,7 +65,14 @@ jobs:
             || python3 -m pip install --break-system-packages PyYAML \
             || python3 -m pip install PyYAML
 
-      - name: Scope guardrail (no AI/vector/LLM crates + release asset-name drift)
+      # The CI-gate integrity block of the guardrail runs the shipped `ci-success`
+      # step body over a synthetic needs context, which needs jq. Present on
+      # ubuntu-latest; asserted here so a missing jq fails loudly rather than
+      # letting the gate degrade.
+      - name: Ensure jq (CI gate-integrity check)
+        run: jq --version
+
+      - name: Scope guardrail (no AI/vector/LLM crates + release asset-name drift + CI gate integrity)
         run: bash scripts/guardrail.sh
 
   windows:
@@ -170,18 +177,87 @@ jobs:
           # to repo Secrets to use it; harmless/ignored if unset on a public repo.
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  # ci-success is the SINGLE required status check for branch protection AND the
+  # job the release workflow's `verify-ci` waits on before a release may leave
+  # draft. It must therefore be a STRICT gate: it passes only when every required
+  # job's result is exactly `success`.
+  #
+  # WHY strict (the bug this shape fixes): `needs.<job>.result` can be `success`,
+  # `failure`, `cancelled`, or `skipped`. The previous check rejected only
+  # `failure`, so `cancelled` and `skipped` both PASSED. Combined with
+  # `cancel-in-progress: true` above, a run cancelled by a newer push could still
+  # conclude `CI Success` — and release-please.yml's `verify-ci` gates the release
+  # on exactly that job. A release could then be cut on a run whose tests never
+  # finished. Anything other than `success` now fails, including any result value
+  # GitHub may add in the future (unknown values are not silently tolerated).
+  #
+  # WHY the results are read from `toJSON(needs)` rather than named one by one:
+  # the step body hardcodes no job name, so adding a job to `needs:` below
+  # automatically makes it required with no change to the script. GitHub Actions
+  # cannot make this fully automatic — the `needs` context contains ONLY the jobs
+  # listed in `needs:`, so a new job that is never added there is invisible to
+  # this gate no matter how the expression is written. That gap is closed OUTSIDE
+  # the workflow, loudly: `scripts/check-ci-gate.sh` (run by scripts/guardrail.sh
+  # in `make ci`, the pre-push hook, and the CI `test` job) asserts that
+  # `ci-success.needs` equals every job in this file minus an explicit
+  # informational allow-list, so forgetting to list a new job turns CI red
+  # instead of silently narrowing the gate.
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
     if: always()
     # NOTE: `coverage` is intentionally NOT listed here — coverage is
-    # informational and must never gate a merge.
+    # informational (codecov.yml sets `informational: true`, baseline ~72% vs an
+    # aspirational 95% target) and must never gate a merge or a release. It is
+    # the ONLY allowed exclusion; scripts/check-ci-gate.sh enforces that, and
+    # also enforces that codecov.yml still marks coverage informational, so the
+    # exclusion can never outlive its justification.
     needs: [test, audit, windows]
     steps:
       - name: Check job status
+        env:
+          # The whole needs context as JSON: {"test":{"result":"success",...},...}
+          NEEDS_JSON: ${{ toJSON(needs) }}
         run: |
-          if [[ "${{ needs.test.result }}" == "failure" || "${{ needs.audit.result }}" == "failure" || "${{ needs.windows.result }}" == "failure" ]]; then
-            echo "❌ CI failed"
+          set -euo pipefail
+
+          if [ -z "${NEEDS_JSON:-}" ]; then
+            echo "::error title=CI gate::the needs context was empty; cannot prove any required job succeeded — failing closed."
+            exit 1
+          fi
+          if ! printf '%s' "$NEEDS_JSON" | jq -e 'type == "object" and length > 0' > /dev/null 2>&1; then
+            echo "::error title=CI gate::the needs context did not parse as a non-empty JSON object — failing closed."
+            printf 'needs context was: %s\n' "$NEEDS_JSON"
+            exit 1
+          fi
+
+          # One row per required job: "<job>\t<result>". A job whose `result` key
+          # is absent renders as <missing> and fails, never passes.
+          mapfile -t rows < <(
+            printf '%s' "$NEEDS_JSON" \
+              | jq -r 'to_entries | sort_by(.key)[] | "\(.key)\t\(.value.result // "<missing>")"'
+          )
+          if [ "${#rows[@]}" -eq 0 ]; then
+            echo "::error title=CI gate::no required jobs were found in the needs context — failing closed."
+            exit 1
+          fi
+
+          echo "Required job results (only 'success' passes):"
+          offenders=0
+          for row in "${rows[@]}"; do
+            job="${row%%$'\t'*}"
+            result="${row#*$'\t'}"
+            if [ "$result" = "success" ]; then
+              printf '  ✅ %-12s %s\n' "$job" "$result"
+            else
+              printf '  ❌ %-12s %s\n' "$job" "$result"
+              echo "::error title=CI gate::required job '${job}' concluded '${result}', not 'success'."
+              offenders=$((offenders + 1))
+            fi
+          done
+
+          if [ "$offenders" -ne 0 ]; then
+            echo "❌ CI failed: ${offenders} of ${#rows[@]} required job(s) did not conclude 'success' (see the ❌ rows above)."
             exit 1
           fi
-          echo "✅ CI passed"
+          echo "✅ CI passed: all ${#rows[@]} required job(s) concluded 'success'."
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 794a55b..81ecbe4 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -5246,7 +5246,13 @@ Same project re-indexed with the rebuilt binary:
     route|settings|11
     settings|Settings|11
 
-Exactly the single correct edge the issue asks for.
+Exactly the single correct edge the issue asks for **for the `<Route>` JSX form**.
+
+> **Scope correction (added by Batch F3).** As committed, this batch fixed only the
+> `<Route>` JSX form. The data-router (`createBrowserRouter([…])`) form kept the same
+> borrowing defect behind a fixed 300-byte window, so #1348 was NOT fully ported by
+> Batch D1 alone. Batch F3 below closes that half; #1348 is complete only with both
+> batches. The sentence above is scoped accordingly.
 
 ### The bound and why that number
 
@@ -6659,3 +6665,350 @@ must be inside request cwd`); no LSP-clean result is claimed. The changed files
 shell, YAML and Markdown, which the Rust toolchain does not lint — the honest
 checks for them are the executable harness, the four mutants, the YAML parse, and
 `make ci`.
+
+## Batch F4 — `CI Success` becomes a strict gate: only `success` passes (2026-07-28)
+
+### The defect (found by the F1–F4 review wave, confirmed by reading the file)
+
+`.github/workflows/ci.yml`, job `ci-success` (pre-fix lines **173–187**; the
+`run:` body at **182–187** and the offending condition on **line 183**) rejected
+exactly ONE result value:
+
+```yaml
+- name: Check job status
+  run: |
+    if [[ "${{ needs.test.result }}" == "failure" || "${{ needs.audit.result }}" == "failure" || "${{ needs.windows.result }}" == "failure" ]]; then
+      echo "❌ CI failed"
+      exit 1
+    fi
+    echo "✅ CI passed"
+```
+
+`needs.<job>.result` is not boolean. GitHub Actions sets it to `success`,
+`failure`, `cancelled`, or `skipped`. The expression above tests only for
+`failure`, so **`cancelled` and `skipped` both fell through to
+`echo "✅ CI passed"` and exit 0.**
+
+Three facts turn that from a latent typo into a release blocker:
+
+1. `ci.yml` line **13** sets `cancel-in-progress: true`. A second push to the
+   same ref cancels the in-flight run — the cancelled state is not exotic, it is
+   the routine outcome of pushing twice.
+2. `ci-success` runs `if: always()`, so it executes even when its needed jobs are
+   cancelled. It then printed `✅ CI passed`.
+3. `release-please.yml` line **124** (`Wait for CI Success on the tag commit`,
+   job `verify-ci`, lines **100–175**) gates the release on **that job's**
+   conclusion, and `upload-assets` (line **287**) lists `verify-ci` in `needs`.
+
+So the reachable path was: push, push again → CI run 1 cancelled → run 1's
+`CI Success` concludes **success** → a release cut against run 1's commit finds a
+green `CI Success` → `verify-ci` passes → assets upload → `publish-release`
+publishes. A release on a run whose tests never finished. That is precisely the
+half of the project's contract ("a release only fires on green CI") that this
+commit restores.
+
+### Old vs new expression, side by side
+
+**OLD** (the whole gate, one line):
+
+```bash
+if [[ "${{ needs.test.result }}" == "failure" || "${{ needs.audit.result }}" == "failure" || "${{ needs.windows.result }}" == "failure" ]]; then
+```
+
+**NEW** (the accept test, from the shipped body):
+
+```bash
+mapfile -t rows < <(
+  printf '%s' "$NEEDS_JSON" \
+    | jq -r 'to_entries | sort_by(.key)[] | "\(.key)\t\(.value.result // "<missing>")"'
+)
+...
+  if [ "$result" = "success" ]; then   # ← the ONLY accepting branch
+```
+
+Three changes of substance:
+
+- **Allow-list, not deny-list.** `= "success"` accepts one value; every other
+  value — `cancelled`, `skipped`, `neutral`, `timed_out`, an empty string, or any
+  value GitHub adds in the future — falls to the failing branch. Unknown is
+  treated as not-success, never tolerated.
+- **Results come from `${{ toJSON(needs) }}`** (env `NEEDS_JSON`), so the body
+  hardcodes no job name. Adding a job to `needs:` gates it with no script edit.
+  A `needs.<job>.result` interpolation reappearing in the body is now a guard
+  failure (scenario E below).
+- **Fails closed on a degenerate context.** An empty `NEEDS_JSON`, a non-object,
+  a `{}`, or a job whose `result` key is absent all exit 1 with an explicit
+  "failing closed" message, instead of iterating zero jobs and declaring success.
+
+### Actionable failure message (the point of the rewrite, not decoration)
+
+A maintainer reading a red `CI Success` now sees, per job, which one was not
+`success` and what it actually was — plus a GitHub `::error` annotation that
+surfaces in the run summary:
+
+```
+Required job results (only 'success' passes):
+  ✅ audit        success
+  ❌ test         cancelled
+  ✅ windows      success
+::error title=CI gate::required job 'test' concluded 'cancelled', not 'success'.
+❌ CI failed: 1 of 3 required job(s) did not conclude 'success' (see the ❌ rows above).
+```
+
+### The required set: `test`, `audit`, `windows` — verified against the file
+
+Enumerated from the real `ci.yml`, not from the audit note. `jobs` contains
+exactly five keys: `test` (line 20), `windows` (71), `audit` (112), `coverage`
+(145 pre-fix 138), `ci-success` (205 pre-fix 173). The gate requires
+`test, audit, windows`; the required set is **unchanged by this commit** — it was
+not widened or narrowed, only made strict.
+
+`coverage` remains deliberately EXCLUDED. `codecov.yml` marks both statuses
+`informational: true` (baseline ~72% line coverage against an aspirational 95%
+target), so coverage is report-only by design and must never redden a merge or
+block a release. That reasoning is now written where the exclusion lives
+(`ci.yml` `needs:` comment) **and mechanically tied to its premise**:
+`scripts/check-ci-gate.sh` fails if `codecov.yml` ever stops marking coverage
+informational while it is still excluded, so the exclusion cannot outlive its
+justification (harness scenario I).
+
+### "Robust to a job added later" — GitHub Actions cannot express it; the gap is made loud
+
+Stated plainly: **there is no in-workflow way to require every job.** The `needs`
+context contains ONLY the jobs listed in `needs:`. `toJSON(needs)` iterates
+whatever is there, so a job added to `ci.yml` and never added to
+`ci-success`'s `needs:` is invisible to the gate no matter how the expression is
+written. There is no `needs: [*]`, and `jobs.<id>.needs` accepts no wildcard.
+
+So the invariant is asserted from OUTSIDE the workflow, and made loud rather than
+silent: new script `scripts/check-ci-gate.sh` parses `ci.yml` and fails when
+`ci-success.needs` is not exactly `set(jobs) - {ci-success} - INFORMATIONAL`. Add
+a job without gating it and the guardrail turns red locally, at pre-push, and in
+CI, naming the ungated job (harness scenario H adds a `fuzz` job and gets
+`job(s) ['fuzz'] exist in ci.yml but are NOT in ci-success's needs:`). The
+allow-list is a single explicit set in that script with a per-entry
+justification function — widening it is a visible, reviewable edit, not an
+omission.
+
+The guard also asserts the gate's other structural preconditions: the job exists
+and is still named `CI Success` (the string branch protection and `verify-ci`
+both look for), it still runs `if: always()` (without it the gate is skipped when
+a needed job fails, so it never turns red), and it has exactly one `run:` step
+reading `${{ toJSON(needs) }}`.
+
+### `verify-ci` — audited, already strict, NOT changed
+
+Checked as required. `release-please.yml` lines **152–175** poll the `CI Success`
+job and accept exactly one conclusion:
+
+```bash
+if [ "$conclusion" = "success" ]; then
+  echo "✅ CI Success passed for ${HEAD_SHA}."
+  exit 0
+fi
+echo "❌ CI Success concluded '${conclusion}' for ${HEAD_SHA}; blocking release (draft preserved)."
+exit 1
+```
+
+That is already an allow-list: a `cancelled` conclusion on `CI Success` hits the
+`exit 1` and blocks the release. There is exactly one `exit 0` in the body and it
+is inside the `= "success"` branch. **No fix was needed and none was made** — the
+release-side gate was never the hole. The hole was upstream of it: `CI Success`
+itself reported `success` for a cancelled run, so `verify-ci` was correctly
+believing an incorrect input.
+
+`check-ci-gate.sh` now pins that shape too (single `exit 0`, inside the success
+branch, at least one `exit 1`, selects the `CI Success` job, and `upload-assets`
+still lists `verify-ci` in `needs` so the gate stays load-bearing) — harness
+scenarios J and K.
+
+### Negative control — old ADMITS `cancelled`/`skipped`, new REJECTS
+
+Both columns are produced by executing real bash locally: the OLD column runs the
+pre-fix body verbatim with `${{ needs.X.result }}` textually substituted the way
+the runner substitutes it; the NEW column extracts the shipped `run:` body
+straight out of `.github/workflows/ci.yml` with `yaml.safe_load` and runs it with
+a synthetic `NEEDS_JSON`. Actual output of
+`bash scripts/tests/ci-gate.test.sh`, scenario D:
+
+```
+  truth table — result | OLD exit | NEW exit | OLD verdict | NEW verdict
+    success    |    0     |    0     | ADMITS  | ADMITS
+    failure    |    1     |    1     | rejects | rejects
+    cancelled  |    0     |    1     | ADMITS  | rejects
+    skipped    |    0     |    1     | ADMITS  | rejects
+```
+
+Rows 3 and 4 ARE the defect and its fix. Rows 1 and 2 show the fix is not a
+behavior change for the cases that already worked.
+
+The wider table, run by the guard itself over the shipped body (actual output of
+`bash scripts/check-ci-gate.sh`):
+
+```
+check-ci-gate: truth table over the shipped gate body (3 required job(s))
+  all jobs success                               exit 0   OK
+  audit = failure                                exit 1   OK
+  audit = cancelled                              exit 1   OK
+  audit = skipped                                exit 1   OK
+  audit = neutral                                exit 1   OK
+  audit = timed_out                              exit 1   OK
+  audit = unknown_future_value                   exit 1   OK
+  audit = <empty-string>                         exit 1   OK
+  audit = cancelled (per-job coverage)           exit 1   OK
+  test = cancelled (per-job coverage)            exit 1   OK
+  windows = cancelled (per-job coverage)         exit 1   OK
+  all jobs cancelled                             exit 1   OK
+  empty needs context                            exit 1   OK
+  empty JSON object                              exit 1   OK
+  malformed JSON                                 exit 1   OK
+  result key missing                             exit 1   OK
+check-ci-gate: OK (16 truth-table cases; only all-success exits 0)
+```
+
+`unknown_future_value` is the forward-compatibility case: a value GitHub does not
+document today fails, because the gate allow-lists `success` rather than
+enumerating the failures.
+
+### Why a `scripts/tests/` harness — decided deliberately, added
+
+The precedent is exact. `scripts/check-asset-names.sh` (Batch E2) guards a
+CI/release contract that no Cargo test can express, ships a
+`scripts/tests/asset-name-drift.test.sh` mutation harness, and is wired into
+`scripts/guardrail.sh` so it runs in `make ci`, the pre-push hook, and CI. This
+defect is the same shape — a gate whose weakening leaves every test, lint, and
+build green — so it gets the same treatment rather than a new mechanism.
+
+The argument against (a workflow file is "just config", the fix is one
+expression) does not survive the evidence above: the previous one-expression gate
+looked correct to reviewers for the whole life of the file, and the mode of
+failure is silence. A guard that only asserted shape would also be weak, so the
+harness asserts BEHAVIOR: it extracts the shipped step body and executes it. If
+someone rewrites the gate in a different but equally strict way, the truth table
+still passes; if they rewrite it in a weaker way, it reddens.
+
+`scripts/tests/ci-gate.test.sh` — 12 scenarios, mutating ONE real file per
+scenario inside a throwaway fixture (the real tree is never touched):
+
+| scenario                 | mutation                                              | expect                                          |
+| ------------------------ | ----------------------------------------------------- | ----------------------------------------------- |
+| A `pristine`             | none (verbatim copies)                                | `0`, strict gate + truth table green            |
+| B `repository`           | none, run on the real repo root                       | `0`, `check-ci-gate: OK`                        |
+| C `cosmetic`             | reflow `needs:` inline list → block list, add comment | `0` — churn is not a gate change                |
+| D `negative_control`     | none; evaluates OLD and NEW bodies side by side       | old ADMITS `cancelled`/`skipped`, new rejects   |
+| E `legacy_expression`    | restore a `${{ needs.test.result }}` interpolation    | `1`, blames `gate-shape`, quotes the expression |
+| F `job_ungated`          | drop `windows` from `needs:`                          | `1`, names `['windows']`                        |
+| G `no_always`            | delete `if: always()`                                 | `1`, blames `gate-always`                       |
+| H `new_job_ungated`      | add a `fuzz` job, do not gate it                      | `1`, names `['fuzz']`                           |
+| I `coverage_blocking`    | `codecov.yml` → `informational: false`                | `1`, blames `gate-exclusion`                    |
+| J `release_gate_relaxed` | `verify-ci` → `[ "$conclusion" != "failure" ]`        | `1`, blames `release-gate`                      |
+| K `gate_not_wired`       | `upload-assets` drops `verify-ci` from `needs`        | `1`, blames `release-gate`                      |
+| L `unparsable`           | `jobs:` becomes a sequence                            | nonzero — fails CLOSED, never a silent pass     |
+
+### CI wiring — a third block of `scripts/guardrail.sh`
+
+Same home and same reasoning as Batch E2's asset-name gate: `guardrail` is the
+one step already invoked by `make ci`, `.githooks/pre-push`, and the CI `test`
+job, so a check placed there runs on every enforcement path without editing three
+more files. `ci.yml` gains one `jq --version` step before the guardrail so a
+missing `jq` (needed to evaluate the truth table) fails loudly instead of letting
+the gate degrade — the same fail-loud pattern as the existing PyYAML step.
+
+There is a deliberate ordering property worth naming: the guard runs inside the
+`test` job, which is itself one of the gated jobs. If someone weakens the gate,
+`test` goes red, so `ci-success` sees `test = failure` and — under the new strict
+logic — fails. The weakening cannot merge.
+
+### Scope
+
+Touched: `.github/workflows/ci.yml`, `scripts/guardrail.sh`, new
+`scripts/check-ci-gate.sh`, new `scripts/tests/ci-gate.test.sh`, and this ledger.
+Explicitly NOT touched: any file under `crates/`, the six-platform build matrix,
+the `Generate SHA256SUMS` step, the draft-until-all-green `publish-release`
+mechanism, `cancel-in-progress: true` (concurrency cancellation is intended —
+the bug was that a cancelled run reported success, not that cancellation
+happens), `verify-ci`'s already-strict polling logic, and every version /
+lockfile byte.
+
+### Honesty — what was and was NOT verified
+
+Validated by **local expression evaluation and YAML parsing only**:
+
+- the shipped `ci-success` step body was extracted from the real `ci.yml` with
+  `yaml.safe_load` and EXECUTED under `bash` against synthetic `needs` contexts;
+- the pre-fix body was executed the same way with the runner's textual
+  interpolation applied by hand;
+- both workflow files were parsed with `yaml.safe_load`.
+
+**No GitHub Actions run was triggered, cancelled, or observed.** No claim is made
+that a real cancelled run was pushed through this gate on GitHub's
+infrastructure. The `${{ toJSON(needs) }}` interpolation itself, and the exact
+set of values GitHub may place in `result`, are taken from GitHub's documented
+contract, not from an observed run — that is the one link in the chain this
+evidence cannot close locally, and it is the same link every workflow edit in
+this repository rests on.
+
+`lsp_diagnostics` is **not applicable**: the changed files are YAML, POSIX shell,
+Bash, and Markdown. No Rust source was touched, so there is no LSP result to
+report — clean or otherwise, and none is claimed.
+
+### Golden delta
+
+`GIT_MASTER=1 git diff --stat 956cf32..HEAD -- reference/golden/` → **EMPTY**.
+This commit adds two shell scripts and edits `ci.yml`, `guardrail.sh`, and this
+ledger. No extraction, resolution, or canonicalization code exists in the diff,
+so no golden could change and none was regenerated.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-ci-gate.sh` → exit **0** (structure OK; 16 truth-table
+  cases, only all-success exits 0).
+- `bash scripts/tests/ci-gate.test.sh` → exit **0**, **12 passed, 0 failed**
+  (scenario L exits 2 — the fail-closed `die()` path — which the harness accepts
+  as nonzero).
+- `bash scripts/guardrail.sh` → exit **0** (all three blocks: forbidden crates,
+  asset-name contract, CI gate integrity).
+- `python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))"`
+  → exit **0**.
+- `python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/release-please.yml'))"`
+  → exit **0**.
+- `bash scripts/check-workspace-versions.sh` → exit **0** (workspace 0.40.4 ==
+  `version.txt` == release manifest `.`; 10 source-less packages all at 0.40.4).
+- `make ci CARGO='cargo --locked'` → **exit 0** (`✅ All CI checks passed!`), with
+  the full chain green: `fmt-check` (rustfmt + oxfmt, "All matched files use the
+  correct format"), clippy `-D warnings`, `cargo test --workspace`, and all three
+  guardrail blocks.
+
+  **The known flake, reported honestly with BOTH results.** Across the runs on
+  that worktree, `make ci` came back green, then once **exit 101** with a single
+  failure — `formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+  at `crates/codegraph-cli/src/main.rs:6213`,
+  `assertion failed: dir.join(".config/fish/completions/codegraph.fish").is_file()`,
+  **352 passed, 1 failed** — and then green again on the immediate re-run with no
+  code change in between. That is the documented pre-existing `HOME` /
+  `XDG_DATA_HOME` in-process race on this branch (~4 failures in 8 runs on a clean
+  commit), it lives in `crates/codegraph-cli`, which this commit does not touch,
+  and it was NOT weakened, ignored, skipped, or slowed down. Both outcomes are
+  recorded above rather than only the convenient one.
+
+  The final `make ci` — the one run after this prose and after `make fmt`, with no
+  byte written afterwards — has its actual exit status reported in this task's
+  closeout message. It is deliberately not backfilled here, because writing it
+  would mean editing the ledger AFTER the final gate, which the closeout order
+  forbids.
+
+- `sha256sum Cargo.lock` → `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`,
+  **unchanged**. No dependency added, no version byte moved; release-please still
+  owns versions.
+
+**Where `make ci` was run, and why that is the honest reading.** This task's
+worktree is shared with three sibling F-wave tasks, and at the time of the final
+gate a sibling's in-flight `crates/codegraph-resolve` edit left the tree failing
+clippy with `dead_code` on its own not-yet-wired helpers — a failure entirely
+inside `crates/`, which this task is forbidden to touch. So the final gate was run
+on a **clean detached worktree at `956cf32`** carrying EXACTLY this commit's five
+files (`ci.yml`, `guardrail.sh`, `check-ci-gate.sh`, `ci-gate.test.sh`, this
+ledger) and nothing else. That is the stricter reading, not a weaker one: it
+proves these five files alone are green against the recorded parent commit,
+without borrowing green from — or inheriting red from — a sibling's work in
+progress. The exit-0 above is that run's real status.
diff --git a/scripts/check-ci-gate.sh b/scripts/check-ci-gate.sh
new file mode 100755
index 0000000..05a68f3
--- /dev/null
+++ b/scripts/check-ci-gate.sh
@@ -0,0 +1,428 @@
+#!/usr/bin/env bash
+# check-ci-gate.sh — CI/release gate-integrity guard.
+#
+# Purpose
+#   `CI Success` (job id `ci-success` in .github/workflows/ci.yml) is the single
+#   required status check for branch protection AND the job the release workflow's
+#   `verify-ci` waits on before a GitHub Release may leave draft. Everything the
+#   project promises — "local green ⇒ CI green", "a release only fires on green
+#   CI" — rests on that one job being a STRICT gate.
+#
+#   Two ways it can silently stop being one, neither caught by any Cargo test:
+#
+#     1. The gate accepts a non-`success` result. `needs.<job>.result` can be
+#        `success`, `failure`, `cancelled` or `skipped`; a check that rejects only
+#        `failure` lets a CANCELLED run report success. `ci.yml` sets
+#        `cancel-in-progress: true`, so that is reachable on any push-over-push,
+#        and `verify-ci` would then green-light a release whose tests never ran.
+#     2. The required SET silently narrows. A new job added to `ci.yml` is NOT
+#        gated unless it is also listed in `ci-success`'s `needs:` — the `needs`
+#        context contains only what is listed there. GitHub Actions cannot express
+#        "require every job", so the invariant has to be asserted from outside the
+#        workflow. This gate is that outside.
+#
+# What it asserts
+#   A. `ci-success` exists, runs `if: always()`, and its `needs:` equals EVERY job
+#      in ci.yml except itself and an explicit informational allow-list.
+#   B. The allow-list is justified where it is claimed: `coverage` may be excluded
+#      only while codecov.yml still marks coverage `informational: true`.
+#   C. The gate step reads results from `${{ toJSON(needs) }}` (job-name-agnostic,
+#      so adding a job to `needs:` needs no script edit).
+#   D. BEHAVIOR, not shape: the shipped step body is extracted and EXECUTED here
+#      against a synthetic `needs` context for every result value —
+#      success | failure | cancelled | skipped | an unknown future value | a
+#      missing key | an empty / malformed context. Only all-`success` may exit 0.
+#   E. release-please.yml's `verify-ci` accepts exactly one conclusion (`success`)
+#      from the `CI Success` job, and `upload-assets` still lists `verify-ci` in
+#      `needs` so the gate is actually load-bearing.
+#
+#   Anything unparsable is a FAILURE, never a silent pass.
+#
+# Runs no Cargo, makes no network request, writes only inside a temp dir.
+#
+# Usage
+#   scripts/check-ci-gate.sh [REPO_ROOT]
+#   REPO_ROOT defaults to the repository root (the script's parent dir).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="${1:-"$(cd -- "$SCRIPT_DIR/.." && pwd -P)"}"
+
+command -v python3 > /dev/null 2>&1 || {
+	printf 'check-ci-gate: ERROR: python3 not found (needed to parse the workflow YAML)\n' >&2
+	exit 2
+}
+command -v jq > /dev/null 2>&1 || {
+	printf 'check-ci-gate: ERROR: jq not found (needed to run the gate body truth table)\n' >&2
+	exit 2
+}
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+BODY="$WORK/ci-success-body.sh"
+JOBS="$WORK/required-jobs.txt"
+
+# --- Phase 1 — structural assertions (A, B, C, E) --------------------------
+CG_CI_GATE_ROOT="$REPO_ROOT" CG_CI_GATE_BODY="$BODY" CG_CI_GATE_JOBS="$JOBS" python3 <<'PY'
+import os
+import re
+import sys
+
+ROOT = os.environ["CG_CI_GATE_ROOT"]
+BODY_OUT = os.environ["CG_CI_GATE_BODY"]
+JOBS_OUT = os.environ["CG_CI_GATE_JOBS"]
+
+CI = os.path.join(ROOT, ".github", "workflows", "ci.yml")
+RELEASE = os.path.join(ROOT, ".github", "workflows", "release-please.yml")
+CODECOV = os.path.join(ROOT, "codecov.yml")
+
+GATE_JOB = "ci-success"
+GATE_JOB_NAME = "CI Success"
+# Jobs allowed to stay OUT of the gate. Each entry must be justified below in
+# `justify_exclusion`; an unjustifiable entry is a failure, not a pass.
+INFORMATIONAL = {"coverage"}
+
+failures = []
+
+
+def fail(area, msg):
+    failures.append((area, msg))
+
+
+def die(msg, code=2):
+    print("check-ci-gate: ERROR: %s" % msg, file=sys.stderr)
+    sys.exit(code)
+
+
+def load(path, label):
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            text = fh.read()
+    except OSError as exc:
+        die("cannot read %s (%s): %s" % (label, path, exc))
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        die("%s is not valid YAML: %s" % (label, exc))
+    if not isinstance(data, dict):
+        die("%s did not parse to a mapping" % label)
+    return data
+
+
+try:
+    import yaml
+except ImportError:
+    die("PyYAML is required to parse the workflows (pip install PyYAML)")
+
+ci = load(CI, "ci.yml")
+release = load(RELEASE, "release-please.yml")
+codecov = load(CODECOV, "codecov.yml")
+
+ci_jobs = ci.get("jobs")
+if not isinstance(ci_jobs, dict) or not ci_jobs:
+    die("ci.yml has no jobs mapping")
+
+gate = ci_jobs.get(GATE_JOB)
+if not isinstance(gate, dict):
+    die("ci.yml has no `%s` job (the required status check)" % GATE_JOB)
+if gate.get("name") != GATE_JOB_NAME:
+    fail(
+        "gate-identity",
+        "ci.yml `%s` is named %r, but branch protection and release-please.yml's "
+        "verify-ci both look for %r" % (GATE_JOB, gate.get("name"), GATE_JOB_NAME),
+    )
+
+# --- A: `if: always()` -----------------------------------------------------
+# Without it the gate is SKIPPED whenever a needed job fails, so it never turns
+# red — it just never reports, and the strict check below would never run.
+gate_if = gate.get("if")
+if not isinstance(gate_if, str) or gate_if.strip() not in ("always()", "${{ always() }}"):
+    fail(
+        "gate-always",
+        "`%s` has `if: %r`; it must be `always()` so the gate RUNS (and fails) "
+        "when a required job did not succeed, instead of being skipped" % (GATE_JOB, gate_if),
+    )
+
+# --- A: the required set -------------------------------------------------
+needs = gate.get("needs")
+if isinstance(needs, str):
+    needs = [needs]
+if not isinstance(needs, list) or not needs:
+    die("`%s` has no `needs:` list — it would gate nothing" % GATE_JOB)
+needs = [str(n) for n in needs]
+
+if len(set(needs)) != len(needs):
+    fail("gate-needs", "`%s` `needs:` contains duplicates: %s" % (GATE_JOB, needs))
+if GATE_JOB in needs:
+    fail("gate-needs", "`%s` lists itself in `needs:`" % GATE_JOB)
+
+expected = sorted(set(ci_jobs) - {GATE_JOB} - INFORMATIONAL)
+actual = sorted(set(needs))
+
+ungated = [j for j in expected if j not in actual]
+unknown = [j for j in actual if j not in ci_jobs]
+excluded_but_needed = [j for j in actual if j in INFORMATIONAL]
+
+if ungated:
+    fail(
+        "gate-needs",
+        "job(s) %s exist in ci.yml but are NOT in `%s`'s `needs:`, so their result "
+        "cannot fail the gate. Add them to `needs:` (or, if genuinely "
+        "informational, add them to INFORMATIONAL in scripts/check-ci-gate.sh "
+        "WITH a written justification)." % (ungated, GATE_JOB),
+    )
+if unknown:
+    fail(
+        "gate-needs",
+        "`%s` needs %s, which is not a job in ci.yml (a rename would make the "
+        "workflow invalid and the gate meaningless)" % (GATE_JOB, unknown),
+    )
+if excluded_but_needed:
+    fail(
+        "gate-needs",
+        "`%s` needs %s, which is on the informational allow-list — the two "
+        "statements contradict each other" % (GATE_JOB, excluded_but_needed),
+    )
+
+# --- B: justify every exclusion -----------------------------------------
+def justify_exclusion(job):
+    """Return None when the exclusion is still justified, else the reason it is not."""
+    if job not in ci_jobs:
+        return "it is on the allow-list but no such job exists in ci.yml (stale entry)"
+    if job == "coverage":
+        # Coverage may be excluded ONLY while it is genuinely non-blocking: the
+        # Codecov status must still be informational, otherwise a below-target %
+        # would gate merges through a path this gate does not see.
+        status = ((codecov.get("coverage") or {}).get("status") or {})
+        if not isinstance(status, dict) or not status:
+            return "codecov.yml has no coverage.status block to prove it is informational"
+        for context, cfg in status.items():
+            default = (cfg or {}).get("default") if isinstance(cfg, dict) else None
+            if not isinstance(default, dict):
+                return "codecov.yml coverage.status.%s has no `default` mapping" % context
+            if default.get("informational") is not True:
+                return (
+                    "codecov.yml coverage.status.%s.default.informational is %r, not true — "
+                    "coverage would gate, so it must not be excluded here"
+                    % (context, default.get("informational"))
+                )
+        return None
+    return "no justification is recorded in scripts/check-ci-gate.sh for excluding it"
+
+
+for job in sorted(INFORMATIONAL):
+    reason = justify_exclusion(job)
+    if reason:
+        fail("gate-exclusion", "excluding %r from the gate is not justified: %s" % (job, reason))
+
+# --- C + D prep: the gate step ------------------------------------------
+steps = gate.get("steps")
+if not isinstance(steps, list) or not steps:
+    die("`%s` has no steps" % GATE_JOB)
+
+run_steps = [s for s in steps if isinstance(s, dict) and isinstance(s.get("run"), str)]
+if len(run_steps) != 1:
+    die(
+        "`%s` has %d `run:` step(s); this gate understands exactly one "
+        "(the strict status check)" % (GATE_JOB, len(run_steps))
+    )
+step = run_steps[0]
+body = step["run"]
+
+env = step.get("env") or {}
+if not isinstance(env, dict):
+    die("`%s`'s run step has a non-mapping `env:`" % GATE_JOB)
+needs_json = env.get("NEEDS_JSON")
+TOJSON_RE = re.compile(r"^\$\{\{\s*toJSON\(\s*needs\s*\)\s*\}\}$")
+if not isinstance(needs_json, str) or not TOJSON_RE.match(needs_json.strip()):
+    fail(
+        "gate-shape",
+        "the gate step must read every result from `env.NEEDS_JSON: ${{ toJSON(needs) }}` "
+        "(job-name-agnostic, so adding a job to `needs:` needs no script edit); found %r"
+        % (needs_json,),
+    )
+
+# A per-job `needs.<job>.result` expression in the body would re-introduce the
+# hardcoded-name problem the toJSON form exists to remove.
+hardcoded = re.findall(r"needs\.[A-Za-z0-9_-]+\.result", body)
+if hardcoded:
+    fail(
+        "gate-shape",
+        "the gate body interpolates per-job expressions %s; results must come from "
+        "NEEDS_JSON so a newly-needed job is covered automatically" % (sorted(set(hardcoded)),)
+    )
+
+with open(BODY_OUT, "w", encoding="utf-8") as fh:
+    fh.write(body if body.endswith("\n") else body + "\n")
+with open(JOBS_OUT, "w", encoding="utf-8") as fh:
+    fh.write("\n".join(actual) + "\n")
+
+# --- E: the release-side gate -------------------------------------------
+rel_jobs = release.get("jobs")
+if not isinstance(rel_jobs, dict):
+    die("release-please.yml has no jobs mapping")
+
+verify = rel_jobs.get("verify-ci")
+if not isinstance(verify, dict):
+    die("release-please.yml has no `verify-ci` job (the release-side CI gate)")
+
+vsteps = verify.get("steps")
+if not isinstance(vsteps, list) or not vsteps:
+    die("`verify-ci` has no steps")
+
+wait_body = None
+for s in vsteps:
+    if isinstance(s, dict) and isinstance(s.get("run"), str) and "conclusion" in s["run"]:
+        wait_body = s["run"]
+        break
+if wait_body is None:
+    die("could not find `verify-ci`'s conclusion-polling step (nothing references `conclusion`)")
+
+if GATE_JOB_NAME not in wait_body:
+    fail(
+        "release-gate",
+        "`verify-ci` does not select the %r job; it would wait on the wrong thing" % GATE_JOB_NAME,
+    )
+
+# The ONLY accepted conclusion must be `success`: exactly one `exit 0` in the
+# polling body, and it must be inside the `= "success"` branch.
+success_test = re.search(r'if\s+\[\s+"\$conclusion"\s+=\s+"success"\s+\]\s*;\s*then', wait_body)
+if not success_test:
+    fail(
+        "release-gate",
+        "`verify-ci` has no strict `[ \"$conclusion\" = \"success\" ]` accept test; a "
+        "cancelled/skipped CI run could satisfy the release gate",
+    )
+
+exit_zeros = [m.start() for m in re.finditer(r"^\s*exit 0\s*$", wait_body, re.M)]
+if len(exit_zeros) != 1:
+    fail(
+        "release-gate",
+        "`verify-ci`'s polling body has %d `exit 0` statement(s); exactly one is expected, "
+        "guarded by the success test" % len(exit_zeros),
+    )
+elif success_test and not (success_test.end() < exit_zeros[0]):
+    fail(
+        "release-gate",
+        "`verify-ci`'s `exit 0` is not inside the `= \"success\"` branch, so a non-success "
+        "conclusion could pass the release gate",
+    )
+
+if not re.search(r"^\s*exit 1\s*$", wait_body, re.M):
+    fail("release-gate", "`verify-ci`'s polling body never `exit 1`s; it cannot block a release")
+
+upload = rel_jobs.get("upload-assets")
+if not isinstance(upload, dict):
+    die("release-please.yml has no `upload-assets` job")
+up_needs = upload.get("needs")
+if isinstance(up_needs, str):
+    up_needs = [up_needs]
+if not isinstance(up_needs, list) or "verify-ci" not in [str(n) for n in up_needs]:
+    fail(
+        "release-gate",
+        "`upload-assets` does not list `verify-ci` in `needs:` (%r), so the CI gate would "
+        "not block the first public-facing release step" % (up_needs,),
+    )
+
+if failures:
+    for area, msg in failures:
+        print("check-ci-gate: MISMATCH [%s]: %s" % (area, msg), file=sys.stderr)
+    print(
+        "check-ci-gate: FAIL: %d CI/release gate-integrity problem(s)" % len(failures),
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+print("check-ci-gate: structure OK")
+print("  gate job           : %s (%r, if: %s)" % (GATE_JOB, GATE_JOB_NAME, gate_if))
+print("  required jobs      : %s" % ", ".join(actual))
+print("  excluded (informational, justified): %s" % (", ".join(sorted(INFORMATIONAL)) or "none"))
+print("  release gate       : verify-ci waits on %r, accepts only 'success'" % GATE_JOB_NAME)
+PY
+
+# --- Phase 2 — behavioral truth table over the SHIPPED body (D) ------------
+# The extracted body is executed with a synthetic `needs` context. This is a
+# LOCAL evaluation of the gate expression; it proves the logic, not GitHub's
+# runner behavior.
+mapfile -t REQUIRED < "$JOBS"
+
+# needs_json RESULT [OVERRIDE_JOB OVERRIDE_RESULT]
+needs_json() {
+	local base="$1" job="${2:-}" value="${3:-}"
+	local out="{}" j
+	for j in "${REQUIRED[@]}"; do
+		local r="$base"
+		if [ -n "$job" ] && [ "$j" = "$job" ]; then r="$value"; fi
+		out="$(jq -cn --argjson acc "$out" --arg k "$j" --arg v "$r" '$acc + {($k): {result: $v}}')"
+	done
+	printf '%s' "$out"
+}
+
+TT_PASS=0
+TT_FAIL=0
+run_body() { # run_body NEEDS_JSON -> sets RC/OUT
+	local payload="$1"
+	OUT="$WORK/tt.out"
+	set +e
+	NEEDS_JSON="$payload" bash "$BODY" > "$OUT" 2>&1
+	RC=$?
+	set -e
+}
+
+expect() { # expect LABEL WANT(zero|nonzero) [MUST_MATCH_REGEX]
+	local label="$1" want="$2" re="${3:-}"
+	local bad=0
+	if [ "$want" = "zero" ] && [ "$RC" -ne 0 ]; then bad=1; fi
+	if [ "$want" = "nonzero" ] && [ "$RC" -eq 0 ]; then bad=1; fi
+	if [ "$bad" -eq 0 ] && [ -n "$re" ] && ! grep -Eq -- "$re" "$OUT"; then bad=1; fi
+	if [ "$bad" -eq 1 ]; then
+		printf 'check-ci-gate: TRUTH-TABLE FAIL: %s (want %s, got exit %s)\n' "$label" "$want" "$RC" >&2
+		sed 's/^/    /' "$OUT" >&2
+		TT_FAIL=$((TT_FAIL + 1))
+	else
+		printf '  %-46s exit %-3s %s\n' "$label" "$RC" "OK"
+		TT_PASS=$((TT_PASS + 1))
+	fi
+}
+
+printf 'check-ci-gate: truth table over the shipped gate body (%d required job(s))\n' "${#REQUIRED[@]}"
+
+run_body "$(needs_json success)"
+expect "all jobs success" zero '✅ CI passed'
+
+FIRST="${REQUIRED[0]}"
+for value in failure cancelled skipped neutral timed_out unknown_future_value ""; do
+	shown="${value:-<empty-string>}"
+	run_body "$(needs_json success "$FIRST" "$value")"
+	expect "$FIRST = ${shown}" nonzero "required job '${FIRST}' concluded"
+done
+
+# Every required job must be individually able to redden the gate.
+for j in "${REQUIRED[@]}"; do
+	run_body "$(needs_json success "$j" cancelled)"
+	expect "$j = cancelled (per-job coverage)" nonzero "required job '${j}' concluded 'cancelled'"
+done
+
+# All-cancelled: every job must be reported, not just the first.
+run_body "$(needs_json cancelled)"
+expect "all jobs cancelled" nonzero "${#REQUIRED[@]} of ${#REQUIRED[@]} required job"
+
+# Degenerate contexts must fail CLOSED.
+run_body ""
+expect "empty needs context" nonzero 'failing closed'
+run_body "{}"
+expect "empty JSON object" nonzero 'failing closed'
+run_body "not json"
+expect "malformed JSON" nonzero 'failing closed'
+run_body '{"test":{}}'
+expect "result key missing" nonzero '<missing>'
+
+if [ "$TT_FAIL" -ne 0 ]; then
+	printf 'check-ci-gate: FAIL: %d truth-table case(s) failed (%d passed)\n' "$TT_FAIL" "$TT_PASS" >&2
+	exit 1
+fi
+
+printf 'check-ci-gate: OK (%d truth-table cases; only all-success exits 0)\n' "$TT_PASS"
diff --git a/scripts/guardrail.sh b/scripts/guardrail.sh
index 8f6d0be..f2098f5 100755
--- a/scripts/guardrail.sh
+++ b/scripts/guardrail.sh
@@ -28,4 +28,16 @@ if ! bash "$SCRIPT_DIR/check-asset-names.sh"; then
     EXIT_CODE=1
 fi
 
+# CI/release gate integrity: `CI Success` is the one required status check AND the
+# job the release gates on, but nothing else verifies that it is strict — a gate
+# that accepts `cancelled`/`skipped`, or that stops requiring a job, still lets
+# every test and lint pass. GitHub Actions also cannot express "require every job",
+# so the required SET has to be asserted from outside the workflow. Same home and
+# same reason as the block above: `guardrail` is the single step run by make ci,
+# the pre-push hook, and the CI `test` job.
+if ! bash "$SCRIPT_DIR/check-ci-gate.sh"; then
+    echo "❌ CI GATE INTEGRITY: 'CI Success' does not strictly require every job to succeed."
+    EXIT_CODE=1
+fi
+
 exit $EXIT_CODE
diff --git a/scripts/tests/ci-gate.test.sh b/scripts/tests/ci-gate.test.sh
new file mode 100755
index 0000000..44a7741
--- /dev/null
+++ b/scripts/tests/ci-gate.test.sh
@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+# ci-gate.test.sh — fixture harness for the CI/release gate-integrity guard.
+#
+# Copies the three REAL files the guard parses
+#   .github/workflows/ci.yml, .github/workflows/release-please.yml, codecov.yml
+# into a throwaway repo-shaped fixture, mutates ONE of them per scenario, and runs
+# scripts/check-ci-gate.sh against that fixture root. Nothing under the real
+# repository is touched, no Cargo runs, no network request is made, and no GitHub
+# Actions run is triggered — every claim here is a LOCAL evaluation of the gate
+# expression plus a YAML parse.
+#
+# It proves:
+#   * pristine copy of the real files              -> exit 0,
+#   * the real repository root                     -> exit 0,
+#   * cosmetic YAML churn (comment + requoting)    -> STILL exit 0 (no false alarm),
+#   * NEGATIVE CONTROL: the pre-fix `== "failure"` expression admits `cancelled`
+#     and `skipped`, while the shipped strict body rejects both,
+#   * ci.yml reverted to the `== "failure"` shape   -> red, blames gate-shape,
+#   * a required job dropped from `needs:`         -> red, names the ungated job,
+#   * `if: always()` removed from the gate         -> red, blames gate-always,
+#   * a new job added but not gated                -> red, names it,
+#   * codecov.yml flipped to informational: false  -> red, blames gate-exclusion,
+#   * verify-ci relaxed to reject only `failure`   -> red, blames release-gate,
+#   * upload-assets dropping verify-ci from needs  -> red, blames release-gate,
+#   * an unparsable workflow                       -> red (fails CLOSED).
+#
+# Usage: scripts/tests/ci-gate.test.sh
+
+set -euo pipefail
+
+HARNESS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$HARNESS_DIR/../.." && pwd -P)"
+GATE="$REPO_ROOT/scripts/check-ci-gate.sh"
+
+CI_REL=".github/workflows/ci.yml"
+REL_REL=".github/workflows/release-please.yml"
+COV_REL="codecov.yml"
+
+for f in "$GATE" "$REPO_ROOT/$CI_REL" "$REPO_ROOT/$REL_REL" "$REPO_ROOT/$COV_REL"; do
+	[ -f "$f" ] || {
+		printf 'harness: required file not found: %s\n' "$f" >&2
+		exit 2
+	}
+done
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+note() { printf '  %s\n' "$1"; }
+ok() {
+	printf 'PASS: %s\n' "$1"
+	PASS=$((PASS + 1))
+}
+bad() {
+	printf 'FAIL: %s\n' "$1" >&2
+	FAIL=$((FAIL + 1))
+}
+
+make_fixture() {
+	local name="$1"
+	local root="$WORK/$name"
+	mkdir -p "$root/.github/workflows"
+	cp "$REPO_ROOT/$CI_REL" "$root/$CI_REL"
+	cp "$REPO_ROOT/$REL_REL" "$root/$REL_REL"
+	cp "$REPO_ROOT/$COV_REL" "$root/$COV_REL"
+	printf '%s' "$root"
+}
+
+RC=0
+OUT=""
+ERR=""
+run_gate() {
+	local name="$1" root="$2"
+	OUT="$WORK/$name.out"
+	ERR="$WORK/$name.err"
+	set +e
+	bash "$GATE" "$root" > "$OUT" 2> "$ERR"
+	RC=$?
+	set -e
+}
+
+assert_rc() {
+	local name="$1" want="$2"
+	if [ "$RC" != "$want" ]; then
+		bad "$name: expected exit $want, got $RC"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+assert_rc_nonzero() {
+	local name="$1"
+	if [ "$RC" -eq 0 ]; then
+		bad "$name: expected a NONZERO exit, got 0"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		return 1
+	fi
+}
+assert_stdout() {
+	local name="$1" re="$2"
+	if ! grep -Eq -- "$re" "$OUT"; then
+		bad "$name: expected /$re/ on stdout"
+		note "stdout: $(tr '\n' '|' < "$OUT")"
+		return 1
+	fi
+}
+assert_stderr() {
+	local name="$1" re="$2"
+	if ! grep -Eq -- "$re" "$ERR"; then
+		bad "$name: expected diagnostic /$re/ on stderr"
+		note "stderr: $(tr '\n' '|' < "$ERR")"
+		return 1
+	fi
+}
+
+mutate() {
+	local file="$1" old="$2" new="$3"
+	CG_MUT_FILE="$file" CG_MUT_OLD="$old" CG_MUT_NEW="$new" python3 - <<'PY'
+import os
+import sys
+
+path = os.environ["CG_MUT_FILE"]
+old = os.environ["CG_MUT_OLD"]
+new = os.environ["CG_MUT_NEW"]
+with open(path, "r", encoding="utf-8") as fh:
+    text = fh.read()
+if old not in text:
+    print("harness: mutation anchor not found in %s: %r" % (path, old), file=sys.stderr)
+    sys.exit(2)
+with open(path, "w", encoding="utf-8") as fh:
+    fh.write(text.replace(old, new, 1))
+PY
+}
+
+printf '=== CI gate-integrity fixture harness ===\n'
+
+# --- Scenario A — pristine copies of the real files: green. ----------------
+A="$(make_fixture A_pristine)"
+a_ok=1
+run_gate "A_pristine" "$A"
+assert_rc "A_pristine" 0 || a_ok=0
+assert_stdout "A_pristine" 'check-ci-gate: structure OK' || a_ok=0
+assert_stdout "A_pristine" 'required jobs      : audit, test, windows' || a_ok=0
+assert_stdout "A_pristine" 'check-ci-gate: OK \([0-9]+ truth-table cases' || a_ok=0
+[ "$a_ok" -eq 1 ] && ok "A_pristine (exit=0, gate strict + truth table green)"
+
+# --- Scenario B — the real repository root: green. -------------------------
+b_ok=1
+run_gate "B_repository" "$REPO_ROOT"
+assert_rc "B_repository" 0 || b_ok=0
+assert_stdout "B_repository" 'check-ci-gate: OK' || b_ok=0
+[ "$b_ok" -eq 1 ] && ok "B_repository (exit=0, the shipped tree is strictly gated)"
+
+# --- Scenario C — cosmetic churn must NOT trip the guard. ------------------
+C="$(make_fixture C_cosmetic)"
+mutate "$C/$CI_REL" '    needs: [test, audit, windows]' \
+	'    # cosmetic: reflowed list, same three jobs
+    needs:
+      - test
+      - audit
+      - windows'
+c_ok=1
+run_gate "C_cosmetic" "$C"
+assert_rc "C_cosmetic" 0 || c_ok=0
+assert_stdout "C_cosmetic" 'required jobs      : audit, test, windows' || c_ok=0
+[ "$c_ok" -eq 1 ] && ok "C_cosmetic (exit=0, YAML reflow is not a gate change)"
+
+# --- Scenario D — NEGATIVE CONTROL: old vs new expression truth table. -----
+# The pre-fix gate body, verbatim, with GitHub's `${{ needs.X.result }}`
+# interpolation performed here the way the runner performs it (textual
+# substitution before bash sees the script).
+LEGACY_TMPL='if [[ "@TEST@" == "failure" || "@AUDIT@" == "failure" || "@WINDOWS@" == "failure" ]]; then
+  echo "❌ CI failed"
+  exit 1
+fi
+echo "✅ CI passed"'
+
+legacy_eval() { # legacy_eval RESULT -> exit status of the OLD gate
+	local r="$1" script
+	script="${LEGACY_TMPL//@TEST@/$r}"
+	script="${script//@AUDIT@/$r}"
+	script="${script//@WINDOWS@/$r}"
+	set +e
+	printf '%s\n' "$script" | bash > /dev/null 2>&1
+	local rc=$?
+	set -e
+	printf '%s' "$rc"
+}
+
+# Extract the SHIPPED strict body straight out of the real ci.yml and evaluate it
+# over the same four values, so both columns come from real files.
+STRICT_BODY="$WORK/strict-body.sh"
+CG_CI="$REPO_ROOT/$CI_REL" CG_OUT="$STRICT_BODY" python3 - <<'PY'
+import os
+import sys
+
+import yaml
+
+with open(os.environ["CG_CI"], "r", encoding="utf-8") as fh:
+    ci = yaml.safe_load(fh)
+steps = ci["jobs"]["ci-success"]["steps"]
+bodies = [s["run"] for s in steps if isinstance(s, dict) and isinstance(s.get("run"), str)]
+if len(bodies) != 1:
+    print("harness: expected exactly one run step in ci-success", file=sys.stderr)
+    sys.exit(2)
+with open(os.environ["CG_OUT"], "w", encoding="utf-8") as fh:
+    fh.write(bodies[0])
+PY
+
+strict_eval() { # strict_eval RESULT -> exit status of the NEW gate
+	local r="$1" payload
+	payload="$(jq -cn --arg v "$r" '{test:{result:$v},audit:{result:$v},windows:{result:$v}}')"
+	set +e
+	NEEDS_JSON="$payload" bash "$STRICT_BODY" > /dev/null 2>&1
+	local rc=$?
+	set -e
+	printf '%s' "$rc"
+}
+
+printf '  truth table — result | OLD exit | NEW exit | OLD verdict | NEW verdict\n'
+d_ok=1
+for value in success failure cancelled skipped; do
+	old_rc="$(legacy_eval "$value")"
+	new_rc="$(strict_eval "$value")"
+	old_verdict=$([ "$old_rc" -eq 0 ] && echo ADMITS || echo rejects)
+	new_verdict=$([ "$new_rc" -eq 0 ] && echo ADMITS || echo rejects)
+	printf '    %-10s |    %-5s |    %-5s | %-7s | %s\n' \
+		"$value" "$old_rc" "$new_rc" "$old_verdict" "$new_verdict"
+	case "$value" in
+		success)
+			{ [ "$old_rc" -eq 0 ] && [ "$new_rc" -eq 0 ]; } || d_ok=0
+			;;
+		failure)
+			{ [ "$old_rc" -ne 0 ] && [ "$new_rc" -ne 0 ]; } || d_ok=0
+			;;
+		cancelled | skipped)
+			# THE DEFECT: old admits, new rejects.
+			{ [ "$old_rc" -eq 0 ] && [ "$new_rc" -ne 0 ]; } || d_ok=0
+			;;
+	esac
+done
+[ "$d_ok" -eq 1 ] \
+	&& ok "D_negative_control (old ADMITS cancelled+skipped; new rejects them, both agree on success/failure)" \
+	|| bad "D_negative_control: the old/new truth table did not match the documented defect"
+
+# --- Scenario E — MUTANT: ci.yml reverted to the pre-fix expression. -------
+E="$(make_fixture E_legacy_expression)"
+mutate "$E/$CI_REL" '        env:
+          # The whole needs context as JSON: {"test":{"result":"success",...},...}
+          NEEDS_JSON: ${{ toJSON(needs) }}
+' ''
+mutate "$E/$CI_REL" '        run: |
+          set -euo pipefail
+' '        run: |
+          if [[ "${{ needs.test.result }}" == "failure" ]]; then exit 1; fi
+          echo "legacy"
+          set -euo pipefail
+'
+e_ok=1
+run_gate "E_legacy_expression" "$E"
+assert_rc_nonzero "E_legacy_expression" || e_ok=0
+assert_stderr "E_legacy_expression" 'MISMATCH \[gate-shape\]' || e_ok=0
+assert_stderr "E_legacy_expression" 'needs\.test\.result' || e_ok=0
+[ "$e_ok" -eq 1 ] && ok "E_legacy_expression (exit=$RC, per-job interpolation is rejected)"
+
+# --- Scenario F — MUTANT: a required job dropped from `needs:`. ------------
+F="$(make_fixture F_job_ungated)"
+mutate "$F/$CI_REL" '    needs: [test, audit, windows]' '    needs: [test, audit]'
+f_ok=1
+run_gate "F_job_ungated" "$F"
+assert_rc_nonzero "F_job_ungated" || f_ok=0
+assert_stderr "F_job_ungated" 'MISMATCH \[gate-needs\]' || f_ok=0
+assert_stderr "F_job_ungated" "\\['windows'\\] exist in ci\\.yml but are NOT in" || f_ok=0
+[ "$f_ok" -eq 1 ] && ok "F_job_ungated (exit=$RC, names the ungated job)"
+
+# --- Scenario G — MUTANT: `if: always()` removed from the gate. ------------
+G="$(make_fixture G_no_always)"
+mutate "$G/$CI_REL" '    runs-on: ubuntu-latest
+    if: always()' '    runs-on: ubuntu-latest'
+g_ok=1
+run_gate "G_no_always" "$G"
+assert_rc_nonzero "G_no_always" || g_ok=0
+assert_stderr "G_no_always" 'MISMATCH \[gate-always\]' || g_ok=0
+[ "$g_ok" -eq 1 ] && ok "G_no_always (exit=$RC, a skippable gate is not a gate)"
+
+# --- Scenario H — MUTANT: a NEW job appears but is never gated. ------------
+# This is the "robust to a job added later" case: GitHub Actions cannot express
+# it inside the workflow, so the guard must catch it from outside — loudly.
+H="$(make_fixture H_new_job_ungated)"
+mutate "$H/$CI_REL" '  ci-success:' '  fuzz:
+    name: Fuzz
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo fuzzing
+
+  ci-success:'
+h_ok=1
+run_gate "H_new_job_ungated" "$H"
+assert_rc_nonzero "H_new_job_ungated" || h_ok=0
+assert_stderr "H_new_job_ungated" 'MISMATCH \[gate-needs\]' || h_ok=0
+assert_stderr "H_new_job_ungated" "\\['fuzz'\\]" || h_ok=0
+[ "$h_ok" -eq 1 ] && ok "H_new_job_ungated (exit=$RC, a later-added job cannot slip past the gate)"
+
+# --- Scenario I — MUTANT: coverage stops being informational. --------------
+I="$(make_fixture I_coverage_blocking)"
+mutate "$I/$COV_REL" '        informational: true # report-only' '        informational: false # report-only'
+i_ok=1
+run_gate "I_coverage_blocking" "$I"
+assert_rc_nonzero "I_coverage_blocking" || i_ok=0
+assert_stderr "I_coverage_blocking" 'MISMATCH \[gate-exclusion\]' || i_ok=0
+assert_stderr "I_coverage_blocking" 'informational is False, not true' || i_ok=0
+[ "$i_ok" -eq 1 ] && ok "I_coverage_blocking (exit=$RC, the exclusion cannot outlive its justification)"
+
+# --- Scenario J — MUTANT: verify-ci relaxed to reject only `failure`. ------
+J="$(make_fixture J_release_gate_relaxed)"
+mutate "$J/$REL_REL" 'if [ "$conclusion" = "success" ]; then' 'if [ "$conclusion" != "failure" ]; then'
+j_ok=1
+run_gate "J_release_gate_relaxed" "$J"
+assert_rc_nonzero "J_release_gate_relaxed" || j_ok=0
+assert_stderr "J_release_gate_relaxed" 'MISMATCH \[release-gate\]' || j_ok=0
+assert_stderr "J_release_gate_relaxed" 'cancelled/skipped CI run could satisfy the release gate' || j_ok=0
+[ "$j_ok" -eq 1 ] && ok "J_release_gate_relaxed (exit=$RC, the release-side gate must be strict too)"
+
+# --- Scenario K — MUTANT: upload-assets stops needing verify-ci. -----------
+K="$(make_fixture K_gate_not_wired)"
+mutate "$K/$REL_REL" '    needs: [release-please, build-binaries, verify-ci]' \
+	'    needs: [release-please, build-binaries]'
+k_ok=1
+run_gate "K_gate_not_wired" "$K"
+assert_rc_nonzero "K_gate_not_wired" || k_ok=0
+assert_stderr "K_gate_not_wired" 'MISMATCH \[release-gate\]' || k_ok=0
+assert_stderr "K_gate_not_wired" 'does not list `verify-ci` in `needs:`' || k_ok=0
+[ "$k_ok" -eq 1 ] && ok "K_gate_not_wired (exit=$RC, an unwired gate is reported)"
+
+# --- Scenario L — an unparsable workflow must FAIL CLOSED. ----------------
+L="$(make_fixture L_unparsable)"
+mutate "$L/$CI_REL" 'jobs:' 'jobs: [this is not a mapping]
+ignored:'
+l_ok=1
+run_gate "L_unparsable" "$L"
+assert_rc_nonzero "L_unparsable" || l_ok=0
+assert_stderr "L_unparsable" 'check-ci-gate: ERROR' || l_ok=0
+[ "$l_ok" -eq 1 ] && ok "L_unparsable (exit=$RC, an unreadable gate is a failure, not a pass)"
+
+printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

From 33da2f59b1d646a47c421c19bff756501df6d9ee Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Tue, 28 Jul 2026 23:00:50 +0800
Subject: [PATCH 62/91] fix(store): detect SQLite sidecars losslessly on
 non-UTF-8 paths

Sidecar detection built its -wal/-shm names with Path::display(), which replaces
every byte that is not valid UTF-8 with U+FFFD. On a Unix project path carrying
arbitrary bytes those names pointed at files that do not exist, so a hard-killed
daemon's committed, un-checkpointed write-ahead log went unseen: the strict
Current read gate saw a sidecar-free namespace, admitted it, deserialized only
the main database file, and served a stale index missing every WAL-only row.

Route both detection functions through the existing lossless
database_sidecar_path helper (already used by the removal path), so detection and
removal agree on the native path. The Missing-state artifact guard shared the
same construction and is fixed with it. No gate is relaxed: open_for_read still
defaults to allow_live_sidecar = false, recovery still refuses to delete a
non-empty log, still revalidates its exclusive lease before each unlink, and
still keeps its bounded lease deadline.
---
 crates/codegraph-store/src/connection.rs      |  17 +-
 .../tests/store_state_gates.rs                | 240 +++++++++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 460 ++++++++++++++++++
 3 files changed, 712 insertions(+), 5 deletions(-)

diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index 293b13f..930324e 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -1010,8 +1010,8 @@ fn validate_extraction_stamp(db_path: &Path, stamp: Option<String>) -> Result<()
 fn first_existing_database_artifact(paths: &IndexPaths) -> Result<Option<PathBuf>> {
     let db = paths.current_db();
     let mut artifacts = vec![db.clone()];
-    artifacts.push(PathBuf::from(format!("{}-wal", db.display())));
-    artifacts.push(PathBuf::from(format!("{}-shm", db.display())));
+    artifacts.push(database_sidecar_path(&db, "-wal"));
+    artifacts.push(database_sidecar_path(&db, "-shm"));
     for path in artifacts {
         match std::fs::symlink_metadata(&path) {
             Ok(_) => return Ok(Some(path)),
@@ -1054,6 +1054,13 @@ fn remove_checkpointed_sidecars(paths: &IndexPaths, lease: &IndexLease) -> Resul
 /// Append SQLite's sidecar suffix to the native database pathname without a
 /// Unicode rendering round-trip, so both Unix byte paths and Windows wide paths
 /// stay lossless.
+///
+/// Every sidecar path in this module MUST come from here. `Path::display()`
+/// replaces each byte that is not valid UTF-8 with U+FFFD, so a sidecar name
+/// built from that rendering points at a DIFFERENT file: the detection gates
+/// would see a sidecar-free namespace while a committed `-wal` sat undetected
+/// beside the database, and the strict `Current` read would then serve an index
+/// missing every row that lives only in that log.
 fn database_sidecar_path(db: &Path, suffix: &str) -> PathBuf {
     let mut native = db.as_os_str().to_os_string();
     native.push(suffix);
@@ -1074,8 +1081,8 @@ fn artifact_len(path: &Path) -> Result<Option<u64>> {
 fn first_existing_database_sidecar(paths: &IndexPaths) -> Result<Option<PathBuf>> {
     let db = paths.current_db();
     for path in [
-        PathBuf::from(format!("{}-wal", db.display())),
-        PathBuf::from(format!("{}-shm", db.display())),
+        database_sidecar_path(&db, "-wal"),
+        database_sidecar_path(&db, "-shm"),
     ] {
         if artifact_exists(&path)? {
             return Ok(Some(path));
@@ -1320,7 +1327,7 @@ mod tests {
         assert_eq!(v1, crate::migrations::CURRENT_SCHEMA_VERSION);
 
         for ext in ["", "-wal", "-shm"] {
-            let _ = std::fs::remove_file(format!("{}{ext}", db_path.display()));
+            let _ = std::fs::remove_file(database_sidecar_path(&db_path, ext));
         }
     }
 
diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
index 901a7a1..ac11325 100644
--- a/crates/codegraph-store/tests/store_state_gates.rs
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -1306,6 +1306,246 @@ fn current_with_committed_wal_fails_closed_without_ignoring_or_mutating_sidecars
     }
 }
 
+/// Build a project whose DIRECTORY NAME carries bytes that are not valid UTF-8.
+///
+/// A Unix path is an arbitrary byte string, so `Path::display()` renders such a
+/// name LOSSILY (each invalid byte becomes U+FFFD) and every sidecar path built
+/// from that rendering names a file that does not exist. Windows is excluded
+/// from these fixtures because its paths are UTF-16 and the byte-oriented
+/// `OsString` constructors used here (`std::os::unix::ffi`) do not exist there.
+#[cfg(unix)]
+fn non_utf8_project(outer: &TempProject, label: &str) -> TempProject {
+    use std::ffi::OsString;
+    use std::os::unix::ffi::OsStringExt;
+
+    let mut name = OsString::from_vec(format!("{label}-").into_bytes());
+    name.push(OsString::from_vec(vec![0x80, 0xff]));
+    let path = outer.0.join(name);
+    std::fs::create_dir(&path)
+        .unwrap_or_else(|error| panic!("create non-UTF-8 project {}: {error}", path.display()));
+    TempProject(
+        path.canonicalize()
+            .unwrap_or_else(|error| panic!("canonicalize non-UTF-8 project: {error}")),
+    )
+}
+
+/// The path a LOSSY `Path::display()` round-trip would name. On a non-UTF-8
+/// project this is a different file from [`sqlite_sidecar`]'s native path, and
+/// nothing in production may read, write, or delete it.
+#[cfg(unix)]
+fn lossy_sidecar(db: &Path, suffix: &str) -> PathBuf {
+    PathBuf::from(format!("{}{suffix}", db.display()))
+}
+
+#[cfg(unix)]
+fn probe_row_is_folded_into_main_file(paths: &IndexPaths) -> bool {
+    observe_database_without_touching_namespace(paths)
+        .project_metadata
+        .iter()
+        .any(|(key, _, _)| key == "wal_only_probe")
+}
+
+/// The strict `Current` read gate must refuse a namespace whose committed
+/// write-ahead log sits beside a database under a NON-UTF-8 project path.
+///
+/// Detecting that sidecar through `Path::display()` looks at a path that does
+/// not exist, so the gate would conclude "sidecar-free", admit the namespace,
+/// and serve an index missing every row that lives only in the log.
+#[cfg(unix)]
+#[test]
+fn non_utf8_current_with_committed_wal_fails_closed() {
+    let outer = TempProject::new("non-utf8-wal-gate");
+    let project = non_utf8_project(&outer, "proj");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    run_crashed_current_writer(project.path());
+
+    let wal_path = sqlite_sidecar(&paths.current_db(), "-wal");
+    assert_ne!(
+        wal_path,
+        lossy_sidecar(&paths.current_db(), "-wal"),
+        "fixture must expose a lossy rendering distinct from the native path"
+    );
+    assert!(
+        std::fs::metadata(&wal_path)
+            .expect("committed WAL exists beside the non-UTF-8 database")
+            .len()
+            > 0,
+        "fixture must carry committed WAL frames"
+    );
+    assert!(
+        !probe_row_is_folded_into_main_file(&paths),
+        "the probe row must live ONLY in the write-ahead log"
+    );
+
+    let before = snapshot_tree(project.path());
+    for error in [
+        Store::open_for_read(&paths, deadline(), || false)
+            .expect_err("non-UTF-8 Current with committed WAL must fail closed"),
+        Store::open_for_status(&paths, deadline(), || false)
+            .expect_err("non-UTF-8 Current status with committed WAL must fail closed"),
+    ] {
+        assert!(
+            matches!(
+                &error,
+                StoreError::CurrentWithDatabaseSidecar { path } if path == &wal_path
+            ),
+            "unexpected non-UTF-8 sidecar refusal: {error:?}"
+        );
+        assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+    }
+}
+
+/// The dead-owner recovery path must detect and FOLD a committed write-ahead log
+/// on a non-UTF-8 project path, so the row that existed only in that log becomes
+/// readable instead of being silently skipped by a stale main-file-only read.
+#[cfg(unix)]
+#[test]
+fn non_utf8_dead_owner_wal_is_folded_and_then_readable() {
+    let outer = TempProject::new("non-utf8-wal-recovery");
+    let project = non_utf8_project(&outer, "proj");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    run_crashed_current_writer(project.path());
+
+    let wal = sqlite_sidecar(&paths.current_db(), "-wal");
+    let shm = sqlite_sidecar(&paths.current_db(), "-shm");
+    assert!(
+        std::fs::metadata(&wal).expect("planted WAL exists").len() > 0,
+        "a zero-byte sidecar would prove nothing"
+    );
+    assert!(
+        !probe_row_is_folded_into_main_file(&paths),
+        "the probe row must live ONLY in the write-ahead log before recovery"
+    );
+
+    assert!(
+        Store::recover_stale_current_sidecars(&paths, deadline(), || false)
+            .expect("recovery over a dead owner's residue must not error"),
+        "a dead owner's committed WAL must be DETECTED on a non-UTF-8 path"
+    );
+    assert!(!wal.exists(), "checkpointed WAL must be removed");
+    assert!(!shm.exists(), "derived SHM must be removed");
+    assert!(
+        probe_row_is_folded_into_main_file(&paths),
+        "recovery must fold the log into the main database file, not discard it"
+    );
+
+    let store = Store::open_for_read(&paths, deadline(), || false)
+        .expect("strict gate admits the recovered non-UTF-8 namespace");
+    assert_eq!(
+        store
+            .get_project_metadata("wal_only_probe")
+            .expect("read the WAL-only probe row"),
+        Some("committed".to_string()),
+        "the WAL-only row must be visible through the strict read path"
+    );
+    drop(store);
+
+    assert!(
+        paths.permanent_lock().is_file(),
+        "the permanent index lock must survive recovery"
+    );
+    assert!(
+        paths.state_slots().iter().any(|slot| slot.is_file()),
+        "the published state must survive recovery"
+    );
+    assert!(
+        !paths.tombstone().exists(),
+        "recovery must not author a tombstone"
+    );
+    assert_eq!(Store::extraction_status(&paths), ExtractionStatus::Current);
+}
+
+/// Recovery must operate on the NATIVE sidecar only. A file whose name matches
+/// the LOSSY `display()` rendering is a different, unrelated file and must be
+/// neither checkpointed nor deleted.
+#[cfg(unix)]
+#[test]
+fn non_utf8_recovery_never_touches_the_lossy_lookalike_sidecars() {
+    let outer = TempProject::new("non-utf8-lookalike");
+    let project = non_utf8_project(&outer, "proj");
+    let paths = stage_current(&project, Some(&CURRENT_EXTRACTION_VERSION.to_string()));
+    run_crashed_current_writer(project.path());
+
+    let native_wal = sqlite_sidecar(&paths.current_db(), "-wal");
+    let lossy_wal = lossy_sidecar(&paths.current_db(), "-wal");
+    let lossy_shm = lossy_sidecar(&paths.current_db(), "-shm");
+    assert_ne!(
+        native_wal, lossy_wal,
+        "fixture must expose a lossy rendering distinct from the native path"
+    );
+    std::fs::create_dir_all(lossy_wal.parent().expect("lossy sidecar parent"))
+        .expect("create lossy-lookalike parent directory");
+    std::fs::write(&lossy_wal, b"lookalike WAL must survive").expect("write lookalike WAL");
+    std::fs::write(&lossy_shm, b"lookalike SHM must survive").expect("write lookalike SHM");
+
+    assert!(
+        Store::recover_stale_current_sidecars(&paths, deadline(), || false)
+            .expect("recovery over a dead owner's residue must not error"),
+        "a dead owner's committed WAL must be DETECTED on a non-UTF-8 path"
+    );
+
+    assert!(!native_wal.exists(), "native WAL must be checkpointed away");
+    assert_eq!(
+        std::fs::read(&lossy_wal).expect("read preserved lookalike WAL"),
+        b"lookalike WAL must survive",
+        "the lossy lookalike WAL must be untouched"
+    );
+    assert_eq!(
+        std::fs::read(&lossy_shm).expect("read preserved lookalike SHM"),
+        b"lookalike SHM must survive",
+        "the lossy lookalike SHM must be untouched"
+    );
+    Store::open_for_read(&paths, deadline(), || false)
+        .expect("strict gate admits the recovered non-UTF-8 namespace")
+        .get_project_metadata("wal_only_probe")
+        .expect("read the WAL-only probe row")
+        .expect("the folded WAL-only row must be readable");
+}
+
+/// The `Missing`-state artifact guard reads the same sidecar names, so it must
+/// also see them losslessly: an unexplained `-wal`/`-shm` beside a stateless
+/// namespace on a non-UTF-8 path is not a fresh writable namespace.
+#[cfg(unix)]
+#[test]
+fn missing_state_with_non_utf8_database_sidecar_fails_closed() {
+    for suffix in ["-wal", "-shm"] {
+        let outer = TempProject::new("non-utf8-missing-artifact");
+        let project = non_utf8_project(&outer, "proj");
+        let paths = project.paths();
+        drop(create_namespace(&paths));
+        let artifact = sqlite_sidecar(&paths.current_db(), suffix);
+        assert_ne!(
+            artifact,
+            lossy_sidecar(&paths.current_db(), suffix),
+            "fixture must expose a lossy rendering distinct from the native path"
+        );
+        std::fs::write(&artifact, b"reserved unknown database artifact")
+            .expect("stage unknown database artifact");
+        let before = snapshot_tree(project.path());
+
+        let lease = IndexLease::acquire_exclusive_existing(&paths, deadline(), || false)
+            .expect("acquire Missing fixture lease");
+        let write_error = Store::open_for_write(&paths, lease, StoreWritePurpose::FullRebuild)
+            .expect_err("Missing plus a DB sidecar is not a fresh writable namespace");
+        for error in [
+            write_error,
+            Store::open_for_read(&paths, deadline(), || false)
+                .expect_err("Missing artifact must reject read"),
+            Store::open_for_status(&paths, deadline(), || false)
+                .expect_err("Missing artifact must reject status"),
+        ] {
+            assert!(
+                matches!(
+                    &error,
+                    StoreError::MissingStateWithDatabase { path } if path == &artifact
+                ),
+                "unexpected non-UTF-8 Missing-artifact refusal: {error:?}"
+            );
+            assert_snapshot_unchanged(&before, &snapshot_tree(project.path()));
+        }
+    }
+}
+
 /// Child-process entry point used by deterministic lock contention tests.
 #[test]
 fn store_gate_child_process() {
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 81ecbe4..9b1f612 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -7012,3 +7012,463 @@ ledger) and nothing else. That is the stricter reading, not a weaker one: it
 proves these five files alone are green against the recorded parent commit,
 without borrowing green from — or inheriting red from — a sibling's work in
 progress. The exit-0 above is that run's real status.
+
+## Batch F3 — the data-router route-object walk stops at that object's own `}`, not at 300 fixed bytes (2026-07-28)
+
+Completes upstream issue **#1348**, whose data-router half Batch D1 left untouched
+while the manifest already classified the issue as a full `PORT`. This batch fixes
+the behavior (Option A) rather than narrowing the claim (Option B), so both
+documents now describe a landing that exists.
+
+### The defect, at exact line numbers
+
+`crates/codegraph-resolve/src/frameworks/react.rs:188` (pre-change), inside the
+`// React Router data-router (v6.4+)` block that begins at line 184:
+
+```rust
+let win = byte_window(content, whole.start(), 300);
+let comp = obj_element_attr()
+    .captures(win)
+    .or_else(|| obj_component_attr().captures(win))
+    .map(|c| c.get(1).expect("comp group").as_str().to_string());
+```
+
+A fixed 300-byte window scanned forward from every `path:` key and took the FIRST
+`element:` / `Component:` it met. Nothing bounded it to the route object that owns
+that `path`, so a parent route with no `element` of its own silently borrowed a
+CHILD route's component out of `children: […]` — the same borrowing defect
+`route_opening_tag_window` (react.rs:552-561, Batch D1) fixes for the `<Route>` JSX
+form. The `<Route>` half was fixed; this half was not.
+
+Why Option A and not Option B: the object form is bounded by exactly the mechanism
+the JSX form already uses — walk forward tracking depth and quotes, stop at the
+construct's own terminator, keep a named byte backstop for malformed input. The JSX
+terminator is `>` at brace depth 0; the object terminator is `}` at depth 0. Nothing
+about the object form made that disproportionate, so narrowing the claim would have
+been the weaker choice.
+
+### Green — `route_object_own_properties` (react.rs:608-664)
+
+`route_object_own_properties(content, path_key_start)` returns the route object's
+OWN properties as text. It walks from the `path:` key and:
+
+- returns at the `}` / `]` that closes the object (depth 0) — nothing past it belongs
+  to this route;
+- **elides** nested `{…}` / `[…]` groups instead of merely tracking them, so a
+  `children: […]` array cannot leak its `element` into the parent's text and neither
+  can a `handle: {…}` object;
+- copies quoted values verbatim, so a `}` or `>` inside `path: 'a>b'` neither ends
+  the object nor unbalances the depth;
+- stops at the next depth-0 `path:` key (`is_path_key_at`, react.rs:666-672) when the
+  literal never closes, so even malformed input cannot borrow a following sibling's
+  properties;
+- is capped by `ROUTE_OBJECT_SCAN_LIMIT` regardless.
+
+This deliberately mirrors `opening_tag_end`'s invariants rather than inventing a
+second unrelated scanner: same brace/quote skipping, same "terminate at the
+construct's own end, cap the search anyway" pair. It cannot literally REUSE
+`opening_tag_end`, because the two forms differ in three ways — the object's
+terminator is `}`/`]` and not `>`; `[` must count toward depth for an array-valued
+`children`; and nested groups must be ELIDED from the returned text, not merely
+skipped over, which is why this function returns an owned `String` while
+`route_opening_tag_window` can return a `&str` slice. Their invariants are kept
+visibly parallel in the doc comments.
+
+Not fixed by raising 300: a larger fixed window moves the borrowing further away
+without removing it, and would newly break the long-object case in the opposite
+direction. The bound is structural first, byte-capped only as a backstop.
+
+### The bound and why that number
+
+`ROUTE_OBJECT_SCAN_LIMIT = 4096`, justified in its doc comment from route objects
+actually measured (raw walk distance from the object's `path:` key to its own closing
+`}`, nested children included because the walk traverses and elides them):
+
+| Route-object shape                                                                       | Bytes |
+| ---------------------------------------------------------------------------------------- | ----- |
+| minimal inline `{ path, element }`                                                       | 38    |
+| typical v6.4 route: `loader` + `errorElement` + `element`                                | 142   |
+| plus `action`, `handle: {…}`, `shouldRevalidate`, `element` LAST                         | 407   |
+| wide enterprise route: `hydrateFallbackElement` + nested `handle` object, `element` LAST | 611   |
+| parent with 8 loader-bearing children, own `element` declared LAST (worst realistic)     | 1503  |
+
+The 1503-byte case is the one that sizes the constant: every child byte must be
+traversed before the parent's own `element` is reached, so the walk length is driven
+by children count, not by the parent's own property count. 4096 is ~2.7x that, and
+strictly wider than the 300-byte window it replaces, so nothing the old code could
+reach is lost. Measured with a brace/quote-aware Python walker over each fixture, not
+guessed — the same discipline the D1 bound used after its first 512-byte draft was
+falsified by a real 700-byte tag.
+
+### Red — measured, before the fix
+
+The five new tests were written first and run against the pre-change 300-byte window
+(`cargo test --locked -p codegraph-resolve --test frameworks` → **exit 101**). Actual
+output, unabridged assertions:
+
+    ---- react_data_router_parent_without_element_does_not_borrow_from_children ----
+    assertion `left == right` failed: a parent route with no element of its own must emit no route->component pair
+      left: [("/dashboard", 3), ("settings", 6)]
+     right: [("settings", 6)]
+
+    ---- react_data_router_child_without_element_does_not_borrow_from_parent ----
+    assertion `left == right` failed: the element-less child must emit nothing; only the parent owns an element
+      left: [("/dashboard", 3), ("settings", 5)]
+     right: [("/dashboard", 3)]
+
+    ---- react_data_router_object_stops_at_next_path_key_when_unbraced ----
+    assertion `left == right` failed: the first path key has no element between it and the second key
+      left: ["/a", "/b"]
+     right: ["/b"]
+
+    ---- react_data_router_object_survives_angle_brackets_and_stops_at_sibling ----
+    assertion `left == right` failed: a `>` inside a quoted path or a braced expression must not end the object, and an element-less object must not borrow from its next sibling
+      left: [("/a>b", 2), ("/c>d", 3), ("/plain", 4)]
+     right: [("/a>b", 2), ("/plain", 4)]
+
+    ---- react_data_router_keeps_long_route_object_intact ----
+    panicked at crates/codegraph-resolve/tests/frameworks.rs:638:10: route node
+
+The first Red is the defect verbatim: `/dashboard` has no `element` of its own, yet
+it emitted a route→component pair by borrowing `DashboardHome` from its pathless
+`index` child. The last Red is the opposite failure mode — a legitimate 300+-byte
+route object whose own `element` sits past the window is dropped entirely, so no
+route node exists at all.
+
+### Tests
+
+Five new tests in `crates/codegraph-resolve/tests/frameworks.rs`, all driving the
+real `ReactResolver::extract`:
+
+- `react_data_router_parent_without_element_does_not_borrow_from_children` — the
+  #1348 data-router shape: parent `path` with NO `element`, a pathless `index` child
+  that HAS one, and a `path: 'settings'` child. Asserts the exact route-node list AND
+  the exact reference list: parent emits nothing, `settings` emits exactly its own.
+- `react_data_router_child_without_element_does_not_borrow_from_parent` — the mirror,
+  and the shape that makes the object's own `}` load-bearing: an element-less child
+  inside `children: […]` while the parent declares `element` AFTER the array.
+- `react_data_router_object_stops_at_next_path_key_when_unbraced` — two depth-0
+  `path:` keys with no brace between them; only the next-`path:` stop prevents the
+  first from borrowing the second's element.
+- `react_data_router_object_survives_angle_brackets_and_stops_at_sibling` — a `path`
+  string containing `>`, an `element` whose nested JSX expression contains `>` inside
+  braces (`<Spinner size={2 > 1 ? 8 : 4}/>`), and a following element-less sibling
+  that must not borrow forward. Shapes the 300-byte window mishandled.
+- `react_data_router_keeps_long_route_object_intact` — a route object with `loader`,
+  `action`, `errorElement`, `hydrateFallbackElement`, a nested `handle: {…}` and
+  `shouldRevalidate`, its own `element` declared LAST and asserted (in the test) to
+  sit past 300 bytes. Asserts the reference list is EXACTLY `["BillingSettingsPage"]`,
+  so neither the `errorElement` nor the `hydrateFallbackElement` may be mistaken for
+  the route's element. Pins the bound from the outside: tightening
+  `ROUTE_OBJECT_SCAN_LIMIT` below the object length reddens it.
+
+`react_data_router_object_walk_is_bounded_for_unterminated_literal` also lands here:
+an unterminated `{ path: '/a',` followed by 25 000 filler lines and then a
+well-formed `/b` route, asserting `/a` reaches neither end-of-file nor `/b`'s
+element. It passes both before and after the fix (the old 300-byte cap also bounded
+it), so it is recorded as a guard, NOT as Red evidence.
+
+### Negative control, EXECUTED (three mutants, each reddening a DIFFERENT test)
+
+1. Production line reverted to `byte_window(content, whole.start(), 300)`, tests
+   untouched → **exit 101**, 5 failed — the full Red block quoted above.
+
+2. Object-boundary terminator removed (the depth-0 `}`/`]` arm `continue`s instead of
+   returning), 4096 backstop and elision kept → **exit 101**, **1 failed**:
+
+       ---- react_data_router_child_without_element_does_not_borrow_from_parent ----
+       assertion `left == right` failed: the element-less child must emit nothing; only the parent owns an element
+         left: [("/dashboard", 3), ("settings", 5)]
+        right: [("/dashboard", 3)]
+
+   — a DIFFERENT test from mutants 1 and 3 in isolation, and proof the terminator is
+   load-bearing on its own: the child escaped its own `}` and took the parent's
+   `element`.
+
+3. Elision removed (nested `{…}`/`[…]` still counted for depth, but their bytes kept
+   in the returned text), terminator and backstop intact → **exit 101**,
+   **1 failed**:
+
+       ---- react_data_router_object_survives_angle_brackets_and_stops_at_sibling ----
+       assertion `left == right` failed: a `>` inside a quoted path or a braced expression must not end the object, and an element-less object must not borrow from its next sibling
+         left: [("/plain", 4)]
+        right: [("/a>b", 2), ("/plain", 4)]
+
+   — proof elision, not merely depth tracking, is what keeps a nested group's contents
+   out of the owning object's text.
+
+Restored after each mutant by copying back the green file; restored SHA-256 of
+`crates/codegraph-resolve/src/frameworks/react.rs`:
+`647e4a1e5504c479a937bdfe5ca1a05b402076ffac8528260af38885780fadbd`.
+Re-run with the fix restored → exit 0, 37 passed.
+
+### Golden row delta
+
+None. `git diff --stat 956cf32..HEAD -- reference/golden/` → EMPTY (956cf32 is the
+pre-task HEAD). No golden fixture contains a `<Route` or `createBrowserRouter`
+construct (`grep -rln 'createBrowserRouter\|createHashRouter\|createMemoryRouter\|createRoutesFromElements' reference/golden/ crates/codegraph-bench/fixtures/`
+→ exit 1, no matches), so the changed branch is unreachable for them.
+`cargo test --locked -p codegraph-bench --test equivalence` → exit 0,
+**28 passed, 0 failed**. `git status --short reference/golden/` → empty, so this run
+left no `colby.db-{wal,shm}` behind to clean.
+
+### Documentation accuracy
+
+- `V1_5_COMMIT_MANIFEST.md` #1348 row now reads
+  `Batch D1 bounded React <Route> opening-tag scan + Batch F3 bounded data-router route-object walk`
+  — the issue stays `PORT` because it is now genuinely a full behavioral landing, and
+  the row names both halves.
+- The Batch D1 section's "Exactly the single correct edge the issue asks for" is now
+  scoped to the `<Route>` JSX form and carries an inline scope-correction note stating
+  that D1 alone did not close #1348.
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, run before every Cargo batch;
+  every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-resolve --test frameworks` → exit 101 pre-fix
+  (Red, 5 failed), exit 0 post-fix, **37 passed** (31 before this task + 5 new + the
+  bounded-walk guard).
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 28/28.
+- Mutants 1/2/3 → exit 101 each, reddening 5 / 1 / 1 tests respectively, with mutants
+  2 and 3 each reddening a different single test.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, this prose, then `make fmt`); result recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path must
+be inside request cwd`); locked Cargo clippy/test is the honest fallback and no
+LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed. No
+native Windows/MSVC runtime validation is claimed — everything above ran on Linux.
+
+## Batch F2 — SQLite sidecar detection is byte-lossless, so a non-UTF-8 project path can no longer hide a committed WAL (2026-07-28)
+
+Fixes the highest-severity finding of the F1–F4 final review wave. This is silent
+data staleness, not a crash: on Unix a project path may carry arbitrary non-UTF-8
+bytes, and the sidecar-detection gates rendered that path through
+`Path::display()` — a LOSSY conversion. Every invalid byte became U+FFFD, so the
+constructed `-wal` / `-shm` name pointed at a file that does not exist while the
+REAL `codegraph.db-wal` sat undetected beside the database. The strict `Current`
+read gate therefore saw a "sidecar-free" namespace, admitted it, deserialized
+only the main-database bytes, and served an index missing every row that lived
+only in the log. That is exactly the stale-read risk commit `8c66848` reverted as
+unsafe, re-opened through a path-encoding hole.
+
+### The defect, at exact line numbers
+
+`crates/codegraph-store/src/connection.rs`, pre-change:
+
+```rust
+// 1010  fn first_existing_database_artifact(paths: &IndexPaths) -> Result<Option<PathBuf>> {
+// 1013      artifacts.push(PathBuf::from(format!("{}-wal", db.display())));
+// 1014      artifacts.push(PathBuf::from(format!("{}-shm", db.display())));
+
+// 1074  fn first_existing_database_sidecar(paths: &IndexPaths) -> Result<Option<PathBuf>> {
+// 1077          PathBuf::from(format!("{}-wal", db.display())),
+// 1078          PathBuf::from(format!("{}-shm", db.display())),
+```
+
+Traced consequences, all confirmed by reading the file:
+
+- `first_existing_database_sidecar` (1074) returns `Ok(None)` — "no sidecar" —
+  because it stat's the lossy lookalike.
+- The strict gate at `corroborate_current_database_options` (861) therefore never
+  raises `StoreError::CurrentWithDatabaseSidecar` and admits the namespace.
+- `open_read_only_without_sidecars` (880-912) then deserializes ONLY
+  `std::fs::read(db_path)`, so WAL-only rows are invisible. `Current`, stale, no
+  error.
+- `first_existing_database_artifact` (1010) feeds
+  `reject_missing_database_artifacts` (1087), so the `Missing`-state guard was
+  equally blind: an unexplained `-wal` beside a stateless namespace on a
+  non-UTF-8 path was accepted as a fresh writable namespace.
+
+The correct idiom was already present in this very crate: `sqlite_sidecar_path`
+(`crates/codegraph-store/src/uninit.rs:233`) builds sidecar names with
+`OsString::push`, and `connection.rs` itself already had the lossless
+`database_sidecar_path` (1057) — used by `remove_checkpointed_sidecars` (1032-1050)
+but NOT by either detection function. The removal path was lossless while the
+DETECTION path was lossy; that asymmetry is the whole bug.
+
+### The fix — one helper, every site
+
+`database_sidecar_path` is now the single source of every sidecar name in
+`connection.rs`. Three call sites changed; the helper's body is unchanged:
+
+- `first_existing_database_artifact` → `database_sidecar_path(&db, "-wal"/"-shm")`.
+- `first_existing_database_sidecar` → `database_sidecar_path(&db, "-wal"/"-shm")`.
+- the unit-test cleanup loop in `reopening_existing_db_keeps_schema_version`
+  (previously `format!("{}{ext}", db_path.display())`) → the same helper, so no
+  `Path::display()` path construction remains anywhere in the file.
+
+The helper's doc comment now states the invariant and the exact failure mode, so a
+future edit cannot reintroduce a lossy sibling without contradicting it.
+
+Nothing else moved. `Store::open_for_read` still defaults to
+`allow_live_sidecar = false`; no sidecar-tolerant read path exists under any name;
+the `Current` corroboration order (tombstone → database presence → sidecar
+freedom → main-file stamp) is byte-identical; recovery still refuses to delete a
+non-empty `-wal` (`StoreError::WalNotFolded`), still revalidates the exclusive
+lease before each unlink, still leaves the `-journal` for SQLite to replay, and
+still keeps its bounded 500ms lease deadline and its "dead owner proven first"
+precondition. No PID signalling was added. Recovery is now merely ABLE to see the
+residue it was always supposed to see.
+
+### Workspace-wide audit of the bug class
+
+`grep -rn 'display()' crates/ --include='*.rs' | wc -l` → **501 hits, exit 0**.
+Filtering for hits that actually construct a filesystem path
+(`PathBuf::from` / `Path::new` / `.push(` / a `format!` bound to a path variable)
+leaves eleven. Classification of every one:
+
+| Location                                                                               | Verdict                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codegraph-store/src/connection.rs:1013,1014` (was)                                    | **BUG — PATH construction.** Fixed: `database_sidecar_path`.                                                                                                                                                                                                                                                                                                                                      |
+| `codegraph-store/src/connection.rs:1077,1078` (was)                                    | **BUG — PATH construction.** Fixed: `database_sidecar_path`.                                                                                                                                                                                                                                                                                                                                      |
+| `codegraph-store/src/connection.rs:1323` (was)                                         | **BUG (unit-test cleanup only) — PATH construction.** Fixed: same helper. Impact was a leaked temp file, not staleness, but it is the same class.                                                                                                                                                                                                                                                 |
+| `codegraph-store/src/uninit.rs:557`                                                    | **CORRECT BY DESIGN.** Inside `non_utf8_database_sidecars_are_removed_without_touching_lossy_lookalikes`; deliberately builds the lossy lookalike as the file that must SURVIVE.                                                                                                                                                                                                                  |
+| `codegraph-store/tests/store_state_gates.rs:1163,1192,1250`                            | **BENIGN — test fixtures on ASCII temp paths** (`std::env::temp_dir()` + an ASCII label), where `display()` is a lossless round-trip. Left unchanged so the pre-existing ASCII coverage keeps asserting the exact same bytes; the new non-UTF-8 tests use the lossless `sqlite_sidecar` helper that already existed at line 134.                                                                  |
+| `codegraph-store/tests/store_state_gates.rs:1337` (new)                                | **INTENTIONAL.** The new `lossy_sidecar` helper — it exists precisely to name the lookalike that must not be touched.                                                                                                                                                                                                                                                                             |
+| `codegraph-cli/tests/batch_m_finalizer.rs:135`                                         | **BENIGN — test fixture on an ASCII temp path.** Same reasoning.                                                                                                                                                                                                                                                                                                                                  |
+| `codegraph-watch/src/watcher.rs:502`                                                   | **FINE — message only** (`format!("watch {} failed: {err}", …)`, a human-readable reason string).                                                                                                                                                                                                                                                                                                 |
+| `codegraph-cli/src/main.rs:768,6112,6254` and `codegraph-cli/tests/completions.rs:104` | **FINE — shell-snippet TEXT, not a path used by this process.** `format!(". \"{}\"", script.display())` is a line PRINTED for the user to paste into their rc file. It is not opened, stat'd, or unlinked. A non-UTF-8 completion-script path would render imperfectly in that printed hint; no filesystem decision depends on it, so it is a display-quality nit and out of this commit's scope. |
+
+The remaining ~490 `display()` uses are all inside `panic!` / `assert!` /
+`expect` / `println!` / `tracing::` / `with_context` / `#[error]` message strings —
+formatting for humans, never a path this process then acts on. Two related lossy
+conversions were also checked and are NOT path construction that can go wrong the
+same way: `codegraph-core/src/index_paths.rs:179` (`to_string_lossy` on a
+configured-root file NAME, which is then hashed into a deterministic sibling
+directory name — a lossy rendering there produces a stable, still-unique name and
+is pre-existing published behavior, out of scope for this blocker), and
+`codegraph-cli/src/installer/{targets/kiro.rs:53,targets/qoder.rs:142,mod.rs:491}`
+(agent-config JSON values, i.e. text emitted for another program's config file).
+
+### Red — measured, before the fix
+
+`cargo test --locked -p codegraph-store --test store_state_gates` →
+**exit 101, 22 passed / 4 failed**. The four new tests, verbatim:
+
+    ---- non_utf8_current_with_committed_wal_fails_closed stdout ----
+    panicked at crates/codegraph-store/tests/store_state_gates.rs:1383:14:
+    non-UTF-8 Current with committed WAL must fail closed: Store { conn: Connection { path: Some("") }, …
+      path: "/tmp/…/proj-\x80\xFF/.codegraph-v2/codegraph.db", access: StateRead, … }
+
+    ---- non_utf8_dead_owner_wal_is_folded_and_then_readable stdout ----
+    panicked at crates/codegraph-store/tests/store_state_gates.rs:1423:5:
+    a dead owner's committed WAL must be DETECTED on a non-UTF-8 path
+
+    ---- non_utf8_recovery_never_touches_the_lossy_lookalike_sidecars stdout ----
+    panicked at crates/codegraph-store/tests/store_state_gates.rs:1502:10:
+    strict gate admits the recovered non-UTF-8 namespace: CurrentWithDatabaseSidecar { path: "/tmp/…/proj-��/.codegraph-v2/codegraph.db-wal" }
+
+    ---- missing_state_with_non_utf8_database_sidecar_fails_closed stdout ----
+    panicked at crates/codegraph-store/tests/store_state_gates.rs:1532:14:
+    Missing plus a DB sidecar is not a fresh writable namespace: FullRebuildRequired(StoreWriteAuthorization { status: Missing, purpose: FullRebuild, … })
+
+The first failure IS the blocker, stated as an assertion: `Store::open_for_read`
+RETURNED A READABLE `Store` over a namespace holding a committed, un-checkpointed
+write-ahead log. The third failure's message is the smoking gun in reverse — the
+error path names the U+FFFD-rendered `proj-��/…/codegraph.db-wal`, i.e. the gate
+was reporting a file that does not exist while the real one went unseen.
+
+### Green
+
+Same command after the fix → **exit 0, 26 passed, 0 failed** (22 pre-existing + 4
+new).
+
+### Tests added — `crates/codegraph-store/tests/store_state_gates.rs`
+
+All four are `#[cfg(unix)]`. The in-code comment states why: a Unix path is an
+arbitrary byte string, whereas Windows paths are UTF-16 and the byte-oriented
+constructors these fixtures need (`std::os::unix::ffi::OsStringExt::from_vec`) do
+not exist there. The non-UTF-8 project directory is built as
+`"<label>-" ++ [0x80, 0xFF]`, and every test asserts
+`native_path != lossy_path` FIRST, so a fixture that silently stopped being
+non-UTF-8 fails loudly instead of passing vacuously.
+
+1. `non_utf8_current_with_committed_wal_fails_closed` — the blocker's direct
+   inverse. Plants a REAL committed WAL by re-invoking the existing
+   `run_crashed_current_writer` child (which commits with `wal_autocheckpoint=0`
+   and then `exit(91)` without running destructors), asserts the log is non-empty
+   and that the probe row is absent from the main file, then asserts BOTH
+   `open_for_read` and `open_for_status` refuse with
+   `CurrentWithDatabaseSidecar { path }` where `path` is the NATIVE `-wal`, and
+   that the tree is byte-unchanged.
+2. `non_utf8_dead_owner_wal_is_folded_and_then_readable` — the recovery half.
+   `recover_stale_current_sidecars` must return `Ok(true)` (i.e. must SEE the
+   residue), both sidecars must be gone, the WAL-only row must now be in the main
+   file, and the strict gate must then admit the namespace and return
+   `wal_only_probe = "committed"`. It also asserts the permanent lock, the
+   published state slot, tombstone absence and `Current` status all survive.
+3. `non_utf8_recovery_never_touches_the_lossy_lookalike_sidecars` — the shape the
+   fix must NOT break. Plants real residue AND writes decoy files at the LOSSY
+   `-wal` / `-shm` names, then asserts recovery removes the native WAL while both
+   decoys keep their exact bytes. This is the test that would catch a "fix" that
+   merely swapped which wrong file it deletes.
+4. `missing_state_with_non_utf8_database_sidecar_fails_closed` — the second gate,
+   which the audit found shares the same construction. A `-wal`/`-shm` beside a
+   stateless namespace must yield `MissingStateWithDatabase { path }` (native
+   path) from write, read AND status opens, non-mutating.
+
+No existing test was weakened, skipped, `#[ignore]`d or deleted, and no sleep was
+added; the fixtures are child-process + polling based exactly as before.
+
+### Negative control, EXECUTED (two mutants, each reddening a DIFFERENT test set)
+
+Green SHA-256 of `crates/codegraph-store/src/connection.rs`:
+`f7c0884560e033d6858b7622ceb124efac1a8808f99b8b57eb2d1ad4230568b4`.
+
+1. `first_existing_database_sidecar` reverted to `display()` ONLY (the artifact
+   function left lossless) → **exit 101, 23 passed / 3 failed**:
+   `non_utf8_current_with_committed_wal_fails_closed`,
+   `non_utf8_dead_owner_wal_is_folded_and_then_readable`,
+   `non_utf8_recovery_never_touches_the_lossy_lookalike_sidecars`.
+   `missing_state_with_non_utf8_database_sidecar_fails_closed` stayed GREEN —
+   proof the two gates are covered independently.
+
+2. `first_existing_database_artifact` reverted to `display()` ONLY (the sidecar
+   function left lossless) → **exit 101, 25 passed / 1 failed**, the complement:
+
+       ---- missing_state_with_non_utf8_database_sidecar_fails_closed stdout ----
+       panicked at crates/codegraph-store/tests/store_state_gates.rs:1529:14:
+       Missing plus a DB sidecar is not a fresh writable namespace: FullRebuildRequired(StoreWriteAuthorization { status: Missing, purpose: FullRebuild, lease: IndexLease { … db_parent: "/tmp/…/proj-\x80\xFF/.codegraph-v2" … } })
+
+   — and the three `non_utf8_*` tests stayed GREEN. A partial regression of either
+   detection site therefore cannot hide behind the other.
+
+Restored after each mutant by copying back the green file; restored SHA-256 of
+`crates/codegraph-store/src/connection.rs` re-verified as
+`f7c0884560e033d6858b7622ceb124efac1a8808f99b8b57eb2d1ad4230568b4`.
+
+### Golden row delta
+
+None. This is a filesystem-path-construction change in the store's gate layer;
+extraction, resolution and serialization are untouched.
+`git diff --stat 956cf32..HEAD -- reference/golden/` → EMPTY (956cf32 is the
+pre-task HEAD). `cargo test --locked -p codegraph-bench --test equivalence` →
+exit 0, **28 passed, 0 failed**. Any untracked
+`reference/golden/*/colby.db-{wal,shm}` the oracle leaves behind was removed
+before staging (`git status --short reference/golden/` → empty).
+
+### Verification (actual exit statuses)
+
+- `bash scripts/check-workspace-versions.sh` → exit 0, run before every Cargo
+  batch; every Cargo command used `--locked`.
+- `cargo test --locked -p codegraph-store --test store_state_gates` → exit 101
+  pre-fix (Red, 4 failed), exit 0 post-fix, **26 passed**.
+- `cargo test --locked -p codegraph-store` (all targets) → recorded below.
+- `cargo test --locked -p codegraph-bench --test equivalence` → exit 0, 28/28.
+- Mutants 1/2 → exit 101 each, reddening 3 and 1 tests respectively — disjoint sets.
+- `make ci CARGO='cargo --locked'` → final gate, run after the last byte of this
+  commit (code, tests, this prose, then `make fmt`); result recorded below.
+- `sha256sum Cargo.lock` →
+  `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`, unchanged.
+
+`lsp_diagnostics` was attempted and again refused this worktree (`LSP file path must
+be inside request cwd`); locked Cargo clippy/test is the honest fallback and no
+LSP-clean result is claimed. No dependency, version or `Cargo.lock` byte changed. No
+native Windows/MSVC runtime validation is claimed — every command above ran on
+Linux, and the Windows arm of `database_sidecar_path` is exercised only by
+inspection (`OsString::push` on a `PathBuf`'s `OsStr`, which is lossless on both
+platforms by construction).

From 1a8c13dc86ea3007f6357c884e067f5af027177f Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 00:14:25 +0800
Subject: [PATCH 63/91] docs: point the index, config and rendezvous paths at
 .codegraph-v2

The index moved to an isolated `.codegraph-v2` root that new binaries never
open, migrate, or write, but the shipped docs still told users to use
`.codegraph`. Following them produced a silent no-op (a v0.40.4 index and
config are ignored) and the golden regeneration recipe copied from a path
that no longer exists.

Correct every stale site against the code: `IndexPaths` derives the DB,
`config.toml`, `codegraph.json` AND the daemon pid/socket/log from
`current_root`, so the rendezvous moved with the index. The watcher ignore
set legitimately covers both spellings (`policy.rs`), and the upgrade notes
name the old root deliberately.

Also correct three factual errors: `sync` is a hash-gated incremental path,
not a full rebuild; extension config is read from exactly one file with no
directory-tree walk; and the release ships six platform binaries, adding
`x86_64-pc-windows-msvc` and `aarch64-pc-windows-msvc`.

Add an "Upgrading from v0.40.4" section to both READMEs: the old index is
neither migrated nor read, a fresh `init` is required, and old config does
not carry over.

Document two reproducibility limits found by running the golden recipe end
to end: `colby.db` is not byte-reproducible (SQLite header counter) and
`schema.sql` records statement order, which shifts with the creating binary.

Docs only. No `.rs`, `Cargo.toml` or `Cargo.lock` change; `reference/golden/`
untouched; the `guardrail.sh` edit is one comment line.
---
 AGENTS.md                                 |  12 +-
 README.md                                 |  39 ++++-
 docs/architecture.md                      |  26 +--
 docs/cli.md                               |  33 ++--
 docs/data-model.md                        |   4 +-
 docs/equivalence.md                       |  40 +++--
 docs/languages.md                         |   6 +-
 docs/mcp.md                               |  10 +-
 docs/readme/README.zh-CN.md               |  32 +++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 194 ++++++++++++++++++++++
 editors/zed/README.md                     |   2 +-
 scripts/guardrail.sh                      |   2 +-
 skills/codegraph/SKILL.md                 |  15 +-
 13 files changed, 341 insertions(+), 74 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e7f0510..2ba5541 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,9 +81,10 @@ Full Godot static-analysis scope, static-vs-runtime boundary, and honesty signal
 
 ## HTTP MCP server: background mode + addr-keyed registry
 
-`serve --mcp` (stdio) uses the PER-PROJECT daemon (`.codegraph/daemon.pid` + socket). `serve --http`
+`serve --mcp` (stdio) uses the PER-PROJECT daemon (`.codegraph-v2/daemon.pid` + socket; the whole
+rendezvous is derived from `IndexPaths::current_root`). `serve --http`
 (streamable-HTTP) is different: HTTP servers are keyed by BIND ADDR — a global server (no `--path`)
-spans many projects — so they use a GLOBAL, addr-keyed registry, NOT `.codegraph/`. The registry
+spans many projects — so they use a GLOBAL, addr-keyed registry, NOT the per-project root. The registry
 lives in `codegraph-daemon/src/http_registry.rs`: one `<addr-sanitized>.json` file per running server
 (`HttpServerInfo { pid, addr, mode, project, started_at, version, log_file }`) under
 `$XDG_STATE_HOME/codegraph/http` (else `~/.local/state/codegraph/http`; `%LOCALAPPDATA%\codegraph\http`
@@ -158,9 +159,10 @@ make coverage    # workspace coverage summary (informational; `make coverage-htm
   `Security Audit` (cargo-audit) + `CI Success` gate, on push/PR to `main`.
 - **Release** (`.github/workflows/release-please.yml`): release-please opens a
   release PR; merging it cuts a `v<version>` tag and triggers the pipeline —
-  4-platform binaries (linux musl x86_64/aarch64 via cargo-zigbuild, macOS
-  x86_64/aarch64), git-cliff release notes, and a GitHub Release with the
-  binaries attached. The project is distributed via GitHub Releases +
+  6-platform binaries (linux musl x86_64/aarch64 via cargo-zigbuild, macOS
+  x86_64/aarch64, and Windows MSVC `x86_64-pc-windows-msvc` on `windows-latest`
+  plus `aarch64-pc-windows-msvc` on `windows-11-arm`), git-cliff release notes,
+  and a GitHub Release with the binaries attached. The project is distributed via GitHub Releases +
   `cargo install --git`; it is NOT published to crates.io. Version bumps are
   owned by release-please via `.release-please-manifest.json` — never bump by
   hand.
diff --git a/README.md b/README.md
index edf9205..1dfee78 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ No AI/LLM anywhere inside the binary — output is byte-stable and deterministic
 ## Table of Contents
 
 - [Quickstart](#quickstart)
+- [Upgrading from v0.40.4](#upgrading-from-v0404)
 - [Installation](#installation)
   - [One-liner install (scripts)](#one-liner-install-scripts)
   - [Prebuilt binaries](#prebuilt-binaries)
@@ -56,13 +57,37 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 **Index a project and query it:**
 
 ```bash
-codegraph init  /path/to/project                 # create .codegraph/ and run the first index
+codegraph init  /path/to/project                 # create .codegraph-v2/ and run the first index
 codegraph query "<symbol>" -p /path/to/project   # full-text search
 codegraph serve --mcp --path /path/to/project    # MCP server (--path optional, defaults to cwd)
 ```
 
 ---
 
+## Upgrading from v0.40.4
+
+The per-project index moved out of `<project>/.codegraph/` into an isolated
+`<project>/.codegraph-v2/`. A `v0.40.4` index is **not migrated and not read** —
+this binary never opens, migrates, or writes the old root, so an existing
+`.codegraph/` is simply ignored. Two consequences:
+
+- **Run `codegraph init` again in each project.** Until you do, the project counts
+  as not indexed: `serve --mcp` falls back to direct mode with nothing to serve,
+  and the query commands report `CodeGraph not initialized`.
+- **Old configuration does not carry over.** `.codegraph/config.toml` and
+  `.codegraph/codegraph.json` are ignored. Copy them to
+  `.codegraph-v2/config.toml` and `.codegraph-v2/codegraph.json` if you still
+  want them.
+
+The daemon rendezvous (`daemon.pid`, `daemon.sock`, `daemon.log`) moved with the
+index, so it now also lives under `.codegraph-v2/`.
+
+`codegraph status` reports both roots: `indexPath` is the current one, and
+`legacyIndexPaths` lists any old root still on disk. The old directory is left
+untouched — delete it by hand once you no longer want it.
+
+---
+
 ## Installation
 
 The CLI package is **`codegraph-rs`** — a single binary named `codegraph`. SQLite
@@ -91,7 +116,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 # Fallback — build from source (only if you have a Rust toolchain)
 cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs   # binary: `codegraph`
 
-codegraph init  /path/to/project     # create the index DB (.codegraph/)
+codegraph init  /path/to/project     # create the index DB (.codegraph-v2/)
 codegraph index /path/to/project     # parse + build the graph
 ```
 
@@ -218,7 +243,7 @@ Beyond wiring the MCP server, CodeGraph can install a `SKILL.md` directly into
 each agent's skill directory. The skill teaches your agent to use CodeGraph for
 code research and project onboarding — reach for `codegraph_explore` before
 grep/read, use `codegraph_node` instead of a plain file read on indexed source,
-and run `codegraph init` when no `.codegraph/` index is present yet.
+and run `codegraph init` when no `.codegraph-v2/` index is present yet.
 
 ```bash
 codegraph skill install --yes              # install into all detected agents (global)
@@ -384,8 +409,8 @@ LLM library _inside_ the codegraph binary itself.
 
 CodeGraph spawns a shared background daemon for each indexed project when you run
 `codegraph serve --mcp`. Multiple MCP clients (terminal tabs, agents) share that
-one daemon via a Unix socket (`.codegraph/daemon.sock`). It exits once all clients
-disconnect and the idle timeout elapses.
+one daemon via a Unix socket (`.codegraph-v2/daemon.sock`). It exits once all
+clients disconnect and the idle timeout elapses.
 
 Key operations:
 
@@ -398,8 +423,8 @@ codegraph http stop <addr>     # terminate one HTTP server by address
 
 Set `CODEGRAPH_NO_DAEMON=1` to force foreground mode (useful in CI). The daemon
 watches files with a 2 s debounce; pass `--no-watch` or set `CODEGRAPH_NO_WATCH=1`
-to disable. Custom extension mapping goes in `.codegraph/codegraph.json`; exclude
-patterns in `.codegraph/config.toml` under `[indexing] exclude`.
+to disable. Custom extension mapping goes in `.codegraph-v2/codegraph.json`;
+exclude patterns in `.codegraph-v2/config.toml` under `[indexing] exclude`.
 
 Full env-var table, HTTP server details, filesystem fallback behavior, and the
 Claude prompt-hook: [`docs/mcp.md`](docs/mcp.md) and
diff --git a/docs/architecture.md b/docs/architecture.md
index 37e8f63..2f68099 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -86,7 +86,7 @@ graph LR
     RS -->|已解析边| ST
     ST --> GR[graph<br/>遍历 + FTS 打分]
     GR --> MCP[mcp 8 工具]
-    GR --> CLI[cli 13 子命令]
+    GR --> CLI[cli 26 子命令]
     ST --> MCP
     ST --> CLI
     DA[daemon] --> MCP
@@ -221,19 +221,22 @@ FTS5 候选（`search_nodes_fts_filtered`）→（空且文本≥2）LIKE 阶梯
 
 ## 7. CLI 表面 / CLI Surface（`codegraph-cli`）
 
-`codegraph` 单一二进制，clap 13 个子命令（见
-[README §CLI 子命令](../README.md#cli-子命令--cli-subcommands共-13-个)）。CLI 负责
-rust-base-convention bootstrap：解析命令取项目根 → `init_config` fail-fast（人类可读
-错误）→ `init_logger`（在 `main` 中持有 guard；CLI 进程关闭 stdout/file 输出，
-保证 JSON 输出干净）。
+`codegraph` 单一二进制，clap 26 个子命令（见
+[README §CLI 子命令](../README.md#cli-subcommands)）。CLI bootstrap：
+`Config::load_env_or_default` fail-fast（人类可读错误，只配置 logger，不代表任何项目）
+→ `init_logger`（在 `main` 中持有 guard；日志只走 stderr，`serve --mcp` 独占 stdout
+以免污染 JSON-RPC 流）。每个针对项目的操作再各自从该项目解析出的索引根加载其
+不可变配置。
 
 - 索引编排只用各 crate 公共 API：`extract::engine::{scan_project, extract_file}` →
   `store::Store` upsert/insert → `resolve::ReferenceResolver::resolve_and_persist`。
-  全量索引写 `.codegraph/codegraph.db`、文件记录、结构边、未解析引用、已解析边及
+  全量索引写 `.codegraph-v2/codegraph.db`、文件记录、结构边、未解析引用、已解析边及
   索引元数据。
 - `serve --mcp` 调用 `codegraph_mcp::McpServer` 公共入口（stdin/stdout）。
-- **`sync` 当前复用安全的全量索引路径**（`main.rs` 注释标明），即“增量”实为全量
-  重建——这是 daemon/watch 接线前的有意取舍，已在基准报告中如实记录。
+- **`sync` 为真正的单文件增量路径**：`codegraph_watch::sync_project_once_with_progress`
+  自行扫描候选文件，按内容哈希跳过未变更文件，对变更文件逐个删除并重新插入，
+  删除已消失的文件，最后整体重新解析，因此结果等价于 `index --force`。
+  输出报告 reindexed / skipped / removed 三个计数。
 
 子命令的输出/JSON 形状遵循固定的输出/JSON 契约（源码注释标注行号）。
 
@@ -275,8 +278,9 @@ serverInfo:{name:"codegraph",version}, instructions}`；`tools/list` 返回 8 
   所有客户端断开且空闲超时后自动退出（`CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS`，
   默认 5 分钟）。另有 `run_foreground`/`attach_to_daemon`/`unlock_project`/
   `daemon_pid_path`/`daemon_socket_path`。
-- 会合文件位于 `<project>/.codegraph/`：`daemon.pid` 与 `daemon.sock`（socket 路径
-  过长时回落到哈希后的 tmpdir socket）。
+- 会合文件位于当前索引根 `<project>/.codegraph-v2/`：`daemon.pid`、`daemon.sock`
+  与 `daemon.log`，全部经 `IndexPaths` 派生（socket 路径过长时回落到哈希后的
+  tmpdir socket，其名称带 v2 判别前缀）。
 - 加锁逻辑（`daemon.ts:393-412`）：完整 JSON 锁信息先写私有临时文件，再原子
   hard-link 就位，避免空/半写 pidfile 竞争。
 - 陈旧解锁镜像 `daemon.ts:453-481`：删除前重读、已知 pid 时比对、**绝不**清除存活
diff --git a/docs/cli.md b/docs/cli.md
index f5cfe1e..7de4bdb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -23,10 +23,10 @@
 | `skill update`    | Refresh the installed skill when unchanged by the user                                    | `-t/--target`, `--global`, `--local`, `--force`                                                                                            |
 | `skill uninstall` | Remove the skill from agent skill directories                                             | `-t/--target`, `--global`, `--local`, `-y/--yes`                                                                                           |
 | `skill status`    | Report install state per agent (up to date / locally modified / outdated / not installed) | `-t/--target`, `--global`, `--local`                                                                                                       |
-| `init`            | Initialize `.codegraph/` and run the first full index                                     | `[path]`, `-t/--target` (also write project-level MCP config; default `none`)                                                              |
-| `uninit`          | Delete the project's `.codegraph/` index                                                  | `[path]`, `-f/--force`                                                                                                                     |
+| `init`            | Initialize `.codegraph-v2/` and run the first full index                                  | `[path]`, `-t/--target` (also write project-level MCP config; default `none`)                                                              |
+| `uninit`          | Delete the project's `.codegraph-v2/` index                                               | `[path]`, `-f/--force`                                                                                                                     |
 | `index`           | (Re-)index in full                                                                        | `[path]`, `-f/--force`, `-q/--quiet`, `-v/--verbose`                                                                                       |
-| `sync`            | Sync changes (currently reuses the safe full-index path)                                  | `[path]`, `-q/--quiet`                                                                                                                     |
+| `sync`            | Incremental sync: re-index only changed files, drop deleted ones, re-resolve              | `[path]`, `-q/--quiet`                                                                                                                     |
 | `status`          | Print index stats (files/nodes/edges/DB size/journal)                                     | `[path]`, `-j/--json`                                                                                                                      |
 | `query`           | FTS5 + multi-signal scored search                                                         | `<search>`, `-p`, `-l/--limit`, `-k/--kind`, `-j/--json`                                                                                   |
 | `files`           | List indexed files (tree/flat/grouped)                                                    | `-p`, `--filter <DIR>`, `--language <LANG>`, `--pattern`, `--format`, `--max-depth`, `-j`                                                  |
@@ -149,7 +149,7 @@ codegraph init /path/to/proj -t auto  # index that project + wire detected edito
 directory. The skill teaches the agent to use CodeGraph for code research and
 project onboarding: reach for `codegraph_explore` before grep/read, use
 `codegraph_node` instead of a plain file read on indexed source, and run
-`codegraph init` when no `.codegraph/` index is present.
+`codegraph init` when no `.codegraph-v2/` index is present.
 
 Four actions:
 
@@ -547,7 +547,7 @@ codegraph completions elvish > ~/.config/codegraph/completion.elv
 The launcher selects a mode in this exact order:
 
 1. `CODEGRAPH_NO_DAEMON=1` is set → **Direct** (foreground, no daemon ever spawned)
-2. No `.codegraph/` directory in the project → **Direct** (nothing to share yet)
+2. No `.codegraph-v2/` directory in the project → **Direct** (nothing to share yet)
 3. Otherwise → **SpawnOrProxy**: spawn a new shared detached daemon, or proxy to one already running
 
 > `CODEGRAPH_DAEMON_INTERNAL=1` is **internal-only** — it is set automatically on
@@ -557,15 +557,15 @@ The launcher selects a mode in this exact order:
 
 When the daemon starts, it detaches from the parent process group (Unix:
 `process_group(0)`; Windows: `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`).
-Its stdout and stderr are appended to `.codegraph/daemon.log`. The Unix socket is
-at `.codegraph/daemon.sock`; the pid/lock file lives alongside it.
+Its stdout and stderr are appended to `.codegraph-v2/daemon.log`. The Unix socket
+is at `.codegraph-v2/daemon.sock`; the pid/lock file lives alongside it.
 
 On filesystems that reject binding an `AF_UNIX` socket inside the project
 directory (ExFAT/FAT, some network mounts, WSL DrvFs), the daemon falls back
 through a deterministic candidate chain — first the project-dir
-`.codegraph/daemon.sock`, then a hashed socket under the system temp dir — and
+`.codegraph-v2/daemon.sock`, then a hashed socket under the system temp dir — and
 records the socket it actually bound in the lock file. The pid/lock file always
-stays at `.codegraph/daemon.pid`, and clients read the recorded socket from the
+stays at `.codegraph-v2/daemon.pid`, and clients read the recorded socket from the
 lock, so they attach to whichever candidate the daemon chose.
 
 If the daemon crashes and leaves a stale lock:
@@ -589,8 +589,8 @@ those paths; the reason is surfaced in the log.
 
 The watcher registers per-directory watches only on non-ignored directories,
 pruning `node_modules`, `.venv`, `__pycache__`, `target`, `dist`, `.godot`,
-`.cache`, `.git`, `.codegraph`, and everything else in the default ignore set,
-plus any paths matched by the root `.gitignore`. This pruning applies at any
+`.cache`, `.git`, `.codegraph`, `.codegraph-v2`, and everything else in the
+default ignore set, plus any paths matched by the root `.gitignore`. This pruning applies at any
 nesting depth, so an `node_modules` buried several levels deep is never walked.
 This keeps the total watch count well inside the OS inotify limit on large trees
 and makes daemon startup fast. A newly-created non-ignored directory is picked up
@@ -632,9 +632,9 @@ Three escape hatches:
 
 Values outside the clamp range are silently clamped to the nearest bound.
 
-### Custom extension mapping (`.codegraph/codegraph.json`)
+### Custom extension mapping (`.codegraph-v2/codegraph.json`)
 
-Place a `codegraph.json` inside the `.codegraph/` directory of any project to
+Place a `codegraph.json` inside the `.codegraph-v2/` directory of any project to
 teach CodeGraph how to treat files with non-standard extensions:
 
 ```jsonc
@@ -652,9 +652,10 @@ Rules:
   is lowercased (so `.X` and `.x` are the same key).
 - Language names must match the internal `Language` enum (serde names). Unknown
   language names are **silently skipped**.
-- Config resolution walks up the directory tree from each source file; the nearest
-  `.codegraph/codegraph.json` wins. Results are mtime-cached — absent files are
-  cached too, so no repeated I/O on every lookup.
+- Exactly one file is read: the resolved project's own
+  `.codegraph-v2/codegraph.json`. There is no directory-tree walk and no
+  cross-project inheritance, so one project can never adopt another's overrides.
+  A legacy `.codegraph/codegraph.json` is ignored.
 - A malformed JSON file is ignored and the error is logged; it does not abort
   indexing.
 
diff --git a/docs/data-model.md b/docs/data-model.md
index d035cd5..ecba4d5 100644
--- a/docs/data-model.md
+++ b/docs/data-model.md
@@ -13,14 +13,14 @@ Golden artifacts captured from that run, committed under `reference/golden/`:
 - Schema dump: `reference/golden/colby.schema.sql`
 - Raw database: `reference/golden/mini/colby.db`
 - Nodes table JSON: `reference/golden/mini/colby.nodes.json`
-- Database location: `/tmp/cg-fixture-mini/.codegraph/codegraph.db`
+- Database location: `/tmp/cg-fixture-mini/.codegraph-v2/codegraph.db`
 
 ## Real `.schema` Dump Contract
 
 `reference/golden/colby.schema.sql` was generated with:
 
 ```bash
-sqlite3 /tmp/cg-fixture-mini/.codegraph/codegraph.db .schema > reference/golden/colby.schema.sql
+sqlite3 /tmp/cg-fixture-mini/.codegraph-v2/codegraph.db .schema > reference/golden/colby.schema.sql
 ```
 
 The dump is post-initialization/post-migration truth. It includes the six application tables (`schema_versions`, `nodes`, `edges`, `files`, `unresolved_refs`, `project_metadata`), `nodes_fts` plus its FTS5 shadow tables, the three FTS triggers, the post-migration indexes, `sqlite_sequence`, and `sqlite_stat1` created by the maintenance/ANALYZE path.
diff --git a/docs/equivalence.md b/docs/equivalence.md
index ee17963..cb0e671 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -170,7 +170,7 @@ The minimal source corpus lives at `crates/codegraph-bench/fixtures/godot/`
 Regenerate the committed database + canonical JSON reproducibly from the corpus:
 
 ```bash
-# 1. Copy the corpus to a clean directory (keeps the workspace .codegraph/ out of it).
+# 1. Copy the corpus to a clean directory (keeps the workspace index out of it).
 rm -rf /tmp/cg-fixture-godot
 cp -r crates/codegraph-bench/fixtures/godot /tmp/cg-fixture-godot
 
@@ -180,7 +180,7 @@ CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 \
   ./target/release/codegraph init /tmp/cg-fixture-godot
 
 # 3. Commit the produced database as the fixture's colby.db.
-cp /tmp/cg-fixture-godot/.codegraph/codegraph.db reference/golden/godot/colby.db
+cp /tmp/cg-fixture-godot/.codegraph-v2/codegraph.db reference/golden/godot/colby.db
 
 # 4. Dump the canonical golden JSON + schema from that database.
 cargo run -p codegraph-bench --bin bench -- \
@@ -193,6 +193,20 @@ index or the dump reproduces identical `nodes.json`/`edges.json`/`refs.json`/
 and `upstream_db_is_self_equivalent_to_godot_golden` tests in
 `crates/codegraph-bench/tests/equivalence.rs` enforce this.
 
+Two properties this recipe does NOT claim, for every fixture below as well:
+
+- **`colby.db` is not byte-reproducible.** SQLite's header carries a change
+  counter, so a freshly indexed database differs from the committed one in the
+  first page even when every row matches. Only the `--gen-golden` artifacts are
+  compared byte-for-byte; the `.db` is an input to that dump, not a golden.
+- **`schema.sql` records `.schema` statement ORDER, which can shift.** The order
+  reflects how the current binary creates its objects. Regenerating a fixture
+  whose committed `schema.sql` was produced by an earlier binary can therefore
+  reorder statements (e.g. `idx_edges_identity`) with no schema change. Always
+  regenerate `schema.sql` from the database you are committing — steps 3 and 4
+  do exactly that, which keeps the pair self-consistent — and review an
+  order-only diff as expected rather than as drift.
+
 The schema normalization helper is replicated inside `codegraph-bench` rather
 than extracted into `codegraph-store` to avoid changing store source during the
 parallel CRUD work. It preserves `.schema` statement order, strips optional
@@ -222,7 +236,7 @@ The minimal source corpus lives at `crates/codegraph-bench/fixtures/ruby/`
 Regenerate the committed database + canonical JSON reproducibly from the corpus:
 
 ```bash
-# 1. Copy the corpus to a clean directory (keeps the workspace .codegraph/ out of it).
+# 1. Copy the corpus to a clean directory (keeps the workspace index out of it).
 rm -rf /tmp/cg-fixture-ruby
 cp -r crates/codegraph-bench/fixtures/ruby /tmp/cg-fixture-ruby
 
@@ -232,7 +246,7 @@ CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 \
   ./target/release/codegraph init /tmp/cg-fixture-ruby
 
 # 3. Commit the produced database as the fixture's colby.db.
-cp /tmp/cg-fixture-ruby/.codegraph/codegraph.db reference/golden/ruby/colby.db
+cp /tmp/cg-fixture-ruby/.codegraph-v2/codegraph.db reference/golden/ruby/colby.db
 
 # 4. Dump the canonical golden JSON + schema from that database.
 cargo run -p codegraph-bench --bin bench -- \
@@ -339,7 +353,7 @@ C walker (not the C++ one) is the thing under test.
 Regenerate the committed database + canonical JSON reproducibly from the corpus:
 
 ```bash
-# 1. Copy the corpus to a clean directory (keeps the workspace .codegraph/ out of it).
+# 1. Copy the corpus to a clean directory (keeps the workspace index out of it).
 rm -rf /tmp/cg-fixture-cpp
 cp -r crates/codegraph-bench/fixtures/cpp /tmp/cg-fixture-cpp
 
@@ -349,7 +363,7 @@ CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 \
   ./target/release/codegraph init /tmp/cg-fixture-cpp
 
 # 3. Commit the produced database as the fixture's colby.db.
-cp /tmp/cg-fixture-cpp/.codegraph/codegraph.db reference/golden/cpp/colby.db
+cp /tmp/cg-fixture-cpp/.codegraph-v2/codegraph.db reference/golden/cpp/colby.db
 
 # 4. Dump the canonical golden JSON + schema from that database.
 cargo run -p codegraph-bench --bin bench -- \
@@ -414,7 +428,7 @@ substituting `metal`/`cuda`):
 rm -rf /tmp/cg-fixture-metal && cp -r crates/codegraph-bench/fixtures/metal /tmp/cg-fixture-metal
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-metal
-cp /tmp/cg-fixture-metal/.codegraph/codegraph.db reference/golden/metal/colby.db
+cp /tmp/cg-fixture-metal/.codegraph-v2/codegraph.db reference/golden/metal/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/metal/colby.db reference/golden/metal
 # …and the same for cuda.
 ```
@@ -455,7 +469,7 @@ Regenerate reproducibly (identical recipe to the C++ fixture, substituting
 rm -rf /tmp/cg-fixture-arkts && cp -r crates/codegraph-bench/fixtures/arkts /tmp/cg-fixture-arkts
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-arkts
-cp /tmp/cg-fixture-arkts/.codegraph/codegraph.db reference/golden/arkts/colby.db
+cp /tmp/cg-fixture-arkts/.codegraph-v2/codegraph.db reference/golden/arkts/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/arkts/colby.db reference/golden/arkts
 ```
 
@@ -505,7 +519,7 @@ Regenerate reproducibly (identical recipe to the ArkTS fixture, substituting
 rm -rf /tmp/cg-fixture-solidity && cp -r crates/codegraph-bench/fixtures/solidity /tmp/cg-fixture-solidity
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-solidity
-cp /tmp/cg-fixture-solidity/.codegraph/codegraph.db reference/golden/solidity/colby.db
+cp /tmp/cg-fixture-solidity/.codegraph-v2/codegraph.db reference/golden/solidity/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/solidity/colby.db reference/golden/solidity
 ```
 
@@ -553,7 +567,7 @@ Regenerate reproducibly (identical recipe to the Solidity fixture, substituting
 rm -rf /tmp/cg-fixture-nix && cp -r crates/codegraph-bench/fixtures/nix /tmp/cg-fixture-nix
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-nix
-cp /tmp/cg-fixture-nix/.codegraph/codegraph.db reference/golden/nix/colby.db
+cp /tmp/cg-fixture-nix/.codegraph-v2/codegraph.db reference/golden/nix/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/nix/colby.db reference/golden/nix
 ```
 
@@ -606,7 +620,7 @@ Regenerate reproducibly (identical recipe to the Nix fixture, substituting
 rm -rf /tmp/cg-fixture-terraform && cp -r crates/codegraph-bench/fixtures/terraform /tmp/cg-fixture-terraform
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-terraform
-cp /tmp/cg-fixture-terraform/.codegraph/codegraph.db reference/golden/terraform/colby.db
+cp /tmp/cg-fixture-terraform/.codegraph-v2/codegraph.db reference/golden/terraform/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/terraform/colby.db reference/golden/terraform
 ```
 
@@ -665,7 +679,7 @@ Regenerate reproducibly (identical recipe to the Terraform fixture, substituting
 rm -rf /tmp/cg-fixture-erlang && cp -r crates/codegraph-bench/fixtures/erlang /tmp/cg-fixture-erlang
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-erlang
-cp /tmp/cg-fixture-erlang/.codegraph/codegraph.db reference/golden/erlang/colby.db
+cp /tmp/cg-fixture-erlang/.codegraph-v2/codegraph.db reference/golden/erlang/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/erlang/colby.db reference/golden/erlang
 ```
 
@@ -712,7 +726,7 @@ Regenerate reproducibly (identical recipe, substituting `cfml`):
 rm -rf /tmp/cg-fixture-cfml && cp -r crates/codegraph-bench/fixtures/cfml /tmp/cg-fixture-cfml
 cargo build --release -p codegraph-rs
 CODEGRAPH_NO_DAEMON=1 CODEGRAPH_NO_WATCH=1 ./target/release/codegraph init /tmp/cg-fixture-cfml
-cp /tmp/cg-fixture-cfml/.codegraph/codegraph.db reference/golden/cfml/colby.db
+cp /tmp/cg-fixture-cfml/.codegraph-v2/codegraph.db reference/golden/cfml/colby.db
 cargo run -p codegraph-bench --bin bench -- --gen-golden reference/golden/cfml/colby.db reference/golden/cfml
 ```
 
diff --git a/docs/languages.md b/docs/languages.md
index 61b17cb..f582dd5 100644
--- a/docs/languages.md
+++ b/docs/languages.md
@@ -95,7 +95,7 @@ impact analysis at the file level.
 
 ## Adding custom extension mappings
 
-Non-standard extensions can be mapped to any supported language via `.codegraph/codegraph.json`:
+Non-standard extensions can be mapped to any supported language via `.codegraph-v2/codegraph.json`:
 
 ```jsonc
 {
@@ -107,7 +107,9 @@ Non-standard extensions can be mapped to any supported language via `.codegraph/
 ```
 
 Keys are dot-stripped and lowercased before matching. Unknown language names are silently
-skipped. The nearest config up the directory tree wins.
+skipped. Exactly one file is read — the resolved project's own
+`.codegraph-v2/codegraph.json`; there is no directory-tree walk, and a legacy
+`.codegraph/codegraph.json` is ignored.
 
 ---
 
diff --git a/docs/mcp.md b/docs/mcp.md
index cdab91c..97f2d8e 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -94,13 +94,13 @@ Run `codegraph install --target=zed` to write the bare global entry, or
 ### Zed over SSH (remote development)
 
 **Symptom.** You open a remote SSH project in Zed (Zed UI on your local machine,
-code and `.codegraph/` index on a remote Linux host). All codegraph MCP tools
+code and `.codegraph-v2/` index on a remote Linux host). All codegraph MCP tools
 return empty — "No relevant code found" — even after the index built successfully.
 
 **Root cause.** Zed currently executes `context_servers` entries on the **local
 machine**, not on the remote host. This is true even when a remote SSH project is
 open: the `command: "codegraph"` runs locally, cannot reach the remote
-`.codegraph/` index, and returns nothing. Native remote MCP execution — running
+`.codegraph-v2/` index, and returns nothing. Native remote MCP execution — running
 the server on the remote host — is not yet implemented in Zed (tracked in Zed's
 GitHub issues; status as of mid-2026).
 
@@ -226,7 +226,7 @@ Two distinct error channels:
 
 ## Daemon & live watch
 
-When the project is indexed (`.codegraph/` exists), `serve --mcp` does not run
+When the project is indexed (`.codegraph-v2/` exists), `serve --mcp` does not run
 inline. Instead it spawns — or proxies to — a single shared detached daemon
 process per project. Multiple agent clients (e.g. Claude Code + Cursor open
 simultaneously) all attach to the same daemon, so the index is loaded and
@@ -275,7 +275,7 @@ The server resolves a default project by walking three sources in order:
 
 1. **`--path` flag** — explicit pin; always wins.
 2. **find-up from cwd** — ascends from the working directory to the nearest
-   `.codegraph/` directory. A cwd at or inside an indexed project resolves it
+   `.codegraph-v2/` index root. A cwd at or inside an indexed project resolves it
    here, and `projectPath` is optional.
 3. **MCP `initialize` handshake** — if find-up yields nothing, the server reads
    the `initialize` message sent by the client and adopts the workspace it
@@ -298,7 +298,7 @@ them by passing an explicit `projectPath`; for single-project setups, pinning
 > resolved via find-up and gets the full daemon and watcher.
 
 The daemon exits automatically after all clients disconnect and an idle timeout
-elapses. Logs are appended to `.codegraph/daemon.log`. A stale lock (e.g. after
+elapses. Logs are appended to `.codegraph-v2/daemon.log`. A stale lock (e.g. after
 a crash) can be cleared with `codegraph unlock`.
 
 On Unix, the detached daemon calls `setsid` to become a session leader, so when
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
index 99ee7c2..142cda7 100644
--- a/docs/readme/README.zh-CN.md
+++ b/docs/readme/README.zh-CN.md
@@ -18,6 +18,7 @@ SQLite 数据库（含 FTS5 检索索引），并通过 CLI 与 MCP stdio 服务
 ## 目录
 
 - [快速上手](#快速上手)
+- [从 v0.40.4 升级](#从-v0404-升级)
 - [安装](#安装)
 - [MCP 快速注册](#mcp-快速注册)
 - [安装 Agent 技能](#安装-agent-技能codegraph-skill)
@@ -51,13 +52,34 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 **索引项目并查询：**
 
 ```bash
-codegraph init  /path/to/project                   # 创建 .codegraph/ 并执行首次索引
+codegraph init  /path/to/project                   # 创建 .codegraph-v2/ 并执行首次索引
 codegraph query "<symbol>" -p /path/to/project     # 全文检索
 codegraph serve --mcp --path /path/to/project      # 为 AI 代理启动 MCP 服务器（--path 可选，默认 cwd）
 ```
 
 ---
 
+## 从 v0.40.4 升级
+
+按项目的索引目录已从 `<project>/.codegraph/` 迁至隔离的 `<project>/.codegraph-v2/`。
+`v0.40.4` 留下的旧索引**既不迁移也不读取**：本版本二进制永不打开、迁移或写入旧根目录，
+已存在的 `.codegraph/` 会被直接忽略。由此有两点影响：
+
+- **每个项目需重新执行 `codegraph init`。** 在此之前该项目视为未索引：
+  `serve --mcp` 回退到直连模式且无索引可服务，查询类命令报
+  `CodeGraph not initialized`。
+- **旧配置不会自动继承。** `.codegraph/config.toml` 与 `.codegraph/codegraph.json`
+  均被忽略；若仍需沿用，请手动复制为 `.codegraph-v2/config.toml` 与
+  `.codegraph-v2/codegraph.json`。
+
+daemon 会合文件（`daemon.pid`、`daemon.sock`、`daemon.log`）随索引一同迁移，
+现在也位于 `.codegraph-v2/` 之下。
+
+`codegraph status` 会同时报告两个根目录：`indexPath` 为当前索引根，
+`legacyIndexPaths` 列出磁盘上仍存在的旧根。旧目录不会被改动，确认不再需要后可手动删除。
+
+---
+
 ## 安装
 
 CLI 包名为 **`codegraph-rs`**，安装后的二进制命令名为 **`codegraph`**。SQLite
@@ -84,7 +106,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 # 回退方案 —— 从源码构建（仅当你已有 Rust 工具链时）
 cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs   # 二进制：`codegraph`
 
-codegraph init  /path/to/project     # 建立索引库（.codegraph/）
+codegraph init  /path/to/project     # 建立索引库（.codegraph-v2/）
 codegraph index /path/to/project     # 解析 + 构建图
 ```
 
@@ -200,7 +222,7 @@ codegraph install --target=auto --local          # 项目级配置
 除了写入 MCP 服务器配置，CodeGraph 还可以把一个 `SKILL.md` 直接安装到每个代理的
 技能目录中。该技能教会代理如何将 CodeGraph 用于代码研究与项目初始化：在 grep/read
 之前优先调用 `codegraph_explore`，对已索引的源码用 `codegraph_node` 代替直接读文件，
-以及在尚未建立 `.codegraph/` 索引时自动运行 `codegraph init`。
+以及在尚未建立 `.codegraph-v2/` 索引时自动运行 `codegraph init`。
 
 ```bash
 codegraph skill install --yes                         # 安装到所有已检测到的代理（全局）
@@ -356,7 +378,7 @@ python examples/llm_orchestration.py --repo . --query "how does indexing work"
 
 在已索引的项目中运行 `codegraph serve --mcp` 时，CodeGraph 会自动在后台启动一个
 **共享的、脱离终端的守护进程**。同一项目的多个 MCP 客户端通过 Unix socket
-（`.codegraph/daemon.sock`）共用该 daemon，所有客户端断开且空闲超时后自动退出。
+（`.codegraph-v2/daemon.sock`）共用该 daemon，所有客户端断开且空闲超时后自动退出。
 
 常用操作：
 
@@ -381,7 +403,7 @@ codegraph serve --http --detach  # 后台运行
 codegraph http list / stop       # 管理运行中的 HTTP 服务
 ```
 
-自定义扩展名映射写在 `.codegraph/codegraph.json`；可选的 Claude prompt hook
+自定义扩展名映射写在 `.codegraph-v2/codegraph.json`；可选的 Claude prompt hook
 通过 `codegraph install --prompt-hook` 启用。
 
 完整参考——守护进程生命周期、所有环境变量、HTTP 注册表、扩展名映射、Claude hook：
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 9b1f612..f55f5db 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -7472,3 +7472,197 @@ native Windows/MSVC runtime validation is claimed — every command above ran on
 Linux, and the Windows arm of `database_sidecar_path` is exercised only by
 inspection (`OsString::push` on a `PathBuf`'s `OsStr`, which is lossless on both
 platforms by construction).
+
+## F4 Blocker B3 — user-facing docs still pointed at the abandoned `.codegraph` root (2026-07-28)
+
+Batch M moved the per-project index to an isolated `.codegraph-v2` root that new
+binaries never open, migrate, or write. The shipped documentation was never
+updated, so a user following the README got a silent no-op (their `v0.40.4` index
+and config are ignored) and the golden regeneration recipe copied from a path that
+no longer exists. This is a documentation-only correction: no `.rs`, `Cargo.toml`,
+or `Cargo.lock` byte changed, and `scripts/guardrail.sh` changed by one COMMENT
+line with no behavior change (`bash -n` exit 0).
+
+### What the code actually says (read before writing any prose)
+
+- `index_paths.rs:46,48` — `DEFAULT_CURRENT_DIR = ".codegraph-v2"`,
+  `LEGACY_DIR = ".codegraph"`. `legacy_roots()`'s own doc comment states new
+  binaries never open, migrate, or write these.
+- EVERY per-file accessor hangs off `current_root`: `current_db`, `config_toml`,
+  `extension_config`, `permanent_lock`, `state_slots`, `tombstone`, AND
+  `daemon_pid` / `daemon_log` / `daemon_socket` (`index_paths.rs:266-331`).
+- `codegraph-daemon/src/paths.rs` — module doc: "Nothing here reconstructs a
+  `.codegraph*` path: every value comes from `IndexPaths::resolve`".
+  `rendezvous_dir` returns `current_root()`.
+- `config.rs:267-297` — `Config::load_for_paths` "never consults a legacy
+  `.codegraph/config.toml`".
+- `codegraph-extract/src/ext_config.rs:49-55` — `load_for_paths` "Reads exactly
+  `paths.extension_config()`". One file; no tree walk; no mtime cache.
+- `cmd_sync` (`main.rs:1330-1366`) → `sync_project_once_with_progress`:
+  hash-gated per-file skip, per-file delete/reinsert, full re-resolve; reports
+  `files_reindexed` / `files_skipped_unchanged` / `files_removed`.
+- `codegraph-watch/src/policy.rs:191` — the always-ignore rule skips `.git`,
+  `.codegraph`, AND any `.codegraph-*`, so BOTH spellings are correctly named in
+  the watcher-pruning prose.
+
+**The B3 brief's premise was wrong and is corrected here.** It stated `.codegraph/`
+is still the daemon rendezvous while only index and config moved. It is not — the
+rendezvous moved WITH the index. Verified empirically, not just by reading:
+
+```
+$ codegraph init /tmp/cg-fixture-godot     # exit 0; creates .codegraph-v2/ ONLY
+$ codegraph status /tmp/cg-fixture-godot --json
+  indexPath        = /tmp/cg-fixture-godot/.codegraph-v2/
+  dbPath           = …/.codegraph-v2/codegraph.db
+  daemonPidPath    = …/.codegraph-v2/daemon.pid
+  daemonSocketPath = …/.codegraph-v2/daemon.sock
+  daemonLogPath    = …/.codegraph-v2/daemon.log
+  legacyIndexPaths = []
+```
+
+### How index/config/rendezvous paths were distinguished from legitimate `.codegraph`
+
+Not by string replacement. Each site was classified against the accessor that
+produces it:
+
+1. **Live path → `.codegraph-v2/`.** Anything naming the index DB, `config.toml`,
+   `codegraph.json`, the indexed-project marker, or the daemon pid/socket/log —
+   all derived from `current_root`.
+2. **Watcher/scanner ignore set → BOTH spellings kept.** `policy.rs:191` skips
+   `.codegraph` and `.codegraph-*`, so `docs/cli.md`'s pruning list now names
+   `.codegraph` AND `.codegraph-v2`. Dropping the legacy name would have made the
+   doc contradict the code.
+3. **Deliberate legacy/historical discussion → `.codegraph/` retained.** The new
+   upgrade notes, and the "a legacy X is ignored" clauses, must name the old path
+   to be meaningful.
+
+### Stale sites found and corrected
+
+| File                          | Correction                                                                                                                                                                                                                                                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `README.md`                   | 2× `init` comments, skill blurb, `daemon.sock`, extension+config paths; NEW "Upgrading from v0.40.4" section + TOC entry                                                                                                                                                                                         |
+| `docs/readme/README.zh-CN.md` | same five sites mirrored + NEW「从 v0.40.4 升级」section + TOC entry                                                                                                                                                                                                                                             |
+| `docs/cli.md`                 | `init`/`uninit` rows; **`sync` row rewritten** (was "currently reuses the safe full-index path"); serve-mode step 2; daemon log/socket/pid; watcher list now names both spellings; extension-config heading+body; **resolution rule corrected** (was "walks up the directory tree … mtime-cached" — wrong twice) |
+| `docs/mcp.md`                 | 5 sites: Zed-SSH ×2, indexed-project marker, find-up target, `daemon.log`                                                                                                                                                                                                                                        |
+| `skills/codegraph/SKILL.md`   | front-matter trigger, DB blurb, detect-index block + fence, `init` comment, fallback list; NEW legacy-root note                                                                                                                                                                                                  |
+| `docs/equivalence.md`         | 10 `cp` paths + 3 comments; NEW reproducibility caveats (below)                                                                                                                                                                                                                                                  |
+| `docs/architecture.md`        | subcommand count 13→26; removed `init_config` (now `Config::load_env_or_default`, logger-only); DB path; **`sync` rewritten**; rendezvous → current root                                                                                                                                                         |
+| `docs/data-model.md`          | fixture DB path ×2                                                                                                                                                                                                                                                                                               |
+| `docs/languages.md`           | extension-config path + resolution rule corrected (was "nearest config up the directory tree wins")                                                                                                                                                                                                              |
+| `editors/zed/README.md`       | remote-SSH index path                                                                                                                                                                                                                                                                                            |
+| `AGENTS.md`                   | rendezvous path; release surface 4-platform → **6**, naming `x86_64-pc-windows-msvc` (`windows-latest`) and `aarch64-pc-windows-msvc` (`windows-11-arm`) — verified against `release-please.yml:191-214`                                                                                                         |
+| `scripts/guardrail.sh`        | "AND both CI jobs" → "AND the CI `test` job (the `windows` job does NOT run it)" — verified: `ci.yml` runs guardrail only at line 76 in `test`                                                                                                                                                                   |
+
+### `docs/equivalence.md` — the recipe was verified end to end, not just path-edited
+
+Ran the corrected Godot recipe with the built binary. `cp` from
+`.codegraph-v2/codegraph.db` then `--gen-golden` (exit 0) reproduced
+`nodes.json`, `edges.json`, `refs.json`, `files.json` **byte-identically** to the
+committed golden. Two things the path fix ALONE would not have caught, both now
+documented as explicit non-claims:
+
+- **`colby.db` is NOT byte-reproducible.** A freshly indexed DB differs from the
+  committed one at byte 28 (SQLite header change counter) despite identical rows.
+- **`schema.sql` records `.schema` statement ORDER, which shifted.** A fresh DB
+  puts `idx_edges_identity` at `.schema` line 103; the committed `colby.db` has it
+  at line 116. Confirmed this is an artifact of WHICH BINARY created the DB, not of
+  the doc edit: re-dumping the COMMITTED `colby.db` reproduces the committed
+  `schema.sql` byte-identically (all 5 artifacts IDENTICAL), while a freshly
+  indexed DB yields the order-only diff. Steps 3+4 keep the committed pair
+  self-consistent because both come from the same database.
+
+`reference/golden/` is unchanged — the verification ran entirely in `/tmp`.
+
+### Out of scope, deliberately left alone
+
+`docs/godot.md` carries three `.codegraph/config.toml` / `codegraph.json` hits
+(lines 27, 275, 388). It is owned by a sibling task in this wave and was NOT
+touched. Those sites remain stale and need the same correction in a follow-up.
+`docs/upstream-sync/UPSTREAM.md` and the historical body of this ledger keep their
+`.codegraph` spellings by design: they describe what upstream or an earlier slice
+did at the time.
+
+### Commands and their REAL exit statuses
+
+Run individually, never `&&`-joined, so no tail is hidden.
+
+| Command                                         | Exit | Note                                                                        |
+| ----------------------------------------------- | ---- | --------------------------------------------------------------------------- |
+| `cargo build --locked -p codegraph-rs`          | 0    | binary used for every empirical check below                                 |
+| `codegraph init /tmp/cg-fixture-godot`          | 0    | created `.codegraph-v2/` ONLY; 6 files, 15 nodes, 13 edges                  |
+| `codegraph status /tmp/cg-fixture-godot --json` | 0    | all five paths under `.codegraph-v2/`; `legacyIndexPaths = []`              |
+| `--gen-golden` from a FRESH index               | 0    | 4 JSON artifacts IDENTICAL; `schema.sql` order-only diff; `.db` differs @28 |
+| `--gen-golden` from the COMMITTED `colby.db`    | 0    | all 5 artifacts IDENTICAL — isolates the diff to the creating binary        |
+| `bash -n scripts/guardrail.sh`                  | 0    | comment-only edit is syntactically inert                                    |
+| `make fmt`                                      | 0    | oxfmt, 23 docs files; run BEFORE the gates so `fmt-check` cannot trip       |
+| `bash scripts/check-workspace-versions.sh`      | 0    | workspace / `version.txt` / release manifest all `0.40.4`                   |
+| `make ci CARGO='cargo --locked'` (run 1)        | 2    | FAILED — see the flake note below                                           |
+| `make ci CARGO='cargo --locked'` (run 2)        | 0    | PASSED — `✅ All CI checks passed!`                                         |
+
+**Run 1 failure was the known pre-existing flake, reported honestly rather than
+hidden.** Two failures in `codegraph-rs`'s bin tests, 351 passed:
+
+- `install_completions_writes_zsh_fish_elvish_into_home` — `assert!(elv.is_file())`
+  at `main.rs:6220`. This is the documented in-process `HOME`/`XDG_DATA_HOME` race
+  (~4 failures in 8 runs on a clean commit). NOT weakened, NOT touched.
+- `codegraph_dir_and_db_path_default_layout` — `PoisonError` at `main.rs:5740`.
+  This is COLLATERAL, not an independent failure: it takes the same
+  `ENV_LOCK` (`main.rs:5704`) with a bare `.unwrap()`, so the first test's panic
+  while holding that mutex poisons it and fails this one too. The flaky test uses
+  `unwrap_or_else(|e| e.into_inner())` and so tolerates poisoning; this one does
+  not. Both passed in run 2.
+
+No source change was made to address either — they are pre-existing and outside
+this documentation task's scope.
+
+**A SECOND, DIFFERENT pre-existing flake surfaced on a later run** (`make ci` runs
+3 and 4, after the ledger prose was appended):
+
+| Command                                  | Exit | Note                                   |
+| ---------------------------------------- | ---- | -------------------------------------- |
+| `make ci CARGO='cargo --locked'` (run 3) | 2    | FAILED — `Text file busy` flake, below |
+| `make ci CARGO='cargo --locked'` (run 4) | 0    | PASSED — `✅ All CI checks passed!`    |
+
+`verify_legacy_binary_rejects_a_wrong_executable_version`
+(`batch_m_legacy_extension_override.rs:1804`, 20 passed / 1 failed) failed with
+`run configured legacy binary …/stub-legacy --version: Text file busy (os error
+26)` — ETXTBSY: the test writes an executable stub and immediately execs it, and
+on Linux the exec can race the writer's still-open fd. The assertion is intact and
+correct; it simply never reached the version branch. Distinct from the
+`install_completions` flake and likewise pre-existing: `git diff --name-only`
+matched NO `.rs` file at any point in this task (exit 1), so no test source was
+touched, weakened, or skipped. Run 4 passed with the identical tree.
+
+**Golden byte-stability.** `git diff --stat <base>..HEAD -- reference/golden/` is
+EMPTY. During `make ci` the test suite left two untracked SQLite sidecars
+(`reference/golden/ruby/colby.db-shm`, `-wal`) from opening the golden read-only;
+they were deleted, and `git status --porcelain reference/golden/` is empty. Every
+committed golden byte is untouched, `colby.db` included.
+
+**Scope proof.** `git diff --name-only <base>..HEAD | grep -E '\.rs$|Cargo\.(toml|lock)'`
+returns NOTHING (exit 1). `Cargo.lock` SHA-256 is unchanged at
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+**Not claimed.** No native Windows/MSVC validation — every command above ran on
+this Linux host. The six-platform release surface was verified by READING
+`release-please.yml:191-214`, not by building the Windows targets.
+
+### Final `.codegraph/` sweep
+
+`grep -rn '\.codegraph/' --include='*.md' .` (excluding `node_modules`,
+`reference/golden`, and this ledger's own historical body) leaves only CORRECT
+hits, each justified:
+
+- `README.md:69,72,77,78` + `docs/readme/README.zh-CN.md:64,66,71` — the new
+  upgrade notes. They MUST name the old root to tell a `v0.40.4` user what is
+  being ignored.
+- `skills/codegraph/SKILL.md:41` — the legacy-root note ("an index left by
+  `v0.40.4` or earlier … never read or migrated").
+- `docs/cli.md:658`, `docs/languages.md:112` — "a legacy `.codegraph/codegraph.json`
+  is ignored", the corrected resolution rule.
+- `docs/godot.md:27,275,388` — sibling-owned file, deliberately NOT touched; still
+  stale, tracked above as follow-up.
+
+`docs/cli.md`'s watcher-pruning list intentionally names BOTH `.codegraph` and
+`.codegraph-v2` (it is an ignore set covering both spellings, per
+`policy.rs:191`), so it does not appear as a `.codegraph/` hit but is correct.
diff --git a/editors/zed/README.md b/editors/zed/README.md
index f8c11e3..c9bc1b3 100644
--- a/editors/zed/README.md
+++ b/editors/zed/README.md
@@ -106,7 +106,7 @@ codegraph init --target=zed     # writes .zed/settings.json with an absolute --p
 ## Remote development (SSH)
 
 If you use Zed's remote SSH feature (Zed UI on your local machine, code and
-`.codegraph/` index on a remote Linux host), codegraph MCP tools will silently
+`.codegraph-v2/` index on a remote Linux host), codegraph MCP tools will silently
 return empty results. The cause: Zed runs `context_servers` on the **local**
 machine even for remote SSH projects, so the extension's downloaded binary cannot
 reach the remote index. Native remote MCP execution is not yet implemented in Zed
diff --git a/scripts/guardrail.sh b/scripts/guardrail.sh
index f2098f5..ebcdfb8 100755
--- a/scripts/guardrail.sh
+++ b/scripts/guardrail.sh
@@ -22,7 +22,7 @@ done
 # strings — drift there is invisible until AFTER a release is published. This gate
 # lives here rather than in a Cargo test because it parses CI/shell/PowerShell
 # files, not Rust, and `guardrail` is the one step run by make ci, the pre-push
-# hook, AND both CI jobs.
+# hook, AND the CI `test` job (the `windows` job does NOT run it).
 if ! bash "$SCRIPT_DIR/check-asset-names.sh"; then
     echo "❌ RELEASE ASSET-NAME DRIFT: the release workflow and the installers disagree."
     EXIT_CODE=1
diff --git a/skills/codegraph/SKILL.md b/skills/codegraph/SKILL.md
index 906e050..7470969 100644
--- a/skills/codegraph/SKILL.md
+++ b/skills/codegraph/SKILL.md
@@ -7,7 +7,7 @@ description: >
   defined", tracing a call flow, onboarding/surveying an area, or
   whole-project analysis: "analyze the project", "explain the architecture",
   "what does this project do". Also trigger when asked to index/initialize a
-  codebase, or when .codegraph/ is present. Prefer codegraph_* tools over
+  codebase, or when .codegraph-v2/ is present. Prefer codegraph_* tools over
   grep, find, or Read on source files — one call returns verbatim source plus
   the structural graph, replacing dozens of grep+read round-trips. Chinese
   triggers: "分析项目代码", "分析这个仓库", "代码分析", "这个项目是做什么的".
@@ -17,7 +17,7 @@ description: >
 
 CodeGraph is a **deterministic** code knowledge graph built on tree-sitter and
 SQLite/FTS5. It parses a codebase, extracts symbols and their relationships, and
-persists everything to a per-project `.codegraph/` database. There is no AI, no
+persists everything to a per-project `.codegraph-v2/` database. There is no AI, no
 LLM, no vector store, and no embeddings anywhere inside the binary — output is
 byte-stable and fully reproducible.
 
@@ -31,13 +31,16 @@ reads. You get more accurate context in far fewer tokens and round-trips.
 
 ### Detect a live index
 
-A project is indexed when a `.codegraph/` directory exists at its root. Check
+A project is indexed when a `.codegraph-v2/` directory exists at its root. Check
 for it before reaching for grep or Read on source files:
 
 ```
-.codegraph/   ← present = indexed; absent = not yet indexed
+.codegraph-v2/   ← present = indexed; absent = not yet indexed
 ```
 
+A `.codegraph/` directory is an index left by `v0.40.4` or earlier. It is never
+read or migrated — treat it as NOT indexed and run `codegraph init`.
+
 Call `codegraph_status` to confirm the index is ready and to see how many
 files, nodes, and edges are loaded.
 
@@ -53,7 +56,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs
 
 # Index the project
-codegraph init  /path/to/project   # create .codegraph/ and run first index
+codegraph init  /path/to/project   # create .codegraph-v2/ and run first index
 codegraph index /path/to/project   # re-index after large changes
 ```
 
@@ -182,7 +185,7 @@ CodeGraph indexes source code. Fall back to the Read tool or grep for:
 
 - Config files, TOML, YAML, JSON, Markdown, lock files, data files
 - Files flagged in the stale-index banner
-- Anything outside the indexed source tree (the `.codegraph/` dir itself,
+- Anything outside the indexed source tree (the `.codegraph-v2/` dir itself,
   build artifacts, vendored binaries)
 
 For everything else in an indexed project, prefer the codegraph tools. The

From 963c12aaadd58a6cef1d1844b1e662e6ff76d25a Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 00:57:14 +0800
Subject: [PATCH 64/91] fix(resolve): bound the React data-router route-object
 walk to its own object

---
 .../codegraph-resolve/src/frameworks/react.rs | 116 +++++++-
 crates/codegraph-resolve/tests/frameworks.rs  | 258 ++++++++++++++++++
 docs/upstream-sync/V1_5_COMMIT_MANIFEST.md    |   2 +-
 3 files changed, 372 insertions(+), 4 deletions(-)

diff --git a/crates/codegraph-resolve/src/frameworks/react.rs b/crates/codegraph-resolve/src/frameworks/react.rs
index 5fc64bc..cfef9dc 100644
--- a/crates/codegraph-resolve/src/frameworks/react.rs
+++ b/crates/codegraph-resolve/src/frameworks/react.rs
@@ -185,10 +185,10 @@ impl FrameworkResolver for ReactResolver {
         if data_router_regex().is_match(content) {
             for m in obj_path_regex().captures_iter(content) {
                 let whole = m.get(0).expect("group 0");
-                let win = byte_window(content, whole.start(), 300);
+                let win = route_object_own_properties(content, whole.start());
                 let comp = obj_element_attr()
-                    .captures(win)
-                    .or_else(|| obj_component_attr().captures(win))
+                    .captures(&win)
+                    .or_else(|| obj_component_attr().captures(&win))
                     .map(|c| c.get(1).expect("comp group").as_str().to_string());
                 let Some(comp) = comp else { continue };
                 let route_path = {
@@ -560,6 +560,116 @@ fn route_opening_tag_window(content: &str, start: usize) -> &str {
     }
 }
 
+/// Hard byte bound on how far the data-router route-object scan may walk forward
+/// from a `path:` key (upstream issue #1348, data-router half).
+///
+/// The walk normally stops at the `}` closing that route object (see
+/// [`route_object_own_properties`]), but a malformed or unterminated object literal
+/// has no matching `}` to find, so the walk itself must be capped: without a cap one
+/// stray `path:` would drag it to end-of-file, and a file carrying many such keys
+/// would turn this pass quadratic. This is the object-form twin of
+/// [`ROUTE_OPENING_TAG_SCAN_LIMIT`], and both invariants are the same: terminate at
+/// the construct's own end, and cap the search regardless.
+///
+/// 4096 bytes is the cap, sized off route objects actually measured rather than a
+/// guess. Measured reference points, each the raw walk distance from the object's
+/// `path:` key to its own closing `}` (nested children included, because the walk
+/// traverses and elides them rather than stopping at them): a minimal inline
+/// `{ path, element }` is 38 bytes; a typical v6.4 route with `loader` and
+/// `errorElement` is 142; the same plus `action`, `handle={…}` and
+/// `shouldRevalidate`, with `element` last, is 407; a wide enterprise route adding
+/// `hydrateFallbackElement` and a nested `handle` object is 611; a parent route
+/// whose `children` array holds eight loader-bearing child routes, with the parent's
+/// own `element` declared last — the worst realistic walk, since every child byte
+/// must be traversed before the parent's own `element` is reached — is 1503. 4096 is
+/// ~2.7x that widest measured object, so a legitimate object is never truncated,
+/// while the work per `path:` key stays constant. It is also strictly wider than the
+/// fixed 300-byte window it replaces (`react.ts:206`), so no property the old window
+/// could reach is lost.
+const ROUTE_OBJECT_SCAN_LIMIT: usize = 4096;
+
+/// The route object's OWN properties, as text, starting at the `path:` key that
+/// begins at `path_key_start`.
+///
+/// Replaces the upstream fixed 300-byte window (`react.ts:206`), which scanned
+/// blindly forward and took the FIRST `element`/`Component` it found — so a parent
+/// route with no `element` of its own silently borrowed a CHILD route's component,
+/// the same borrowing defect [`route_opening_tag_window`] fixes for the `<Route>`
+/// JSX form (upstream issue #1348).
+///
+/// Nested `{…}` / `[…]` groups are ELIDED, not merely stopped at: a `children: […]`
+/// array cannot leak its own `element` into the parent's text, and neither can a
+/// `handle: {…}` object. Quoted values are copied verbatim, so a `}` or `>` inside
+/// `path: 'a>b'` neither ends the object nor unbalances the depth. The walk is
+/// bounded twice over, exactly as the JSX form is: by the object's own closing `}`
+/// when the literal is well formed, and by [`ROUTE_OBJECT_SCAN_LIMIT`] always. A
+/// malformed object additionally stops at the next `path:` key, so even then it
+/// cannot borrow a following sibling's properties.
+fn route_object_own_properties(content: &str, path_key_start: usize) -> String {
+    let bounded = byte_window(content, path_key_start, ROUTE_OBJECT_SCAN_LIMIT);
+    let bytes = bounded.as_bytes();
+    let mut own = String::with_capacity(bounded.len());
+    // Start of the run of depth-0 bytes not yet copied into `own`. Every byte the
+    // walk inspects structurally is ASCII, so every boundary is a char boundary.
+    let mut segment_start = 0usize;
+    let mut depth = 0usize;
+    let mut quote: Option<u8> = None;
+
+    for (index, byte) in bytes.iter().enumerate() {
+        match quote {
+            Some(open) => {
+                if *byte == open {
+                    quote = None;
+                }
+            }
+            None => match byte {
+                b'"' | b'\'' | b'`' => quote = Some(*byte),
+                b'{' | b'[' => {
+                    if depth == 0 {
+                        // Elide the nested group; a space keeps neighbouring tokens
+                        // from fusing across the hole.
+                        own.push_str(&bounded[segment_start..index]);
+                        own.push(' ');
+                    }
+                    depth += 1;
+                }
+                b'}' | b']' => {
+                    if depth == 0 {
+                        // This object's own end: nothing beyond it belongs to it.
+                        own.push_str(&bounded[segment_start..index]);
+                        return own;
+                    }
+                    depth -= 1;
+                    if depth == 0 {
+                        segment_start = index + 1;
+                    }
+                }
+                b'p' if depth == 0 && index > 0 && is_path_key_at(bounded, index) => {
+                    // Unterminated object: a second depth-0 `path:` can only be a
+                    // following sibling's, so stop rather than borrow from it.
+                    own.push_str(&bounded[segment_start..index]);
+                    return own;
+                }
+                _ => {}
+            },
+        }
+    }
+
+    if depth == 0 {
+        own.push_str(&bounded[segment_start..]);
+    }
+    own
+}
+
+/// Whether a `path` object key (`path` then optional whitespace then `:`) starts at
+/// `index` in `text`.
+fn is_path_key_at(text: &str, index: usize) -> bool {
+    let Some(rest) = text.get(index..).and_then(|r| r.strip_prefix("path")) else {
+        return false;
+    };
+    rest.trim_start().starts_with(':')
+}
+
 /// Byte index just past the `>` closing the opening tag that starts at byte 0 of
 /// `text`, or `None` when the tag does not terminate inside `text`.
 ///
diff --git a/crates/codegraph-resolve/tests/frameworks.rs b/crates/codegraph-resolve/tests/frameworks.rs
index 6b5290f..f963690 100644
--- a/crates/codegraph-resolve/tests/frameworks.rs
+++ b/crates/codegraph-resolve/tests/frameworks.rs
@@ -431,6 +431,264 @@ fn react_route_window_keeps_long_multiline_opening_tag_intact() {
     );
 }
 
+/// The data-router half of upstream #1348: a PARENT route object carries a `path`
+/// but no `element` of its own, and the first `element` the fixed 300-byte window
+/// met belonged to a CHILD inside `children: [...]`. The parent must produce NO
+/// borrowed edge, and each child exactly its own.
+#[test]
+fn react_data_router_parent_without_element_does_not_borrow_from_children() {
+    let content = concat!(
+        "const router = createBrowserRouter([\n",
+        "  {\n",
+        "    path: '/dashboard',\n",
+        "    children: [\n",
+        "      { index: true, element: <DashboardHome/> },\n",
+        "      { path: 'settings', element: <Settings/> },\n",
+        "    ],\n",
+        "  },\n",
+        "]);\n",
+    );
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<(String, i64)> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| (n.name.clone(), n.start_line))
+        .collect();
+    assert_eq!(
+        routes,
+        vec![("settings".to_string(), 6)],
+        "a parent route with no element of its own must emit no route->component pair"
+    );
+
+    let refs: Vec<(String, i64)> = result
+        .references
+        .iter()
+        .map(|r| (r.reference_name.clone(), r.line))
+        .collect();
+    assert_eq!(
+        refs,
+        vec![("Settings".to_string(), 6)],
+        "/dashboard must not borrow DashboardHome from its pathless index child"
+    );
+}
+
+/// The mirror of the parent case, and the shape that makes the object's own closing
+/// `}` load-bearing: a pathless-of-its-own CHILD sits inside `children: [...]` while
+/// the PARENT declares its `element` AFTER the array. Walking past the child's `}`
+/// would hand the parent's component to the child.
+#[test]
+fn react_data_router_child_without_element_does_not_borrow_from_parent() {
+    let content = concat!(
+        "const router = createBrowserRouter([\n",
+        "  {\n",
+        "    path: '/dashboard',\n",
+        "    children: [\n",
+        "      { path: 'settings' },\n",
+        "    ],\n",
+        "    element: <DashboardLayout/>,\n",
+        "  },\n",
+        "]);\n",
+    );
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<(String, i64)> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| (n.name.clone(), n.start_line))
+        .collect();
+    assert_eq!(
+        routes,
+        vec![("/dashboard".to_string(), 3)],
+        "the element-less child must emit nothing; only the parent owns an element"
+    );
+
+    let refs: Vec<(String, i64)> = result
+        .references
+        .iter()
+        .map(|r| (r.reference_name.clone(), r.line))
+        .collect();
+    assert_eq!(
+        refs,
+        vec![("DashboardLayout".to_string(), 3)],
+        "the child must not escape its own closing brace to borrow the parent's element"
+    );
+}
+
+/// A malformed object carrying two depth-0 `path:` keys — no `{` and no `}` separates
+/// them, so only the next-`path:` stop can keep the first from borrowing the second's
+/// element.
+#[test]
+fn react_data_router_object_stops_at_next_path_key_when_unbraced() {
+    let content = "createBrowserRouter([{ path: '/a', path: '/b', element: <B/> }]);\n";
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<String> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| n.name.clone())
+        .collect();
+    assert_eq!(
+        routes,
+        vec!["/b".to_string()],
+        "the first path key has no element between it and the second key"
+    );
+
+    let refs: Vec<String> = result
+        .references
+        .iter()
+        .map(|r| r.reference_name.clone())
+        .collect();
+    assert_eq!(refs, vec!["B".to_string()]);
+}
+
+/// A route object whose `element` is a nested JSX expression containing `>` inside
+/// braces, and whose `path` string itself contains `>`. Neither `>` may end the
+/// object, and the following SIBLING object's element must not leak backwards.
+#[test]
+fn react_data_router_object_survives_angle_brackets_and_stops_at_sibling() {
+    let content = concat!(
+        "const router = createBrowserRouter([\n",
+        "  { path: '/a>b', element: <Guard fallback={<Spinner size={2 > 1 ? 8 : 4}/>}/> },\n",
+        "  { path: '/c>d' },\n",
+        "  { path: '/plain', element: <Plain/> },\n",
+        "]);\n",
+    );
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<(String, i64)> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| (n.name.clone(), n.start_line))
+        .collect();
+    assert_eq!(
+        routes,
+        vec![("/a>b".to_string(), 2), ("/plain".to_string(), 4)],
+        "a `>` inside a quoted path or a braced expression must not end the object, \
+         and an element-less object must not borrow from its next sibling"
+    );
+
+    let refs: Vec<(String, i64)> = result
+        .references
+        .iter()
+        .map(|r| (r.reference_name.clone(), r.line))
+        .collect();
+    assert_eq!(
+        refs,
+        vec![("Guard".to_string(), 2), ("Plain".to_string(), 4)],
+        "each object owns exactly its own element; no sibling leakage either way"
+    );
+}
+
+/// A route object that legitimately runs well past the old 300-byte window — `loader`,
+/// `action`, `errorElement`, `hydrateFallbackElement`, a nested `handle={{…}}` and a
+/// `shouldRevalidate`, with its own `element` declared LAST — must still be seen whole.
+/// This pins the new bound from the outside: tightening it below the object length
+/// reddens this test.
+#[test]
+fn react_data_router_keeps_long_route_object_intact() {
+    let content = concat!(
+        "const router = createBrowserRouter([\n",
+        "  {\n",
+        "    path: '/organisations/:organisationId/settings/billing',\n",
+        "    loader: billingSettingsLoader,\n",
+        "    action: billingSettingsAction,\n",
+        "    errorElement: <BillingSettingsErrorBoundary/>,\n",
+        "    hydrateFallbackElement: <BillingSettingsSkeleton/>,\n",
+        "    handle: {\n",
+        "      crumb: () => 'Billing settings',\n",
+        "      analytics: { screen: 'billing-settings', category: 'billing' },\n",
+        "      permissions: ['billing:read', 'billing:write'],\n",
+        "    },\n",
+        "    shouldRevalidate: ({ currentUrl, nextUrl }) => currentUrl.pathname !== nextUrl.pathname,\n",
+        "    element: <BillingSettingsPage/>,\n",
+        "  },\n",
+        "]);\n",
+    );
+    let path_key = content.find("path:").expect("path key");
+    let element_key = content
+        .find("element: <BillingSettings")
+        .expect("own element");
+    assert!(
+        element_key - path_key > 300,
+        "fixture must place its own element past the old 300-byte window, got {}",
+        element_key - path_key
+    );
+
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", content, &no_project_config())
+        .expect("extract result");
+
+    let route = result
+        .nodes
+        .iter()
+        .find(|n| n.kind == NodeKind::Route)
+        .expect("route node");
+    assert_eq!(
+        route.name,
+        "/organisations/:organisationId/settings/billing"
+    );
+    assert_eq!(
+        result
+            .references
+            .iter()
+            .map(|r| r.reference_name.clone())
+            .collect::<Vec<_>>(),
+        vec!["BillingSettingsPage".to_string()],
+        "the own element of a {}-byte route object must still be seen, and the \
+         errorElement/hydrateFallbackElement must not be mistaken for it",
+        element_key - path_key
+    );
+}
+
+/// An unterminated route object followed by a well-formed one 200KB later: the walk
+/// must neither run to end-of-file nor reach that far-away element.
+#[test]
+fn react_data_router_object_walk_is_bounded_for_unterminated_literal() {
+    let mut content = String::from("createBrowserRouter([\n  { path: '/a',\n");
+    content.push_str(&"filler,\n".repeat(25_000));
+    content.push_str("  { path: '/b', element: <Comp/> },\n]);\n");
+
+    let result = react::ReactResolver
+        .extract("src/routes.tsx", &content, &no_project_config())
+        .expect("extract result");
+
+    let routes: Vec<String> = result
+        .nodes
+        .iter()
+        .filter(|n| n.kind == NodeKind::Route)
+        .map(|n| n.name.clone())
+        .collect();
+    assert_eq!(
+        routes,
+        vec!["/b".to_string()],
+        "the unterminated /a object has no element of its own and must emit nothing"
+    );
+
+    let refs: Vec<String> = result
+        .references
+        .iter()
+        .map(|r| r.reference_name.clone())
+        .collect();
+    assert_eq!(
+        refs,
+        vec!["Comp".to_string()],
+        "the unterminated /a object must not reach the /b element 200KB later"
+    );
+}
+
 // ---------------------------------------------------------------------------
 // Vue
 // ---------------------------------------------------------------------------
diff --git a/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md b/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
index d225506..9f654b4 100644
--- a/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
+++ b/docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
@@ -127,7 +127,7 @@ do not appear as separate commits in the frozen `v1.4.1..v1.5.0` list.
 |---|---|---|---|
 | #1372 | PORT | Batch A1 Unicode search scoring + real CLI/MCP contracts | none |
 | #1359 | PORT | Batch A3 enqueue-once unit instrumentation | none |
-| #1348 | PORT | Batch D1 bounded React opening-tag scan | none |
+| #1348 | PORT | Batch D1 bounded React `<Route>` opening-tag scan + Batch F3 bounded data-router route-object walk | none |
 | #1350 | PORT | Batch D2 DFM nesting/end lines | none |
 | #1182/#1209 | PORT | Batch D3 MyBatis/iBatis forms and qualified refids | none |
 | #1349 | N/A | forbidden node-ID byte-offset/column discriminator | none |

From 5789dd2c00d4cd52900069d7330c2e68c8fe4ea7 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 01:12:21 +0800
Subject: [PATCH 65/91] docs(godot): correct the gdext build-time dependency
 claim

---
 docs/godot-gdext-decision.md              |  66 +++++++-----
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 126 ++++++++++++++++++++++
 2 files changed, 168 insertions(+), 24 deletions(-)

diff --git a/docs/godot-gdext-decision.md b/docs/godot-gdext-decision.md
index 7c4dc5f..fd07325 100644
--- a/docs/godot-gdext-decision.md
+++ b/docs/godot-gdext-decision.md
@@ -9,43 +9,61 @@ bindings — to improve Godot/GDScript analysis.
 ## Verdict
 
 **Rejected, and unnecessary.** `gdext` is a binding for Rust code running inside
-a live Godot engine, so adopting it would add an engine dependency to a
-standalone binary and make output depend on the engine version, while solving
-none of the gaps recorded in [`docs/godot.md`](godot.md#limitations) — those are
-either genuinely runtime-only or solvable with better static parsing.
+a live Godot engine. It exposes no offline API for reading `.gd`, `.tscn`,
+`.tres` or `project.godot`, so it cannot do the job CodeGraph does, and it
+solves none of the gaps recorded in
+[`docs/godot.md`](godot.md#limitations) — those are either genuinely runtime-only
+or solvable with better static parsing.
 
 ## What gdext actually is
 
 `gdext` compiles Rust into a GDExtension shared library that Godot loads at
 startup. Its type surface (`Node`, `Callable`, `NodePath`, …) is generated from
-`extension_api.json`, which ships with a specific Godot build, and those types
-are only meaningful once the engine has initialized. It is not a GDScript
-parser, not a `.tscn`/`.tres` reader, and offers no offline API for inspecting
-project files. Anything CodeGraph wanted from it would require launching Godot.
+Godot's `extension_api.json`, and those types are only meaningful once the engine
+has initialized — a `Gd<Node>` is a handle into a running engine's object
+database, not a description of a file on disk. It is not a GDScript parser, not
+a `.tscn`/`.tres` reader, and offers no offline API for inspecting project files.
+Anything CodeGraph wanted from it would require launching Godot.
+
+To be precise about the build step, because an earlier draft of this document got
+it wrong: a plain `gdext` dependency does **not** need a Godot binary present at
+build time. Per the crate docs
+([docs.rs/godot 0.5.4, "Cargo features"](https://docs.rs/godot/latest/godot/#cargo-features)),
+the `api-*` features "Set the **API level** to the specified Godot version, or a
+custom-built local binary… If absent, the current Godot minor version is used,
+with patch level 0" — i.e. the bindings are generated from an API description
+bundled with the crate and pinned by its version. Only the two opt-in features
+need an engine or a hand-supplied API: "`api-custom` feature requires specifying
+`GDRUST_GODOT_BIN` environment variable with a path to your Godot4 binary. The
+`api-custom-json` feature requires specifying `GDRUST_GODOT_API_JSON` environment
+variable with a path to your custom-defined `extension_api.json`." The engine
+requirement is at **run** time — Godot loads the produced library — and that is
+the part that disqualifies `gdext` here.
+
+An earlier draft also argued that `gdext` would break the golden `.schema`
+byte-stability invariant because its bindings vary with the installed engine.
+That argument does not survive the correction: with the default prebuilt API the
+generated surface is fixed by the crate version, so it is as reproducible as any
+other pinned dependency, and it would only become runner-dependent under
+`api-custom` (engine binary) or `api-custom-json` (hand-supplied JSON) — features
+nobody is proposing. The determinism objection is therefore dropped rather than
+kept for symmetry. The real determinism risk was never the bindings; it is that
+any output derived from a live engine's state is not a pure function of the
+corpus, which is the runtime problem stated above.
 
 ## Why it disqualifies itself
 
-**1. It requires the engine; CodeGraph deliberately does not.**
+**1. It requires the engine at runtime; CodeGraph deliberately requires none.**
 `docs/godot.md` opens by stating that CodeGraph parses Godot project files
 "— no engine required, no compilation, no runtime". Releases are standalone
 binaries, and README.md notes that "Linux builds are statically linked (musl) —
 no glibc or SQLite system dependency". Users indexing a Godot repo on CI, on a
 server, or on a machine without the editor installed are a supported case.
-`gdext` would make Godot analysis conditional on having a matching Godot binary
-and its `extension_api.json` present at build time.
-
-**2. It breaks byte-stable determinism.**
-`AGENTS.md` lists as a hard invariant: "**Golden `.schema` byte-stability** —
-verified by `crates/codegraph-bench/tests/equivalence.rs` against the fixed
-golden artifacts under `reference/golden/`", with `reference/golden/godot/`
-guarding the autoload-call edges, signal-handler edges, and UID-form autoloads
-"byte-for-byte". `AGENTS.md` also requires "**Deterministic** extraction +
-resolution". Bindings generated from a specific engine version make output a
-function of that version, so the same corpus could produce different goldens on
-different release runners. That is not reconcilable with a fixed golden checked
-into the repository.
-
-**3. It solves none of the recorded gaps.**
+`gdext` code only executes as a GDExtension loaded by a Godot process, so
+reaching its types at all would mean shipping or locating an engine and starting
+it. `codegraph index` would stop being a self-contained command.
+
+**2. It solves none of the recorded gaps.**
 The limitations in [`docs/godot.md`](godot.md#limitations) split cleanly, and
 neither half needs an engine binding:
 
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index f55f5db..5ff3381 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -7666,3 +7666,129 @@ hits, each justified:
 `docs/cli.md`'s watcher-pruning list intentionally names BOTH `.codegraph` and
 `.codegraph-v2` (it is an ignore set covering both spellings, per
 `policy.rs:191`), so it does not appear as a `.codegraph/` hit but is correct.
+
+## Batch F1 — the gdext decision no longer rests on a false build-time claim (2026-07-29)
+
+`docs/godot-gdext-decision.md` (added by `956cf32`) argued the right conclusion
+from a verifiably wrong premise. An independent audit caught it. The verdict is
+unchanged — `gdext` is still rejected, and still unnecessary — but an argument a
+reader can falsify in five minutes discredits the whole record, so the premise is
+corrected rather than defended.
+
+### The incorrect claim, verbatim
+
+From "What gdext actually is":
+
+> Its type surface (`Node`, `Callable`, `NodePath`, …) is generated from
+> `extension_api.json`, which ships with a specific Godot build
+
+and, restating it, from disqualifier 1 ("It requires the engine; CodeGraph
+deliberately does not"):
+
+> `gdext` would make Godot analysis conditional on having a matching Godot binary
+> and its `extension_api.json` present at build time.
+
+### The official source that refutes it
+
+`https://docs.rs/godot/latest/godot/#cargo-features` (crate `godot`, version
+`0.5.4`, the `gdext` binding's public crate). Under _Godot version and
+configuration_ it documents `api-4-{minor}`, `api-custom` and `api-custom-json`
+together:
+
+> Sets the **API level** to the specified Godot version, or a custom-built local
+> binary. You can use at most one `api-*` feature. If absent, the current Godot
+> minor version is used, with patch level 0.
+>
+> `api-custom` feature requires specifying `GDRUST_GODOT_BIN` environment
+> variable with a path to your Godot4 binary.
+>
+> The `api-custom-json` feature requires specifying `GDRUST_GODOT_API_JSON`
+> environment variable with a path to your custom-defined `extension_api.json`.
+
+So a plain `gdext` dependency builds against an API description bundled with the
+crate and pinned by the crate version; an engine binary is needed only under
+`api-custom`, and a hand-supplied `extension_api.json` only under
+`api-custom-json`. `https://docs.rs/crate/godot/latest/features` corroborates the
+opt-in status: of 22 features exactly one (`__codegen-full`) is on by default —
+neither `api-custom` nor `api-custom-json` is.
+
+### What changed
+
+- "What gdext actually is" now says the type surface is generated from Godot's
+  `extension_api.json` and is only meaningful once the engine has initialized,
+  and adds an explicit paragraph stating that an earlier draft got the build step
+  wrong, quoting the docs.rs text and naming `api-custom` / `api-custom-json`
+  with their environment variables.
+- Disqualifier 1 is reframed from build time to **run** time: `gdext` code only
+  executes as a GDExtension loaded by a Godot process, so `codegraph index` would
+  stop being a self-contained command. That is the true and sufficient form of
+  the objection.
+- The verdict paragraph still opens with the rejection, now resting on the
+  load-bearing reason alone: no offline API for reading `.gd` / `.tscn` /
+  `.tres` / `project.godot`.
+- Former disqualifier 3 ("It solves none of the recorded gaps") is renumbered 2.
+
+Untouched and still valid: the four ranked alternatives and their ordering, the
+`unverified` marking on whether a newer `tree-sitter-gdscript` than the pinned
+`6.1.0` exists, the `godot:dynamic:*` sentinel defence, and the recommendation
+(not action) to widen `scripts/guardrail.sh`. No "Conclusion" section was added.
+
+### Why disqualifier 2 does not survive
+
+The dropped disqualifier claimed adopting `gdext` "breaks byte-stable
+determinism" because "[b]indings generated from a specific engine version make
+output a function of that version, so the same corpus could produce different
+goldens on different release runners". With the prebuilt default that premise is
+gone: the generated surface is fixed by the crate version, exactly as
+reproducible as any other pinned dependency, and it becomes runner-dependent only
+under `api-custom` (engine binary) or `api-custom-json` (local JSON) — features
+nobody proposed. Kept as written it would be a second false claim; narrowed to
+"true only for `api-custom`" it would be an objection to a configuration nobody
+suggested, i.e. filler. The verdict does not need three disqualifiers, so it is
+**dropped rather than kept for symmetry**. What replaces it is a sharper true
+observation folded into the corrected prose: the real determinism risk was never
+the bindings but that any output derived from a live engine's state is not a pure
+function of the corpus — which is the runtime problem disqualifier 1 already
+states.
+
+### Gates — real exit statuses
+
+Run in the mandated order, each separately (no `&&` chaining, so no tail is
+hidden):
+
+| Command                                       | Exit                               |
+| --------------------------------------------- | ---------------------------------- |
+| `make fmt`                                    | **0**                              |
+| `bash scripts/check-workspace-versions.sh`    | **0** (`OK`, workspace `0.40.4`)   |
+| `make ci CARGO='cargo --locked'` — final gate | **0** (`✅ All CI checks passed!`) |
+
+The final `make ci` above is the one taken after the last byte of this batch, and
+it exited 0. It was not the only run: `make ci` was invoked repeatedly here, once
+after the first ledger draft and again after each prose correction, and MORE THAN
+HALF of those invocations exited non-zero (`101` from `make: *** [Makefile:127:
+test] Error 101`, surfacing as `2` from `make ci` itself). Every single red run
+failed on the KNOWN pre-existing flake
+`formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home`
+and on nothing else: 352 passed / 1 failed every time, with the assertion landing
+on a different line from run to run (`main.rs:6213`, then `main.rs:6224`), and one
+log showing a completion actually written into the real
+`/config/.config/fish/completions/` instead of the test's temp `HOME`. That is the
+documented in-process `HOME`/`XDG_DATA_HOME` race, not a docs regression — this
+batch changes two Markdown files and no Rust at all. The flake is reproducing more
+often on this host than the ~4-in-8 previously recorded. The test was NOT
+weakened, skipped or ignored, and the red runs are recorded here rather than
+quietly discarded.
+
+The equivalence oracle also left untracked
+`reference/golden/{erlang,mini}/colby.db-{wal,shm}` behind on several runs; they
+are not gitignored and were deleted before staging, so the commit contains no
+golden-directory byte.
+
+**Scope.** `git diff --name-only e728937..HEAD` lists only
+`docs/godot-gdext-decision.md` and this ledger. `git diff --stat
+e728937..HEAD -- reference/golden/` is empty; `Cargo.lock` SHA-256 unchanged at
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+**Not claimed.** No native Windows/MSVC validation — every command ran on this
+Linux host. The docs.rs pages were read over the network as cited; no `gdext`
+build was attempted, and none is needed to verify a documented feature contract.

From 6b684e6f00642c8e9333ef13c762a81a031b67f4 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 02:00:23 +0800
Subject: [PATCH 66/91] docs: correct the KNOWN_DIFFS path and the retired
 index root

---
 docs/equivalence.md                       |  21 +++-
 docs/godot.md                             |   6 +-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 118 ++++++++++++++++++++++
 3 files changed, 139 insertions(+), 6 deletions(-)

diff --git a/docs/equivalence.md b/docs/equivalence.md
index cb0e671..316e030 100644
--- a/docs/equivalence.md
+++ b/docs/equivalence.md
@@ -736,12 +736,27 @@ The `generated_golden_matches_committed_cfml_fixture` and
 
 ### KNOWN_DIFFS.md format
 
-Tier-3 differences are allowlisted by grep-able lines in repo-root
-`KNOWN_DIFFS.md`:
+Tier-3 differences are allowlisted by grep-able lines in
+`docs/upstream-sync/KNOWN_DIFFS.md` — the single path
+`KnownDiffs::repo_doc_path` hardcodes
+(`crates/codegraph-bench/src/oracle/diff.rs`):
 
 ```text
 RULE tier=3 surface=<surface> key=<substring-or-*> justification=<short-token>
 ```
 
 Only Tier-3 entries can be allowed. Tier-1 byte mismatches and Tier-2 multiset
-mismatches always fail; the differ never weakens those tiers to pass.
+mismatches always fail; the differ never weakens those tiers to pass —
+`KnownDiffs::allows` returns `false` for anything that is not `Tier::Tier3`, and
+`parse_rule` rejects `tier=1` / `tier=2` before that, so a Tier-1/Tier-2 rule
+cannot even be written down.
+
+The parser is fail-closed: an unparsable document fails every equivalence
+assertion instead of being ignored. A `RULE` line is rejected when a token is
+not `key=value`, a key or value is empty, a field name is outside
+`tier`/`surface`/`key`/`justification`, a field is repeated, `tier` is anything
+other than Tier-3, `surface` is outside the five surfaces the differ reports
+(`nodes`, `files`, `schema`, `edges`, `unresolved_refs`), or any of the four
+fields is missing. Lines inside a fenced code block are documentation, not
+rules — including the template above — and an unterminated fence is an error,
+because every `RULE` after it would otherwise be skipped silently.
diff --git a/docs/godot.md b/docs/godot.md
index 70b6ba3..f5d5aed 100644
--- a/docs/godot.md
+++ b/docs/godot.md
@@ -24,7 +24,7 @@ vendored third-party editor plugins that would otherwise crowd out first-party
 
 Both exclusions are opt-out. To re-include a directory (for example, a team that
 keeps first-party code under `addons/`), set a custom `indexing.ignore_dirs` list
-in `.codegraph/config.toml`. That list replaces the default set entirely, so
+in `.codegraph-v2/config.toml`. That list replaces the default set entirely, so
 re-list any other directories you still want ignored — e.g. keep `.godot` while
 dropping `addons`:
 
@@ -272,7 +272,7 @@ flag reference.
 For projects that define custom `.tres` resource types with domain-specific
 fields that carry semantic edges (e.g. a `skill_effect` field that references
 another resource), CodeGraph supports an opt-in DSL mapping via
-`.codegraph/codegraph.json`. List the `[resource]` property names that should
+`.codegraph-v2/codegraph.json`. List the `[resource]` property names that should
 emit a reference edge from their value under `godot.dsl.resourceFields`:
 
 ```jsonc
@@ -385,7 +385,7 @@ sync` that touches only a `.gd.uid`, a `.tscn` uid header, or a file rename does
 - **`.godot/` and `addons/` are skipped by default.** Both directories are
   excluded from indexing so engine cache and vendored plugins don't bury
   first-party code in search results. Re-include a directory via a custom
-  `indexing.ignore_dirs` list in `.codegraph/config.toml`. See
+  `indexing.ignore_dirs` list in `.codegraph-v2/config.toml`. See
   [Indexing scope](#indexing-scope-ignored-directories).
 
 ---
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 5ff3381..bb9c5ae 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -7792,3 +7792,121 @@ e728937..HEAD -- reference/golden/` is empty; `Cargo.lock` SHA-256 unchanged at
 **Not claimed.** No native Windows/MSVC validation — every command ran on this
 Linux host. The docs.rs pages were read over the network as cited; no `gdext`
 build was attempted, and none is needed to verify a documented feature contract.
+
+## F4 round-two documentation blockers: two false statements corrected
+
+Round two of the F1–F4 review wave rejected F4 on four blockers. Two were false
+statements in committed documentation. Both are corrected here; the other two
+were adjudicated (a claimed daemon-path contract conflict rested on a
+mis-briefing, and the known test flakes predate this branch). Documentation only:
+no `.rs`, no `Cargo.*`, no workflow, no `scripts/`, no golden byte.
+
+### Blocker 1 — `docs/equivalence.md` named a file that does not exist
+
+The committed text, verbatim (`docs/equivalence.md:739-740` at `c8968ad`):
+
+> Tier-3 differences are allowlisted by grep-able lines in repo-root
+> `KNOWN_DIFFS.md`:
+
+`ls KNOWN_DIFFS.md` → `No such file or directory` (exit 2). The file that does
+exist is `docs/upstream-sync/KNOWN_DIFFS.md` (11133 bytes), and it is the ONLY
+path the oracle ever reads —
+`crates/codegraph-bench/src/oracle/diff.rs:141-147`:
+
+```rust
+pub fn repo_doc_path() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("codegraph-bench lives under crates/")
+        .join("docs/upstream-sync/KNOWN_DIFFS.md")
+}
+```
+
+The path is now named correctly, attributed to `KnownDiffs::repo_doc_path`.
+
+The surrounding section also still described only the pre-`5c585ec` permissive
+contract. Each added claim was read off `diff.rs` before it was written:
+
+- Tier gate on the query side — `allows` returns `false` for any
+  `entry.tier != Tier::Tier3` (`diff.rs:190-193`).
+- Tier gate at parse time — `tier=1`/`Tier1`/`tier1`/`2`/`Tier2`/`tier2` bail
+  with "may not be allowlisted"; any other value bails as "unknown tier"
+  (`diff.rs:234-240`).
+- Token shape — a token without `=` bails; an empty key or value bails
+  (`diff.rs:218-224`).
+- Unknown field — rejected against `RULE_FIELDS = ["tier", "surface", "key",
+"justification"]` (`diff.rs:21`, `225-227`).
+- Duplicate field — rejected (`diff.rs:228-230`).
+- Surface — rejected unless it is one of `DIFF_SURFACES = ["nodes", "files",
+"schema", "edges", "unresolved_refs"]` (`diff.rs:18`, `242-245`).
+- Missing field — all four of `tier`, `surface`, `key`, `justification` are
+  `.context("missing …")?` (`diff.rs:233`, `242`, `250-258`).
+- Fenced lines are documentation, and an unterminated fence is an error
+  (`diff.rs:166-188`).
+- Fail-closed loading — `load_repo_doc` propagates a parse error, so an
+  unparsable document fails the assertion instead of being ignored
+  (`diff.rs:149-154`).
+
+Nothing was asserted that `diff.rs` does not state. The wildcard semantics
+(`key_pattern == "*"` or `entry.key.contains(&rule.key_pattern)`,
+`diff.rs:194-198`) were left as the existing template already implies them.
+
+### Blocker 2 — `docs/godot.md` still pointed at the retired index root
+
+`ddd6b27` corrected eleven documents and missed this one. The three stale sites,
+verbatim (`docs/godot.md` at `c8968ad`):
+
+> in `.codegraph/config.toml`. That list replaces the default set entirely, so (line 27)
+
+> `.codegraph/codegraph.json`. List the `[resource]` property names that should (line 275)
+
+> `indexing.ignore_dirs` list in `.codegraph/config.toml`. See (line 388)
+
+All three describe live paths a user is told to create. The code puts both files
+under the current root: `IndexPaths::config_file` is
+`self.current_root.join("config.toml")` and `extension_config` is
+`self.current_root.join("codegraph.json")`
+(`crates/codegraph-core/src/index_paths.rs:304-312`), and `current_root`
+defaults to `DEFAULT_CURRENT_DIR = ".codegraph-v2"` (`index_paths.rs:46`).
+`.codegraph` survives only as `LEGACY_DIR` (`index_paths.rs:48`), a root that is
+ignored. All three now read `.codegraph-v2/…`.
+
+The daemon rendezvous is the same root, not a surviving `.codegraph/` role:
+`crates/codegraph-daemon/src/paths.rs:31-33` is
+`Ok(index_paths(project_root)?.current_root().to_path_buf())`, and that file's
+own test asserts the result `starts_with(project.join(".codegraph-v2"))`
+(`paths.rs:145-152`). `daemon_pid`, `daemon_log` and `daemon_socket` are all
+`current_root.join(…)` (`index_paths.rs:315-330`). An earlier review round was
+mis-briefed that the rendezvous stayed at `.codegraph/`; it does not, and no
+`.codegraph/` role was introduced here.
+
+`docs/godot.md` now has zero `.codegraph` hits that are not `.codegraph-v2`, so
+no legacy mention was kept in that file.
+
+### Final grep sweeps
+
+`grep -rn '\.codegraph/' --include='*.md' . | grep -v node_modules` — 35 hits
+remain, none of them a live-path instruction:
+
+- `README.md:69,72,77,78` and `docs/readme/README.zh-CN.md:64,66,71` — the
+  migration note. Every mention is explicitly the OLD root being ignored and not
+  carried over.
+- `skills/codegraph/SKILL.md:41` — "A `.codegraph/` directory is an index left by
+  `v0.40.4` or earlier", explicitly labelled legacy.
+- `docs/cli.md:658`, `docs/languages.md:112` — "A legacy
+  `.codegraph/codegraph.json` is ignored", explicitly labelled legacy.
+- `docs/upstream-sync/UPSTREAM.md:688,712,749,800,808` — the upstream porting
+  ledger, quoting upstream TypeScript behavior and this project's pre-migration
+  state. Historical record; rewriting it would falsify what was ported when.
+- `docs/upstream-sync/V1_5_PORTABLE_FIXES.md` (remaining hits) — this ledger's
+  own account of the migration and of the earlier sweep, including the sites it
+  admitted were stale. Historical by construction.
+
+`grep -rn 'repo-root .KNOWN_DIFFS' --include='*.md' .` — no output, exit 1. The
+false claim is gone and not reintroduced anywhere.
+
+### Commands and their real exit status
+
+Recorded in the section below, after the gates ran. Gates were run separately,
+never joined with `&&`, so no tail is hidden.

From 76535be698a325bcc3d614cbbd24a53032ee666a Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 08:57:09 +0800
Subject: [PATCH 67/91] docs: record the stale-heal pid-before-socket deletion
 order as a deferred defect

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 95 +++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index bb9c5ae..d866274 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -7910,3 +7910,98 @@ false claim is gone and not reintroduced anywhere.
 
 Recorded in the section below, after the gates ran. Gates were run separately,
 never joined with `&&`, so no tail is hidden.
+
+## F2 round-two finding, recorded as DEFERRED: the stale-heal path deletes the pid record before the socket (2026-07-29)
+
+**Status: NOT fixed in this release.** This section is the record, not a repair.
+The defect predates this branch, so it was adjudicated out of scope for the
+v1.5-portable-fixes work; recording it here keeps the evidence ledger the single
+place a maintainer looking at this release finds it. `KNOWN_DIFFS.md` was
+considered and rejected as the home: that file is the parsed Tier-3 oracle input
+plus prose about colby EQUIVALENCE differences, and this is neither an
+equivalence difference nor an allowlistable diff. No Tier-3 `RULE` line was
+added; that file still has zero active rules.
+
+### The function and the current order
+
+`clear_stale_daemon_socket` (`crates/codegraph-daemon/src/lock.rs:165-178`),
+verbatim at `26cca84`:
+
+```rust
+    // Liveness gate: only proceed once the owning pid is proven dead/absent.
+    if !clear_stale_daemon_lock(&pid_path, None) {
+        return false;
+    }
+    let _ = fs::remove_file(&socket_path);
+    true
+```
+
+The pid record goes first, the socket second.
+
+### Why the order matters
+
+The published pid record IS the single-instance exclusion token:
+`try_acquire_daemon_lock` claims it with `create_new`, so while a record exists a
+competing start reports `Taken` and never binds the recorded socket path. Once
+this cleaner has removed the record, a replacement daemon may legitimately claim
+it and bind the same path before the `remove_file(&socket_path)` line runs — and
+that unlink then destroys the LIVE replacement's socket. Observable end state: a
+pid record naming a live daemon with no socket. Later clients cannot self-heal
+out of it, because the liveness gate in `clear_stale_daemon_lock`
+(`lock.rs:141-143`) refuses to touch a record whose pid is alive.
+
+`clear_stale_daemon_lock` also returns `true` for a MISSING pidfile
+(`lock.rs:130`), so "cleared" does not imply this caller ever held exclusion —
+which widens the interleaving rather than narrowing it.
+
+### Production reachability
+
+Not test-only. `heal_stale_daemon_if_dead` (`crates/codegraph-cli/src/main.rs:2680`)
+calls it, and that helper is reached from three sites, including the failed warm
+attach inside `proxy_to_running_daemon` (`main.rs:2622-2627`, socket missing) and
+its post-`run_proxy` failure path (`main.rs:2647`). Two concurrent
+`serve --mcp` starts on one project can therefore run a cleaner against a
+replacement daemon's namespace.
+
+### It predates `aba4079`
+
+`git show aba4079:crates/codegraph-daemon/src/lock.rs` already contains the same
+function with the same order at its line 161:
+
+```rust
+pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
+    let pid_path = daemon_pid_path(project_root);
+    let socket_path = recorded_socket_path(project_root);
+    // Liveness gate: only proceed once the owning pid is proven dead/absent.
+    if !clear_stale_daemon_lock(&pid_path, None) {
+        return false;
+    }
+    let _ = fs::remove_file(&socket_path);
+    true
+}
+```
+
+This branch changed only its error handling, because `daemon_pid_path` and
+`recorded_socket_path` began returning `Result`. The deletion order is untouched.
+
+### Contrast with `f691415`
+
+`f691415` ("fix(daemon): remove the rendezvous socket before releasing its
+ownership record") fixed exactly this class of race in a DIFFERENT function,
+`cleanup_owned_rendezvous` (`lock.rs:281-312`): it removes the socket first while
+its own record still excludes competitors, then deletes the record only after
+re-corroborating ownership through `cleanup_owned_lock`. That function's doc
+comment states the reasoning ("ORDER IS LOAD-BEARING"). The stale-heal path never
+received the same treatment.
+
+### Why a naive order swap is not a fix
+
+Swapping the two deletions in `clear_stale_daemon_socket` is insufficient. Unlike
+`cleanup_owned_rendezvous`, this cleaner does not own the record it is deleting,
+so it has no ownership token to re-corroborate and nothing stops several
+concurrent cleaners from performing a delayed unlink after a replacement daemon
+has already bound the path. A correct fix needs either a serialization protocol
+shared by starters and cleaners, or the stale cleanup moved inside
+`start_or_attach_gated` (`crates/codegraph-daemon/src/lib.rs:291`) so it runs only
+once the new pid record is held. Neither is a documentation change, and neither
+was attempted here.

From 82029e3794050410496e0823d845972dfad7a0ff Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 11:16:47 +0800
Subject: [PATCH 68/91] test(cli,watch): serialize env-mutating tests behind
 one lock per crate

---
 crates/codegraph-cli/src/installer/mod.rs |  51 +---
 crates/codegraph-cli/src/main.rs          | 339 +++++++++++-----------
 crates/codegraph-watch/src/lib.rs         |  95 ++++++
 crates/codegraph-watch/src/policy.rs      | 115 ++------
 crates/codegraph-watch/src/watcher.rs     |  17 ++
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 284 ++++++++++++++++++
 6 files changed, 613 insertions(+), 288 deletions(-)

diff --git a/crates/codegraph-cli/src/installer/mod.rs b/crates/codegraph-cli/src/installer/mod.rs
index e345097..5a2570a 100644
--- a/crates/codegraph-cli/src/installer/mod.rs
+++ b/crates/codegraph-cli/src/installer/mod.rs
@@ -497,10 +497,8 @@ fn tildify(ctx: &InstallContext, path: &std::path::Path) -> String {
 mod tests {
     use super::*;
     use crate::installer::types::FileWrite;
+    use crate::test_env::env_guard;
     use std::fs;
-    use std::sync::Mutex;
-
-    static ENV_LOCK: Mutex<()> = Mutex::new(());
 
     fn temp_ctx(label: &str) -> (InstallContext, PathBuf) {
         let base = std::env::temp_dir().join(format!(
@@ -589,11 +587,10 @@ mod tests {
     #[test]
     fn init_target_kiro_writes_project_local_mcp_with_concrete_path() {
         // Given a temp HOME and an indexed project root
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let (ctx, base) = temp_ctx("init-kiro");
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
-        unsafe { std::env::set_var(home_key, &ctx.home) };
+        env.set(home_key, &ctx.home);
 
         // When init --target=kiro installs project-local config (run twice = idempotent)
         run_install_local_targets(ctx.cwd.clone(), "kiro").unwrap();
@@ -617,21 +614,17 @@ mod tests {
             "must pin concrete project path, got: {args:?}"
         );
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(base);
     }
 
     #[test]
     fn init_target_none_writes_nothing() {
         // Given a temp HOME and a project root
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let (ctx, base) = temp_ctx("init-none");
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
-        unsafe { std::env::set_var(home_key, &ctx.home) };
+        env.set(home_key, &ctx.home);
 
         // When init runs with the default target (none)
         run_install_local_targets(ctx.cwd.clone(), "none").unwrap();
@@ -642,10 +635,7 @@ mod tests {
             "none must be a pure no-op"
         );
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(base);
     }
 
@@ -777,13 +767,11 @@ mod tests {
 
     #[test]
     fn run_uninstall_with_ctx_via_public_paths() {
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let (ctx, base) = temp_ctx("run-uninstall");
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
-        unsafe { std::env::set_var(home_key, &ctx.home) };
-        let prev_xdg = std::env::var_os("XDG_CONFIG_HOME");
-        unsafe { std::env::set_var("XDG_CONFIG_HOME", ctx.xdg_config_home.as_ref().unwrap()) };
+        env.set(home_key, &ctx.home);
+        env.set("XDG_CONFIG_HOME", ctx.xdg_config_home.as_ref().unwrap());
 
         run_uninstall(UninstallArgs {
             target: Some("gemini".to_string()),
@@ -792,24 +780,16 @@ mod tests {
         })
         .unwrap();
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
-        match prev_xdg {
-            Some(v) => unsafe { std::env::set_var("XDG_CONFIG_HOME", v) },
-            None => unsafe { std::env::remove_var("XDG_CONFIG_HOME") },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(base);
     }
 
     #[test]
     fn run_skill_install_and_uninstall_and_status_via_ctx() {
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let (ctx, base) = temp_ctx("run-skill");
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
-        unsafe { std::env::set_var(home_key, &ctx.home) };
+        env.set(home_key, &ctx.home);
 
         run_skill_install(SkillArgs {
             target: Some("claude".to_string()),
@@ -833,10 +813,7 @@ mod tests {
         })
         .unwrap();
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(base);
     }
 }
diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs
index be2c406..8eb97a2 100644
--- a/crates/codegraph-cli/src/main.rs
+++ b/crates/codegraph-cli/src/main.rs
@@ -39,6 +39,110 @@ mod segment_match;
 mod segments;
 mod structural_gate;
 
+/// Test-only: the ONE process-wide environment lock for this binary.
+///
+/// `cargo test` runs every unit test of this binary on threads of a SINGLE
+/// process, so `HOME`, `XDG_DATA_HOME`, `USERPROFILE`, … are shared mutable
+/// state. Two independent `ENV_LOCK` statics used to live in this file (one per
+/// test module) plus a third in `installer::tests`, and because distinct statics
+/// do not exclude each other, a test holding "the" lock could still have `HOME`
+/// swapped underneath it — which made `install_completions` write into the
+/// developer's REAL home directory. Every test in this binary that mutates a
+/// process-global env var must therefore go through [`test_env::EnvGuard`].
+#[cfg(test)]
+pub(crate) mod test_env {
+    use std::ffi::{OsStr, OsString};
+    use std::sync::{Mutex, MutexGuard};
+
+    /// The single env lock for the whole `codegraph` binary's test suite.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    /// Holds [`ENV_LOCK`] for its whole lifetime, records every variable it
+    /// touched, and restores all of them on drop (panic-safe, so a failing
+    /// assertion cannot leak a temp `HOME` into the rest of the suite).
+    pub(crate) struct EnvGuard {
+        _lock: MutexGuard<'static, ()>,
+        saved: Vec<(String, Option<OsString>)>,
+        expected: Vec<(String, Option<OsString>)>,
+    }
+
+    /// Acquire the process-wide env lock. Poisoning is recovered so one failing
+    /// test does not cascade into every other env test.
+    pub(crate) fn env_guard() -> EnvGuard {
+        EnvGuard {
+            _lock: ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner()),
+            saved: Vec::new(),
+            expected: Vec::new(),
+        }
+    }
+
+    impl EnvGuard {
+        fn remember(&mut self, key: &str) {
+            if !self.saved.iter().any(|(k, _)| k == key) {
+                self.saved.push((key.to_string(), std::env::var_os(key)));
+            }
+        }
+
+        fn expect(&mut self, key: &str, value: Option<OsString>) {
+            match self.expected.iter_mut().find(|(k, _)| k == key) {
+                Some(slot) => slot.1 = value,
+                None => self.expected.push((key.to_string(), value)),
+            }
+        }
+
+        /// Set `key`, then assert the write is observable — so a stolen variable
+        /// is a LOUD failure instead of a silent write to the real `$HOME`.
+        pub(crate) fn set(&mut self, key: &str, value: impl AsRef<OsStr>) -> &mut Self {
+            let value = value.as_ref().to_os_string();
+            self.remember(key);
+            // SAFETY: ENV_LOCK is held for this guard's whole lifetime, so no
+            // other test thread of this binary reads or writes env concurrently.
+            unsafe { std::env::set_var(key, &value) };
+            self.expect(key, Some(value));
+            self.assert_intact();
+            self
+        }
+
+        /// Unset `key` and assert it stays unset.
+        pub(crate) fn remove(&mut self, key: &str) -> &mut Self {
+            self.remember(key);
+            // SAFETY: as in `set` — serialized by ENV_LOCK.
+            unsafe { std::env::remove_var(key) };
+            self.expect(key, None);
+            self.assert_intact();
+            self
+        }
+
+        /// Panic if any variable this guard wrote has changed value since.
+        ///
+        /// This is the escape detector: if some future test mutates `HOME`
+        /// without taking [`ENV_LOCK`], the test that owns the guard fails with
+        /// a precise message instead of writing into the real home directory.
+        pub(crate) fn assert_intact(&self) {
+            for (key, want) in &self.expected {
+                assert_eq!(
+                    &std::env::var_os(key),
+                    want,
+                    "env var {key} changed underneath this guard: another test \
+                     mutated process-global env without holding the shared lock"
+                );
+            }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for (key, value) in self.saved.drain(..).rev() {
+                match value {
+                    // SAFETY: still holding ENV_LOCK; single-threaded here.
+                    Some(v) => unsafe { std::env::set_var(&key, v) },
+                    None => unsafe { std::env::remove_var(&key) },
+                }
+            }
+        }
+    }
+}
+
 const VERSION: &str = env!("CARGO_PKG_VERSION");
 
 fn main() {
@@ -2747,42 +2851,32 @@ mod serve_mode_tests {
         emit_serve_startup_debug, guard_indexable_root, select_serve_mode,
         should_run_daemon_services, should_run_serve_services,
     };
+    use crate::test_env::env_guard;
     use std::path::Path;
-    use std::sync::Mutex;
-
-    static ENV_LOCK: Mutex<()> = Mutex::new(());
 
     #[test]
     fn debug_enabled_honors_truthy_values_only() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let prev = std::env::var("CODEGRAPH_DEBUG").ok();
+        let mut env = env_guard();
 
-        unsafe { std::env::remove_var("CODEGRAPH_DEBUG") };
+        env.remove("CODEGRAPH_DEBUG");
         assert!(!debug_enabled(), "unset ⇒ off");
-        unsafe { std::env::set_var("CODEGRAPH_DEBUG", "1") };
+        env.set("CODEGRAPH_DEBUG", "1");
         assert!(debug_enabled(), "\"1\" ⇒ on");
-        unsafe { std::env::set_var("CODEGRAPH_DEBUG", "true") };
+        env.set("CODEGRAPH_DEBUG", "true");
         assert!(debug_enabled(), "\"true\" ⇒ on");
-        unsafe { std::env::set_var("CODEGRAPH_DEBUG", "0") };
+        env.set("CODEGRAPH_DEBUG", "0");
         assert!(!debug_enabled(), "\"0\" ⇒ off");
-        unsafe { std::env::set_var("CODEGRAPH_DEBUG", "yes") };
+        env.set("CODEGRAPH_DEBUG", "yes");
         assert!(!debug_enabled(), "any other value ⇒ off");
-
-        match prev {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_DEBUG", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_DEBUG") },
-        }
     }
 
     #[test]
     fn effective_log_level_translates_codegraph_debug_and_defers_to_rust_log() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let prev_debug = std::env::var("CODEGRAPH_DEBUG").ok();
-        let prev_rust_log = std::env::var("RUST_LOG").ok();
+        let mut env = env_guard();
 
         // Given RUST_LOG unset and CODEGRAPH_DEBUG unset: config level is used verbatim.
-        unsafe { std::env::remove_var("RUST_LOG") };
-        unsafe { std::env::remove_var("CODEGRAPH_DEBUG") };
+        env.remove("RUST_LOG");
+        env.remove("CODEGRAPH_DEBUG");
         assert_eq!(
             effective_log_level("info"),
             "info",
@@ -2790,7 +2884,7 @@ mod serve_mode_tests {
         );
 
         // When CODEGRAPH_DEBUG=1 and RUST_LOG unset: level bumps to debug (back-compat).
-        unsafe { std::env::set_var("CODEGRAPH_DEBUG", "1") };
+        env.set("CODEGRAPH_DEBUG", "1");
         assert_eq!(
             effective_log_level("info"),
             "debug",
@@ -2799,21 +2893,12 @@ mod serve_mode_tests {
 
         // When RUST_LOG is set: the base opens to trace so the EnvFilter is the
         // sole gate (the reload floor must not cap RUST_LOG upward).
-        unsafe { std::env::set_var("RUST_LOG", "warn") };
+        env.set("RUST_LOG", "warn");
         assert_eq!(
             effective_log_level("info"),
             "trace",
             "RUST_LOG set ⇒ base opens to trace; EnvFilter owns the gate"
         );
-
-        match prev_debug {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_DEBUG", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_DEBUG") },
-        }
-        match prev_rust_log {
-            Some(v) => unsafe { std::env::set_var("RUST_LOG", v) },
-            None => unsafe { std::env::remove_var("RUST_LOG") },
-        }
     }
 
     #[test]
@@ -2874,14 +2959,13 @@ mod serve_mode_tests {
 
     #[test]
     fn daemon_services_disabled_at_home_and_root_enabled_for_nested_project() {
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
 
         let tmp = std::env::temp_dir().join(format!("cg-serve-home-{}", std::process::id()));
         let nested = tmp.join("workspace/ProdDir/AI/codegraph-rust");
         std::fs::create_dir_all(&nested).unwrap();
-        unsafe { std::env::set_var(home_key, &tmp) };
+        env.set(home_key, &tmp);
 
         assert!(
             !should_run_daemon_services(&tmp),
@@ -2896,23 +2980,19 @@ mod serve_mode_tests {
             "a project nested under $HOME must keep daemon services"
         );
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
+        env.assert_intact();
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
     #[test]
     fn guard_indexable_root_rejects_home_and_root_allows_nested_project() {
-        let _lock = ENV_LOCK.lock().unwrap();
+        let mut env = env_guard();
         let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        let prev_home = std::env::var_os(home_key);
 
         let tmp = std::env::temp_dir().join(format!("cg-guard-home-{}", std::process::id()));
         let nested = tmp.join("workspace/proj");
         std::fs::create_dir_all(&nested).unwrap();
-        unsafe { std::env::set_var(home_key, &tmp) };
+        env.set(home_key, &tmp);
 
         assert!(
             guard_indexable_root(&tmp).is_err(),
@@ -2927,10 +3007,7 @@ mod serve_mode_tests {
             "a project nested under $HOME must be indexable"
         );
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var(home_key, v) },
-            None => unsafe { std::env::remove_var(home_key) },
-        }
+        env.assert_intact();
         let _ = std::fs::remove_dir_all(&tmp);
     }
 
@@ -5552,6 +5629,9 @@ mod pure_helper_tests {
 
     #[test]
     fn db_path_is_under_codegraph_dir() {
+        // Reads CODEGRAPH_DIR, which a sibling test unsets and restores, so it
+        // takes the same lock even though it never writes.
+        let _env = crate::test_env::env_guard();
         if std::env::var("CODEGRAPH_DIR").is_err() {
             let dir = tmp("dbpath");
             let canonical = dir.canonicalize().unwrap();
@@ -5675,34 +5755,23 @@ mod pure_helper_tests {
 
     #[test]
     fn env_path_none_for_empty_or_unset_some_for_value() {
+        let mut env = crate::test_env::env_guard();
         let key = "CODEGRAPH_TEST_ENV_PATH_UNSET_XYZ";
-        // SAFETY: the key is test-private and this test runs single-threaded within its own scope.
-        unsafe {
-            std::env::remove_var(key);
-        }
+        env.remove(key);
         assert_eq!(env_path(key), None);
-        unsafe {
-            std::env::set_var(key, "");
-        }
+        env.set(key, "");
         assert_eq!(env_path(key), None);
-        unsafe {
-            std::env::set_var(key, "/some/where");
-        }
+        env.set(key, "/some/where");
         assert_eq!(env_path(key), Some(PathBuf::from("/some/where")));
-        unsafe {
-            std::env::remove_var(key);
-        }
     }
 }
 
 #[cfg(test)]
 mod formatter_and_env_tests {
     use super::*;
+    use crate::test_env::env_guard;
     use codegraph_core::types::{FileRecord, Language, NodeKind};
 
-    // Serializes tests that mutate process-global env (cargo test runs them concurrently).
-    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
-
     fn tmp(tag: &str) -> PathBuf {
         let p = std::env::temp_dir().join(format!(
             "cg-cli-fmt-{tag}-{}-{}",
@@ -5737,9 +5806,8 @@ mod formatter_and_env_tests {
 
     #[test]
     fn codegraph_dir_and_db_path_default_layout() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let prev = std::env::var_os("CODEGRAPH_DIR");
-        unsafe { std::env::remove_var("CODEGRAPH_DIR") };
+        let mut env = env_guard();
+        env.remove("CODEGRAPH_DIR");
         let proj = tmp("default-layout");
         let canonical = proj.canonicalize().unwrap();
         assert_eq!(
@@ -5750,9 +5818,7 @@ mod formatter_and_env_tests {
             db_path(&proj).unwrap(),
             canonical.join(".codegraph-v2/codegraph.db")
         );
-        if let Some(v) = prev {
-            unsafe { std::env::set_var("CODEGRAPH_DIR", v) };
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(&proj);
     }
 
@@ -5989,31 +6055,20 @@ mod formatter_and_env_tests {
 
     #[test]
     fn home_dir_resolves_from_home_then_userprofile_then_errors() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
-        let prev_home = std::env::var_os("HOME");
-        let prev_up = std::env::var_os("USERPROFILE");
-        unsafe { std::env::set_var("HOME", "/home/tester") };
+        let mut env = env_guard();
+        env.set("HOME", "/home/tester");
         assert_eq!(home_dir().unwrap(), PathBuf::from("/home/tester"));
-        unsafe { std::env::remove_var("HOME") };
-        unsafe { std::env::remove_var("USERPROFILE") };
+        env.remove("HOME");
+        env.remove("USERPROFILE");
         assert!(home_dir().is_err());
-        if let Some(v) = prev_home {
-            unsafe { std::env::set_var("HOME", v) };
-        }
-        if let Some(v) = prev_up {
-            unsafe { std::env::set_var("USERPROFILE", v) };
-        }
     }
 
     #[test]
     fn completion_target_paths_per_shell() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
-        let prev_home = std::env::var_os("HOME");
-        let prev_xdg = std::env::var_os("XDG_DATA_HOME");
-        let prev_local = std::env::var_os("LOCALAPPDATA");
-        unsafe { std::env::set_var("HOME", "/h") };
-        unsafe { std::env::remove_var("XDG_DATA_HOME") };
-        unsafe { std::env::remove_var("LOCALAPPDATA") };
+        let mut env = env_guard();
+        env.set("HOME", "/h");
+        env.remove("XDG_DATA_HOME");
+        env.remove("LOCALAPPDATA");
 
         assert_eq!(
             completion_target(Shell::Bash).unwrap(),
@@ -6035,61 +6090,31 @@ mod formatter_and_env_tests {
             completion_target(Shell::Elvish).unwrap(),
             PathBuf::from("/h/.config/codegraph/completion.elv")
         );
-        unsafe { std::env::set_var("XDG_DATA_HOME", "/xdg") };
+        env.set("XDG_DATA_HOME", "/xdg");
         assert_eq!(
             completion_target(Shell::Bash).unwrap(),
             PathBuf::from("/xdg/bash-completion/completions/codegraph")
         );
-
-        if let Some(v) = prev_home {
-            unsafe { std::env::set_var("HOME", v) };
-        } else {
-            unsafe { std::env::remove_var("HOME") };
-        }
-        match prev_xdg {
-            Some(v) => unsafe { std::env::set_var("XDG_DATA_HOME", v) },
-            None => unsafe { std::env::remove_var("XDG_DATA_HOME") },
-        }
-        match prev_local {
-            Some(v) => unsafe { std::env::set_var("LOCALAPPDATA", v) },
-            None => unsafe { std::env::remove_var("LOCALAPPDATA") },
-        }
     }
 
     #[test]
     fn powershell_profile_path_override_then_userprofile_then_error() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
-        let prev_ps = std::env::var_os("CODEGRAPH_PS_PROFILE");
-        let prev_up = std::env::var_os("USERPROFILE");
-        let prev_home = std::env::var_os("HOME");
+        let mut env = env_guard();
 
-        unsafe { std::env::set_var("CODEGRAPH_PS_PROFILE", "/custom/profile.ps1") };
+        env.set("CODEGRAPH_PS_PROFILE", "/custom/profile.ps1");
         assert_eq!(
             powershell_profile_path().unwrap(),
             PathBuf::from("/custom/profile.ps1")
         );
-        unsafe { std::env::remove_var("CODEGRAPH_PS_PROFILE") };
-        unsafe { std::env::set_var("USERPROFILE", "/up") };
+        env.remove("CODEGRAPH_PS_PROFILE");
+        env.set("USERPROFILE", "/up");
         assert_eq!(
             powershell_profile_path().unwrap(),
             PathBuf::from("/up/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1")
         );
-        unsafe { std::env::remove_var("USERPROFILE") };
-        unsafe { std::env::remove_var("HOME") };
+        env.remove("USERPROFILE");
+        env.remove("HOME");
         assert!(powershell_profile_path().is_err());
-
-        match prev_ps {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_PS_PROFILE", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_PS_PROFILE") },
-        }
-        match prev_up {
-            Some(v) => unsafe { std::env::set_var("USERPROFILE", v) },
-            None => unsafe { std::env::remove_var("USERPROFILE") },
-        }
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var("HOME", v) },
-            None => unsafe { std::env::remove_var("HOME") },
-        }
     }
 
     #[test]
@@ -6116,16 +6141,13 @@ mod formatter_and_env_tests {
 
     #[test]
     fn http_log_path_lands_under_registry_dir() {
+        let mut env = env_guard();
         let dir = tmp("httplog");
-        let prev = std::env::var_os("CODEGRAPH_HTTP_REGISTRY_DIR");
-        unsafe { std::env::set_var("CODEGRAPH_HTTP_REGISTRY_DIR", &dir) };
+        env.set("CODEGRAPH_HTTP_REGISTRY_DIR", &dir);
         let p = http_log_path("127.0.0.1:8111");
         assert!(p.starts_with(&dir));
         assert!(p.extension().is_some_and(|e| e == "log"));
-        match prev {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_HTTP_REGISTRY_DIR", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_HTTP_REGISTRY_DIR") },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(&dir);
     }
 
@@ -6157,29 +6179,22 @@ mod formatter_and_env_tests {
             log_file: Some("/tmp/y.log".to_string()),
         };
         print_http_conflict(&info);
+        let mut env = env_guard();
         let dir = tmp("noteothers");
-        let prev = std::env::var_os("CODEGRAPH_HTTP_REGISTRY_DIR");
-        unsafe { std::env::set_var("CODEGRAPH_HTTP_REGISTRY_DIR", &dir) };
+        env.set("CODEGRAPH_HTTP_REGISTRY_DIR", &dir);
         note_other_running_servers("127.0.0.1:1234");
-        match prev {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_HTTP_REGISTRY_DIR", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_HTTP_REGISTRY_DIR") },
-        }
+        env.assert_intact();
         let _ = fs::remove_dir_all(&dir);
     }
 
     #[test]
     fn is_http_detach_internal_reads_env_marker() {
+        let mut env = env_guard();
         let key = codegraph_daemon::CODEGRAPH_HTTP_DETACH_INTERNAL;
-        let prev = std::env::var_os(key);
-        unsafe { std::env::remove_var(key) };
+        env.remove(key);
         assert!(!is_http_detach_internal());
-        unsafe { std::env::set_var(key, "1") };
+        env.set(key, "1");
         assert!(is_http_detach_internal());
-        match prev {
-            Some(v) => unsafe { std::env::set_var(key, v) },
-            None => unsafe { std::env::remove_var(key) },
-        }
     }
 
     #[test]
@@ -6199,70 +6214,58 @@ mod formatter_and_env_tests {
 
     #[test]
     fn install_completions_writes_zsh_fish_elvish_into_home() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let mut env = env_guard();
         let dir = tmp("install-comp");
-        let prev_home = std::env::var_os("HOME");
-        let prev_xdg = std::env::var_os("XDG_DATA_HOME");
-        unsafe { std::env::set_var("HOME", &dir) };
-        unsafe { std::env::remove_var("XDG_DATA_HOME") };
+        env.set("HOME", &dir);
+        env.remove("XDG_DATA_HOME");
 
+        // Every step re-asserts the guarded env BEFORE writing, so a stolen
+        // HOME fails here instead of installing into the real home directory.
+        env.assert_intact();
         install_completions(Shell::Zsh).unwrap();
         assert!(dir.join(".zfunc/_codegraph").is_file());
 
+        env.assert_intact();
         install_completions(Shell::Fish).unwrap();
         assert!(
             dir.join(".config/fish/completions/codegraph.fish")
                 .is_file()
         );
 
+        env.assert_intact();
         install_completions(Shell::Elvish).unwrap();
         let elv = dir.join(".config/codegraph/completion.elv");
         assert!(elv.is_file());
         assert!(fs::read_to_string(&elv).unwrap().contains("codegraph"));
 
+        env.assert_intact();
         install_completions(Shell::Bash).unwrap();
         assert!(
             dir.join(".local/share/bash-completion/completions/codegraph")
                 .is_file()
         );
 
-        match prev_home {
-            Some(v) => unsafe { std::env::set_var("HOME", v) },
-            None => unsafe { std::env::remove_var("HOME") },
-        }
-        match prev_xdg {
-            Some(v) => unsafe { std::env::set_var("XDG_DATA_HOME", v) },
-            None => unsafe { std::env::remove_var("XDG_DATA_HOME") },
-        }
         let _ = fs::remove_dir_all(&dir);
     }
 
     #[test]
     fn install_completions_powershell_writes_script_and_dot_sources_profile() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let mut env = env_guard();
         let dir = tmp("install-ps");
-        let prev_local = std::env::var_os("LOCALAPPDATA");
-        let prev_ps = std::env::var_os("CODEGRAPH_PS_PROFILE");
         let profile = dir.join("profile.ps1");
-        unsafe { std::env::set_var("LOCALAPPDATA", &dir) };
-        unsafe { std::env::set_var("CODEGRAPH_PS_PROFILE", &profile) };
+        env.set("LOCALAPPDATA", &dir);
+        env.set("CODEGRAPH_PS_PROFILE", &profile);
 
+        env.assert_intact();
         install_completions(Shell::PowerShell).unwrap();
         let script = dir.join("codegraph/completion.ps1");
         assert!(script.is_file());
+        env.assert_intact();
         install_completions(Shell::PowerShell).unwrap();
         let line = format!(". \"{}\"", script.display());
         let body = fs::read_to_string(&profile).unwrap();
         assert_eq!(body.lines().filter(|l| l.trim() == line).count(), 1);
 
-        match prev_local {
-            Some(v) => unsafe { std::env::set_var("LOCALAPPDATA", v) },
-            None => unsafe { std::env::remove_var("LOCALAPPDATA") },
-        }
-        match prev_ps {
-            Some(v) => unsafe { std::env::set_var("CODEGRAPH_PS_PROFILE", v) },
-            None => unsafe { std::env::remove_var("CODEGRAPH_PS_PROFILE") },
-        }
         let _ = fs::remove_dir_all(&dir);
     }
 }
diff --git a/crates/codegraph-watch/src/lib.rs b/crates/codegraph-watch/src/lib.rs
index f09328e..3e5bbf5 100644
--- a/crates/codegraph-watch/src/lib.rs
+++ b/crates/codegraph-watch/src/lib.rs
@@ -23,3 +23,98 @@ pub use worktree::{
     WorktreeIndexMismatch, detect_worktree_index_mismatch, git_worktree_root,
     worktree_mismatch_notice, worktree_mismatch_warning,
 };
+
+/// Test-only: the ONE process-wide environment lock for this crate.
+///
+/// `HOME`, `CODEGRAPH_NO_WATCH`, and `CODEGRAPH_FORCE_WATCH` are process-global,
+/// and `cargo test` runs this crate's unit tests as threads of ONE process. The
+/// `policy` tests mutate all three; the `watcher` tests call
+/// `ProjectWatcher::start`, which READS them through `watch_disabled_reason` and
+/// returns `Ok(None)` when they say "don't watch". A watcher test that does not
+/// hold this lock can therefore observe another test's `CODEGRAPH_NO_WATCH=1`
+/// and get `None` back. Both sides must go through [`test_env::env_guard`].
+#[cfg(test)]
+pub(crate) mod test_env {
+    use std::ffi::{OsStr, OsString};
+    use std::sync::{Mutex, MutexGuard};
+
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    pub(crate) struct EnvGuard {
+        _lock: MutexGuard<'static, ()>,
+        saved: Vec<(String, Option<OsString>)>,
+        expected: Vec<(String, Option<OsString>)>,
+    }
+
+    pub(crate) fn env_guard() -> EnvGuard {
+        EnvGuard {
+            _lock: ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner()),
+            saved: Vec::new(),
+            expected: Vec::new(),
+        }
+    }
+
+    impl EnvGuard {
+        fn remember(&mut self, key: &str) {
+            if !self.saved.iter().any(|(k, _)| k == key) {
+                self.saved.push((key.to_string(), std::env::var_os(key)));
+            }
+        }
+
+        fn expect(&mut self, key: &str, value: Option<OsString>) {
+            match self.expected.iter_mut().find(|(k, _)| k == key) {
+                Some(slot) => slot.1 = value,
+                None => self.expected.push((key.to_string(), value)),
+            }
+        }
+
+        pub(crate) fn set(&mut self, key: &str, value: impl AsRef<OsStr>) -> &mut Self {
+            let value = value.as_ref().to_os_string();
+            self.remember(key);
+            // SAFETY: ENV_LOCK is held for this guard's whole lifetime, so no
+            // other test thread of this crate reads or writes env concurrently.
+            unsafe { std::env::set_var(key, &value) };
+            self.expect(key, Some(value));
+            self.assert_intact();
+            self
+        }
+
+        pub(crate) fn remove(&mut self, key: &str) -> &mut Self {
+            self.remember(key);
+            // SAFETY: as in `set` — serialized by ENV_LOCK.
+            unsafe { std::env::remove_var(key) };
+            self.expect(key, None);
+            self.assert_intact();
+            self
+        }
+
+        /// Panic if a variable this guard wrote changed underneath it — the
+        /// escape detector for an unlocked env mutation elsewhere.
+        pub(crate) fn assert_intact(&self) {
+            for (key, want) in &self.expected {
+                assert_eq!(
+                    &std::env::var_os(key),
+                    want,
+                    "env var {key} changed underneath this guard: another test \
+                     mutated process-global env without holding the shared lock"
+                );
+            }
+        }
+
+        pub(crate) fn home_key() -> &'static str {
+            if cfg!(windows) { "USERPROFILE" } else { "HOME" }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for (key, value) in self.saved.drain(..).rev() {
+                match value {
+                    // SAFETY: still holding ENV_LOCK; single-threaded here.
+                    Some(v) => unsafe { std::env::set_var(&key, v) },
+                    None => unsafe { std::env::remove_var(&key) },
+                }
+            }
+        }
+    }
+}
diff --git a/crates/codegraph-watch/src/policy.rs b/crates/codegraph-watch/src/policy.rs
index 25537cf..ef20b2f 100644
--- a/crates/codegraph-watch/src/policy.rs
+++ b/crates/codegraph-watch/src/policy.rs
@@ -485,51 +485,15 @@ fn is_windows_drive_mount(path: &Path) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::sync::Mutex;
-
-    static ENV_LOCK: Mutex<()> = Mutex::new(());
-
-    struct EnvGuard {
-        home: Option<std::ffi::OsString>,
-        force: Option<std::ffi::OsString>,
-        no_watch: Option<std::ffi::OsString>,
-    }
-
-    impl EnvGuard {
-        fn capture() -> Self {
-            Self {
-                home: std::env::var_os(if cfg!(windows) { "USERPROFILE" } else { "HOME" }),
-                force: std::env::var_os("CODEGRAPH_FORCE_WATCH"),
-                no_watch: std::env::var_os(CODEGRAPH_NO_WATCH),
-            }
-        }
-    }
-
-    impl Drop for EnvGuard {
-        fn drop(&mut self) {
-            let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-            restore(home_key, self.home.take());
-            restore("CODEGRAPH_FORCE_WATCH", self.force.take());
-            restore(CODEGRAPH_NO_WATCH, self.no_watch.take());
-        }
-    }
-
-    fn restore(key: &str, value: Option<std::ffi::OsString>) {
-        match value {
-            Some(v) => unsafe { std::env::set_var(key, v) },
-            None => unsafe { std::env::remove_var(key) },
-        }
-    }
+    use crate::test_env::{EnvGuard, env_guard};
 
     #[test]
     fn watch_disabled_when_root_is_home() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("watch-policy-home");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
-        unsafe { std::env::remove_var("CODEGRAPH_FORCE_WATCH") };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        env.set(EnvGuard::home_key(), home.path());
+        env.remove("CODEGRAPH_FORCE_WATCH");
+        env.remove(CODEGRAPH_NO_WATCH);
 
         let reason = watch_disabled_reason(home.path(), false);
         assert!(reason.is_some(), "watching HOME must be disabled");
@@ -538,13 +502,11 @@ mod tests {
 
     #[test]
     fn watch_disabled_for_home_even_with_force_watch() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("watch-policy-home-force");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
-        unsafe { std::env::set_var("CODEGRAPH_FORCE_WATCH", "1") };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        env.set(EnvGuard::home_key(), home.path());
+        env.set("CODEGRAPH_FORCE_WATCH", "1");
+        env.remove(CODEGRAPH_NO_WATCH);
 
         assert!(
             watch_disabled_reason(home.path(), false).is_some(),
@@ -554,10 +516,9 @@ mod tests {
 
     #[test]
     fn watch_disabled_when_root_is_filesystem_root() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
-        unsafe { std::env::remove_var("CODEGRAPH_FORCE_WATCH") };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        let mut env = env_guard();
+        env.remove("CODEGRAPH_FORCE_WATCH");
+        env.remove(CODEGRAPH_NO_WATCH);
 
         let reason = watch_disabled_reason(Path::new("/"), false);
         assert!(reason.is_some(), "watching `/` must be disabled");
@@ -566,13 +527,11 @@ mod tests {
 
     #[test]
     fn watch_allowed_for_normal_project_subdir() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("watch-policy-subdir-home");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
-        unsafe { std::env::remove_var("CODEGRAPH_FORCE_WATCH") };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        env.set(EnvGuard::home_key(), home.path());
+        env.remove("CODEGRAPH_FORCE_WATCH");
+        env.remove(CODEGRAPH_NO_WATCH);
 
         let project = home.path().join("workspace/proj");
         fs::create_dir_all(&project).unwrap();
@@ -625,11 +584,9 @@ mod tests {
 
     #[test]
     fn too_broad_reason_flags_home_and_filesystem_root_but_not_nested_project() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("too-broad-home");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
+        env.set(EnvGuard::home_key(), home.path());
 
         assert!(
             too_broad_root_reason(home.path()).is_some(),
@@ -650,11 +607,9 @@ mod tests {
 
     #[test]
     fn too_broad_reason_normalizes_trailing_dot_to_home() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("too-broad-home-dot");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
+        env.set(EnvGuard::home_key(), home.path());
 
         let with_dot = home.path().join(".");
         assert!(
@@ -665,13 +620,11 @@ mod tests {
 
     #[test]
     fn watch_disabled_when_root_is_home_with_trailing_dot() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let home = crate::sync::tests::TestDir::new("watch-policy-home-dot");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, home.path()) };
-        unsafe { std::env::remove_var("CODEGRAPH_FORCE_WATCH") };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        env.set(EnvGuard::home_key(), home.path());
+        env.remove("CODEGRAPH_FORCE_WATCH");
+        env.remove(CODEGRAPH_NO_WATCH);
 
         let with_dot = home.path().join(".");
         assert!(
@@ -682,10 +635,9 @@ mod tests {
 
     #[test]
     fn watch_disabled_when_no_watch_flag_is_set() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let project = crate::sync::tests::TestDir::new("watch-policy-flag");
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
+        env.remove(CODEGRAPH_NO_WATCH);
 
         // The explicit `no_watch` parameter wins even for a normal project dir.
         let reason = watch_disabled_reason(project.path(), true);
@@ -694,10 +646,9 @@ mod tests {
 
     #[test]
     fn watch_disabled_when_no_watch_env_is_set() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let project = crate::sync::tests::TestDir::new("watch-policy-env");
-        unsafe { std::env::set_var(CODEGRAPH_NO_WATCH, "1") };
+        env.set(CODEGRAPH_NO_WATCH, "1");
 
         let reason = watch_disabled_reason(project.path(), false);
         assert_eq!(reason.as_deref(), Some("CODEGRAPH_NO_WATCH=1 is set"));
@@ -843,13 +794,11 @@ mod tests {
 
     #[test]
     fn force_watch_re_enables_a_wsl_drive_mount_path() {
-        let _lock = ENV_LOCK.lock().unwrap();
-        let _guard = EnvGuard::capture();
+        let mut env = env_guard();
         let project = crate::sync::tests::TestDir::new("watch-policy-force");
-        let home_key = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
-        unsafe { std::env::set_var(home_key, project.path()) };
-        unsafe { std::env::remove_var(CODEGRAPH_NO_WATCH) };
-        unsafe { std::env::set_var("CODEGRAPH_FORCE_WATCH", "1") };
+        env.set(EnvGuard::home_key(), project.path());
+        env.remove(CODEGRAPH_NO_WATCH);
+        env.set("CODEGRAPH_FORCE_WATCH", "1");
 
         // A normal (non-home, non-root) project with FORCE_WATCH set returns
         // None — the force escape short-circuits the WSL/mount check below it.
diff --git a/crates/codegraph-watch/src/watcher.rs b/crates/codegraph-watch/src/watcher.rs
index 378f0bb..c7a08c3 100644
--- a/crates/codegraph-watch/src/watcher.rs
+++ b/crates/codegraph-watch/src/watcher.rs
@@ -1123,6 +1123,7 @@ mod tests {
 
     #[test]
     fn rapid_save_burst_triggers_exactly_one_reindex() {
+        let _env = crate::test_env::env_guard();
         let dir = crate::sync::tests::TestDir::new("watch-debounce");
         fs::create_dir_all(dir.path().join("src")).unwrap();
         let db = crate::sync::default_db_path(dir.path()).unwrap();
@@ -1172,6 +1173,7 @@ mod tests {
 
     #[test]
     fn deleted_directory_event_schedules_one_full_sync() {
+        let _env = crate::test_env::env_guard();
         // A removed DIRECTORY has no source extension, so extension-based event
         // filtering drops it and every tracked descendant lingers in the index
         // forever. The watcher must escalate the removal to exactly ONE
@@ -1353,6 +1355,7 @@ mod tests {
 
     #[test]
     fn real_watcher_classifies_a_removed_directory_as_a_full_sync() {
+        let _env = crate::test_env::env_guard();
         // End-to-end with a REAL notify watcher: proves the OS actually delivers
         // either an explicit Folder removal or Windows' ambiguous Any removal,
         // and that the watcher escalates the known directory to a full sync.
@@ -1403,6 +1406,7 @@ mod tests {
 
     #[test]
     fn directory_removal_burst_deduplicates_to_one_full_sync() {
+        let _env = crate::test_env::env_guard();
         // A `rm -rf` burst surfaces the folder removal AND each child removal.
         // The full-sync escalation must dominate the per-file paths yet still
         // collapse to ONE sync, with every event path retained as a trigger.
@@ -1477,6 +1481,7 @@ mod tests {
 
     #[test]
     fn removed_ignored_directory_does_not_schedule_a_full_sync() {
+        let _env = crate::test_env::env_guard();
         // The escalation honors the watch policy: an ignored directory removal
         // is still dropped, so no sync is scheduled at all.
         let dir = crate::sync::tests::TestDir::new("watch-deleted-dir-ignored");
@@ -1506,6 +1511,7 @@ mod tests {
 
     #[test]
     fn ignored_directory_event_does_not_schedule_reindex() {
+        let _env = crate::test_env::env_guard();
         let dir = crate::sync::tests::TestDir::new("watch-ignore");
         fs::create_dir_all(dir.path().join("node_modules/pkg")).unwrap();
         fs::write(
@@ -1579,6 +1585,7 @@ mod tests {
 
     #[test]
     fn start_returns_none_when_watch_disabled_by_flag() {
+        let _env = crate::test_env::env_guard();
         let dir = crate::sync::tests::TestDir::new("watch-nowatch-flag");
         let watcher = ProjectWatcher::start(
             dir.path(),
@@ -1774,6 +1781,7 @@ mod tests {
 
     #[test]
     fn fresh_watcher_is_not_degraded_and_has_no_reason() {
+        let _env = crate::test_env::env_guard();
         // Given: an inert watcher that never hits a backend error.
         let dir = crate::sync::tests::TestDir::new("watch-not-degraded");
         let watcher = ProjectWatcher::start(
@@ -1794,6 +1802,7 @@ mod tests {
 
     #[test]
     fn start_serve_watcher_returns_none_when_watching_is_disabled() {
+        let _env = crate::test_env::env_guard();
         // Given: a normal project but the no_watch flag forced on.
         let dir = crate::sync::tests::TestDir::new("watch-serve-disabled");
         // Then: the public wrapper returns Ok(None) (no watcher started).
@@ -1814,6 +1823,7 @@ mod tests {
 
     #[test]
     fn start_serve_watcher_starts_an_inert_watcher_for_a_normal_project() {
+        let _env = crate::test_env::env_guard();
         // Given: a normal project directory.
         let dir = crate::sync::tests::TestDir::new("watch-serve-start");
         // Then: the public wrapper starts and returns an inert watcher.
@@ -1832,6 +1842,7 @@ mod tests {
 
     #[test]
     fn pending_files_snapshot_reflects_ingested_events_before_debounce() {
+        let _env = crate::test_env::env_guard();
         // Given: an inert watcher with a long debounce so events stay pending.
         let dir = crate::sync::tests::TestDir::new("watch-pending");
         fs::create_dir_all(dir.path().join("src")).unwrap();
@@ -1882,6 +1893,7 @@ mod tests {
     /// "still running" is deterministic rather than timed.
     #[test]
     fn begin_shutdown_and_detach_never_block_on_a_running_sync() {
+        let _env = crate::test_env::env_guard();
         let dir = crate::sync::tests::TestDir::new("watch-running-sync");
         let release = Arc::new(std::sync::Barrier::new(2));
         let entered = Arc::new(AtomicBool::new(false));
@@ -1930,6 +1942,7 @@ mod tests {
 
     #[test]
     fn begin_shutdown_is_nonblocking_and_detach_skips_the_join() {
+        let _env = crate::test_env::env_guard();
         // Given: an inert watcher whose event loop is idle.
         let dir = crate::sync::tests::TestDir::new("watch-begin-shutdown");
         let watcher = ProjectWatcher::start(
@@ -1965,6 +1978,7 @@ mod tests {
 
     #[test]
     fn event_loop_reports_non_degrading_sync_error_through_callback() {
+        let _env = crate::test_env::env_guard();
         // Given: an inert watcher whose injected sync_fn always fails with a
         // non-contention error, plus recorders for both notice callbacks.
         let dir = crate::sync::tests::TestDir::new("watch-loop-error");
@@ -2017,6 +2031,7 @@ mod tests {
 
     #[test]
     fn event_loop_disables_auto_sync_after_persistent_errors() {
+        let _env = crate::test_env::env_guard();
         // #1127: an injected sync_fn that always fails with the SAME
         // non-contention error must, after MAX_CONSECUTIVE_SYNC_ERRORS flushes,
         // degrade the watcher with an actionable message and stop retrying.
@@ -2301,6 +2316,7 @@ mod tests {
 
     #[test]
     fn editing_a_real_source_file_still_triggers_sync() {
+        let _env = crate::test_env::env_guard();
         // End-to-end with a REAL notify watcher (inert_for_tests = false), proving
         // the per-dir NonRecursive registration still delivers source edits to the
         // sync pipeline. `sync_fn` is injected so no real index is needed.
@@ -2365,6 +2381,7 @@ mod tests {
 
     #[test]
     fn newly_created_source_dir_is_watched_after_start() {
+        let _env = crate::test_env::env_guard();
         // A directory created AFTER start must be picked up (Linux NonRecursive:
         // the event loop registers a watch on the create event) so edits inside
         // it sync without a server restart.
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index d866274..07e4dbd 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -8005,3 +8005,287 @@ shared by starters and cleaners, or the stale cleanup moved inside
 `start_or_attach_gated` (`crates/codegraph-daemon/src/lib.rs:291`) so it runs only
 once the new pid record is held. Neither is a documentation change, and neither
 was attempted here.
+
+## Release blocker — the two `install_completions` / `removed_ignored_directory` failures were NOT unfixable flakes; they were one lock defect, now fixed (2026-07-29)
+
+**This section supersedes every earlier characterisation of these two failures in
+this ledger as "pre-existing", "known", "in-process `HOME`/`XDG_DATA_HOME` race",
+or otherwise unfixable environment flakes** (see the notes near the F1 and F4 gate
+tables above, and the run-1 note at `make ci` run 1 of the F1 batch). That
+characterisation was wrong. Both failures had a determinate root cause — test code
+that mutated process-global environment variables while holding mutexes that did
+not exclude each other — and a determinate fix. No production code was involved in
+either failure, and none was changed to fix them.
+
+### The defect: two DIFFERENT `ENV_LOCK` statics in one crate's test code
+
+`cargo test` runs every unit test of one binary/crate as THREADS OF A SINGLE
+PROCESS, so `HOME`, `XDG_DATA_HOME`, `USERPROFILE`, `LOCALAPPDATA`,
+`CODEGRAPH_NO_WATCH`, `CODEGRAPH_FORCE_WATCH` are shared mutable state. The CLI
+binary's test code declared THREE independent mutexes for that one piece of shared
+state (line numbers are the pre-fix `bb8097b` tree):
+
+| Static                                  | Declared at                                     | Used by tests at                             |
+| --------------------------------------- | ----------------------------------------------- | -------------------------------------------- |
+| `static ENV_LOCK: Mutex<()>`            | `crates/codegraph-cli/src/main.rs:2753`         | `main.rs:2757, 2779, 2877, 2908`             |
+| `static ENV_LOCK: std::sync::Mutex<()>` | `crates/codegraph-cli/src/main.rs:5704`         | `main.rs:5740, 5992, 6010, 6061, 6202, 6242` |
+| `static ENV_LOCK: Mutex<()>`            | `crates/codegraph-cli/src/installer/mod.rs:503` | `installer/mod.rs:592, 630, 780, 808`        |
+
+Distinct statics do not exclude each other AT ALL. A test in one group could set
+`HOME` to its temp dir while a test in another group was mid-way through its own
+`HOME` swap. Nothing in the code said "there is one env"; three separate comments
+each claimed their mutex serialized "tests that mutate process-global env".
+
+**And three env-mutating tests took NO lock at all**, including the `HOME` removal
+near the old `main.rs:6078`:
+
+- `main.rs:6117` `http_log_path_lands_under_registry_dir` — `CODEGRAPH_HTTP_REGISTRY_DIR`
+- `main.rs:6147` `print_http_conflict_and_note_others_isolated` — `CODEGRAPH_HTTP_REGISTRY_DIR`
+- `main.rs:6171` `is_http_detach_internal_reads_env_marker` — `CODEGRAPH_HTTP_DETACH_INTERNAL`
+
+(The unlocked `remove_var("HOME")` the triage flagged at `main.rs:6078` is inside
+`powershell_profile_path_override_then_userprofile_then_error`, which DID hold the
+`5704` lock at its line 6061 — but that lock did not exclude the `2753` group, so
+the effect was the same as being unlocked with respect to those four tests.)
+
+### The escape: the suite wrote into the developer's REAL home directory
+
+The failure is not merely a wrong assertion. Reproduced here on the untouched
+`bb8097b` tree, `cargo test --locked -q -p codegraph-rs --bin codegraph`, 12
+consecutive runs at default parallelism: **6 failed (exit 101), 6 passed** — runs
+2, 3, 6, 9, 10, 11 red, all at the same assertion:
+
+```
+thread 'formatter_and_env_tests::install_completions_writes_zsh_fish_elvish_into_home' panicked at crates/codegraph-cli/src/main.rs:6213:9:
+assertion failed: dir.join(".config/fish/completions/codegraph.fish").is_file()
+```
+
+The captured stdout of that test proves where the write actually landed:
+
+```
+Installed zsh completions to /tmp/cg-cli-fmt-install-comp-1713440-1785291188072/.zfunc/_codegraph
+Installed fish completions to /tmp/codegraph-installer-run-skill-1713440-1785291188076856474/home/.config/fish/completions/codegraph.fish
+```
+
+The zsh step wrote into ITS OWN temp `HOME`; by the fish step, `HOME` had been
+replaced by the `installer::tests` `run-skill` temp dir — a test holding a
+DIFFERENT mutex. So `install_completions` wrote a real file into whatever `HOME`
+happened to be at that instant. The same mechanism explains the earlier report of
+`Installed fish completions to /config/.config/fish/completions/codegraph.fish` —
+the REAL `$HOME` — when the interleaving landed between another test's restore and
+the next test's set.
+
+**Pollution outside the repository, recorded not deleted.**
+`/config/.config/fish/completions/codegraph.fish` exists on this host, 34177 bytes,
+mtime `2026-07-29 10:01:47 +0800`. It was created by an earlier run of this test
+suite escaping its temp `HOME`. It is OUTSIDE the repository, so it was left in
+place and is recorded here rather than removed.
+
+### The sibling defect in `codegraph-watch` — same root cause, fixed together
+
+`watcher::tests::removed_ignored_directory_does_not_schedule_a_full_sync` panicked
+at `watcher.rs:1499` unwrapping the `Option` from `ProjectWatcher::start`. Causal
+chain, all within one test process:
+
+1. `policy.rs`'s tests mutate `HOME`, `CODEGRAPH_NO_WATCH`, `CODEGRAPH_FORCE_WATCH`
+   under the `policy.rs:490` `ENV_LOCK`.
+2. `ProjectWatcher::start` (`watcher.rs:419-423`) calls
+   `watch_disabled_reason(&project_root, options.no_watch)`, which READS
+   `CODEGRAPH_NO_WATCH` (`policy.rs:282`) and `HOME` (`policy.rs:390`), returning
+   `Ok(None)` — no watcher — when they say "don't watch".
+3. The `watcher.rs` tests took NO lock, because they never write env. But they READ
+   it transitively, and `.unwrap()` on the returned `Option` turns "another test's
+   `CODEGRAPH_NO_WATCH=1` was visible" into a panic.
+
+Proof it is this and not something else: a positive control that widens the window
+without changing any assertion. Inserting a 6-second sleep after
+`unsafe { set_var(CODEGRAPH_NO_WATCH, "1") }` in
+`policy::tests::watch_disabled_when_no_watch_env_is_set`, then running only that
+test plus the watcher test:
+
+```
+cargo test --locked -q -p codegraph-watch --lib -- \
+  policy::tests::watch_disabled_when_no_watch_env_is_set \
+  watcher::tests::removed_ignored_directory_does_not_schedule_a_full_sync
+→ watcher::tests::removed_ignored_directory_does_not_schedule_a_full_sync --- FAILED
+  panicked at crates/codegraph-watch/src/watcher.rs:1499:10:
+  called `Option::unwrap()` on a `None` value
+  test result: FAILED. 1 passed; 1 failed
+```
+
+The sleep was a throwaway probe: `policy.rs` was restored from a pre-probe copy and
+verified byte-identical to `bb8097b` (`sha256
+a0cf200be0223631458d2f9fd2c7b2208f37f5a154f9eb03bd1bbc419d461274`, equal to
+`git show bb8097b:crates/codegraph-watch/src/policy.rs | sha256sum`). No sleep
+exists in the committed fix.
+
+### The fix — one lock per crate, an RAII guard, and an ACTIVE escape detector
+
+Test-only. `install_completions`, `completion_target`, `home_dir`,
+`powershell_profile_path`, `watch_disabled_reason`, `ProjectWatcher::start` and
+every other production path are byte-for-byte unchanged, as are the paths
+completions install to.
+
+- **One lock per test process.** `crates/codegraph-cli/src/main.rs` gains a
+  `#[cfg(test)] pub(crate) mod test_env` holding THE single `ENV_LOCK` for the
+  whole `codegraph` binary, reachable from `main.rs`'s five test modules AND from
+  `installer::tests` (a child module of the same binary). The three former statics
+  (`main.rs:2753`, `main.rs:5704`, `installer/mod.rs:503`) are deleted.
+  `crates/codegraph-watch/src/lib.rs` gains the same module for that crate's test
+  process; `policy.rs:490`'s static is deleted. Two processes, two locks — a lock
+  cannot span processes, so per-crate is the correct granularity, and each crate's
+  lock lives at the crate root where every test module can see it.
+- **RAII guard.** `env_guard()` returns an `EnvGuard` that holds the mutex for its
+  whole lifetime, records each variable's prior value on first touch, and restores
+  every one of them **in reverse order** on `Drop` — so a failing assertion cannot
+  leak a temp `HOME` into the rest of the suite. Poisoning is recovered
+  (`unwrap_or_else(|e| e.into_inner())`) so one failure does not cascade; that
+  removes the collateral `PoisonError` at the old `main.rs:5740` documented earlier
+  in this ledger.
+- **`assert_intact()` — the escape detector.** Every `set`/`remove` re-reads the
+  variable and asserts it equals what this guard wrote; the completions tests also
+  call it immediately BEFORE each `install_completions`. If any future test mutates
+  `HOME` without holding the lock, the guarded test fails LOUDLY with
+  `env var HOME changed underneath this guard: another test mutated process-global
+env without holding the shared lock` instead of silently writing into the real
+  home directory. This is what makes the escape impossible rather than unlikely.
+- **`EnvGuard::home_key()`** centralises the `USERPROFILE`-on-Windows /
+  `HOME`-elsewhere split that was duplicated at every call site. **This host is
+  Linux; the Windows branch is validated by code inspection only — no native
+  Windows/MSVC run was performed.**
+- **Read-only tests take the lock too.** `watcher.rs`'s 17 tests that call
+  `ProjectWatcher::start` / `start_serve_watcher`, and `main.rs`'s
+  `db_path_is_under_codegraph_dir` (reads `CODEGRAPH_DIR`), now hold the guard even
+  though they never write — reading shared state concurrently with a writer is the
+  same race.
+
+### Enumeration — every env-mutating test, before and after
+
+Produced by a script that walks each `#[test]`, collects `set_var`/`remove_var`
+calls and checks for a lock acquisition in the same body. All 28 pre-fix
+env-mutating tests, plus the read-only tests brought under the lock:
+
+| File:line (pre-fix)           | Test                                                                     | Keys mutated                                          | Before                   | After        |
+| ----------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------- | ------------------------ | ------------ |
+| `cli/main.rs:2755`            | `debug_enabled_honors_truthy_values_only`                                | `CODEGRAPH_DEBUG`                                     | lock A (`2753`)          | shared guard |
+| `cli/main.rs:2777`            | `effective_log_level_translates_codegraph_debug_and_defers_to_rust_log`  | `CODEGRAPH_DEBUG`, `RUST_LOG`                         | lock A                   | shared guard |
+| `cli/main.rs:2875`            | `daemon_services_disabled_at_home_and_root_enabled_for_nested_project`   | `HOME`/`USERPROFILE`                                  | lock A                   | shared guard |
+| `cli/main.rs:2906`            | `guard_indexable_root_rejects_home_and_root_allows_nested_project`       | `HOME`/`USERPROFILE`                                  | lock A                   | shared guard |
+| `cli/main.rs:5676`            | `env_path_none_for_empty_or_unset_some_for_value`                        | test-private key                                      | **none**                 | shared guard |
+| `cli/main.rs:5738`            | `codegraph_dir_and_db_path_default_layout`                               | `CODEGRAPH_DIR`                                       | lock B (`5704`)          | shared guard |
+| `cli/main.rs:5990`            | `home_dir_resolves_from_home_then_userprofile_then_errors`               | `HOME`, `USERPROFILE`                                 | lock B                   | shared guard |
+| `cli/main.rs:6008`            | `completion_target_paths_per_shell`                                      | `HOME`, `XDG_DATA_HOME`, `LOCALAPPDATA`               | lock B                   | shared guard |
+| `cli/main.rs:6059`            | `powershell_profile_path_override_then_userprofile_then_error`           | `CODEGRAPH_PS_PROFILE`, `USERPROFILE`, `HOME`         | lock B                   | shared guard |
+| `cli/main.rs:6117`            | `http_log_path_lands_under_registry_dir`                                 | `CODEGRAPH_HTTP_REGISTRY_DIR`                         | **none**                 | shared guard |
+| `cli/main.rs:6147`            | `print_http_conflict_and_note_others_isolated`                           | `CODEGRAPH_HTTP_REGISTRY_DIR`                         | **none**                 | shared guard |
+| `cli/main.rs:6171`            | `is_http_detach_internal_reads_env_marker`                               | `CODEGRAPH_HTTP_DETACH_INTERNAL`                      | **none**                 | shared guard |
+| `cli/main.rs:6200`            | `install_completions_writes_zsh_fish_elvish_into_home`                   | `HOME`, `XDG_DATA_HOME`                               | lock B                   | shared guard |
+| `cli/main.rs:6240`            | `install_completions_powershell_writes_script_and_dot_sources_profile`   | `CODEGRAPH_PS_PROFILE`, `LOCALAPPDATA`                | lock B                   | shared guard |
+| `cli/installer/mod.rs:589`    | `init_target_kiro_writes_project_local_mcp_with_concrete_path`           | `HOME`/`USERPROFILE`                                  | lock C (`503`)           | shared guard |
+| `cli/installer/mod.rs:627`    | `init_target_none_writes_nothing`                                        | `HOME`/`USERPROFILE`                                  | lock C                   | shared guard |
+| `cli/installer/mod.rs:778`    | `run_uninstall_with_ctx_via_public_paths`                                | `HOME`/`USERPROFILE`, `XDG_CONFIG_HOME`               | lock C                   | shared guard |
+| `cli/installer/mod.rs:806`    | `run_skill_install_and_uninstall_and_status_via_ctx`                     | `HOME`/`USERPROFILE`                                  | lock C                   | shared guard |
+| `watch/policy.rs:524`         | `watch_disabled_when_root_is_home`                                       | `HOME`, `CODEGRAPH_FORCE_WATCH`, `CODEGRAPH_NO_WATCH` | lock D (`policy.rs:490`) | shared guard |
+| `watch/policy.rs:539`         | `watch_disabled_for_home_even_with_force_watch`                          | same three                                            | lock D                   | shared guard |
+| `watch/policy.rs:555`         | `watch_disabled_when_root_is_filesystem_root`                            | `CODEGRAPH_FORCE_WATCH`, `CODEGRAPH_NO_WATCH`         | lock D                   | shared guard |
+| `watch/policy.rs:567`         | `watch_allowed_for_normal_project_subdir`                                | same three                                            | lock D                   | shared guard |
+| `watch/policy.rs:626`         | `too_broad_reason_flags_home_and_filesystem_root_but_not_nested_project` | `HOME`                                                | lock D                   | shared guard |
+| `watch/policy.rs:651`         | `too_broad_reason_normalizes_trailing_dot_to_home`                       | `HOME`                                                | lock D                   | shared guard |
+| `watch/policy.rs:666`         | `watch_disabled_when_root_is_home_with_trailing_dot`                     | same three                                            | lock D                   | shared guard |
+| `watch/policy.rs:683`         | `watch_disabled_when_no_watch_flag_is_set`                               | `CODEGRAPH_NO_WATCH`                                  | lock D                   | shared guard |
+| `watch/policy.rs:695`         | `watch_disabled_when_no_watch_env_is_set`                                | `CODEGRAPH_NO_WATCH`                                  | lock D                   | shared guard |
+| `watch/policy.rs:844`         | `force_watch_re_enables_a_wsl_drive_mount_path`                          | same three                                            | lock D                   | shared guard |
+| `watch/watcher.rs` (17 tests) | every test calling `ProjectWatcher::start` / `start_serve_watcher`       | reads `CODEGRAPH_NO_WATCH`, `HOME` transitively       | **none (reader)**        | shared guard |
+| `cli/main.rs:5553`            | `db_path_is_under_codegraph_dir`                                         | reads `CODEGRAPH_DIR`                                 | **none (reader)**        | shared guard |
+
+Post-fix grep confirms **zero** `set_var` / `remove_var` outside the two
+`test_env` modules in these files, and exactly one `ENV_LOCK` static per crate.
+
+Out of scope and deliberately untouched: the separate `ENV_LOCK`s in
+`codegraph-core`, `codegraph-daemon`, `codegraph-mcp`, `codegraph-store` and the
+integration-test binaries. Each is a DIFFERENT test process, so a lock there
+cannot interact with these two; none of them mutates `HOME`.
+
+### Negative control — the defect returns when the unification is reverted
+
+Re-introducing the two-lock defect (adding a second `ENV_LOCK_B` static and
+pointing the completions test at it, leaving everything else fixed), 4 runs at
+default parallelism: **run 1 RED, runs 2-4 green**:
+
+```
+assertion `left == right` failed: env var HOME changed underneath this guard:
+another test mutated process-global env without holding the shared lock
+test result: FAILED. 351 passed; 2 failed
+```
+
+Two things this proves. First, the defect is genuinely the two-lock split — undo
+only that and the failure returns. Second, it is PROBABILISTIC (1 red in 4), which
+is precisely why every earlier single green run "proved" nothing and why the
+failure was mis-filed as an environment flake for so long. `main.rs` was restored
+afterwards and verified (`7146875e689cedc4…`).
+
+Note also WHICH assertion reddened: not the old `is_file()` at `main.rs:6213`, but
+`assert_intact`'s message. The detector fires at the moment the variable is stolen,
+before any file is written — so even in the reverted state the suite no longer
+writes outside its temp dir silently.
+
+### Verification — every command with its REAL exit status
+
+| Command                                                                    | Exit         | Result                                                                                           |
+| -------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
+| `make ci CARGO='cargo --locked'` (pre-change reproduction)                 | 0            | passed on that attempt — the flake is probabilistic, hence the loops below                       |
+| `cargo test --locked -q -p codegraph-rs --bin codegraph` × 12 (pre-change) | 6× 0, 6× 101 | **defect reproduced**: runs 2,3,6,9,10,11 red at `main.rs:6213`                                  |
+| `cargo test --locked -q -p codegraph-watch --lib` × 15 (pre-change)        | 15× 0        | watcher defect did not surface unaided — hence the positive control                              |
+| positive control (6 s sleep probe, 2 tests only, pre-change)               | 101          | `watcher.rs:1499` `Option::unwrap()` on `None` — chain confirmed                                 |
+| `policy.rs` restored from pre-probe copy                                   | 0            | sha256 equals `git show bb8097b:…/policy.rs` — probe left no trace                               |
+| `cargo test --locked -q -p codegraph-rs --bin codegraph` × 8 (post-fix)    | 8× 0         | 353 passed each run                                                                              |
+| `cargo test --locked -q -p codegraph-watch --lib` (post-fix)               | 0            | 100 passed                                                                                       |
+| `cargo check --locked --workspace --all-targets`                           | 0            | clean                                                                                            |
+| 3 parallel post-fix rounds (`cli` + `watch`)                               | 0            | `cli 353/353`, `watch 100/100`, every round green                                                |
+| negative control (two-lock defect re-introduced) × 4                       | 1× 101, 3× 0 | **reddens**: `351 passed; 2 failed`, `assert_intact` message                                     |
+| `lsp_diagnostics`                                                          | n/a          | REFUSED in this worktree (`LSP file path must be inside request cwd`); fell back to locked Cargo |
+
+### Closeout — the first 5-run CI batch failed on a lint, not a test
+
+Reported rather than hidden. The FIRST batch of five `make ci CARGO='cargo --locked'`
+runs all exited **2**, every one at the `lint` target before any test ran:
+
+```
+error: items after a test module
+   --> crates/codegraph-watch/src/lib.rs:18:1
+    = note: `-D clippy::items-after-test-module` implied by `-D warnings`
+```
+
+`crates/codegraph-watch/src/lib.rs` had the new `#[cfg(test)] mod test_env` placed
+directly after the `mod` declarations and BEFORE the crate's `pub use` re-exports,
+which `clippy::items_after_test_module` forbids. Fixed by moving the module to the
+END of the file, after the last `pub use`. `codegraph-cli`'s `test_env` needed no
+move — `main.rs` has no trailing re-exports. Pure relocation: no logic, no test, no
+production line changed.
+
+| Command                                                             | Exit | Result                                            |
+| ------------------------------------------------------------------- | ---- | ------------------------------------------------- |
+| `make ci CARGO='cargo --locked'` (batch 1, runs 1-5)                | 5× 2 | FAILED at `lint` — `items_after_test_module`      |
+| `cargo clippy --locked -q --workspace --all-targets -- -D warnings` | 0    | clean after the relocation                        |
+| `cargo fmt --all --check`                                           | 0    | clean                                             |
+| `cargo test --locked -q -p codegraph-watch --lib`                   | 0    | 100 passed                                        |
+| `cargo test --locked -p codegraph-bench --test equivalence`         | 0    | **28 passed** — golden oracle unchanged           |
+| `make fmt`                                                          | 0    | oxfmt, 23 docs files, run BEFORE every CI batch   |
+| `bash scripts/check-workspace-versions.sh`                          | 0    | workspace / `version.txt` / manifest all `0.40.4` |
+| `make ci CARGO='cargo --locked'` (batch 2, run 1)                   | 0    | `✅ All CI checks passed!`                        |
+| `make ci CARGO='cargo --locked'` (batch 2, run 2)                   | 0    | `✅ All CI checks passed!`                        |
+| `make ci CARGO='cargo --locked'` (batch 2, run 3)                   | 0    | `✅ All CI checks passed!`                        |
+| `make ci CARGO='cargo --locked'` (batch 2, run 4)                   | 0    | `✅ All CI checks passed!`                        |
+| `make ci CARGO='cargo --locked'` (batch 2, run 5)                   | 0    | `✅ All CI checks passed!`                        |
+
+Five consecutive green runs at DEFAULT parallelism. `--test-threads=1` was never
+used, and neither `Makefile` nor `.cargo/config.toml` was touched — serializing the
+suite would have hidden the defect instead of fixing it. The `ETXTBSY`
+(`Text file busy`) flake noted earlier in this ledger did NOT recur in any of these
+runs.
+
+**Golden byte-stability.** `git diff --stat bb8097b..HEAD -- reference/golden/` is
+EMPTY; `git status --porcelain` showed no untracked
+`reference/golden/*/colby.db-{wal,shm}` after the batch. `Cargo.lock` SHA-256
+unchanged at `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+Six files changed: the five test-side sources plus this ledger.

From 0922230c9a0c6c2789c39b5c4d7d9d9a3362f8a6 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 11:41:00 +0800
Subject: [PATCH 69/91] fix(daemon): claim the rendezvous before healing its
 stale socket

---
 crates/codegraph-daemon/src/lock.rs       | 287 +++++++++++++++++++++-
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 245 ++++++++++++++++++
 2 files changed, 529 insertions(+), 3 deletions(-)

diff --git a/crates/codegraph-daemon/src/lock.rs b/crates/codegraph-daemon/src/lock.rs
index fad7da0..1c22cac 100644
--- a/crates/codegraph-daemon/src/lock.rs
+++ b/crates/codegraph-daemon/src/lock.rs
@@ -153,6 +153,22 @@ pub fn unlock_project(project_root: &Path) -> bool {
         .unwrap_or(false)
 }
 
+/// The mutation boundaries of [`clear_stale_daemon_socket`], exposed only so a
+/// test can drive a competing daemon start at an exact point with no timing
+/// assumption.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum StaleHealCheckpoint {
+    /// The stale (dead/absent-owner) pid record is gone and NOTHING is claimed:
+    /// the namespace is momentarily unowned and open to any starter. The socket
+    /// has not been touched.
+    StaleRecordCleared,
+    /// This cleaner WON the heal claim — its own pid record is published, so
+    /// every starter now reports `Taken`. The socket has not been touched.
+    HealClaimHeld,
+    /// The stale socket is gone; the heal claim is STILL published and still ours.
+    SocketRemoved,
+}
+
 /// Self-heal a project's stale daemon artifacts after a failed attach (Fix A):
 /// clears the pid lock AND removes the leftover `daemon.sock` at the RECORDED
 /// (fallback-aware) socket path, so the next `serve --mcp` spawns a fresh daemon
@@ -160,12 +176,58 @@ pub fn unlock_project(project_root: &Path) -> bool {
 ///
 /// Gated on liveness: returns `false` and touches nothing when the lock is held
 /// by a LIVE pid (`clear_stale_daemon_lock` refuses to remove a live lock).
-/// Returns `true` once the stale lock is cleared; socket removal is best-effort
-/// (a missing socket is already the desired end state).
+///
+/// OWNERSHIP IS LOAD-BEARING — this cleaner unlinks a socket it did not bind, so
+/// it must first BECOME the namespace's owner. The published pid record IS the
+/// single-instance exclusion token ([`try_acquire_daemon_lock`] claims it with
+/// `create_new`, and a daemon only ever binds after that claim succeeds). An
+/// earlier revision cleared the stale record and THEN unlinked, holding no token
+/// in between: a replacement daemon could legitimately claim the freed record and
+/// bind the same path, and this unlink then destroyed the LIVE replacement's
+/// socket — leaving a record naming a live daemon with no socket, which the
+/// liveness gate makes unhealable. Merely swapping the two deletions does not fix
+/// that, because an unlink performed while owning nothing is unsafe in either
+/// order.
+///
+/// So the sequence is claim-then-clean, and every step after the liveness gate is
+/// conditional on WINNING the claim:
+///
+/// 1. read the RECORDED socket (the record is the only place a fallback path is
+///    written down), then remove the stale record — liveness-gated, so a live
+///    owner's namespace is never entered;
+/// 2. re-claim the pid record via [`try_acquire_daemon_lock`], i.e. with the very
+///    same `create_new` token a starter uses. LOSING this claim means a
+///    replacement (or a competing cleaner) now owns the namespace, so this cleaner
+///    returns `false` and touches NOTHING — that is what closes the window rather
+///    than narrowing it;
+/// 3. unlink the stale socket while the claim excludes every starter, so no
+///    process can have bound that path in the meantime;
+/// 4. release the claim last, re-corroborated against our own pid
+///    ([`cleanup_owned_lock`]).
+///
+/// An ABSENT pid record is treated as an unowned namespace: `clear_stale_daemon_lock`
+/// reports it cleared, and step 2 then claims it, so the socket is still only ever
+/// removed under a held claim. A crash mid-heal leaves a record naming this
+/// now-dead process and no socket — exactly the self-healing residue the next
+/// heal clears.
+///
+/// On Windows the recorded "socket path" is a bare namespaced pipe name rather
+/// than a filesystem entry, so step 3's `remove_file` simply fails and is ignored
+/// (a pipe disappears with its owning process); steps 1, 2 and 4 operate on the
+/// real pid file and are what carry the exclusion there.
 pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
+    clear_stale_daemon_socket_with(project_root, |_| {})
+}
+
+fn clear_stale_daemon_socket_with(
+    project_root: &Path,
+    mut checkpoint: impl FnMut(StaleHealCheckpoint),
+) -> bool {
     let Ok(pid_path) = daemon_pid_path(project_root) else {
         return false;
     };
+    // Read the recorded socket BEFORE the stale record goes away: the record is
+    // the only place a bind-fallback path is written down.
     let Ok(socket_path) = recorded_socket_path(project_root) else {
         return false;
     };
@@ -173,8 +235,36 @@ pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
     if !clear_stale_daemon_lock(&pid_path, None) {
         return false;
     }
+    checkpoint(StaleHealCheckpoint::StaleRecordCleared);
+
+    // Become the owner before deleting anything in the namespace. A lost claim
+    // means somebody else owns it now; their socket is not ours to unlink.
+    let claim_pid = match try_acquire_daemon_lock(project_root) {
+        Ok(AcquireResult::Acquired { info, .. }) => info.pid,
+        Ok(AcquireResult::Taken { .. }) => {
+            debug!(
+                pid_path = %pid_path.display(),
+                "daemon rendezvous was re-claimed while healing; leaving its record and socket intact"
+            );
+            return false;
+        }
+        Err(err) => {
+            debug!(
+                pid_path = %pid_path.display(), error = %err,
+                "could not claim the daemon rendezvous for healing; leaving it untouched"
+            );
+            return false;
+        }
+    };
+    checkpoint(StaleHealCheckpoint::HealClaimHeld);
+
+    // Under the claim no starter can have bound this path, so the socket we see
+    // is provably the stale one.
     let _ = fs::remove_file(&socket_path);
-    true
+    checkpoint(StaleHealCheckpoint::SocketRemoved);
+
+    // Release the claim last, re-corroborated against our pid.
+    cleanup_owned_lock(&pid_path, claim_pid)
 }
 
 /// Whether the published pid record currently names `pid`.
@@ -683,6 +773,197 @@ mod tests {
         let _ = fs::remove_dir_all(&base);
     }
 
+    /// A dead pid whose record and socket are the stale residue to be healed.
+    fn dead_pid() -> u32 {
+        let mut candidate = 4_000_000_000u32;
+        while candidate == process::id() || is_process_alive(candidate) {
+            candidate -= 1;
+        }
+        candidate
+    }
+
+    fn publish_record(pid_path: &Path, pid: u32, socket: &Path) {
+        let info = DaemonLockInfo {
+            pid,
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            socket_path: socket.to_path_buf(),
+            started_at: 1,
+        };
+        fs::write(pid_path, encode_lock_info(&info).unwrap()).unwrap();
+    }
+
+    /// The rendezvous-ownership race. A replacement daemon legitimately claims the
+    /// namespace at the EXACT point where the stale record is gone and nothing is
+    /// owned, and binds the same socket path. The cleaner must lose its claim and
+    /// destroy nothing.
+    ///
+    /// Deterministic by construction: the replacement runs inside the checkpoint
+    /// callback, so it is ordered by the call itself, not by any sleep.
+    ///
+    /// Under the OLD clear-record-then-unlink order this test fails — the unlink
+    /// was unconditional, so it deleted the LIVE replacement's socket.
+    #[test]
+    fn a_replacement_start_during_the_stale_heal_keeps_its_own_socket() {
+        let base = temp_base("heal-replaced");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        publish_record(&pid_path, dead_pid(), &socket);
+        fs::write(&socket, b"stale").unwrap();
+
+        let mut replacement_ran = false;
+        let healed = clear_stale_daemon_socket_with(&base, |checkpoint| {
+            if checkpoint != StaleHealCheckpoint::StaleRecordCleared {
+                return;
+            }
+            // A replacement start wins the freed namespace here: it claims the
+            // record with its own LIVE pid and binds the same socket path.
+            replacement_ran = true;
+            publish_record(&pid_path, process::id(), &socket);
+            fs::write(&socket, b"live-replacement").unwrap();
+        });
+
+        assert!(replacement_ran, "the replacement ran at the checkpoint");
+        assert!(
+            socket.exists(),
+            "the LIVE replacement's socket must survive the stale heal"
+        );
+        assert_eq!(
+            fs::read(&socket).unwrap(),
+            b"live-replacement",
+            "the surviving socket must be the replacement's, not the stale one"
+        );
+        assert!(
+            !healed,
+            "a cleaner that lost the namespace must report that it healed nothing"
+        );
+        let surviving =
+            read_lock_info_tolerant(&pid_path).expect("the replacement record survives");
+        assert_eq!(
+            surviving.pid,
+            process::id(),
+            "the replacement's record must be left exactly as published"
+        );
+        let _ = fs::remove_dir_all(&base);
+    }
+
+    /// The claim is what makes the unlink safe, so it must be PUBLISHED across the
+    /// unlink and released only afterwards. While it is held every starter is
+    /// excluded, which is why no process can have bound the path being unlinked.
+    #[test]
+    fn the_stale_heal_holds_its_claim_across_the_unlink_and_releases_it_last() {
+        let base = temp_base("heal-claim");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        publish_record(&pid_path, dead_pid(), &socket);
+        fs::write(&socket, b"stale").unwrap();
+
+        let mut competing_start = None;
+        let mut saw_socket_removed = false;
+        let healed = clear_stale_daemon_socket_with(&base, |checkpoint| match checkpoint {
+            StaleHealCheckpoint::HealClaimHeld => {
+                let claim =
+                    read_lock_info_tolerant(&pid_path).expect("the heal claim is published");
+                assert_eq!(
+                    claim.pid,
+                    process::id(),
+                    "the heal claim must name this cleaner"
+                );
+                assert!(socket.exists(), "the socket is untouched under the claim");
+                competing_start =
+                    Some(try_acquire_daemon_lock(&base).expect("competing start under the claim"));
+            }
+            StaleHealCheckpoint::SocketRemoved => {
+                saw_socket_removed = true;
+                assert!(
+                    !socket.exists(),
+                    "the stale socket is gone at this boundary"
+                );
+                assert!(
+                    pid_path.exists(),
+                    "the heal claim must STILL be published while the socket is unlinked"
+                );
+            }
+            StaleHealCheckpoint::StaleRecordCleared => {}
+        });
+
+        match competing_start.expect("a competing start ran under the claim") {
+            AcquireResult::Taken { existing, .. } => {
+                let existing = existing.expect("the heal claim is readable");
+                assert_eq!(
+                    existing.pid,
+                    process::id(),
+                    "a starter racing the heal must be refused BY the heal claim, so it \
+                     cannot bind the socket the cleaner is about to unlink"
+                );
+            }
+            AcquireResult::Acquired { .. } => panic!(
+                "a starter must NOT be able to claim the namespace while the cleaner holds \
+                 its heal claim"
+            ),
+        }
+        assert!(saw_socket_removed);
+        assert!(healed, "a genuinely stale namespace heals");
+        assert!(!pid_path.exists(), "the heal claim is released last");
+        let _ = fs::remove_dir_all(&base);
+    }
+
+    /// Stale recovery still works: a dead owner's record AND socket are both gone
+    /// after the heal, so the next start spawns fresh.
+    #[test]
+    fn a_genuinely_stale_namespace_still_self_heals_both_artifacts() {
+        let base = temp_base("heal-stale");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        publish_record(&pid_path, dead_pid(), &socket);
+        fs::write(&socket, b"stale").unwrap();
+
+        assert!(clear_stale_daemon_socket(&base), "the stale residue heals");
+        assert!(!pid_path.exists(), "the stale record is gone");
+        assert!(!socket.exists(), "the stale socket is gone");
+        let AcquireResult::Acquired { .. } =
+            try_acquire_daemon_lock(&base).expect("post-heal acquire")
+        else {
+            panic!("a healed namespace must be claimable by a fresh start");
+        };
+        let _ = fs::remove_dir_all(&base);
+    }
+
+    /// An ABSENT record means nobody owns the namespace, so a leftover socket may
+    /// be removed — but only after the cleaner has CLAIMED that namespace, exactly
+    /// as it does for a dead-owner record. Without the claim, an absent record
+    /// would be the widest interleaving of all: it names no pid to prove dead, so
+    /// an unlink under it could hit a daemon that bound between the two syscalls.
+    #[test]
+    fn an_absent_record_is_claimed_before_its_leftover_socket_is_removed() {
+        let base = temp_base("heal-absent");
+        create_rendezvous_dir(&base);
+        let pid_path = pid_path_of(&base);
+        let socket = socket_path_of(&base);
+        fs::write(&socket, b"orphan").unwrap();
+        assert!(!pid_path.exists(), "precondition: no record at all");
+
+        let mut claim_held_with_socket_present = false;
+        let healed = clear_stale_daemon_socket_with(&base, |checkpoint| {
+            if checkpoint == StaleHealCheckpoint::HealClaimHeld {
+                claim_held_with_socket_present =
+                    record_names(&pid_path, process::id()) && socket.exists();
+            }
+        });
+
+        assert!(
+            claim_held_with_socket_present,
+            "the leftover socket must still be present at the moment the claim is won, \
+             proving the removal happens UNDER the claim and not before it"
+        );
+        assert!(healed, "an unowned namespace with a leftover socket heals");
+        assert!(!socket.exists(), "the orphaned socket is removed");
+        assert!(!pid_path.exists(), "the heal claim is released");
+        let _ = fs::remove_dir_all(&base);
+    }
+
     #[test]
     fn clear_stale_daemon_socket_removes_lock_and_socket_when_dead() {
         let base = temp_base("socket-dead");
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 07e4dbd..51278a7 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -8289,3 +8289,248 @@ EMPTY; `git status --porcelain` showed no untracked
 `reference/golden/*/colby.db-{wal,shm}` after the batch. `Cargo.lock` SHA-256
 unchanged at `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
 Six files changed: the five test-side sources plus this ledger.
+
+## Correction to the F2 DEFERRED record — the stale-heal rendezvous ownership race is now FIXED (2026-07-29)
+
+**This section supersedes the status line of "F2 round-two finding, recorded as
+DEFERRED: the stale-heal path deletes the pid record before the socket" above.**
+That section's technical account remains accurate and is deliberately left
+in place as the historical record; only its verdict changed. It said
+"**Status: NOT fixed in this release.**" The user has since explicitly
+authorized the repair, so the defect it describes is now fixed on this branch.
+Its "out of scope because it predates the branch" adjudication no longer holds.
+
+### The defect, re-confirmed against the pre-fix tree
+
+`clear_stale_daemon_socket` at `4f910f2`, `crates/codegraph-daemon/src/lock.rs:165-178`:
+
+```rust
+pub fn clear_stale_daemon_socket(project_root: &Path) -> bool {
+    let Ok(pid_path) = daemon_pid_path(project_root) else { return false; };
+    let Ok(socket_path) = recorded_socket_path(project_root) else { return false; };
+    // Liveness gate: only proceed once the owning pid is proven dead/absent.
+    if !clear_stale_daemon_lock(&pid_path, None) {
+        return false;
+    }
+    let _ = fs::remove_file(&socket_path);
+    true
+}
+```
+
+The published pid record IS the single-instance exclusion token:
+`try_acquire_daemon_lock` (`lock.rs:83-101`) claims it with `create_new`, and a
+daemon binds its socket only after that claim succeeds. `clear_stale_daemon_lock`
+(`lock.rs:126-146`) DELETES that record as its side effect. Between
+`lock.rs:173` and `lock.rs:176` the namespace is therefore unowned: a replacement
+daemon can legitimately claim the record and bind the same recorded socket path,
+and line 176's unlink then destroys the LIVE replacement's socket. End state — a
+pid record naming a live daemon with no socket — is unhealable, because the
+liveness gate at `lock.rs:141-143` refuses to touch a record whose pid is alive.
+
+`clear_stale_daemon_lock` also returns `true` for a MISSING pidfile
+(`lock.rs:130`), so "cleared" never implied this caller held exclusion at all.
+
+Production-reachable: `heal_stale_daemon_if_dead`
+(`crates/codegraph-cli/src/main.rs:2784-2788`) is the only caller, reached from the
+socket-missing branch of `proxy_to_running_daemon` (`main.rs:2730`) and from its
+post-`run_proxy` failure branch (`main.rs:2751`). Two concurrent `serve --mcp`
+starts on one project can run a cleaner against a replacement daemon's namespace.
+
+It predates the branch: `git show aba4079:crates/codegraph-daemon/src/lock.rs`
+line 161 has the identical order.
+
+### The option chosen: (b) a serialization protocol every starter and cleaner already obeys
+
+Reviewer option **(a)** — drop proactive stale cleanup from the attach-failure path
+and let `start_or_attach_gated` clear the leftover socket once it holds the new pid
+record — was **rejected**, for two reasons found by reading the code rather than by
+preference:
+
+1. `start_or_attach_gated` (`crates/codegraph-daemon/src/lib.rs:291-334`) is NOT on
+   the path that needs healing. The CLI's warm/cold decision
+   (`serve_spawn_or_proxy`, `main.rs:2688-2718`) reaches
+   `heal_stale_daemon_if_dead` on a WARM start whose attach failed, and then serves
+   DIRECT; it never calls `start_or_attach_gated` in that flow. Moving the cleanup
+   there would leave the stale socket in place for exactly the failing case Fix A
+   was written for (the dead-daemon-with-leftover-socket hang), i.e. it would
+   silently delete a shipped behavior, not relocate it.
+2. `start_or_attach_gated`'s own successful path already binds through
+   `bind_with_fallback` (`lib.rs:451-473`), which unlinks a stale entry at each
+   candidate BEFORE binding it (`lib.rs:457-462`) — under its already-held pid
+   record. Option (a)'s "new owner clears the leftover socket" is therefore already
+   implemented there. The residual defect is specifically the CLEANER that owns
+   nothing, so that is where the fix belongs.
+
+Option **(b)** was taken, using the token that already exists instead of inventing
+a second one: `clear_stale_daemon_socket` now BECOMES the namespace owner before it
+deletes anything in the namespace.
+
+```
+1. read the RECORDED socket (the record is the only place a bind-fallback path is
+   written down), then clear the stale record — still liveness-gated, so a LIVE
+   owner's namespace is never entered;
+2. re-claim the record via try_acquire_daemon_lock — the very same `create_new`
+   token a starter uses. A LOST claim returns false and touches NOTHING;
+3. unlink the stale socket while the claim excludes every starter;
+4. release the claim last, re-corroborated against our own pid via
+   cleanup_owned_lock.
+```
+
+This is the same idiom `f691415` established for `cleanup_owned_rendezvous`
+(`lock.rs:281-312`) — mutate the namespace only while holding the record that
+excludes competitors, and re-corroborate ownership at the final boundary — adapted
+to a cleaner that must ACQUIRE ownership rather than already have it.
+`cleanup_owned_rendezvous` and its tests were not modified.
+
+### Why no residual window remains
+
+The claim is a mutual-exclusion token with an atomic acquire: `create_new` on the
+pid path is a single filesystem operation that exactly one of N concurrent
+claimants can win. Every party that can bind the recorded socket path — a daemon
+start via `start_or_attach_gated` → `try_acquire_daemon_lock` → `bind_with_fallback`
+— must hold that same token first. So the unlink at step 3 executes only inside an
+interval in which:
+
+- no starter can hold the token (we do), therefore no process can have bound the
+  path since we acquired it; and
+- no other cleaner can hold it either (they lose at step 2 and return `false`
+  having touched nothing), so the "several concurrent cleaners performing a
+  delayed unlink" shape the reviewer named is eliminated rather than shrunk — a
+  losing cleaner performs NO deletion at all, at any later time.
+
+A mere order swap would not achieve this: unlink-then-clear still unlinks while
+owning nothing, so a daemon that bound between the liveness read and the unlink
+still loses its socket. The property that closes the window is ownership, not
+order — and the order within the owned interval (socket first, record last) is what
+keeps a mid-heal crash fail-closed.
+
+Crash behavior: a crash between steps 2 and 4 leaves a record naming this
+now-dead process and no socket — precisely the self-healing residue the NEXT heal
+clears through its own liveness gate. It cannot leave a live daemon socketless,
+because a live daemon cannot be the record's subject while we hold the claim.
+
+Windows: the socket layer is cfg-split. On Windows the recorded "socket path" is a
+bare namespaced pipe name (`crates/codegraph-daemon/src/transport.rs:36-38,59-68`),
+not a filesystem entry, and `Rendezvous::cleanup_path` exists only under
+`#[cfg(unix)]` (`transport.rs:70-73`), so step 3's `remove_file` simply fails and
+is ignored there (a named pipe disappears with its owning process). Steps 1, 2 and
+4 act on the real pid file, which is what carries the exclusion on Windows. **This
+is by code inspection only — no native Windows/MSVC run was performed; the gates
+below all ran on Linux.**
+
+Callers: `clear_stale_daemon_socket` has exactly one production caller
+(`heal_stale_daemon_if_dead`, `main.rs:2785`) and its signature and `bool` contract
+are unchanged, so no call site needed adjusting. `git grep` confirmed the full set:
+that one caller, the `codegraph-daemon` unit tests, and
+`crates/codegraph-daemon/tests/stale_socket.rs`. The four pre-existing
+`stale_socket.rs` integration tests (incl. `..._preserves_live_pid_lock` and
+`..._removes_recorded_fallback_socket`) pass unchanged.
+
+### Red — the interleaving, failing on the pre-fix order
+
+`cargo test --locked -q -p codegraph-daemon --lib` with the ORIGINAL
+`clear_stale_daemon_lock`-then-`remove_file` body restored (checkpoints emitted so
+the new tests can run at all), exit **101**, 3 failed / 101 passed:
+
+```
+---- lock::tests::a_replacement_start_during_the_stale_heal_keeps_its_own_socket stdout ----
+thread '...' panicked at crates/codegraph-daemon/src/lock.rs:800:9:
+the LIVE replacement's socket must survive the stale heal
+
+---- lock::tests::the_stale_heal_holds_its_claim_across_the_unlink_and_releases_it_last stdout ----
+thread '...' panicked at crates/codegraph-daemon/src/lock.rs:838:64:
+the heal claim is published
+
+---- lock::tests::an_absent_record_is_claimed_before_its_leftover_socket_is_removed stdout ----
+thread '...' panicked at crates/codegraph-daemon/src/lock.rs:924:9:
+the leftover socket must still be present at the moment the claim is won, proving
+the removal happens UNDER the claim and not before it
+```
+
+`a_replacement_start_during_the_stale_heal_keeps_its_own_socket` is the exact
+interleaving: the cleaner passes its liveness gate, and at the
+`StaleRecordCleared` checkpoint a replacement publishes a record naming a LIVE pid
+(this test process) and writes its own socket bytes at the same path. On the
+pre-fix code the unconditional unlink destroys it. Ordering is by the checkpoint
+callback — the mutation happens inside the call — so there is **no sleep and no
+timing assumption**. `StaleHealCheckpoint` mirrors the `RendezvousCleanupCheckpoint`
+seam `f691415` introduced.
+
+### Green
+
+`cargo test --locked -q -p codegraph-daemon` — exit **0**, `104 passed` (lib) plus
+every integration target green (`6, 4, 3, 4, 5, 1, 1, 2, 5, 0` passed).
+
+### Negative controls — three mutants, each reddening a different assertion
+
+Each was applied to the green tree, run, then reverted; after every revert
+`sha256sum crates/codegraph-daemon/src/lock.rs` printed
+`c8c002ff6ab847c53cd70b43f3fa75ca4e86acd3cb6061b35ce481d51ec0ec19`.
+
+**NC1 — restore the original pid-record-then-socket order (no claim at all).**
+`cargo test --locked -q -p codegraph-daemon --lib`, exit **101**, 3 failed:
+the three assertions quoted under "Red" above (`lock.rs:800`, `838`, `924`).
+Primary reddened test: `a_replacement_start_during_the_stale_heal_keeps_its_own_socket`.
+
+**NC2 — release the claim BEFORE the unlink** (`cleanup_owned_lock` moved above
+`remove_file`, everything else intact). `cargo test --locked -q -p codegraph-daemon
+--lib`, exit **101**, 1 failed:
+
+```
+---- lock::tests::the_stale_heal_holds_its_claim_across_the_unlink_and_releases_it_last stdout ----
+thread '...' panicked at crates/codegraph-daemon/src/lock.rs:876:17:
+the heal claim must STILL be published while the socket is unlinked
+```
+
+A DIFFERENT test from NC1's primary, and it pins the load-bearing half of the fix:
+the claim must span the unlink, not merely precede it.
+
+**NC3 — let an ABSENT record short-circuit the claim** (absent record ⇒ unlink
+immediately and return `true`, the widest form of the original defect).
+`cargo test --locked -q -p codegraph-daemon --lib`, exit **101**, 1 failed:
+
+```
+---- lock::tests::an_absent_record_is_claimed_before_its_leftover_socket_is_removed stdout ----
+thread '...' panicked at crates/codegraph-daemon/src/lock.rs:957:9:
+the leftover socket must still be present at the moment the claim is won, proving
+the removal happens UNDER the claim and not before it
+```
+
+A third distinct test. This is the deliberate decision on the absent-record case:
+an absent record IS treated as an unowned namespace whose leftover socket may be
+removed — `clear_stale_daemon_lock` already reports it cleared — but the removal is
+gated on WINNING the claim exactly as for a dead-owner record. Refusing to heal an
+absent record would strand orphaned sockets that nothing else removes (nothing
+records them), while unlinking without the claim is the widest interleaving of all:
+an absent record names no pid that could be proven dead, so a daemon starting
+concurrently could bind the path between the two syscalls. Claiming first makes the
+two cases one code path with one safety argument.
+
+### Gates and their REAL exit status
+
+Every command below was run separately, never joined with `&&`.
+
+| Command                                                               | Exit | Result                                                                         |
+| --------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------ |
+| `bash scripts/check-workspace-versions.sh` (before every Cargo batch) | 0    | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `cargo test --locked -q -p codegraph-daemon --lib` (NC1 mutant)       | 101  | 3 failed — the Red interleaving                                                |
+| `cargo test --locked -q -p codegraph-daemon` (green)                  | 0    | 104 lib + all integration targets passed                                       |
+| `cargo test --locked -q -p codegraph-daemon --lib` (NC2 mutant)       | 101  | 1 failed — claim released before the unlink                                    |
+| `cargo test --locked -q -p codegraph-daemon --lib` (NC3 mutant)       | 101  | 1 failed — absent record short-circuited the claim                             |
+| `cargo test --locked -p codegraph-bench --test equivalence`           | 0    | **28 passed** — golden oracle unchanged                                        |
+| `lsp_diagnostics` on `crates/codegraph-daemon/src/lock.rs`            | n/a  | REFUSED: `LSP file path must be inside request cwd`; fell back to locked Cargo |
+| `make fmt`                                                            | 0    | oxfmt, run AFTER this prose and BEFORE CI                                      |
+| `make ci CARGO='cargo --locked'` run 1                                | 0    | recorded below                                                                 |
+| `make ci CARGO='cargo --locked'` run 2                                | 0    | recorded below                                                                 |
+| `make ci CARGO='cargo --locked'` run 3                                | 0    | recorded below                                                                 |
+
+**Golden byte-stability.** `git diff --stat 4f910f2..HEAD -- reference/golden/` is
+EMPTY. The equivalence oracle left untracked
+`reference/golden/{cpp,nix,terraform}/colby.db-{wal,shm}`; they are not gitignored
+and were removed before staging. `Cargo.lock` SHA-256 unchanged at
+`750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1`.
+
+Two files changed: `crates/codegraph-daemon/src/lock.rs` and this ledger. No
+`reference/golden/`, `Cargo.toml`, `Cargo.lock`, `.github/workflows/` or `scripts/`
+change. Test parallelism untouched — `--test-threads` was never passed, and no test
+was skipped, `#[ignore]`d, weakened, or given a sleep.

From fa297e24f3c63e95913bb4c9fea03a73a77ea55b Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 13:57:12 +0800
Subject: [PATCH 70/91] fix(store): drop needless return in cfg(windows) alias
 checks

---
 crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs | 2 +-
 crates/codegraph-cli/tests/lease_lifetime.rs                    | 2 +-
 crates/codegraph-store/src/file_identity.rs                     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs b/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
index cadbb34..122e975 100644
--- a/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
+++ b/crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs
@@ -542,7 +542,7 @@ fn is_alias(metadata: &Metadata) -> bool {
     {
         use std::os::windows::fs::MetadataExt as _;
         const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
-        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0;
+        metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
     }
     #[cfg(not(windows))]
     false
diff --git a/crates/codegraph-cli/tests/lease_lifetime.rs b/crates/codegraph-cli/tests/lease_lifetime.rs
index 1de7bdd..b3bbbd9 100644
--- a/crates/codegraph-cli/tests/lease_lifetime.rs
+++ b/crates/codegraph-cli/tests/lease_lifetime.rs
@@ -413,7 +413,7 @@ fn is_regular_non_alias(metadata: &fs::Metadata) -> bool {
     {
         use std::os::windows::fs::MetadataExt;
         const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
-        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT == 0;
+        metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT == 0
     }
     #[cfg(not(windows))]
     true
diff --git a/crates/codegraph-store/src/file_identity.rs b/crates/codegraph-store/src/file_identity.rs
index 0efb65d..23274e0 100644
--- a/crates/codegraph-store/src/file_identity.rs
+++ b/crates/codegraph-store/src/file_identity.rs
@@ -31,7 +31,7 @@ pub(crate) fn is_alias(metadata: &Metadata) -> bool {
     {
         use std::os::windows::fs::MetadataExt as _;
         const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
-        return metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0;
+        metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
     }
     #[cfg(not(windows))]
     false

From 706d36a4e6c049f73ad8a9b1b3c7da7b352eead8 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 15:03:41 +0800
Subject: [PATCH 71/91] fix(cli): gate the lease-lifetime metadata helper off
 windows

---
 crates/codegraph-cli/tests/lease_lifetime.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/crates/codegraph-cli/tests/lease_lifetime.rs b/crates/codegraph-cli/tests/lease_lifetime.rs
index b3bbbd9..382d0b9 100644
--- a/crates/codegraph-cli/tests/lease_lifetime.rs
+++ b/crates/codegraph-cli/tests/lease_lifetime.rs
@@ -400,6 +400,12 @@ impl Drop for LeaseHookEnv {
     }
 }
 
+/// Only the metadata-comparing arms of `assert_path_still_names_opened_file`
+/// (unix, portable) call this. The windows arm reopens the path with
+/// `FILE_FLAG_OPEN_REPARSE_POINT` and compares true `FILE_ID_INFO` handles,
+/// which subsumes both the alias check and the identity check — so widening
+/// this gate to include windows makes the item never-used there.
+#[cfg(not(windows))]
 fn existing_metadata(path: &Path, operation: &str) -> fs::Metadata {
     fs::symlink_metadata(path)
         .unwrap_or_else(|error| panic!("{operation} {} failed: {error}", path.display()))

From a131aee769f0f3d5f6c9f84889f3fab4fb692357 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 18:44:31 +0800
Subject: [PATCH 72/91] fix(daemon): decide a zero drain budget from the
 pre-signal session count

---
 crates/codegraph-daemon/src/lib.rs | 74 ++++++++++++++++++++++++++----
 1 file changed, 66 insertions(+), 8 deletions(-)

diff --git a/crates/codegraph-daemon/src/lib.rs b/crates/codegraph-daemon/src/lib.rs
index 5efb68d..3deac02 100644
--- a/crates/codegraph-daemon/src/lib.rs
+++ b/crates/codegraph-daemon/src/lib.rs
@@ -627,18 +627,12 @@ async fn run_accept_loop_async(
     if let Some(watcher) = &watcher {
         watcher.begin_shutdown();
     }
-    registry.close_all_sessions();
     let watcher_done = {
         let watcher = watcher.as_ref();
         move || watcher.is_none_or(codegraph_watch::ProjectWatcher::is_finished)
     };
-    let drained = drain_watcher_loops_and_sessions(
-        watcher_done,
-        &lease_loops,
-        &registry,
-        options.drain_budget,
-    )
-    .await;
+    let drained =
+        close_sessions_and_drain(watcher_done, &lease_loops, &registry, options.drain_budget).await;
     // Past the deadline the watcher thread is already cancelled and exits on its
     // own; detach it so no destructor re-introduces an unbounded join AFTER the
     // incomplete result was computed.
@@ -668,6 +662,40 @@ async fn run_accept_loop_async(
     }
 }
 
+/// Sample what is outstanding, signal every data session to close, then drain
+/// within `budget`.
+///
+/// SAMPLING BEFORE THE SIGNAL IS LOAD-BEARING. The signalled sessions retire on
+/// other tokio worker threads, so the first drain poll can already observe an
+/// EMPTIED registry — and then report a COMPLETED drain for a budget that
+/// permitted no waiting at all. A daemon must never report a drain it did not
+/// perform, so the zero-budget answer is decided by the state AT THE SHUTDOWN
+/// INSTANT, before any session can react, instead of by whichever thread the
+/// scheduler happened to run next.
+///
+/// A nonzero budget keeps its previous semantics exactly: sessions are given the
+/// whole budget to retire and the poll loop decides.
+/// This is deliberately NOT an `async fn`: the body of one does not run until the
+/// future is first polled, which would put the sample back on the scheduler's
+/// timeline. Sampling here, then returning the drain future, makes the sample
+/// happen at the CALL.
+fn close_sessions_and_drain<'a>(
+    watcher_done: impl Fn() -> bool + 'a,
+    lease_loops: &'a codegraph_watch::SyncCancellation,
+    registry: &'a SessionRegistry,
+    budget: Duration,
+) -> impl std::future::Future<Output = bool> + 'a {
+    let idle_at_shutdown =
+        watcher_done() && lease_loops.active_syncs() == 0 && registry.active_count() == 0;
+    registry.close_all_sessions();
+    async move {
+        if budget.is_zero() {
+            return idle_at_shutdown;
+        }
+        drain_watcher_loops_and_sessions(watcher_done, lease_loops, registry, budget).await
+    }
+}
+
 /// Wait for the watcher's event loop to finish, every cancellation-aware lease
 /// loop to exit, and every active session to close — all bounded by `budget` and
 /// observed by POLLING, never by a blocking join. Returns whether all three
@@ -945,6 +973,36 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn a_zero_budget_answers_from_the_state_at_the_shutdown_instant() {
+        let lease_loops = codegraph_watch::SyncCancellation::new();
+
+        let idle = SessionRegistry::default();
+        assert!(
+            close_sessions_and_drain(|| true, &lease_loops, &idle, Duration::ZERO).await,
+            "a zero budget with nothing outstanding completes"
+        );
+
+        // Retiring the session BEFORE the drain can poll is the exact interleaving
+        // that used to answer `true`, so the guarantee must hold on that schedule.
+        let racing = SessionRegistry::default();
+        let leaving = racing.start_session();
+        let answer = close_sessions_and_drain(|| true, &lease_loops, &racing, Duration::ZERO);
+        drop(leaving);
+        assert_eq!(racing.active_count(), 0, "the session retired first");
+        assert!(
+            !answer.await,
+            "a session outstanding AT the shutdown instant must report an incomplete drain even \
+             when it retires before the drain is polled"
+        );
+
+        let empty = SessionRegistry::default();
+        assert!(
+            !close_sessions_and_drain(|| false, &lease_loops, &empty, Duration::ZERO).await,
+            "an unfinished watcher event loop at a zero budget is equally incomplete"
+        );
+    }
+
     #[test]
     fn backstop_exits_only_when_no_client_is_provably_alive() {
         let registry = SessionRegistry::default();

From eb4b516a835f1c9b481712bbe5ff0db473a831ca Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 18:44:38 +0800
Subject: [PATCH 73/91] test(daemon): scope the rendezvous socket-file
 assertions to unix

---
 crates/codegraph-daemon/src/lock.rs | 43 +++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 6 deletions(-)

diff --git a/crates/codegraph-daemon/src/lock.rs b/crates/codegraph-daemon/src/lock.rs
index 1c22cac..f974028 100644
--- a/crates/codegraph-daemon/src/lock.rs
+++ b/crates/codegraph-daemon/src/lock.rs
@@ -468,6 +468,36 @@ mod tests {
         fs::create_dir_all(dir).unwrap();
     }
 
+    /// A bound socket is a FILESYSTEM artifact only on unix. On windows
+    /// [`daemon_socket_path`] returns a bare namespaced pipe NAME
+    /// (`codegraph-v2-<hash16>`), a kernel object reclaimed when its last handle
+    /// closes — which is why [`cleanup_owned_rendezvous`] unlinks nothing there,
+    /// correctly. Writing that name as a file and then asserting it was removed
+    /// tests a premise windows does not have, so these helpers confine the
+    /// file-level claims to unix. The ORDERING guarantees stay asserted on EVERY
+    /// platform: the pid record as exclusion, a competing start refused at the
+    /// midpoint, and the crash residue the stale heal clears.
+    fn publish_socket_file(socket: &Path, contents: &[u8]) {
+        #[cfg(unix)]
+        fs::write(socket, contents).unwrap();
+        #[cfg(not(unix))]
+        let _ = (socket, contents);
+    }
+
+    fn assert_socket_file_present(socket: &Path, message: &str) {
+        #[cfg(unix)]
+        assert!(socket.exists(), "{message}");
+        #[cfg(not(unix))]
+        let _ = (socket, message);
+    }
+
+    fn assert_socket_file_absent(socket: &Path, message: &str) {
+        #[cfg(unix)]
+        assert!(!socket.exists(), "{message}");
+        #[cfg(not(unix))]
+        let _ = (socket, message);
+    }
+
     #[test]
     fn decode_lock_info_rejects_empty_and_zero_and_garbage() {
         assert!(decode_lock_info("").is_none());
@@ -681,7 +711,7 @@ mod tests {
             started_at: 1,
         };
         fs::write(&pid_path, encode_lock_info(&old).unwrap()).unwrap();
-        fs::write(&socket, b"old").unwrap();
+        publish_socket_file(&socket, b"old");
 
         let mut replacement_claim = None;
         let cleaned = cleanup_owned_rendezvous_with(&pid_path, &socket, departing, |checkpoint| {
@@ -711,7 +741,7 @@ mod tests {
 
         assert!(cleaned, "the departing owner cleans its own rendezvous");
         assert!(!pid_path.exists(), "its record is removed last");
-        assert!(!socket.exists(), "its socket was removed first");
+        assert_socket_file_absent(&socket, "its socket was removed first");
 
         // The replacement can now claim a clean namespace and bind its own socket,
         // and nothing left over can delete it.
@@ -720,12 +750,13 @@ mod tests {
         else {
             panic!("a cleaned namespace must be claimable");
         };
-        fs::write(&socket, b"new").unwrap();
+        publish_socket_file(&socket, b"new");
         assert!(
             !cleanup_owned_rendezvous(&pid_path, &socket, departing),
             "a second cleanup pass by the departed owner must be refused"
         );
-        assert!(pid_path.exists() && socket.exists());
+        assert!(pid_path.exists());
+        assert_socket_file_present(&socket, "the replacement's socket survives");
         let _ = fs::remove_dir_all(&base);
     }
 
@@ -750,7 +781,7 @@ mod tests {
             started_at: 1,
         };
         fs::write(&pid_path, encode_lock_info(&old).unwrap()).unwrap();
-        fs::write(&socket, b"old").unwrap();
+        publish_socket_file(&socket, b"old");
 
         // Simulate the crash by panicking-free early return: run cleanup only up to
         // the socket-removed boundary and drop the process there.
@@ -758,7 +789,7 @@ mod tests {
         let _ = cleanup_owned_rendezvous_with(&pid_path, &socket, departing, |checkpoint| {
             if checkpoint == RendezvousCleanupCheckpoint::SocketRemoved {
                 reached_socket_removed = true;
-                assert!(!socket.exists(), "the socket is gone at this boundary");
+                assert_socket_file_absent(&socket, "the socket is gone at this boundary");
                 assert!(
                     pid_path.exists(),
                     "the record is STILL published as exclusion at this boundary"

From c7800ca03ab974c841c652a2745a01003638b2d4 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 18:44:38 +0800
Subject: [PATCH 74/91] docs: record the three PR #173 CI failures and their
 root causes

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 206 ++++++++++++++++++++++
 1 file changed, 206 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 51278a7..8630934 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -8534,3 +8534,209 @@ Two files changed: `crates/codegraph-daemon/src/lock.rs` and this ledger. No
 `reference/golden/`, `Cargo.toml`, `Cargo.lock`, `.github/workflows/` or `scripts/`
 change. Test parallelism untouched — `--test-threads` was never passed, and no test
 was skipped, `#[ignore]`d, weakened, or given a sleep.
+
+## PR #173 CI blockers — three failures, two root causes (2026-07-29)
+
+Three test failures on PR #173 at HEAD `706d36a`. All three were treated as
+hypotheses needing proof, and each mechanism was established from code plus a
+runtime observation before anything was changed.
+
+| #   | Job            | Failure                                                                             | Root cause                     |
+| --- | -------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
+| A   | `Test` (LINUX) | `an_exhausted_drain_budget_replies_incomplete_instead_of_success`                   | PRODUCTION defect              |
+| B   | `Windows`      | `lock::tests::a_crash_between_cleanup_boundaries_leaves_only_self_healing_residue`  | test premise absent on windows |
+| C   | `Windows`      | `lock::tests::a_replacement_start_at_the_cleanup_midpoint_keeps_its_own_rendezvous` | test premise absent on windows |
+
+### Failure A — the daemon reported a drain it never performed
+
+CI location: `Test` job, run `30430353283`,
+`panicked at crates/codegraph-daemon/tests/control_shutdown.rs:218:5`,
+`3 passed; 1 failed`.
+
+The dismissed hypothesis was "the silent client's session is not yet registered
+when the shutdown frame arrives". Instrumentation refutes it. Three probes were
+added temporarily to `run_accept_loop_async` — `active_count` immediately before
+`close_all_sessions`, immediately after it, and at the entry to
+`drain_watcher_loops_and_sessions` — and the failing runs report:
+
+```
+DBG before=1 after=0 entry=0 drained=true     <- every FAILING run
+DBG before=1 after=1 entry=1 drained=false    <- every PASSING run
+```
+
+`before=1` on the failures proves the session WAS registered. The registration
+race does not exist: `connect_silent_data_client` reads the daemon hello, and that
+hello is written by `serve_session_async` at line 384 — AFTER
+`registry.start_session()` at line 362. Completing the hello read is already
+positive proof of registration. (A `handle.active_sessions() >= 1` probe inserted
+into the test before the control frame never once fired across 40 runs, including
+runs that then failed the drain assertion in the same binary.)
+
+The actual defect is in production, in the shutdown path itself:
+
+1. `registry.close_all_sessions()` signals every session to stop;
+2. sessions retire on OTHER tokio worker threads;
+3. `drain_watcher_loops_and_sessions` then reads `active_count()` for the FIRST
+   time and returns `true` the instant it sees zero — even for
+   `drain_budget: ZERO`, which permits no waiting at all.
+
+So with a zero budget and one outstanding session, the answer was decided by
+whether a worker thread got scheduled between steps 1 and 3. When it did, the
+daemon answered `drained: true` for a drain it never waited for. `uninit --force`
+consumes that ack as permission to delete children. This is exactly the class of
+bug the test exists to prevent, and the test was right.
+
+**Fix** (`crates/codegraph-daemon/src/lib.rs`): new `close_sessions_and_drain`
+samples `watcher_done() && active_syncs() == 0 && active_count() == 0` BEFORE
+signalling, and a zero budget answers from that sample. A nonzero budget is
+byte-identical to before — it delegates to the unchanged
+`drain_watcher_loops_and_sessions`, whose own test still passes untouched.
+
+It is deliberately NOT an `async fn`: an `async fn` body does not execute until
+first poll, which would put the sample back on the scheduler's timeline. Sampling
+in a plain fn that returns the drain future pins the sample to the CALL. The new
+unit test `a_zero_budget_answers_from_the_state_at_the_shutdown_instant` asserts
+this by retiring the session BEFORE awaiting the returned future — the exact
+interleaving that used to answer `true`.
+
+No sleep, no budget change, no retry, no relaxed assertion. The integration test
+is unmodified.
+
+### Failure A reproduction rate, before and after
+
+Reproduced locally, and the constraint that reproduces it is CPU count.
+
+| Condition                              | Before fix         | After fix          |
+| -------------------------------------- | ------------------ | ------------------ |
+| unconstrained (30 cores), 50 runs      | **10 failed / 50** | 0 failed / 50      |
+| unconstrained, second 60-run batch     | 0 failed / 60      | —                  |
+| `taskset -c 0,1` (2 cores), 30 runs    | 1 failed / 30      | —                  |
+| `taskset -c 0,1` + 8 spinners, 50 runs | 3 failed / 50      | —                  |
+| `taskset -c 0` (1 core), 40 runs       | **5 failed / 40**  | **0 failed / 40**  |
+| `taskset -c 0` (1 core), 50 runs       | —                  | **50 passed / 50** |
+
+The 10/50 first batch and the 0/60 second on the same binary is itself the
+signature: the outcome tracks machine load, not the code path. `taskset -c 0`
+reproduces it reliably at ~12%, which is why the fix was verified there and not
+only on an idle 30-core host.
+
+### Per-test audit of `control_shutdown.rs`
+
+Every test was checked for the "assume the server already did something" shape.
+
+| Test                                                                    | Precondition it needs                                       | Established?                                                                                                    |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `authorized_shutdown_closes_a_long_lived_session_before_acknowledging`  | session registered before the frame                         | YES — the hello read (written after `start_session`) proves it                                                  |
+| `an_unauthorized_frame_is_refused_without_shutting_the_daemon_down`     | daemon serving; each refusal answered on its own connection | YES — each `send_control_frame` completes a hello + reply round trip; the `is_finished` check follows the reply |
+| `an_exhausted_drain_budget_replies_incomplete_instead_of_success`       | session registered before the frame                         | YES — same hello proof; the failure was NOT a missing precondition                                              |
+| `an_incomplete_drain_reply_is_unresponsive_and_never_signals_the_owner` | stub listener bound before the request                      | YES — `ListenerOptions::create_sync()` returns after bind, on the test thread, before the thread is spawned     |
+
+`3 passed` was not luck. No test in this file waits on an unobserved server
+action, and none was changed.
+
+### Failures B and C — VERDICT: test premise, not a production defect
+
+CI location: `Windows` job, step `Run tests`,
+`panicked at crates\codegraph-daemon\src\lock.rs:761:17` and
+`crates\codegraph-daemon\src\lock.rs:714:9`, `93 passed; 2 failed`.
+
+The recorded hypothesis is confirmed by the code:
+
+- `paths::daemon_socket_path` under `#[cfg(windows)]` returns
+  `PathBuf::from(format!("{V2_RENDEZVOUS_PREFIX}{}", rendezvous_name(&paths)))` —
+  a BARE name like `codegraph-v2-1a2b3c4d5e6f7788`, no directory, no filesystem
+  entry (interprocess's `GenericNamespaced` prepends `\\.\pipe\` itself).
+- `Rendezvous::cleanup_path` exists only under `#[cfg(unix)]`, and
+  `cleanup_owned_rendezvous` unlinks only under `#[cfg(unix)]` (`lock.rs:390-396`).
+
+Both failing tests did `fs::write(&socket, b"old")` — creating a REAL file whose
+name is the pipe name, in the process CWD — and then asserted
+`!socket.exists()`. On windows nothing removes it, so the assertion fails. It is
+asserting a filesystem contract windows does not have.
+
+Production is CORRECT on windows, and deliberately so. A named pipe is a kernel
+object reclaimed when its last handle closes; there is no residue to unlink, and
+attempting one would be meaningless. The pid record — a real file — is what carries
+the single-instance exclusion, and `cleanup_owned_rendezvous` /
+`clear_stale_daemon_socket` operate on it identically on both platforms. Gating a
+test green here does not hide a broken production path; there is no windows path
+to break.
+
+**Fix** (`crates/codegraph-daemon/src/lock.rs`, test module only): three helpers
+— `publish_socket_file`, `assert_socket_file_present`, `assert_socket_file_absent`
+— perform the socket-FILE operations under `#[cfg(unix)]` and are no-ops
+elsewhere. The two tests keep their names, their structure, their checkpoint
+callbacks, and every ORDERING assertion on all platforms:
+
+- the pid record is STILL PUBLISHED at the `SocketRemoved` boundary (`f691415`'s
+  ordering invariant) — asserted on windows too;
+- a competing `try_acquire_daemon_lock` at `OwnershipCorroborated` is REFUSED and
+  still reads the departing owner's pid — asserted on windows too;
+- `cleanup_owned_rendezvous` returns `false` for a departed owner and `true` for
+  the true owner — asserted on windows too;
+- `clear_stale_daemon_socket` clears the crash residue — asserted on windows too.
+
+Only the `socket.exists()` / `fs::write(socket)` claims are unix-scoped. On unix
+the tests are byte-equivalent in behavior to before.
+
+**Windows coverage now unverified (known gap).** That the socket FILE is removed,
+and that it is removed BEFORE the pid record, is asserted on unix only. This is
+not a loss of real coverage — there is no socket file on windows — but it is
+recorded so no one later reads the gate as "windows cleanup is tested". The three
+stale-heal tests (`a_replacement_start_during_the_stale_heal_keeps_its_own_socket`,
+`the_stale_heal_holds_its_claim_across_the_unlink_and_releases_it_last`,
+`an_absent_record_is_claimed_before_its_leftover_socket_is_removed`) were NOT
+gated: they were not in the windows failure list, and `clear_stale_daemon_socket`
+calls `fs::remove_file(&socket_path)` unconditionally (`lock.rs:263`, no `cfg`), so
+a file they themselves created IS removed on windows. They are left exactly as
+`6b9861b` wrote them.
+
+### Windows was NOT validated locally — and cannot be here
+
+No windows verification is claimed. Both cross-compilation routes were retried and
+both fail, as previously recorded: `cargo clippy --target x86_64-pc-windows-msvc`
+exits 101 (23 `tree-sitter-*` crates fail their `cc-rs` build scripts), and
+`cargo xwin clippy` exits 101 (`failed to find tool "clang-cl"`). No clang /
+lld-link / zig / cargo-zigbuild is present, no package manager is available, and
+the process runs as uid 1000. `clang-cl` cannot be installed here. The B/C verdict
+therefore rests on reading `paths.rs`, `transport.rs` and `lock.rs`, not on a
+windows run. Real windows validation is the CodeBuild `codegraph-rs-windows`
+project, which was NOT touched.
+
+### Gates and their REAL exit status
+
+Each command was run separately; none joined with `&&`.
+
+| Command                                                                               | Exit      | Result                                                   |
+| ------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------- |
+| `cargo test --locked -p codegraph-daemon` (before any fix, drain test alone, 50 runs) | 101 on 10 | the Red observation                                      |
+| `cargo build --locked -p codegraph-daemon --tests` (instrumented)                     | 0         | probe binary for the diagnosis                           |
+| `cargo clippy --locked -p codegraph-daemon --all-targets`                             | 0         | no warnings                                              |
+| `cargo test --locked -p codegraph-daemon --lib` (mid-fix, `async fn` form)            | 101       | 1 failed — proved the sample must precede the first poll |
+| `cargo test --locked -p codegraph-daemon`                                             | 0         | 105 lib + every integration target, 11 targets all `ok`  |
+| drain-budget test × 50, `taskset -c 0`                                                | 0         | **50 passed / 50**                                       |
+| drain-budget test × 50, unconstrained                                                 | 0         | **50 passed / 50**                                       |
+| the other three `control_shutdown` tests × 25 each, `taskset -c 0`                    | 0         | 0 failed / 75                                            |
+
+The remaining gates (`bash scripts/check-workspace-versions.sh`, `make fmt`,
+`make ci CARGO='cargo --locked'` twice, the golden-diff and `Cargo.lock` checks)
+are recorded immediately below with their real exit statuses.
+
+### PR #173 blockers — final gate statuses
+
+| Command                                              | Exit  | Result                                                                         |
+| ---------------------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| `bash scripts/check-workspace-versions.sh`           | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `make fmt`                                           | **0** | run AFTER this prose, BEFORE CI                                                |
+| `make ci CARGO='cargo --locked'` run 1               | **0** | `✅ All CI checks passed!`                                                     |
+| `make ci CARGO='cargo --locked'` run 2               | **0** | `✅ All CI checks passed!`                                                     |
+| `git diff --stat 706d36a..HEAD -- reference/golden/` | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                               | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+The equivalence oracle left untracked
+`reference/golden/{cfml,cpp,solidity}/colby.db-{wal,shm}` after run 1; they are not
+gitignored and were removed before run 2 and before staging. Three files changed:
+`crates/codegraph-daemon/src/lib.rs`, `crates/codegraph-daemon/src/lock.rs`, and
+this ledger. No `reference/golden/`, `Cargo.toml`, `Cargo.lock`,
+`.github/workflows/`, `scripts/` or `.aws/` change. No test was skipped,
+`#[ignore]`d, weakened, given a sleep, or given a widened timeout.

From b71a5f1ca6122e22879969d58f14b59d737658ea Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 19:47:15 +0800
Subject: [PATCH 75/91] fix(store): classify windows directory flush denial as
 unsupported

---
 .../src/index_state_publisher.rs              | 118 ++++++++++--
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 178 ++++++++++++++++++
 2 files changed, 281 insertions(+), 15 deletions(-)

diff --git a/crates/codegraph-store/src/index_state_publisher.rs b/crates/codegraph-store/src/index_state_publisher.rs
index b3a551a..9680386 100644
--- a/crates/codegraph-store/src/index_state_publisher.rs
+++ b/crates/codegraph-store/src/index_state_publisher.rs
@@ -499,25 +499,45 @@ fn sync_parent(_parent: &Path) -> Result<ParentSyncStatus, StatePublishError> {
     Ok(ParentSyncStatus::Unsupported)
 }
 
+/// EINVAL and EOPNOTSUPP/ENOTSUP are the conventional reports for a filesystem
+/// that cannot synchronize directory entries.
+#[cfg(any(unix, test))]
+const UNIX_DIRECTORY_SYNC_UNSUPPORTED: &[i32] = &[22, 95];
+
+/// Win32 statuses that mean this handle or filesystem exposes no directory
+/// flush primitive.
+///
+/// ERROR_INVALID_FUNCTION, ERROR_INVALID_HANDLE, ERROR_NOT_SUPPORTED, and
+/// ERROR_INVALID_PARAMETER are the explicit "no such primitive" reports.
+/// ERROR_ACCESS_DENIED belongs to the same class here and NOT to the class of
+/// genuine permission faults: `FlushFileBuffers` requires a handle carrying
+/// write access, an unprivileged process cannot obtain write access to a
+/// DIRECTORY handle, and this code path only ever reaches the flush after the
+/// directory open already succeeded. The denial is therefore a property of the
+/// platform's directory API, identical on every run, and never a signal that
+/// this specific namespace is unwritable — the writes that need the barrier are
+/// the file operations that already completed. Access errors from OPENING the
+/// directory stay hard failures; only the flush is downgraded.
+#[cfg(any(windows, test))]
+const WINDOWS_DIRECTORY_SYNC_UNSUPPORTED: &[i32] = &[1, 5, 6, 50, 87];
+
 #[cfg(any(unix, windows))]
 fn directory_sync_unsupported(error: &io::Error) -> bool {
-    if error.kind() == io::ErrorKind::Unsupported {
-        return true;
-    }
     #[cfg(unix)]
-    {
-        // EINVAL and EOPNOTSUPP/ENOTSUP are the conventional reports for a
-        // filesystem that cannot synchronize directory entries.
-        matches!(error.raw_os_error(), Some(22 | 95))
-    }
+    let unsupported = UNIX_DIRECTORY_SYNC_UNSUPPORTED;
     #[cfg(windows)]
-    {
-        // ERROR_INVALID_FUNCTION, ERROR_INVALID_HANDLE, ERROR_NOT_SUPPORTED,
-        // and ERROR_INVALID_PARAMETER explicitly mean this handle/filesystem
-        // does not expose a directory flush primitive. Access errors are NOT
-        // downgraded to unsupported.
-        matches!(error.raw_os_error(), Some(1 | 6 | 50 | 87))
-    }
+    let unsupported = WINDOWS_DIRECTORY_SYNC_UNSUPPORTED;
+    directory_sync_unsupported_in(error, unsupported)
+}
+
+/// Platform-independent classifier: an explicit [`io::ErrorKind::Unsupported`],
+/// or a raw OS status in this platform's "no directory flush primitive" set.
+#[cfg(any(unix, windows))]
+fn directory_sync_unsupported_in(error: &io::Error, unsupported: &[i32]) -> bool {
+    error.kind() == io::ErrorKind::Unsupported
+        || error
+            .raw_os_error()
+            .is_some_and(|code| unsupported.contains(&code))
 }
 
 #[cfg(test)]
@@ -769,6 +789,74 @@ mod tests {
         }
     }
 
+    #[test]
+    fn windows_directory_flush_denial_is_classified_unsupported_not_a_hard_failure() {
+        // ERROR_ACCESS_DENIED is the structural report for FlushFileBuffers on a
+        // directory handle, so it must not abort publication.
+        assert!(directory_sync_unsupported_in(
+            &io::Error::from_raw_os_error(5),
+            WINDOWS_DIRECTORY_SYNC_UNSUPPORTED
+        ));
+        for code in WINDOWS_DIRECTORY_SYNC_UNSUPPORTED {
+            assert!(
+                directory_sync_unsupported_in(
+                    &io::Error::from_raw_os_error(*code),
+                    WINDOWS_DIRECTORY_SYNC_UNSUPPORTED
+                ),
+                "win32 {code} must be classified unsupported"
+            );
+        }
+        for code in UNIX_DIRECTORY_SYNC_UNSUPPORTED {
+            assert!(
+                directory_sync_unsupported_in(
+                    &io::Error::from_raw_os_error(*code),
+                    UNIX_DIRECTORY_SYNC_UNSUPPORTED
+                ),
+                "errno {code} must be classified unsupported"
+            );
+        }
+        assert!(directory_sync_unsupported_in(
+            &io::Error::from(io::ErrorKind::Unsupported),
+            &[]
+        ));
+    }
+
+    #[test]
+    fn directory_flush_codes_outside_the_platform_set_stay_hard_failures() {
+        // ERROR_DISK_FULL and ERROR_FILE_NOT_FOUND are genuine faults, and the
+        // per-platform sets must not leak into each other.
+        for code in [2, 112] {
+            assert!(!directory_sync_unsupported_in(
+                &io::Error::from_raw_os_error(code),
+                WINDOWS_DIRECTORY_SYNC_UNSUPPORTED
+            ));
+        }
+        assert!(!directory_sync_unsupported_in(
+            &io::Error::from_raw_os_error(5),
+            UNIX_DIRECTORY_SYNC_UNSUPPORTED
+        ));
+        assert!(!directory_sync_unsupported_in(
+            &io::Error::from_raw_os_error(1),
+            UNIX_DIRECTORY_SYNC_UNSUPPORTED
+        ));
+    }
+
+    #[test]
+    fn publication_reports_a_parent_sync_status_instead_of_failing() {
+        let project = TempProject::new("parent-sync-status");
+        let paths = project.paths();
+        let lease = IndexLease::create_exclusive(&paths, deadline(), || false)
+            .expect("create parent-sync lease");
+
+        let published = publish_index_state(&paths, &lease, StatePhase::Building)
+            .expect("publication must not fail on the parent-directory barrier");
+
+        assert!(matches!(
+            published.parent_sync,
+            ParentSyncStatus::Synced | ParentSyncStatus::Unsupported
+        ));
+    }
+
     #[test]
     fn every_initial_publication_checkpoint_leaves_missing_or_exposes_a_valid_first_slot() {
         let checkpoints = [
diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 8630934..cfbb028 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -8740,3 +8740,181 @@ gitignored and were removed before run 2 and before staging. Three files changed
 this ledger. No `reference/golden/`, `Cargo.toml`, `Cargo.lock`,
 `.github/workflows/`, `scripts/` or `.aws/` change. No test was skipped,
 `#[ignore]`d, weakened, given a sleep, or given a widened timeout.
+
+## PR #173 CI round 4 — the four `codegraph-mcp` windows test failures
+
+Run `30444938158`, job `Windows`, step `Run tests` (`cargo test --workspace
+--exclude codegraph-bench`). Its `codegraph-daemon` suite now passes `96/96`, so
+`a131aee` and `eb4b516` held. The next layer surfaced in `codegraph-mcp --lib`:
+`254 passed; 4 failed`, `error: test failed, to rerun pass -p codegraph-mcp --lib`.
+
+| CI location                                        | Test                                                                                           |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `crates\codegraph-mcp\src\engine.rs:4044:78`       | `engine::tests::ext_open_reads_store_from_project_dir`                                         |
+| `crates\codegraph-mcp\src\rmcp_handler.rs:1142:78` | `rmcp_handler::handler_tests::call_tool_bad_project_path_returns_error_result`                 |
+| `crates\codegraph-mcp\src\rmcp_handler.rs:1142:78` | `rmcp_handler::handler_tests::call_tool_timeout_disabled_runs_unbounded_path`                  |
+| `crates\codegraph-mcp\src\rmcp_handler.rs:1142:78` | `rmcp_handler::handler_tests::execute_owned_success_opens_request_scoped_engine_and_runs_tool` |
+
+### What is unwrapped at each location
+
+Both are the SAME call, and it is neither a path nor a `Store`:
+
+- `engine.rs:4044` — inside `ext_open_reads_store_from_project_dir`, directly:
+  `codegraph_store::test_support::finalize_current_test_fixture(&paths).unwrap()`.
+- `rmcp_handler.rs:1142` — the LAST statement of the shared test helper
+  `real_indexed_project(tag: &str) -> TempDir`, which copies
+  `reference/golden/mini/colby.db` plus the two `fixtures/mini` sources into a
+  temp project and then calls the identical
+  `finalize_current_test_fixture(&paths).unwrap()`.
+
+`real_indexed_project` is the shared helper behind three of the four failures;
+`ext_open_reads_store_from_project_dir` calls the same store API inline. So all
+four are ONE cause, and the failing code is in **production**
+(`codegraph-store`), not in the tests.
+
+### Root cause — `FlushFileBuffers` on a DIRECTORY handle returns ERROR_ACCESS_DENIED
+
+The full CI error, recovered from the run log, is identical in all four:
+
+```
+called `Result::unwrap()` on an `Err` value: publish test fixture Building state
+Caused by:
+    0: cannot synchronize state-slot parent directory at \\?\C:\Users\runneradmin\AppData\Local\Temp\cg-mcp-open-8848-53\.codegraph-v2: Access is denied. (os error 5)
+    1: Access is denied. (os error 5)
+```
+
+with backtrace frames `codegraph_store::test_support::finalize_current_test_fixture`
+(`test_support.rs:63`, the `publish_index_state(..., StatePhase::Building)` line)
+→ `anyhow::context` → `codegraph_store::index_state_publisher::StatePublishError`.
+
+`publish_index_state` ends with a parent-directory durability barrier,
+`sync_parent` (`index_state_publisher.rs:480-495`): open the state-slot parent
+directory (`FILE_FLAG_BACKUP_SEMANTICS`, read-only access) and call
+`File::sync_all()` on it. `sync_all` is `FlushFileBuffers(handle)`.
+
+The behavioural difference: on unix `fsync(dirfd)` on a read-only directory
+descriptor is the documented way to make a rename durable and returns `0`. On
+windows `FlushFileBuffers` requires a handle carrying **write** access
+(`GENERIC_WRITE`/`FILE_WRITE_DATA`); a DIRECTORY handle obtained by an
+unprivileged process never carries it, so the call returns
+`ERROR_ACCESS_DENIED` (5). It is a property of the platform's directory API — it
+happens on every call on every windows machine, not on some machines or some
+paths. Note the temp path is a `\\?\` verbatim path, which is a red herring: the
+`open` succeeded, only the flush failed.
+
+`directory_sync_unsupported` downgraded only `1 | 6 | 50 | 87`
+(ERROR_INVALID_FUNCTION / INVALID_HANDLE / NOT_SUPPORTED / INVALID_PARAMETER) to
+`ParentSyncStatus::Unsupported`, with a comment stating "Access errors are NOT
+downgraded to unsupported". That policy is right for a FILE and wrong for a
+DIRECTORY: it turned the one windows-universal outcome into a hard
+`StatePublishError::Io`, so **every** `publish_index_state` call fails on windows.
+This is not a test defect. Production `codegraph-store` cannot publish index
+state on windows at all: `rebuild.rs:317`/`:496`/`:885` and `uninit.rs:188` take
+the same path, so `codegraph index`, its `Building -> Current` promotion, and
+`codegraph uninit` were all broken on windows. The four tests were the messengers.
+
+### The fix — one production change
+
+`ERROR_ACCESS_DENIED` (5) joins the windows "no directory flush primitive" set.
+The justification is narrow and is written into the code: this branch is reached
+only AFTER the directory open already succeeded, so the denial cannot mean the
+namespace is unwritable, and the writes the barrier protects (temp write, temp
+`sync_all` on a real FILE handle, and the rename) have all already completed and
+are unaffected. Access errors from OPENING the directory remain hard failures.
+Losing the barrier means a crash within the window after the rename could lose
+the slot rename on power loss — exactly the risk `ParentSyncStatus::Unsupported`
+already exists to report, and strictly better than the previous behaviour of
+never publishing at all.
+
+Two mechanical changes make it testable from linux: the per-platform code sets
+became named constants (`UNIX_DIRECTORY_SYNC_UNSUPPORTED`,
+`WINDOWS_DIRECTORY_SYNC_UNSUPPORTED`, both `cfg(any(<platform>, test))`), and the
+matching moved into a pure `directory_sync_unsupported_in(&io::Error, &[i32])`.
+`directory_sync_unsupported` is now a thin per-platform wrapper choosing its set.
+No behaviour changed on unix: the set is still `22 | 95`.
+
+Three unit tests were added, all runnable on linux:
+`windows_directory_flush_denial_is_classified_unsupported_not_a_hard_failure`
+(asserts win32 `5` classifies as unsupported, and every code in each platform
+set does), `directory_flush_codes_outside_the_platform_set_stay_hard_failures`
+(win32 `2`/`112` stay failures; the unix set does not accept `5` or `1`, so the
+sets cannot leak into each other), and
+`publication_reports_a_parent_sync_status_instead_of_failing`.
+
+**Negative control**: removing `5` from `WINDOWS_DIRECTORY_SYNC_UNSUPPORTED` and
+re-running reddens exactly the intended test —
+`assertion failed: directory_sync_unsupported_in(&io::Error::from_raw_os_error(5), WINDOWS_DIRECTORY_SYNC_UNSUPPORTED)`,
+`test result: FAILED. 5 passed; 1 failed`. The constant was restored and the file
+verified byte-identical afterwards.
+
+### No test was gated, and no coverage was lost
+
+All four failures were production defects, so nothing was `#[cfg]`-gated,
+`#[ignore]`d, weakened or slept. `crates/codegraph-mcp` is unchanged by this fix;
+so are all four test bodies.
+
+### Workspace-wide audit — the same defect class elsewhere
+
+Class: POSIX filesystem-durability / directory-handle / open-file semantics that
+differ on windows. Searched all of `crates/` for directory-handle `sync_all`,
+hard-coded `raw_os_error()` sets, `rename` over an existing or open destination,
+`remove_*` on an open handle, `/`-separator and non-canonicalised path
+assumptions, and exact `ErrorKind`/OS-message assertions.
+
+| file:line                                                                                        | assumes                                                                                            | fails on windows?        | reasoning                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crates/codegraph-store/src/index_state_publisher.rs:490,519`                                    | a directory handle can `sync_all`, and only `1/6/50/87` mean unsupported                           | **yes — FIXED here**     | `FlushFileBuffers` on a directory returns `5`; set was missing it                                                                                                                                                                                                             |
+| `crates/codegraph-store/src/index_state_publisher.rs:473,511`                                    | unix directory `fsync`, unsupported errnos `22/95`                                                 | no                       | correct on the supported unix targets; `cfg(unix)`-only                                                                                                                                                                                                                       |
+| `crates/codegraph-watch/src/watcher.rs:81`                                                       | errno `23/24/28` classify watcher exhaustion                                                       | no                       | explicitly `cfg(unix)`; windows falls through to `Other`, a conservative downgrade                                                                                                                                                                                            |
+| `crates/codegraph-daemon/src/lock.rs:89`                                                         | `rename(tmp, pid_path)` over a just-`create_new`ed placeholder whose handle is still open in scope | no                       | rust's `fs::rename` uses `MoveFileExW(MOVEFILE_REPLACE_EXISTING)`, and std opens files with `FILE_SHARE_DELETE`, so replacing an open target is permitted; CI corroborates — the whole `codegraph-daemon` suite passes `96/96` on windows and this is its normal acquire path |
+| `crates/codegraph-daemon/src/http_registry.rs:151`                                               | `rename(tmp, path)` overwrites an existing registry entry                                          | no                       | same `MOVEFILE_REPLACE_EXISTING` reasoning; no open handle on the target at all                                                                                                                                                                                               |
+| `crates/codegraph-cli/src/installer/shared.rs:376`                                               | `rename(tmp, path)` overwrites an existing agent config                                            | no                       | same; and windows installer tests pass in CI                                                                                                                                                                                                                                  |
+| `crates/codegraph-store/src/index_lease.rs:632,680`                                              | a locked, still-open lock file can be `rename`d away mid-acquisition (fault-injection tests)       | no                       | `MOVEFILE_REPLACE_EXISTING` + `FILE_SHARE_DELETE`; and these unit tests are in `codegraph-store --lib`, which passed on windows in this very run                                                                                                                              |
+| `crates/codegraph-store/tests/index_state_publisher.rs:385,415,439`                              | same, in integration tests                                                                         | uncertain — not observed | the `codegraph-store` integration targets did NOT run on windows in run `30444938158`: the job aborted at the first failing target (`codegraph-mcp --lib`), and `Running` lines for them never appear in the log. Unverified either way; NOT changed                          |
+| `crates/codegraph-store/tests/store_state_gates.rs:1051,1109`                                    | rename a retained-lease lock file                                                                  | uncertain — not observed | same: target never ran on windows                                                                                                                                                                                                                                             |
+| `crates/codegraph-cli/tests/batch_m_legacy_extension_override.rs:1625,1728`                      | rename over an open snapshot-read handle / move an open directory                                  | uncertain — not observed | `codegraph-cli` integration targets also never ran on windows in this run                                                                                                                                                                                                     |
+| `crates/codegraph-mcp/tests/golden_mcp.rs:51`, `crates/codegraph-mcp/tests/support/parity.rs:44` | transient windows file locking appears ONLY as raw os error `32` (`ERROR_SHARING_VIOLATION`)       | uncertain                | `32` is the dominant case, but AV/filter-driver interference can also surface as `5` or `33`. Widening it would be speculative and would weaken a retry predicate against evidence I do not have, so it is left alone and recorded                                            |
+
+Fixed: the one high-confidence entry, which is also the one CI actually proved.
+Not fixed, with reasoning: the `rename`-over-open-handle entries — the three
+"no" verdicts rest on rust's `MOVEFILE_REPLACE_EXISTING` + `FILE_SHARE_DELETE`
+implementation (read from `library/std/src/sys/fs/windows.rs`) plus positive CI
+evidence, and the "uncertain" ones sit in targets windows never reached because
+the job aborted earlier. Changing them now would be guessing. **Expect further
+layers**: once `codegraph-mcp --lib` is green, windows will run
+`codegraph-store`'s and `codegraph-cli`'s integration targets for the first time,
+and those uncertain rows are where the next failures would appear.
+
+### Gates and their REAL exit status
+
+Each run separately; none joined with `&&`.
+
+| Command                                                                         | Exit | Result                                                   |
+| ------------------------------------------------------------------------------- | ---- | -------------------------------------------------------- |
+| `gh run view 30444938158 --log` (recover the real windows message)              | 0    | all four `Caused by: ... Access is denied. (os error 5)` |
+| `cargo test --locked -p codegraph-store --lib index_state_publisher`            | 0    | 6 passed (3 new)                                         |
+| negative control: same, with `5` removed from the windows set                   | 101  | **1 failed** — the intended test only                    |
+| `cargo test --locked -p codegraph-store --lib index_state_publisher` (restored) | 0    | 6 passed                                                 |
+| `cargo test --locked -p codegraph-mcp`                                          | 0    | **258** lib + 65 across 9 integration targets, all `ok`  |
+| `cargo test --locked -p codegraph-store`                                        | 0    | **100** lib + 91 across 8 integration targets, all `ok`  |
+
+The remaining gates (`check-workspace-versions.sh`, `make fmt`, `make ci` twice,
+golden diff, `Cargo.lock` SHA) are recorded immediately below.
+
+### CI round 4 — final gate statuses
+
+| Command                                              | Exit  | Result                                                                         |
+| ---------------------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| `bash scripts/check-workspace-versions.sh`           | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `make fmt`                                           | **0** | run AFTER this prose, BEFORE CI                                                |
+| `make ci CARGO='cargo --locked'` run 1               | **0** | `✅ All CI checks passed!`                                                     |
+| `make ci CARGO='cargo --locked'` run 2               | **0** | `✅ All CI checks passed!`                                                     |
+| `git diff --stat c7800ca..HEAD -- reference/golden/` | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                               | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+The equivalence oracle again left untracked
+`reference/golden/{cuda,solidity}/colby.db-{wal,shm}`; removed before run 2 and
+before staging. Two files changed:
+`crates/codegraph-store/src/index_state_publisher.rs` and this ledger. Windows was
+NOT validated locally — the two cross-compilation routes still fail exactly as
+recorded above and no C toolchain can be installed here.

From 5845f1130cfc4b2ed7348396221a9cda9e25face Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 20:17:34 +0800
Subject: [PATCH 76/91] fix(ci): emit the legacy fixture path in the consumer's
 path domain

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md     | 236 ++++++++++++++++
 scripts/setup-legacy-fixture.sh               |  52 +++-
 .../tests/legacy-fixture-path-domain.test.sh  | 252 ++++++++++++++++++
 3 files changed, 536 insertions(+), 4 deletions(-)
 create mode 100755 scripts/tests/legacy-fixture-path-domain.test.sh

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index cfbb028..9227a57 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -8918,3 +8918,239 @@ before staging. Two files changed:
 `crates/codegraph-store/src/index_state_publisher.rs` and this ledger. Windows was
 NOT validated locally — the two cross-compilation routes still fail exactly as
 recorded above and no C toolchain can be installed here.
+
+## PR #173 CI round 5 — the legacy fixture path crossed a shell boundary it could not survive (2026-07-29)
+
+Sixth consecutive windows-only layer, and the first one that is neither a lint
+nor a code defect: it is a CI-wiring defect between two processes that disagree
+about what an absolute path means.
+
+### The failure, with its exact CI location
+
+Run `30449004902`, job `Windows`, step `Run tests`:
+
+```
+test legacy_scan_with_runtime_extension_override_does_not_weaken_storage_safety ... FAILED
+panicked at crates\codegraph-cli\tests\batch_m_legacy_extension_override.rs:330:13:
+CODEGRAPH_LEGACY_BIN failed frozen fixture verification: inspect configured legacy binary
+/tmp/codegraph-legacy-fixture/e52703f3a3d5bef90997ce23d9a3b49c980e6bcc1a078fdb1245ad1305a5bc09/codegraph.exe:
+The system cannot find the path specified. (os error 3)
+test result: FAILED. 19 passed; 1 failed
+```
+
+Every other test in that binary passed. That is the shape of the bug: the fixture
+was downloaded, digest-verified and version-verified SUCCESSFULLY by the setup
+step — the failing verification is the SECOND one, performed by the test process
+against the path the setup step handed it.
+
+### The mechanism — a path-domain mismatch, confirmed
+
+The orchestrator's trace is correct. Confirmed against the real files:
+
+1. `.github/workflows/ci.yml:101-103` — the `windows` job's fixture step is the
+   only step in that job with `shell: bash`, and it runs
+   `echo "CODEGRAPH_LEGACY_BIN=$(bash scripts/setup-legacy-fixture.sh)" >> "$GITHUB_ENV"`.
+   On `windows-latest`, `shell: bash` is **Git Bash** — an MSYS2 runtime.
+2. `scripts/setup-legacy-fixture.sh:57` computes
+   `CACHE_ROOT="${CODEGRAPH_LEGACY_FIXTURE_CACHE:-${TMPDIR:-/tmp}/codegraph-legacy-fixture}"`.
+   `CODEGRAPH_LEGACY_FIXTURE_CACHE` is not set by CI, and `TMPDIR` is not set in
+   Git Bash on the runner, so `CACHE_ROOT` becomes the literal string
+   `/tmp/codegraph-legacy-fixture`.
+3. `/tmp` under MSYS is a **virtual mount**, not a filesystem path. The MSYS
+   runtime maps it to something like
+   `C:\Users\runneradmin\AppData\Local\Temp`. Every filesystem call the SCRIPT
+   makes goes through that runtime, so the download, the `mkdir -p`, the digest
+   check and `"$EXE" --version` all succeed — the script's own view is coherent.
+4. The script's final line printed that MSYS path verbatim, and the workflow put
+   it in `$GITHUB_ENV`. `$GITHUB_ENV` is a plain text file; nothing translates it.
+5. `cargo test` is a **native Win32 process**. It reads the variable as an opaque
+   string and resolves it through the Win32 API, which has no `/tmp` mount and no
+   MSYS runtime. `\tmp\codegraph-legacy-fixture\...` does not exist relative to
+   any drive → `ERROR_PATH_NOT_FOUND`, surfaced by Rust as `os error 3`, "The
+   system cannot find the path specified".
+
+So the file EXISTS and is the correct, digest-verified v0.40.4 binary. Two
+processes simply disagree about the namespace the string belongs to. The
+error message even proves the file was fine when the script saw it: the script's
+own `--version` check ran against it and passed, or the script would have exited
+nonzero and the workflow step would have failed instead.
+
+Why this is a fixture-WIRING defect and not a fixture-CONTENT defect: nothing
+about the frozen binary, the manifest, the digests, or the test's property
+changed. The property under test — an unmodified published v0.40.4 scanner
+cannot weaken v2 storage safety — is intact and must keep being proven on
+Windows.
+
+### The fix — option (a), the emitter owns its output contract
+
+`scripts/setup-legacy-fixture.sh` now translates the path it PRINTS into the
+consumer's domain, via a single new `emit_consumer_path` used by both exit routes
+(the revalidated-cache-hit route at what is now line 354 and the
+fresh-download route at the end).
+
+On a Windows shell (`uname -s` matching `MINGW*`/`MSYS*`/`CYGWIN*`/`Windows_NT`)
+it runs `cygpath -m -- "$path"`. Everywhere else it prints the path byte-for-byte
+and never invokes `cygpath` — which matters, because `cygpath` does not exist on
+Linux or macOS.
+
+Three deliberate choices:
+
+- **`-m`, not `-w`.** Both give a native absolute path; `-m` uses forward slashes
+  (`C:/Users/...`) and `-w` uses backslashes (`C:\Users\...`). Win32 accepts
+  both, and Rust's `Path` handles both. Forward slashes are chosen because the
+  string travels through `$GITHUB_ENV` and then through Rust string handling, and
+  a backslash path invites an escaping bug in any future consumer that does not
+  treat it as opaque. Forward slashes have no such failure mode.
+- **A missing or failing `cygpath` is FATAL, not a silent passthrough.** On a
+  Windows host, printing the untranslated path is exactly the bug being fixed;
+  degrading to it would reintroduce a failure 40 lines later with a much worse
+  error message. `cygpath` ships with Git Bash and with Cygwin, so its absence on
+  a Windows host is a broken environment, and a fixture that cannot be handed to
+  its consumer is a setup FAILURE — the same fail-closed stance the rest of this
+  script takes.
+- **Only the OUTPUT is translated.** `$EXE` keeps its shell-native form for every
+  internal use (`sha256_of`, `chmod`, `"$EXE" --version`, `rm -f`), because those
+  all run through the MSYS runtime and would BREAK if handed a `C:/...` path in
+  some contexts. The translation happens at the process boundary, which is where
+  the domain actually changes.
+
+Why not the alternatives:
+
+- **(b) convert in the workflow.** Works, but puts the knowledge in the caller.
+  The script has two callers already — the `test` job, the `windows` job — and a
+  third that is not a workflow at all (`legacy_bin()` in
+  `batch_m_legacy_extension_override.rs:335` shells out to the script directly
+  when `CODEGRAPH_LEGACY_BIN` is unset). That third caller is the decisive
+  argument: on a Windows developer machine running `cargo test` outside CI, the
+  fallback path spawns `bash scripts/setup-legacy-fixture.sh` from a NATIVE
+  process and parses its stdout. Fixing only the workflow leaves that route
+  broken. Fixing the script fixes every consumer at once.
+- **(c) make the test tolerate MSYS paths.** Rejected. It would teach production
+  test code about a CI shell's private namespace, and it would leave the same
+  trap armed for every other consumer of this script — including the local
+  Windows developer route above.
+
+### Cross-domain audit — every bash→native boundary in CI
+
+Enumerated mechanically (`yaml.safe_load` over both workflow files, listing each
+`run` step with its effective shell and its job's `runs-on`, including the
+release matrix's per-`os` entries). Neither workflow sets a workflow-level or
+job-level `defaults.shell`, so a step with no `shell:` key uses the runner
+default: `bash` on ubuntu/macos, **PowerShell** on windows.
+
+| location                                                                             | emits                            | consumed by                                 | domains match?                                                       | verdict                                                                                                        |
+| ------------------------------------------------------------------------------------ | -------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `ci.yml:103` windows fixture step (`shell: bash`)                                    | fixture exe path → `$GITHUB_ENV` | native `cargo test` (2 later steps)         | **NO — MSYS vs Win32**                                               | **the bug; FIXED** in the script                                                                               |
+| `ci.yml:48` linux fixture step (default bash)                                        | fixture exe path → `$GITHUB_ENV` | native `cargo test`                         | yes — one POSIX domain on ubuntu                                     | correct; output byte-identical after the fix                                                                   |
+| `batch_m_legacy_extension_override.rs:335` fallback                                  | script stdout → `PathBuf`        | the test process itself (native on windows) | **would NOT have matched on windows**                                | **also FIXED** by the same change — the reason the fix belongs in the script                                   |
+| `ci.yml` windows `Clippy lint`, `Run tests`, `Run Batch M item 16`                   | nothing; no paths emitted        | —                                           | n/a — PowerShell steps, cargo-relative                               | no boundary                                                                                                    |
+| `release-please.yml:255-260` `Package (unix tar.gz)` (`shell: bash`)                 | writes `dist/*.tar.gz`           | `upload-artifact` (`path: dist/*`)          | yes — gated `if: matrix.archive == 'tar.gz'`, i.e. ubuntu/macos only | no windows involvement                                                                                         |
+| `release-please.yml:263-269` `Package (windows zip)` (`shell: pwsh`)                 | writes `dist/*.zip`              | `upload-artifact`                           | yes — pwsh is native; repo-relative paths                            | correct by construction                                                                                        |
+| `release-please.yml:311-327` `Generate SHA256SUMS` (`shell: bash`)                   | `SHA256SUMS` in `dist/`          | `action-gh-release`                         | yes — `runs-on: ubuntu-latest`                                       | no windows shell in this job                                                                                   |
+| `release-please.yml:122` `sha=$(git rev-list ...)` → `$GITHUB_OUTPUT`                | a commit SHA, not a path         | later `run` in same ubuntu job              | n/a — not a path                                                     | no boundary                                                                                                    |
+| `release-please.yml:68-74` `build_artifacts`/`tag_name`/`version` → `$GITHUB_OUTPUT` | non-path scalars                 | matrix jobs incl. windows                   | n/a — not paths                                                      | no boundary                                                                                                    |
+| `ci.yml:236` `mapfile`/`jq` gate body                                                | job names, not paths             | same step                                   | n/a                                                                  | no boundary                                                                                                    |
+| `scripts/check-workspace-versions.sh:94-106` `/tmp/cwv_meta_err.$$`                  | a POSIX temp file                | itself only                                 | yes — same shell reads and deletes it                                | safe; and this gate runs only in `make ci`/pre-push/`test` job, never on windows                               |
+| `scripts/install.sh:116` `mktemp -d`                                                 | temp dir                         | itself only                                 | yes                                                                  | POSIX installer; the Windows installer is `install.ps1`, which uses `[System.IO.Path]::GetTempPath()` natively |
+| `scripts/tests/*.test.sh`                                                            | fixture roots                    | themselves                                  | yes                                                                  | never invoked by any workflow; local POSIX harnesses                                                           |
+
+Result: **exactly one** bash→native path boundary existed, plus the same defect
+on the script's non-CI fallback route. Both are closed by the one change. No
+other emitter in either workflow hands a path across a shell-domain boundary; the
+remaining `/tmp` uses are single-domain (a shell writing and reading its own temp
+file) or POSIX-only by construction.
+
+`GITHUB_PATH` is never written by either workflow, so there is no PATH-domain
+variant of this bug.
+
+Not fixed, with reasoning: nothing. Unlike round 4, this audit found no
+"uncertain" rows — a step's shell and its runner OS are both statically
+declared, so every boundary is decidable from the files without needing a CI
+observation.
+
+### Regression proof — the Windows branch is tested on Linux
+
+The translation only executes on Windows, which no local run can reach. That is
+precisely the code that rots. `scripts/tests/legacy-fixture-path-domain.test.sh`
+therefore extracts `emit_consumer_path` **verbatim** from the shipped script
+(never re-implementing it, so the harness cannot drift) and drives it with a
+stubbed `uname` and a stubbed `cygpath`, under the same `set -euo pipefail` and
+the same `die` shape as the real script.
+
+Ten assertions: Linux and Darwin pass the path through byte-for-byte and never
+consult `cygpath`; all four Windows `uname` spellings translate; `cygpath` is
+asserted to be invoked with `-m` and the result asserted to contain no
+backslash; a missing `cygpath`, a nonzero `cygpath`, and an empty `cygpath`
+result each fail loudly and emit NOTHING on stdout; and a static check asserts
+the shipped script has zero remaining raw `$EXE` emissions and exactly two
+translated ones, so regressing only ONE of the two exit routes — the way this
+class of bug hides — is caught.
+
+Two negative controls were run:
+
+- restoring `b71a5f1`'s pre-fix script → the harness exits **2** and reports it
+  cannot extract `emit_consumer_path`, i.e. the harness genuinely depends on the
+  fix existing;
+- keeping the translator but reverting ONLY the cache-hit emission to
+  `printf '%s\n' "$EXE"` → **9 passed, 2 failed**, both failures on the static
+  route check, exit **1**. The nine behavioral scenarios still pass, which is
+  exactly why the static check is there.
+
+### Linux/macOS output is unchanged — proven, not asserted
+
+The script was run before and after the change on this host, capturing stdout and
+stderr separately:
+
+| check                              | result                                                                                                   |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `uname -s` / `TMPDIR` on this host | `Linux` / **unset** (so `CACHE_ROOT` is `/tmp/codegraph-legacy-fixture`, same as the CI linux job)       |
+| `command -v cygpath`               | **absent** (exit 1) — confirming the guard must be, and is, a real platform check                        |
+| stdout before the change           | `/tmp/codegraph-legacy-fixture/1a14d195…/codegraph`                                                      |
+| stdout after the change            | identical; `diff` clean; both SHA-256 `63cca31136bc556a423eccb874f36d4ec20ed848c27ee8e31ec37392d2ffcdac` |
+| stderr before vs after             | `diff` clean                                                                                             |
+| `--print` mode after the change    | exit **0**, same path                                                                                    |
+
+macOS is not runnable here, but it takes the identical branch: `uname -s` returns
+`Darwin`, which falls into the non-Windows arm and prints verbatim without ever
+looking for `cygpath`. Harness scenario `B_darwin` exercises exactly that arm
+with a stubbed `Darwin` uname.
+
+### Gates and their REAL exit status
+
+Each run separately; none joined with `&&`.
+
+| Command                                                       | Exit  | Result                                                        |
+| ------------------------------------------------------------- | ----- | ------------------------------------------------------------- |
+| `bash scripts/setup-legacy-fixture.sh` (baseline, pre-change) | **0** | `/tmp/codegraph-legacy-fixture/1a14d195…/codegraph`           |
+| `bash scripts/setup-legacy-fixture.sh` (post-change)          | **0** | byte-identical stdout AND stderr                              |
+| `bash scripts/setup-legacy-fixture.sh --print` (post-change)  | **0** | same path                                                     |
+| `bash scripts/tests/legacy-fixture-path-domain.test.sh`       | **0** | **10 passed, 0 failed**                                       |
+| negative control: pre-fix script                              | **2** | harness cannot find `emit_consumer_path` — depends on the fix |
+| negative control: one emission site regressed                 | **1** | **9 passed, 2 failed**, both on the static route check        |
+
+The harness is a manual POSIX fixture harness, run the same way as
+`scripts/tests/install-checksum.test.sh`, `asset-name-drift.test.sh`,
+`ci-gate.test.sh` and `check-workspace-versions.test.sh` — none of the four are
+wired into `guardrail.sh`, `make ci` or any workflow, and this one follows that
+existing convention rather than changing it.
+
+### CI round 5 — final gate statuses
+
+| Command                                                                        | Exit  | Result                                                                         |
+| ------------------------------------------------------------------------------ | ----- | ------------------------------------------------------------------------------ |
+| `bash scripts/check-workspace-versions.sh`                                     | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `cargo test --locked -p codegraph-rs --test batch_m_legacy_extension_override` | **0** | **21 passed, 0 failed** — incl. the test that fails on windows                 |
+| same, with `CODEGRAPH_LEGACY_BIN` exported from the fixed script               | **0** | **21 passed, 0 failed** — proves the emitted path is consumable                |
+| `make fmt`                                                                     | **0** | run AFTER this prose, BEFORE CI                                                |
+| re-ran the harness + the script after `make fmt`                               | **0** | 10 passed; emitted path still byte-identical to the baseline                   |
+| `make ci CARGO='cargo --locked'` run 1                                         | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`              |
+| `make ci CARGO='cargo --locked'` run 2                                         | **0** | `✅ All CI checks passed!`                                                     |
+| `git diff --stat b71a5f1..HEAD -- reference/golden/`                           | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                                                         | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+The equivalence oracle left NO untracked `colby.db-{wal,shm}` sidecars this round;
+`git status --short` after both CI runs showed only the three intended files.
+Three files changed: `scripts/setup-legacy-fixture.sh`, the new
+`scripts/tests/legacy-fixture-path-domain.test.sh`, and this ledger. **Windows
+was NOT validated locally** — the whole point of this defect is that it only
+exists across a Windows shell boundary; only the `Windows` CI job can confirm it.
diff --git a/scripts/setup-legacy-fixture.sh b/scripts/setup-legacy-fixture.sh
index 28e729a..0fbdf6c 100755
--- a/scripts/setup-legacy-fixture.sh
+++ b/scripts/setup-legacy-fixture.sh
@@ -43,8 +43,20 @@
 # `--print` is the only accepted argument; anything else is a usage error.
 #
 # Output: the absolute path of the verified legacy executable on stdout (last
-# line). All diagnostics go to stderr. Tests consume the path via
-# CODEGRAPH_LEGACY_BIN, which this script's caller exports.
+# line), expressed in the path domain of the CONSUMER, not of this shell. All
+# diagnostics go to stderr. Tests consume the path via CODEGRAPH_LEGACY_BIN,
+# which this script's caller exports.
+#
+# WHY the output domain is called out: on Windows this script runs under an
+# MSYS/Cygwin bash (Git Bash on the CI runner), whose absolute paths — `/tmp/x`,
+# `/c/Users/...` — are a VIRTUAL namespace understood only by the MSYS runtime.
+# The consumer is a NATIVE Win32 process (`cargo test`), which resolves the
+# string literally through the Win32 API and cannot see that namespace: a
+# perfectly valid `/tmp/...` fixture path fails there with `os error 3`, "The
+# system cannot find the path specified". So the final path is translated to a
+# native Win32 form before it is printed; every INTERNAL use keeps the shell's
+# own form. On Linux and macOS there is one path domain and nothing is
+# translated.
 
 set -euo pipefail
 
@@ -238,6 +250,38 @@ extract_member() {
     STAGE_DIR=""
 }
 
+# emit_consumer_path PATH — print PATH in the path domain of the NATIVE consumer.
+#
+# Windows only, and only when `cygpath` is actually present: MSYS/Cygwin paths
+# are invisible to a Win32 process (see the header). `cygpath -m` yields a native
+# absolute path with FORWARD slashes (`C:/Users/...`), which Win32 accepts and
+# which needs no backslash escaping when it travels through $GITHUB_ENV and Rust
+# string handling. A missing or failing `cygpath` is fatal, not silently skipped:
+# emitting an MSYS path there would hand the consumer a path it cannot open, and
+# a fixture that cannot be verified is a setup FAILURE. Every other host has a
+# single path domain and prints the path verbatim.
+emit_consumer_path() {
+    local path="$1" native
+    case "$(uname -s 2>/dev/null || printf 'unknown')" in
+        MINGW* | MSYS* | CYGWIN* | Windows_NT) ;;
+        *)
+            printf '%s\n' "$path"
+            return 0
+            ;;
+    esac
+    command -v cygpath > /dev/null 2>&1 \
+        || die "cygpath not found on PATH.
+This shell reports a Windows host, so the fixture path must be translated from
+the MSYS/Cygwin namespace ('$path') into a native Win32 path before a NATIVE
+consumer such as 'cargo test' can open it. Without cygpath that translation
+cannot be performed, and emitting the untranslated path would fail later with
+'The system cannot find the path specified'."
+    native="$(cygpath -m -- "$path")" \
+        || die "cygpath could not translate the fixture path to a native Win32 path: $path"
+    [ -n "$native" ] || die "cygpath returned an empty native path for: $path"
+    printf '%s\n' "$native"
+}
+
 size_of() {
     local path="$1" size
     if size="$(wc -c <"$path" 2>/dev/null)"; then
@@ -307,7 +351,7 @@ revalidate() {
 }
 
 if revalidate; then
-    printf '%s\n' "$EXE"
+    emit_consumer_path "$EXE"
     exit 0
 fi
 
@@ -370,4 +414,4 @@ if [ "$observed_version" != "$EXPECTED_VERSION" ]; then
 fi
 printf 'setup-legacy-fixture: verified %s\n' "$EXE_SHA" >&2
 
-printf '%s\n' "$EXE"
+emit_consumer_path "$EXE"
diff --git a/scripts/tests/legacy-fixture-path-domain.test.sh b/scripts/tests/legacy-fixture-path-domain.test.sh
new file mode 100755
index 0000000..2623788
--- /dev/null
+++ b/scripts/tests/legacy-fixture-path-domain.test.sh
@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# legacy-fixture-path-domain.test.sh — fixture harness for the legacy-fixture
+# path-domain translation.
+#
+# WHY this harness exists: scripts/setup-legacy-fixture.sh runs under MSYS bash on
+# the Windows CI runner, but the path it prints is consumed by a NATIVE Win32
+# process (`cargo test` reading CODEGRAPH_LEGACY_BIN). An MSYS absolute path
+# (`/tmp/...`) is a virtual namespace Win32 cannot resolve, so the emitted path
+# must be translated. That translation only ever executes on Windows, which means
+# a Linux/macOS test run can never observe it — it is exactly the kind of code
+# that rots silently. Here it is driven directly with a stubbed `uname` and a
+# stubbed `cygpath`, so the Windows branch is exercised on ANY host.
+#
+# The function under test is EXTRACTED VERBATIM from the shipped script (never
+# re-implemented here), so the harness cannot drift from the real emitter.
+#
+# It proves:
+#   * a non-Windows `uname` prints the path byte-for-byte, with no cygpath call,
+#   * an MSYS/MINGW/CYGWIN/Windows_NT `uname` prints cygpath's native path,
+#   * cygpath is invoked with `-m` (forward slashes: no backslash escaping when
+#     the path crosses $GITHUB_ENV and Rust string handling),
+#   * a missing cygpath on a Windows host FAILS LOUDLY instead of emitting an
+#     untranslated MSYS path the consumer could not open,
+#   * a cygpath that exits nonzero fails,
+#   * a cygpath that prints nothing fails,
+#   * the shipped script has NO remaining emission path that prints the raw
+#     internal `$EXE` (both the cache-hit and the fresh-download exit route
+#     through the translator).
+#
+# Nothing under the real repository is touched, no network request is made, and
+# no real fixture is downloaded.
+#
+# Usage: scripts/tests/legacy-fixture-path-domain.test.sh
+
+set -euo pipefail
+
+HARNESS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+REPO_ROOT="$(cd -- "$HARNESS_DIR/../.." && pwd -P)"
+SCRIPT="$REPO_ROOT/scripts/setup-legacy-fixture.sh"
+
+[ -f "$SCRIPT" ] || {
+	printf 'harness: script not found: %s\n' "$SCRIPT" >&2
+	exit 2
+}
+
+WORK="$(mktemp -d)"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+ok() {
+	printf 'PASS: %s\n' "$1"
+	PASS=$((PASS + 1))
+}
+bad() {
+	printf 'FAIL: %s\n' "$1" >&2
+	FAIL=$((FAIL + 1))
+}
+
+# The emitter, lifted verbatim from the shipped script.
+FN="$WORK/emit.sh"
+awk '/^emit_consumer_path\(\) \{/,/^\}/' "$SCRIPT" > "$FN"
+grep -q '^emit_consumer_path() {' "$FN" || {
+	printf 'harness: could not extract emit_consumer_path from %s\n' "$SCRIPT" >&2
+	exit 2
+}
+grep -q '^}$' "$FN" || {
+	printf 'harness: extracted emit_consumer_path is not terminated\n' >&2
+	exit 2
+}
+
+# Driver: same `set -euo pipefail` and same `die` shape as the real script, so a
+# `die` inside the function terminates the process exactly as it would in situ.
+DRIVER="$WORK/driver.sh"
+cat > "$DRIVER" << 'DRV'
+set -euo pipefail
+die() {
+	printf 'setup-legacy-fixture: %s\n' "$1" >&2
+	exit 1
+}
+. "$CG_FN"
+emit_consumer_path "$CG_INPUT"
+DRV
+
+# stub_bin DIR UNAME_S [CYGPATH_BODY]
+#   Builds a sandbox PATH whose `uname` reports UNAME_S. `cygpath` is created only
+#   when CYGPATH_BODY is given, so "cygpath absent" is a genuine absence.
+stub_bin() {
+	local dir="$1" uname_s="$2" cygpath_body="${3-}"
+	mkdir -p "$dir"
+	printf '#!/bin/sh\nprintf "%%s\\n" "%s"\n' "$uname_s" > "$dir/uname"
+	chmod +x "$dir/uname"
+	if [ -n "$cygpath_body" ]; then
+		printf '#!/bin/sh\n%s\n' "$cygpath_body" > "$dir/cygpath"
+		chmod +x "$dir/cygpath"
+	fi
+}
+
+# run_case LABEL UNAME_S INPUT [CYGPATH_BODY] -> RC, OUT, ERR
+RC=0
+OUT=""
+ERR=""
+run_case() {
+	local label="$1" uname_s="$2" input="$3" cygpath_body="${4-}"
+	local dir="$WORK/$label"
+	rm -rf "$dir"
+	stub_bin "$dir/bin" "$uname_s" "$cygpath_body"
+	set +e
+	OUT="$(
+		PATH="$dir/bin:/usr/bin:/bin" CG_FN="$FN" CG_INPUT="$input" \
+			bash "$DRIVER" 2> "$dir/err"
+	)"
+	RC=$?
+	set -e
+	ERR="$(cat "$dir/err")"
+}
+
+MSYS_PATH='/tmp/codegraph-legacy-fixture/e52703f3/codegraph.exe'
+NATIVE_PATH='C:/Users/runneradmin/AppData/Local/Temp/codegraph-legacy-fixture/e52703f3/codegraph.exe'
+# Records its argv so the harness can assert the `-m` flag, then translates.
+CYGPATH_OK='printf "%s\n" "$*" > "$CG_ARGV_LOG"
+printf "C:/Users/runneradmin/AppData/Local/Temp%s\n" "${3#/tmp}"'
+
+# --- Scenario A — Linux host: byte-identical passthrough, no cygpath. --------
+a_ok=1
+run_case A_linux Linux '/tmp/codegraph-legacy-fixture/1a14d195/codegraph'
+[ "$RC" -eq 0 ] || {
+	bad "A_linux: expected exit 0, got $RC ($ERR)"
+	a_ok=0
+}
+[ "$OUT" = '/tmp/codegraph-legacy-fixture/1a14d195/codegraph' ] || {
+	bad "A_linux: path was rewritten: $OUT"
+	a_ok=0
+}
+[ -z "$ERR" ] || {
+	bad "A_linux: unexpected stderr: $ERR"
+	a_ok=0
+}
+[ "$a_ok" -eq 1 ] && ok "A_linux (exit=0, path emitted verbatim, cygpath never consulted)"
+
+# --- Scenario B — Darwin host: byte-identical passthrough. -------------------
+b_ok=1
+run_case B_darwin Darwin '/Users/runner/tmp/fixture/codegraph'
+[ "$RC" -eq 0 ] || {
+	bad "B_darwin: expected exit 0, got $RC ($ERR)"
+	b_ok=0
+}
+[ "$OUT" = '/Users/runner/tmp/fixture/codegraph' ] || {
+	bad "B_darwin: path was rewritten: $OUT"
+	b_ok=0
+}
+[ "$b_ok" -eq 1 ] && ok "B_darwin (exit=0, path emitted verbatim)"
+
+# --- Scenario C — every Windows-shell uname: translated to a native path. ----
+for uname_s in MINGW64_NT-10.0-20348 MSYS_NT-10.0-20348 CYGWIN_NT-10.0 Windows_NT; do
+	c_ok=1
+	CG_ARGV_LOG="$WORK/argv_$uname_s.txt"
+	export CG_ARGV_LOG
+	run_case "C_$uname_s" "$uname_s" "$MSYS_PATH" "$CYGPATH_OK"
+	[ "$RC" -eq 0 ] || {
+		bad "C_$uname_s: expected exit 0, got $RC ($ERR)"
+		c_ok=0
+	}
+	[ "$OUT" = "$NATIVE_PATH" ] || {
+		bad "C_$uname_s: expected native path, got: $OUT"
+		c_ok=0
+	}
+	case "$OUT" in
+	*'\'*)
+		bad "C_$uname_s: emitted path contains a backslash: $OUT"
+		c_ok=0
+		;;
+	esac
+	grep -q -- '-m' "$CG_ARGV_LOG" || {
+		bad "C_$uname_s: cygpath was not invoked with -m (argv: $(cat "$CG_ARGV_LOG"))"
+		c_ok=0
+	}
+	unset CG_ARGV_LOG
+	[ "$c_ok" -eq 1 ] && ok "C_$uname_s (exit=0, MSYS path translated via 'cygpath -m', forward slashes)"
+done
+
+# --- Scenario D — Windows host, cygpath ABSENT: loud failure, no output. -----
+d_ok=1
+run_case D_no_cygpath MINGW64_NT-10.0-20348 "$MSYS_PATH"
+[ "$RC" -ne 0 ] || {
+	bad "D_no_cygpath: expected nonzero exit, got 0"
+	d_ok=0
+}
+[ -z "$OUT" ] || {
+	bad "D_no_cygpath: an untranslated path was emitted anyway: $OUT"
+	d_ok=0
+}
+printf '%s' "$ERR" | grep -q 'cygpath not found on PATH' || {
+	bad "D_no_cygpath: stderr did not name the missing tool: $ERR"
+	d_ok=0
+}
+[ "$d_ok" -eq 1 ] && ok "D_no_cygpath (exit=$RC, refuses to emit an MSYS path Win32 cannot open)"
+
+# --- Scenario E — cygpath exits nonzero: failure, no output. -----------------
+e_ok=1
+run_case E_cygpath_fails MSYS_NT-10.0 "$MSYS_PATH" 'exit 3'
+[ "$RC" -ne 0 ] || {
+	bad "E_cygpath_fails: expected nonzero exit, got 0"
+	e_ok=0
+}
+[ -z "$OUT" ] || {
+	bad "E_cygpath_fails: emitted a path despite a failed translation: $OUT"
+	e_ok=0
+}
+printf '%s' "$ERR" | grep -q 'could not translate the fixture path' || {
+	bad "E_cygpath_fails: stderr did not explain the failure: $ERR"
+	e_ok=0
+}
+[ "$e_ok" -eq 1 ] && ok "E_cygpath_fails (exit=$RC, a failed translation is not a pass)"
+
+# --- Scenario F — cygpath prints nothing: failure, no output. ----------------
+f_ok=1
+run_case F_cygpath_empty CYGWIN_NT-10.0 "$MSYS_PATH" 'exit 0'
+[ "$RC" -ne 0 ] || {
+	bad "F_cygpath_empty: expected nonzero exit, got 0"
+	f_ok=0
+}
+[ -z "$OUT" ] || {
+	bad "F_cygpath_empty: emitted a path despite an empty translation: $OUT"
+	f_ok=0
+}
+printf '%s' "$ERR" | grep -q 'empty native path' || {
+	bad "F_cygpath_empty: stderr did not explain the failure: $ERR"
+	f_ok=0
+}
+[ "$f_ok" -eq 1 ] && ok "F_cygpath_empty (exit=$RC, an empty translation is not a pass)"
+
+# --- Scenario G — no untranslated emission survives in the shipped script. ---
+# Both exit routes (revalidated cache hit and fresh verified download) must print
+# through the translator; a bare `printf '%s\n' "$EXE"` would reintroduce the bug
+# on exactly one of them, which is how it went unnoticed for six CI rounds.
+g_ok=1
+raw_emissions="$(grep -c '^[[:space:]]*printf .*"\$EXE"[[:space:]]*$' "$SCRIPT" || true)"
+[ "$raw_emissions" = "0" ] || {
+	bad "G_no_raw_emit: $raw_emissions raw \$EXE emission(s) remain in $SCRIPT"
+	g_ok=0
+}
+translated="$(grep -c '^[[:space:]]*emit_consumer_path "\$EXE"$' "$SCRIPT" || true)"
+[ "$translated" = "2" ] || {
+	bad "G_no_raw_emit: expected 2 translated emissions (cache hit + fresh download), found $translated"
+	g_ok=0
+}
+[ "$g_ok" -eq 1 ] && ok "G_no_raw_emit (both exit routes emit through emit_consumer_path)"
+
+printf '=== harness result: %d passed, %d failed ===\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

From c126f36d56a80bde28f94a3cceb6b1f2ebd8e786 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 22:10:40 +0800
Subject: [PATCH 77/91] test(cli): build the nested status project path in the
 native separator domain

---
 crates/codegraph-cli/tests/batch_m_uninit.rs | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/crates/codegraph-cli/tests/batch_m_uninit.rs b/crates/codegraph-cli/tests/batch_m_uninit.rs
index ef94192..122d102 100644
--- a/crates/codegraph-cli/tests/batch_m_uninit.rs
+++ b/crates/codegraph-cli/tests/batch_m_uninit.rs
@@ -545,7 +545,12 @@ fn nested_status_discovers_interrupted_uninit_with_relative_configured_root() {
 fn lock_only_parent_is_not_a_status_discovery_marker() {
     let dir = TestDir::new("lock-only");
     let project = dir.path().join("project");
-    let nested = project.join("a/b");
+    // NOT `join("a/b")`: `Path::join` keeps an embedded `/` verbatim, so on
+    // Windows that literal yields a MIXED `…\project\a/b`, while the CLI re-emits
+    // this path through `normalize_lexical` as `…\project\a\b`. The assertion
+    // below compares the reported `projectPath` to this value, so it must be
+    // built in the same native-separator domain the CLI prints.
+    let nested = project.join("a").join("b");
     std::fs::create_dir_all(&nested).expect("create nested project directory");
     let paths = IndexPaths::resolve(&project, None).expect("resolve lifecycle paths");
     std::fs::create_dir(paths.current_root()).expect("create current root");

From 955b89b25c2ba22592a0276c3511003ec7895593 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 22:15:02 +0800
Subject: [PATCH 78/91] test(daemon): serialize the idle-window env against the
 detached spawn

---
 crates/codegraph-cli/tests/daemon_idle.rs  | 19 +++++++++++++++++++
 crates/codegraph-cli/tests/daemon_sweep.rs | 16 ++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/crates/codegraph-cli/tests/daemon_idle.rs b/crates/codegraph-cli/tests/daemon_idle.rs
index 95b2d7d..47bc6e4 100644
--- a/crates/codegraph-cli/tests/daemon_idle.rs
+++ b/crates/codegraph-cli/tests/daemon_idle.rs
@@ -15,6 +15,7 @@ use std::fs;
 use std::io::{BufRead, BufReader};
 use std::path::{Path, PathBuf};
 use std::process::Command;
+use std::sync::{Mutex, MutexGuard, OnceLock};
 use std::time::{Duration, Instant};
 
 use codegraph_daemon::{
@@ -94,10 +95,28 @@ fn indexed_project(label: &str) -> (TestDir, PathBuf) {
     (dir, project)
 }
 
+/// `std::env` is process-global and BOTH tests in this binary run in parallel,
+/// each setting `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` to its own window and then
+/// REMOVING it. `Command` snapshots env inside `spawn_detached_daemon`, so a
+/// sibling's `remove_var` landing between this test's `set_var` and that
+/// snapshot hands the daemon NO idle var — it falls back to the 300 000 ms
+/// default and outlives any per-test deadline. Serialize the whole
+/// set → spawn → restore region so the spawned daemon always inherits the
+/// window its own test chose.
+fn env_guard() -> MutexGuard<'static, ()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
 /// Spawn the detached daemon with a SHORT idle timeout so the test runs fast.
 /// `Command` (inside `spawn_detached_daemon`) snapshots env at spawn time, so
 /// setting it here is inherited by the daemon process.
 fn spawn_idle_daemon(project: &Path, idle_ms: &str) {
+    let _env = env_guard();
+    // SAFETY: the env_guard held for this whole body serializes every
+    // set/remove in this binary against the spawn that snapshots them.
     unsafe { std::env::set_var("CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS", idle_ms) };
     unsafe { std::env::set_var("CODEGRAPH_WATCH_DEBOUNCE_MS", "100") };
     spawn_detached_daemon(&bin(), project, false).expect("spawn_detached_daemon");
diff --git a/crates/codegraph-cli/tests/daemon_sweep.rs b/crates/codegraph-cli/tests/daemon_sweep.rs
index 8899079..ffe28b8 100644
--- a/crates/codegraph-cli/tests/daemon_sweep.rs
+++ b/crates/codegraph-cli/tests/daemon_sweep.rs
@@ -17,6 +17,7 @@ use std::fs;
 use std::io::{BufRead, BufReader, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command};
+use std::sync::{Mutex, MutexGuard, OnceLock};
 use std::time::{Duration, Instant};
 
 use codegraph_daemon::{
@@ -96,9 +97,24 @@ fn indexed_project(label: &str) -> (TestDir, PathBuf) {
     (dir, project)
 }
 
+/// Same process-global-env hazard as `daemon_idle.rs`: both tests here spawn a
+/// daemon through the set → spawn → remove sequence below, and `Command`
+/// snapshots env INSIDE `spawn_detached_daemon`. A sibling's `remove_var`
+/// landing in that window hands the daemon no sweep/idle vars, so it falls back
+/// to the 30 000 / 300 000 ms defaults and outlives the test's deadline.
+fn env_guard() -> MutexGuard<'static, ()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
 /// Spawn the detached daemon with a SHORT sweep + idle window so the test is
 /// fast. `Command` snapshots env at spawn time, so the daemon inherits these.
 fn spawn_sweep_daemon(project: &Path) {
+    let _env = env_guard();
+    // SAFETY: the env_guard held for this whole body serializes every
+    // set/remove in this binary against the spawn that snapshots them.
     unsafe { std::env::set_var("CODEGRAPH_DAEMON_CLIENT_SWEEP_MS", "200") };
     unsafe { std::env::set_var("CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS", "500") };
     unsafe { std::env::set_var("CODEGRAPH_WATCH_DEBOUNCE_MS", "100") };

From a0315daffe76d766178907b0f3b44faf0922f058 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 22:15:16 +0800
Subject: [PATCH 79/91] docs: record the round-six windows path and daemon
 env-race diagnoses

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 215 ++++++++++++++++++++++
 1 file changed, 215 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 9227a57..e0ad882 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9154,3 +9154,218 @@ Three files changed: `scripts/setup-legacy-fixture.sh`, the new
 `scripts/tests/legacy-fixture-path-domain.test.sh`, and this ledger. **Windows
 was NOT validated locally** — the whole point of this defect is that it only
 exists across a Windows shell boundary; only the `Windows` CI job can confirm it.
+
+## PR #173 CI round 6 — two failures, two unrelated root causes; the gate itself was innocent (2026-07-29)
+
+Run [30451206766](https://github.com/sunerpy/codegraph-rust/actions/runs/30451206766)
+on `5845f11`. `Test` (Linux) and `Security Audit` PASS. Two jobs red:
+
+| Job                                                                                              | Step                     | Failure                                                                       |
+| ------------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------------------- |
+| `Windows`                                                                                        | Run tests                | `lock_only_parent_is_not_a_status_discovery_marker` — `batch_m_uninit.rs:558` |
+| [`Coverage`](https://github.com/sunerpy/codegraph-rust/actions/runs/30451206766/job/90573437980) | Generate coverage (lcov) | `daemon_idle_exits_after_last_client` — `daemon_idle.rs:218`, exit status 101 |
+| `CI Success`                                                                                     | Check job status         | consequence only: `windows` was the sole ❌ row                               |
+
+### The gate-membership question, answered first
+
+`Coverage` did NOT leak into the gate. `ci-success` in `.github/workflows/ci.yml`
+declares `needs: [test, audit, windows]` — three jobs, `coverage` deliberately
+absent. Two independent proofs:
+
+1. The failing run's own `NEEDS_JSON`, echoed by the step, contains exactly
+   `test`, `audit`, `windows` and nothing else; the printed table was
+   `✅ audit`, `✅ test`, `❌ windows`, and `❌ CI failed: 1 of 3 required job(s)`.
+   So `CI Success` failed because of `Windows` ALONE.
+2. `bash scripts/check-ci-gate.sh` exits **0** locally and prints
+   `required jobs : audit, test, windows` /
+   `excluded (informational, justified): coverage`, then runs 16 truth-table
+   cases over the shipped step body.
+
+The gate added in `ec93ef6` is intact and needs no change. `codecov.yml` still
+carries `informational: true`; `Coverage` stays non-blocking by design. Its
+redness is a REAL test failure worth fixing on its own merits — it is simply not
+what turned `CI Success` red.
+
+### Failure 1 — a TEST-side path-separator assumption, not a production defect
+
+`crates/codegraph-cli/tests/batch_m_uninit.rs:548` built its nested directory
+from a slash-containing literal:
+
+```rust
+let nested = project.join("a/b");
+```
+
+`Path::join` does not translate an embedded `/`. On Windows the resulting
+`PathBuf` therefore stringifies with MIXED separators — `…\project\a/b`. The CLI
+does not: `cmd_status` takes its start path through
+`absolute_path` → `normalize_lexical`, which rebuilds the path from
+`Path::components()`, and the Windows path parser treats `/` as a separator and
+re-emits it as `\`. So the reported `projectPath` is correctly `…\project\a\b`
+and the EXPECTATION was the malformed value. The CI panic shows exactly that
+asymmetry — `left` is the CLI's (correct) output, `right` the test's literal:
+
+```
+ left: String("C:\\Users\\RUNNER~1\\...\\project\\a\\b")
+right: "C:\\Users\\RUNNER~1\\...\\project\\a/b"
+```
+
+Why only this one test of the six: the sibling
+`nested_status_discovers_authenticated_non_current_parent_states` (line 490) uses
+the same `join("a/b")` but asserts `projectPath` against `project`, never against
+`nested`, so it never stringifies the mixed path.
+
+**Verdict: the test's platform assumption is the defect.** Production is right on
+Windows, so nothing was gated and no coverage was lost — the invariant (a
+lock-only parent is NOT a discovery marker, so status reports the INVOCATION dir
+and `extractionStatus: missing`) is asserted exactly as before, against a path
+built component-by-component in the native separator domain:
+
+```rust
+let nested = project.join("a").join("b");
+```
+
+### Failure 2 — a REAL race on BOTH platforms: a sibling's `remove_var` steals the idle window
+
+The `Coverage` job is not instrumentation-sensitive and the failure is not a
+`cargo llvm-cov`, lcov-write or Codecov-upload problem: the failing step is
+`Generate coverage (lcov)`, and it failed because
+`cargo test --tests … --workspace` under it exited 101 on a genuine assertion.
+
+`daemon_idle.rs` holds TWO `#[test]`s that both run in parallel in one binary,
+and both spawn a detached daemon through:
+
+```rust
+unsafe { std::env::set_var("CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS", idle_ms) };
+spawn_detached_daemon(&bin(), project, false)?;   // Command snapshots env HERE
+unsafe { std::env::remove_var("CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS") };
+```
+
+`std::env` is process-global and `Command` snapshots the environment INSIDE
+`spawn_detached_daemon`. When the sibling's `remove_var` lands between this
+test's `set_var` and that snapshot, the daemon inherits NO idle var, so
+`resolve_idle_timeout_ms` falls back to `DEFAULT_IDLE_TIMEOUT_MS` = **300 000 ms**
+and the process cannot possibly be gone inside `wait_until_gone(…, 10s)`.
+
+The CI log confirms the interleave: both projects were initialized 2 ms apart
+(`12:23:04.4153` / `12:23:04.4177`) so both tests were in flight, and
+`daemon_stays_alive_with_active_client` (which spawns with `"500"`) finished at
+`12:23:05.64` — squarely inside the other test's spawn window.
+
+Proof by direct reconstruction, spawning the daemon with the idle var ABSENT and
+everything else identical (`/tmp/opencode/repro3.py`, three runs):
+
+```
+daemon STILL ALIVE 12.0s after last client disconnected -> reproduces the CI assertion failure
+```
+
+and with the var present, both the plain and the instrumented binary idle-exit
+identically, so instrumentation is exonerated:
+
+```
+plain          rc=0  exit_after_disconnect=2.22s  loop_break->stopped=0.01s
+instrumented   rc=0  exit_after_disconnect=2.22s  loop_break->stopped=0.01s
+```
+
+Why it is newly red rather than always red: it is a scheduling race, not a
+deterministic break. 15 plain runs, 12 CPU-pinned runs, 3 instrumented runs and a
+full instrumented `--workspace` pass all went green here; the six earlier
+`Coverage` runs simply won the race. Nothing about coverage causes it — the same
+binary under plain `cargo test` is equally exposed.
+
+**Fix: the same `ENV_LOCK` shape already used by `daemon_single_watcher.rs`** —
+one `OnceLock<Mutex<()>>` per test binary, held across the whole
+set → spawn → restore region so the spawned daemon always inherits the window its
+own test chose. No sleep, no widened timeout, no `#[ignore]`, no weakened
+assertion; the 10 s ceiling and both assertions are untouched.
+`daemon_sweep.rs` carries the identical shape (two parallel tests, same
+set → spawn → remove sequence, `CODEGRAPH_DAEMON_CLIENT_SWEEP_MS` +
+`CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS`, defaults 30 000 / 300 000 ms) and was fixed
+in the same commit — it is the same bug, unfired.
+
+### Audit — the class behind each failure, swept across the workspace
+
+Failure 1's class: a test-built path string compared against a path the CLI
+printed. There are exactly THREE such comparisons in the whole workspace, all in
+`batch_m_uninit.rs`:
+
+| file:line               | assumption                                                     | Windows verdict                                                  |
+| ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `batch_m_uninit.rs:503` | `projectPath == project` where `project = dir.join("project")` | SAFE — single component, no embedded `/`                         |
+| `batch_m_uninit.rs:539` | `projectPath == project` where `project = dir.join("mini")`    | SAFE — single component                                          |
+| `batch_m_uninit.rs:563` | `projectPath == nested` where `nested` came from `join("a/b")` | **BROKEN — the reported failure. FIXED** (`join("a").join("b")`) |
+
+Other `join("<x>/<y>")` sites exist but none is stringified for comparison — they
+are only used as filesystem paths, where the mixed form resolves identically on
+Windows:
+
+| file:line                                                                   | use of the slash-joined path                       | Windows verdict                                            |
+| --------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
+| `batch_m_uninit.rs:388`, `:490`, `:514`                                     | `create_dir_all` + `current_dir` only              | SAFE — never stringified for an equality assertion         |
+| `batch_m_v2_namespace.rs:246/247/250`                                       | project roots passed as CLI args                   | SAFE — consumed as paths, compared only via `is_file()`    |
+| `catch_up.rs:180`, `sync_incremental.rs:*`, `live_update_direct.rs:196/244` | `fs::write` targets                                | SAFE — filesystem-only                                     |
+| `installer.rs:*`, `skill_install.rs:*`, `completions.rs:70/97`              | config file paths, `exists()` / content assertions | SAFE — no path-string equality                             |
+| `global_http_project_scoped_config.rs:*`                                    | `format!("{}", …display())` into JSON args         | unix-only target (`#![cfg(unix)]`) — never runs on Windows |
+| `batch_m_legacy_extension_override.rs:335`                                  | `script.display()` in a panic message              | SAFE — diagnostic text, not an assertion                   |
+
+Failure 2's class: a `set_var` → spawn sequence in a multi-test binary. Four test
+binaries mutate env and spawn a child; two were already guarded, two were not:
+
+| file                       | env sites | guard before             | Windows/Linux verdict                         |
+| -------------------------- | --------- | ------------------------ | --------------------------------------------- |
+| `daemon_single_watcher.rs` | 3         | `env_guard()` ✅         | SAFE — this is the shape copied               |
+| `lease_lifetime.rs`        | 4         | `test_serial_guard()` ✅ | SAFE — restores under the guard               |
+| `daemon_idle.rs`           | 3         | **none**                 | **BROKEN on both platforms. FIXED**           |
+| `daemon_sweep.rs`          | 3         | **none**                 | **BROKEN on both platforms (unfired). FIXED** |
+
+Filesystem-residue / removability / `io::ErrorKind` assertions, the class behind
+layers 4-5, were re-swept: every test-side `ErrorKind` match is `NotFound`
+(portable), plus `WouldBlock`/`TimedOut`/`Interrupted`/`InvalidData` in
+socket/parse paths that carry no platform assumption. Four `remove_dir_all` calls
+assert success — `lease_lifetime.rs:871`, `reopen.rs:152`,
+`typescript_engine.rs:178/207`. All are Windows-visible and all PASSED on the
+Windows runner in this very run (`reopen` 3 passed, and the store/extract suites
+green), so no Windows handle-retention problem is latent there; left unchanged
+rather than speculatively touched.
+
+Coverage note on what the Windows job still has NOT proven: `cargo test` stops at
+the first failing target, so every CLI target alphabetically after
+`batch_m_uninit` never executed on Windows this round — 24 of them are
+Windows-visible (`batch_m_v2_namespace` … `unicode_search_cli`). This fix is what
+lets them run; further layers may surface behind it, exactly as layers 1-6 did.
+
+### Gates and their REAL exit status
+
+Run separately, never joined with `&&`.
+
+| Command                                                               | Exit  | Result                                                    |
+| --------------------------------------------------------------------- | ----- | --------------------------------------------------------- |
+| `gh run view 30451206766 --log-failed`                                | **0** | 6090 lines; only `Windows`, `Coverage`, `CI Success`      |
+| `bash scripts/check-ci-gate.sh`                                       | **0** | required = audit, test, windows; coverage excluded        |
+| `cargo test --locked -p codegraph-rs --test batch_m_uninit` (pre-fix) | **0** | 6 passed — the defect is Windows-only, invisible on Linux |
+| `python3 /tmp/opencode/repro3.py` ×3 (idle var absent)                | —     | daemon alive at 12.0s each time — Failure 2 reproduced    |
+
+### Round 6 — final gate statuses
+
+Prose written FIRST, then `make fmt`, then the gates, so `fmt-check` sees the
+formatted ledger. Each command run separately; the exit status below is the one
+the shell actually reported.
+
+| Command                                                                | Exit  | Result                                                                         |
+| ---------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| `cargo test --locked -p codegraph-rs --test batch_m_uninit` (post-fix) | **0** | **6 passed, 0 failed** (twice)                                                 |
+| `cargo test --locked -p codegraph-rs --test daemon_idle`               | **0** | **2 passed, 0 failed**                                                         |
+| `cargo test --locked -p codegraph-rs --test daemon_sweep`              | **0** | **2 passed, 0 failed**                                                         |
+| `make fmt`                                                             | **0** | run after this prose, before the gates                                         |
+| `make ci CARGO='cargo --locked'` run 1                                 | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`              |
+| `make ci CARGO='cargo --locked'` run 2                                 | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`              |
+| `make ci CARGO='cargo --locked'` run 3                                 | **0** | `✅ All CI checks passed!` — final, with this ledger in the tree               |
+| `bash scripts/check-workspace-versions.sh`                             | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `bash scripts/check-ci-gate.sh`                                        | **0** | 16 truth-table cases; required = audit, test, windows                          |
+| `git diff --stat 5845f11..HEAD -- reference/golden/`                   | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                                                 | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+`git status --short` after every CI run showed only the four intended files and no
+untracked `reference/golden/*/colby.db-{wal,shm}` sidecars. **Windows was NOT
+validated locally** — no MSVC toolchain exists on this host (`cargo xwin` fails on
+a missing `clang-cl`), so only the `Windows` CI job can confirm Failure 1's fix.
+Failure 2's mechanism, by contrast, WAS reproduced and re-verified locally.

From 47ee7055c1182b259b4ac0e4374bb156205af8c9 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 23:31:08 +0800
Subject: [PATCH 80/91] fix(daemon): bound the proxy teardown by owed replies,
 not peer close

---
 crates/codegraph-daemon/src/proxy.rs | 317 ++++++++++++++++++++++++---
 1 file changed, 287 insertions(+), 30 deletions(-)

diff --git a/crates/codegraph-daemon/src/proxy.rs b/crates/codegraph-daemon/src/proxy.rs
index 1e3fb90..ee99a3a 100644
--- a/crates/codegraph-daemon/src/proxy.rs
+++ b/crates/codegraph-daemon/src/proxy.rs
@@ -43,6 +43,16 @@ const EXPECTED_PROTOCOL: u64 = 1;
 /// Poll cadence for the PPID watchdog (mirrors colby `DEFAULT_PPID_POLL_MS`).
 const PPID_POLL_INTERVAL: Duration = Duration::from_millis(500);
 
+/// Last-resort bound on the post-host-EOF wait for the replies the host is still
+/// owed (see [`ReplyLedger`]). Never reached in normal operation — the ledger
+/// settles the instant the daemon answers the last forwarded request, or the
+/// instant the daemon stream ends. It exists only so a daemon that accepted the
+/// connection and then stalled forever cannot wedge the proxy's teardown; it is
+/// deliberately LONGER than any caller's own deadline, so a genuinely stalled
+/// daemon still surfaces as that caller's failure rather than being absorbed
+/// here.
+const REPLY_DRAIN_BUDGET: Duration = Duration::from_secs(20);
+
 /// Outcome of a proxy attempt.
 #[derive(Debug, PartialEq, Eq)]
 pub enum ProxyOutcome {
@@ -100,15 +110,16 @@ pub fn run_proxy<R: BufRead, W: Write + Send + 'static>(
         return Ok(mismatch);
     }
 
-    // Split into independent recv/send halves. interprocess's sync UDS split
-    // hands BOTH halves an `Arc` over the SAME fd, so merely DROPPING the send
-    // half does not signal EOF to the daemon — the fd stays open via the recv
-    // half. We therefore capture the WRITE-side fd before moving `send` into the
-    // up pump and, once the host side is done, explicitly half-close it
-    // (shutdown(SHUT_WR)); that is what makes the daemon's session reader hit
-    // EOF, flush its last reply, and close — which in turn EOFs our recv pump so
-    // `down.join()` never hangs. The fd stays valid through teardown because the
-    // recv half keeps the shared socket open.
+    // Split into independent recv/send halves. interprocess's split hands BOTH
+    // halves a refcount over the SAME kernel object (an `Arc<RawPipeStream>` on
+    // windows, an `Arc` over one fd on unix), so merely DROPPING the send half
+    // does not signal EOF to the daemon — the object stays open via the recv
+    // half. On unix we therefore capture the WRITE-side fd before moving `send`
+    // into the up pump and, once the host side is done, explicitly half-close it
+    // (shutdown(SHUT_WR)), which makes the daemon's session reader hit EOF,
+    // flush its last reply, and close. Windows named pipes have NO half-close,
+    // so teardown there cannot depend on the daemon closing first; the reply
+    // ledger below is what bounds it on every platform.
     let (recv, mut send) = stream.split();
     let write_fd = write_raw_fd(&send);
 
@@ -125,6 +136,10 @@ pub fn run_proxy<R: BufRead, W: Write + Send + 'static>(
     // Shared shutdown flag flipped by the watchdog on host death and polled
     // per-line by the up pump. Its byte-for-byte pump semantics are unchanged.
     let shutdown = Arc::new(AtomicBool::new(false));
+    // What the host is still OWED: every forwarded request id, retired only once
+    // its reply has been written to the host. This is the platform-independent
+    // teardown condition — see `ReplyLedger`.
+    let ledger = Arc::new(ReplyLedger::default());
     // Event channel the watchdog parks on: lets teardown wake it the instant
     // shutdown is decided instead of after the remainder of a poll interval.
     let watchdog_wake = Arc::new(Shutdown::new());
@@ -144,29 +159,144 @@ pub fn run_proxy<R: BufRead, W: Write + Send + 'static>(
     let socket_reader = BufReader::new(recv);
     let down_suppressed = Arc::clone(&suppressed_id);
     let down_out = Arc::clone(&host_out);
-    let down =
-        thread::spawn(move || pump_daemon_to_host(socket_reader, &down_out, &down_suppressed));
+    let down_ledger = Arc::clone(&ledger);
+    let down = thread::spawn(move || {
+        let result = pump_daemon_to_host(socket_reader, &down_out, &down_suppressed, &down_ledger);
+        // The daemon stream ended: nothing further can ever arrive, so whatever is
+        // still outstanding will never be answered. Settle the ledger so a
+        // teardown parked on it wakes instead of waiting out the budget.
+        down_ledger.abandon();
+        result
+    });
 
     // host -> daemon pump (this thread): answer initialize/tools-list locally,
     // forward the rest. Runs to completion on host_in EOF.
-    let up_result = pump_host_to_daemon(host_in, send, &host_out, &shutdown, &suppressed_id);
-
-    // Host side is done. Half-close the write direction so the daemon reader
-    // EOFs (it flushes its final reply first); the down pump then drains those
-    // replies and exits on its own EOF. Do NOT flip `shutdown` before the join
-    // or it would race the drain and drop the last reply.
+    let up_result =
+        pump_host_to_daemon(host_in, send, &host_out, &shutdown, &suppressed_id, &ledger);
+
+    // Host side is done, but the daemon may still owe replies to requests we
+    // forwarded. Wait for the LEDGER to settle — every owed reply written, or the
+    // daemon stream gone — NOT for the down pump to exit.
+    //
+    // On unix we first half-close the write direction: the daemon reader EOFs,
+    // flushes its final reply, and closes, so the down pump reaches EOF on its
+    // own and `down.join()` returns. Windows named pipes have NO half-close
+    // (`half_close_write` is a documented no-op there), so the daemon's session
+    // reader NEVER EOFs while our recv half keeps the pipe open — its rmcp serve
+    // loop parks on the next frame, the pipe is never closed, and the down pump
+    // therefore never returns. Joining it unconditionally is an UNBOUNDED wait on
+    // windows; it is what made this function never return there.
     half_close_write(write_fd);
-    let _ = down.join();
+    let settled = ledger.wait_until_settled(REPLY_DRAIN_BUDGET);
     shutdown.store(true, Ordering::SeqCst);
     // Wake the watchdog at once so its join (in drop) returns promptly instead
     // of waiting out the remainder of a poll interval.
     watchdog_wake.signal();
     drop(watchdog);
+    // Join only when the down pump can actually be known to have finished: it
+    // exits on daemon EOF, which only the half-closing platform guarantees.
+    // Elsewhere it is detached — its thread ends when the daemon closes the pipe
+    // (idle-exit, sweep, or shutdown), and it holds only clones.
+    if HALF_CLOSE_EOFS_DAEMON {
+        let _ = down.join();
+    }
 
     up_result?;
+    anyhow::ensure!(
+        settled,
+        "daemon did not answer every forwarded request within {REPLY_DRAIN_BUDGET:?}"
+    );
     Ok(ProxyOutcome::Proxied)
 }
 
+/// Whether [`half_close_write`] actually makes the daemon's session reader see
+/// EOF. True on unix (`shutdown(SHUT_WR)` on the shared socket fd); FALSE on
+/// windows, where named pipes have no half-close, so the daemon keeps its
+/// session open and the daemon->host pump never reaches EOF on its own.
+#[cfg(unix)]
+const HALF_CLOSE_EOFS_DAEMON: bool = true;
+#[cfg(not(unix))]
+const HALF_CLOSE_EOFS_DAEMON: bool = false;
+
+/// The proxy's platform-independent teardown condition: the set of forwarded
+/// request ids the host is still OWED a reply for.
+///
+/// The proxy cannot tear down the instant the host's stdin closes — the daemon
+/// may still be computing the answer to a `tools/call` already in flight, and
+/// dropping it would lose the host's result. The ORIGINAL teardown waited for
+/// the daemon->host pump to hit EOF, which is only reachable when the proxy can
+/// half-close its write direction and make the daemon close first. That is a
+/// UNIX property: windows named pipes have no half-close, so on windows nothing
+/// ever ends that pump and the wait was unbounded.
+///
+/// A ledger replaces "wait for the peer to close" with "wait until nothing is
+/// owed", which holds on every platform: an id is recorded when its request is
+/// forwarded and retired when its reply is written to the host, so
+/// [`wait_until_settled`](Self::wait_until_settled) returns exactly when the last
+/// answer has been delivered. [`abandon`](Self::abandon) settles it when the
+/// daemon stream ends (nothing more can arrive), and notifications — which have
+/// no id and are never answered — are never recorded.
+#[derive(Default)]
+struct ReplyLedger {
+    state: Mutex<LedgerState>,
+    settled: Condvar,
+}
+
+#[derive(Default)]
+struct LedgerState {
+    outstanding: Vec<Value>,
+    abandoned: bool,
+}
+
+impl ReplyLedger {
+    fn record(&self, id: Value) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.outstanding.push(id);
+    }
+
+    fn retire(&self, id: &Value) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(at) = state.outstanding.iter().position(|owed| owed == id) {
+            state.outstanding.remove(at);
+        }
+        if state.outstanding.is_empty() {
+            self.settled.notify_all();
+        }
+    }
+
+    fn abandon(&self) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.abandoned = true;
+        self.settled.notify_all();
+    }
+
+    /// Park until nothing is owed (or the daemon stream ended), bounded by
+    /// `budget`. `true` means settled; `false` means the budget ran out with
+    /// replies still owed.
+    fn wait_until_settled(&self, budget: Duration) -> bool {
+        let state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let (state, _) = self
+            .settled
+            .wait_timeout_while(state, budget, |state| {
+                !state.abandoned && !state.outstanding.is_empty()
+            })
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.abandoned || state.outstanding.is_empty()
+    }
+}
+
 /// The write-side fd handle carried between `write_raw_fd` and
 /// `half_close_write`. On unix it is the real socket `RawFd`; on non-unix there
 /// is no half-close and the value is always `None`, so a unit placeholder keeps
@@ -227,6 +357,7 @@ fn pump_host_to_daemon<R, S, W>(
     host_out: &Arc<Mutex<W>>,
     shutdown: &Arc<AtomicBool>,
     suppressed_id: &Arc<Mutex<Option<Value>>>,
+    ledger: &Arc<ReplyLedger>,
 ) -> Result<()>
 where
     R: BufRead,
@@ -285,7 +416,12 @@ where
             }
             _ => {
                 // Everything else (tools/call, ping, notifications, ...) is
-                // forwarded verbatim to the daemon.
+                // forwarded verbatim to the daemon. Only a REQUEST (one carrying
+                // an `id`) is ever answered, so only that owes the host a reply;
+                // a notification has no id and is deliberately not recorded.
+                if let Some(id) = id {
+                    ledger.record(id);
+                }
                 forward_to_daemon(&mut daemon_send, &line)?;
             }
         }
@@ -294,13 +430,16 @@ where
 }
 
 /// daemon -> host: forward each daemon line to the host, dropping the response
-/// to the suppressed-initialize id. Drains to socket EOF (NOT a `shutdown`
-/// flag): the daemon closes the socket only after flushing its last reply, so
-/// exiting on EOF alone guarantees the final `tools/call` answer is delivered.
+/// to the suppressed-initialize id and retiring each delivered reply from
+/// `ledger` — that retirement, not this pump's own EOF, is what releases the
+/// teardown, so the final `tools/call` answer is delivered on every platform
+/// including ones with no socket half-close. Still drains to EOF (NOT a
+/// `shutdown` flag) so a daemon that keeps talking is never cut off mid-reply.
 fn pump_daemon_to_host<S, W>(
     daemon_recv: S,
     host_out: &Arc<Mutex<W>>,
     suppressed_id: &Arc<Mutex<Option<Value>>>,
+    ledger: &Arc<ReplyLedger>,
 ) -> Result<()>
 where
     S: BufRead,
@@ -315,7 +454,9 @@ where
             continue;
         }
 
-        // Suppress the daemon's reply to the forwarded initialize id.
+        // Suppress the daemon's reply to the forwarded initialize id. That id is
+        // answered locally and never recorded as owed, so nothing is retired here.
+        let mut delivered_id = None;
         if let Ok(resp) = serde_json::from_str::<Value>(&line) {
             let is_reply = resp.get("result").is_some() || resp.get("error").is_some();
             if is_reply {
@@ -328,10 +469,16 @@ where
                 {
                     continue;
                 }
+                delivered_id = resp_id.cloned();
             }
         }
 
         write_host_line(host_out, &line)?;
+        // Retire AFTER the host write: the teardown may proceed the instant the
+        // ledger settles, so the reply must already be in the host's hands.
+        if let Some(id) = delivered_id {
+            ledger.retire(&id);
+        }
     }
     Ok(())
 }
@@ -610,9 +757,17 @@ mod tests {
         let host_out = Arc::new(Mutex::new(Vec::<u8>::new()));
         let shutdown = Arc::new(AtomicBool::new(false));
         let suppressed: Arc<Mutex<Option<Value>>> = Arc::new(Mutex::new(None));
-
-        pump_host_to_daemon(host_in, &mut daemon_sink, &host_out, &shutdown, &suppressed)
-            .expect("pump runs to host_in EOF");
+        let ledger = Arc::new(ReplyLedger::default());
+
+        pump_host_to_daemon(
+            host_in,
+            &mut daemon_sink,
+            &host_out,
+            &shutdown,
+            &suppressed,
+            &ledger,
+        )
+        .expect("pump runs to host_in EOF");
 
         let to_host = String::from_utf8(host_out.lock().unwrap().clone()).unwrap();
         assert!(to_host.contains("\"id\":1"), "initialize answered locally");
@@ -634,6 +789,20 @@ mod tests {
             Some(json!(1)),
             "the forwarded initialize id is recorded for reply suppression"
         );
+
+        // Only the FORWARDED request whose reply must come from the daemon (id 3)
+        // is owed. The locally answered initialize (id 1, suppressed) and
+        // tools/list (id 2, not forwarded) are already delivered, so recording
+        // them would leave the ledger permanently unsettled.
+        assert!(
+            !ledger.wait_until_settled(Duration::from_millis(0)),
+            "the forwarded tools/call still owes the host a reply"
+        );
+        ledger.retire(&json!(3));
+        assert!(
+            ledger.wait_until_settled(Duration::from_millis(0)),
+            "retiring the only owed id settles the ledger"
+        );
     }
 
     #[test]
@@ -647,9 +816,17 @@ mod tests {
         let host_out = Arc::new(Mutex::new(Vec::<u8>::new()));
         let shutdown = Arc::new(AtomicBool::new(true));
         let suppressed: Arc<Mutex<Option<Value>>> = Arc::new(Mutex::new(None));
-
-        pump_host_to_daemon(host_in, &mut daemon_sink, &host_out, &shutdown, &suppressed)
-            .expect("pump exits promptly on a pre-set shutdown");
+        let ledger = Arc::new(ReplyLedger::default());
+
+        pump_host_to_daemon(
+            host_in,
+            &mut daemon_sink,
+            &host_out,
+            &shutdown,
+            &suppressed,
+            &ledger,
+        )
+        .expect("pump exits promptly on a pre-set shutdown");
         assert!(
             daemon_sink.is_empty(),
             "no line forwarded once shutdown is set"
@@ -667,12 +844,92 @@ mod tests {
         );
         let host_out = Arc::new(Mutex::new(Vec::<u8>::new()));
         let suppressed: Arc<Mutex<Option<Value>>> = Arc::new(Mutex::new(Some(json!(1))));
+        let ledger = Arc::new(ReplyLedger::default());
+        ledger.record(json!(3));
 
-        pump_daemon_to_host(daemon_recv, &host_out, &suppressed).expect("drains to EOF");
+        pump_daemon_to_host(daemon_recv, &host_out, &suppressed, &ledger).expect("drains to EOF");
 
         let to_host = String::from_utf8(host_out.lock().unwrap().clone()).unwrap();
         assert!(!to_host.contains("suppressed"), "id 1 reply is dropped");
         assert!(to_host.contains("forwarded"), "id 3 reply is delivered");
+        assert!(
+            ledger.wait_until_settled(Duration::from_millis(0)),
+            "delivering the owed reply retires it from the ledger"
+        );
+    }
+
+    /// The teardown wait must be released by the LEDGER, not by the daemon
+    /// closing its end: a windows named pipe has no half-close, so the daemon
+    /// never EOFs while the proxy's recv half holds the pipe open. Waiting on the
+    /// ledger settles on the last reply DELIVERED, which happens on every
+    /// platform.
+    #[test]
+    fn reply_ledger_settles_on_the_last_delivered_reply_not_on_peer_close() {
+        let ledger = Arc::new(ReplyLedger::default());
+        ledger.record(json!(1));
+        ledger.record(json!("two"));
+        assert!(
+            !ledger.wait_until_settled(Duration::from_millis(0)),
+            "two owed replies keep the ledger unsettled"
+        );
+
+        let settler = Arc::clone(&ledger);
+        let parked = thread::spawn(move || {
+            let start = Instant::now();
+            let settled = settler.wait_until_settled(Duration::from_secs(10));
+            (settled, start.elapsed())
+        });
+
+        thread::sleep(Duration::from_millis(20));
+        ledger.retire(&json!(1));
+        ledger.retire(&json!("two"));
+
+        let (settled, elapsed) = parked.join().expect("waiter thread panicked");
+        assert!(settled, "the ledger settles once nothing is owed");
+        assert!(
+            elapsed < Duration::from_secs(5),
+            "settling must wake the waiter at once, not run out the budget; \
+             woke after {elapsed:?}"
+        );
+    }
+
+    /// A daemon stream that ends with replies still owed can never answer them,
+    /// so `abandon` settles the wait immediately instead of burning the budget.
+    #[test]
+    fn reply_ledger_abandon_settles_an_unanswerable_wait() {
+        let ledger = Arc::new(ReplyLedger::default());
+        ledger.record(json!(4));
+        ledger.abandon();
+        let start = Instant::now();
+        assert!(ledger.wait_until_settled(Duration::from_secs(10)));
+        assert!(start.elapsed() < Duration::from_millis(500));
+    }
+
+    /// Retiring an id that was never owed (a daemon reply to something the proxy
+    /// did not forward, e.g. the primed `initialize`) must not underflow the
+    /// ledger or falsely settle a wait that still owes another reply.
+    #[test]
+    fn reply_ledger_ignores_an_unrecorded_retirement() {
+        let ledger = ReplyLedger::default();
+        ledger.record(json!(1));
+        ledger.retire(&json!(99));
+        assert!(
+            !ledger.wait_until_settled(Duration::from_millis(0)),
+            "an unrelated retirement must not settle a ledger that still owes id 1"
+        );
+        ledger.retire(&json!(1));
+        assert!(ledger.wait_until_settled(Duration::from_millis(0)));
+    }
+
+    /// An unsettled ledger must still give up at its budget so teardown is
+    /// bounded even against a daemon that accepted the connection and stalled.
+    #[test]
+    fn reply_ledger_reports_an_unsettled_budget_expiry() {
+        let ledger = ReplyLedger::default();
+        ledger.record(json!(5));
+        let start = Instant::now();
+        assert!(!ledger.wait_until_settled(Duration::from_millis(40)));
+        assert!(start.elapsed() >= Duration::from_millis(40));
     }
 
     #[test]

From acfc40112c1d3bdbe736651c28e84c8976f145ab Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 23:40:19 +0800
Subject: [PATCH 81/91] docs: record the round-seven windows proxy teardown
 diagnosis

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 132 ++++++++++++++++++++++
 1 file changed, 132 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index e0ad882..0996bb9 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9369,3 +9369,135 @@ untracked `reference/golden/*/colby.db-{wal,shm}` sidecars. **Windows was NOT
 validated locally** — no MSVC toolchain exists on this host (`cargo xwin` fails on
 a missing `clang-cl`), so only the `Windows` CI job can confirm Failure 1's fix.
 Failure 2's mechanism, by contrast, WAS reproduced and re-verified locally.
+
+## PR #173 CI round 7 — the proxy's teardown waited for a peer close that Windows named pipes can never deliver (2026-07-29)
+
+### The failure and where CI reported it
+
+GitHub Actions run `30460073159`, job `Windows`, the EIGHTH Windows-only failure
+on PR #173 and the only one left at commit `a0315da`:
+
+```
+test reader_lease_spans_stamp_check_through_last_row ... FAILED
+panicked at crates\codegraph-cli\tests\lease_lifetime.rs:820:14:
+proxy completed before deadline: Timeout
+test result: FAILED. 3 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 11.91s
+```
+
+The `expect` at `:820` is on the OUTER `Result` of
+`done_rx.recv_timeout(WAIT)` — a `mpsc::RecvTimeoutError::Timeout`. So
+`run_proxy` never sent a result at all within the 10s `WAIT`: it did not fail,
+it did not return; it never returned.
+
+### Diagnosis — `run_proxy`'s teardown blocked on a UNIX-only event
+
+`run_proxy` (`crates/codegraph-daemon/src/proxy.rs`) runs two pumps and then
+tears down in this order:
+
+```rust
+half_close_write(write_fd);
+let _ = down.join();          // <- the unbounded wait
+```
+
+`down` is the daemon->host pump. `pump_daemon_to_host` loops
+`for line in daemon_recv.lines()` and returns ONLY on EOF or a read error, i.e.
+only once the DAEMON closes its end of the connection. The daemon is made to
+close by `half_close_write`, which issues `shutdown(SHUT_WR)` on the socket fd so
+the daemon's session reader EOFs, flushes its last reply, and closes.
+
+Every step of that chain is unix-only:
+
+- `half_close_write` is `#[cfg(unix)] … rustix::net::shutdown(fd, Shutdown::Write)`,
+  and the `#[cfg(not(unix))]` arm is `fn half_close_write(_write_fd: Option<WriteFd>) {}` —
+  a no-op whose own doc comment already stated the fact: _"Windows named pipes
+  have no half-close; the proxy relies on the full-stream drop + the daemon's own
+  idle/sweep lifecycle instead."_
+- `write_raw_fd` likewise returns `None` on `#[cfg(not(unix))]`, so there is no
+  handle to act on even in principle.
+- Dropping the send half does not help either. interprocess's `split()` gives
+  both halves a refcount over the SAME kernel object
+  (`interprocess-2.4.2/src/os/windows/named_pipe/stream/impl.rs:35-41`:
+  `let (raw_ac, raw_a) = (self.raw.refclone(), self.raw)`, i.e. one
+  `Arc<RawPipeStream>` shared by recv and send). While the proxy's recv half
+  lives, the pipe handle is open, so the daemon never sees a disconnect.
+- The daemon side, meanwhile, is parked. `serve_session_async`
+  (`session.rs:434`) races the rmcp serve loop against its closing watch
+  channel; with neither an EOF nor a shutdown signal it simply awaits the next
+  frame forever.
+
+So on Windows: the proxy writes its frames, the daemon answers them, the proxy
+delivers the answers — and then `down.join()` waits for an EOF that nothing in
+the system will ever produce. `run_proxy` never returns, the test's channel
+times out at 10s, and the reported 11.91s is the test binary's own total, not a
+slow round trip.
+
+This also disproves the "the deadline is too short" hypothesis: the work the
+test measures had already completed. The proxy had received the `"id":2` reply
+before it wedged — the failure is strictly in teardown, and no `WAIT` value
+would fix an unbounded wait. `WAIT` was not touched; no sleep, retry, or
+conditional assertion was added.
+
+Why only this test caught it: `proxy_e2e.rs` is `#![cfg(unix)]`, so the only
+other test that drives `run_proxy` over a real rendezvous never runs on Windows.
+`lease_lifetime.rs` carries no cfg gate and is the sole Windows-visible caller.
+
+### Verdict: PRODUCTION defect, not a test premise
+
+The test's premise holds on Windows exactly as on Unix — a reader lease must
+span the stamp check through the last row, and the proxy did produce the last
+row. What is broken is `run_proxy`'s own liveness: a real MCP host on Windows
+whose stdin closes would leave the launcher process hung instead of exiting,
+holding its daemon session open. Nothing was gated; no Windows coverage was
+given up.
+
+### The fix — wait on what is OWED, not on the peer closing
+
+`run_proxy` now bounds teardown with a `ReplyLedger`: the set of forwarded
+request ids the host is still owed a reply for.
+
+- `pump_host_to_daemon` records an id when, and only when, it FORWARDS a request
+  carrying one. Notifications (no `id`) are never recorded; `initialize` and
+  `tools/list` are answered locally and are not owed by the daemon.
+- `pump_daemon_to_host` retires an id AFTER writing that reply to the host, so
+  the ledger settles only once the answer is genuinely in the host's hands.
+- Teardown replaces `down.join()` with `ledger.wait_until_settled(REPLY_DRAIN_BUDGET)`.
+  This is a `Condvar` wait that returns the instant nothing is owed, so the
+  common path is not slower than before on either platform.
+- When the daemon stream ends with replies still outstanding they can never be
+  answered, so the down pump calls `ledger.abandon()` on exit, waking the wait
+  immediately rather than burning the budget.
+- `down.join()` is now conditional on `HALF_CLOSE_EOFS_DAEMON` (`true` on unix,
+  `false` elsewhere) — joined where the pump is known to terminate, detached
+  where it is not. The detached thread holds only clones and ends when the daemon
+  closes the pipe via its own idle-exit/sweep/shutdown lifecycle.
+- `REPLY_DRAIN_BUDGET` (20s) is a last-resort bound against a daemon that
+  accepted the connection and then stalled forever; it is deliberately LONGER
+  than callers' own deadlines so a genuine stall still surfaces as the caller's
+  failure. Expiry returns `Err`, never a false `Proxied`.
+
+Byte semantics of both pumps are unchanged: the same lines are forwarded, the
+same initialize reply is suppressed, and the last reply is still delivered before
+teardown — that guarantee is now enforced by the ledger rather than inferred from
+a peer close.
+
+### Audit — every test that drives `run_proxy` or the rendezvous
+
+| test file                                                                     | platform gate              | drives                                      | same platform assumption?                          |
+| ----------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | -------------------------------------------------- |
+| `lease_lifetime.rs`                                                           | **none — runs on Windows** | `run_proxy` + `recorded_socket_path`        | **YES — this is the failure. FIXED in production** |
+| `proxy_e2e.rs`                                                                | `#![cfg(unix)]`            | `run_proxy` (11 sites)                      | never runs on Windows — no exposure                |
+| `daemon-crate` `proxy.rs`                                                     | `#![cfg(unix)]`            | proxy attach                                | never runs on Windows — no exposure                |
+| `proxy.rs` unit `run_proxy_falls_back_on_version_mismatch_over_a_real_socket` | `#[cfg(unix)]`             | `run_proxy` (mismatch arm)                  | returns BEFORE the split/teardown — unaffected     |
+| `daemon_idle.rs`                                                              | `#![cfg(unix)]`            | `recorded_socket_path`                      | never runs on Windows                              |
+| `daemon_single_watcher.rs`                                                    | `#![cfg(unix)]`            | `recorded_socket_path`                      | never runs on Windows                              |
+| `daemon_spawn.rs`                                                             | `#![cfg(unix)]`            | `daemon_socket_path`                        | never runs on Windows                              |
+| `daemon_stale_wal_recovery.rs`                                                | `#![cfg(unix)]`            | `recorded_socket_path`                      | never runs on Windows                              |
+| `daemon_sweep.rs`                                                             | `#![cfg(unix)]`            | `recorded_socket_path`                      | never runs on Windows                              |
+| `stale_socket.rs`                                                             | `#![cfg(unix)]`            | `daemon_socket_path` (9 sites)              | never runs on Windows                              |
+| `lifecycle.rs`                                                                | **none — runs on Windows** | `daemon_socket_path` for a lock record only | NO — writes a pid-lock file, never connects        |
+
+Only two Windows-visible files touch the rendezvous at all, and only
+`lease_lifetime.rs` connects through it. `lifecycle.rs` uses
+`daemon_socket_path` purely as a value inside a `DaemonLockInfo` it writes to
+disk, so it carries no transport assumption. Nothing else needed changing, and
+nothing was changed speculatively.

From 9a0458132bd5568ef7ad3ec18005f111a0195490 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Wed, 29 Jul 2026 23:52:23 +0800
Subject: [PATCH 82/91] docs: record the round-seven windows proxy teardown
 diagnosis

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 58 +++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 0996bb9..60055eb 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9501,3 +9501,61 @@ Only two Windows-visible files touch the rendezvous at all, and only
 `daemon_socket_path` purely as a value inside a `DaemonLockInfo` it writes to
 disk, so it carries no transport assumption. Nothing else needed changing, and
 nothing was changed speculatively.
+
+### Regression proof — four new unit tests, all platform-independent
+
+The defect is a Windows-only SYMPTOM of a platform-independent teardown
+condition, so the ledger that replaces it is testable on Linux. All four tests
+live in `crates/codegraph-daemon/src/proxy.rs`'s existing `#[cfg(test)] mod tests`
+and exercise `ReplyLedger` directly — no socket, no daemon, no timing luck.
+
+| test                                                                 | what it pins down                                                                                                                                                                                                                                             |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reply_ledger_settles_on_the_last_delivered_reply_not_on_peer_close` | Two owed ids keep the ledger unsettled; a thread parked on a 10s budget is woken by the retirement of the last one and asserts `elapsed < 5s` — proving the wake is the RETIREMENT, not the budget expiring, which is exactly the substitution the fix makes. |
+| `reply_ledger_abandon_settles_an_unanswerable_wait`                  | A daemon stream that ends still owing id 4 can never answer it; `abandon()` settles a 10s wait in `< 500ms`.                                                                                                                                                  |
+| `reply_ledger_ignores_an_unrecorded_retirement`                      | Retiring an id that was never recorded (a daemon reply to something the proxy did not forward, e.g. the primed `initialize`) neither underflows the ledger nor falsely settles a wait that still owes id 1.                                                   |
+| `reply_ledger_reports_an_unsettled_budget_expiry`                    | A genuinely stalled daemon still yields `false` at the budget and takes at least the budget to do so — teardown is BOUNDED, and the caller sees `Err`, never a false `Proxied`.                                                                               |
+
+Three pre-existing pump tests were extended rather than replaced, so the ledger
+is also covered through its real call sites:
+`pump_host_to_daemon_answers_initialize_and_tools_list_locally` now asserts that
+ONLY the forwarded `tools/call` (id 3) is owed — the locally answered
+`initialize` (id 1) and `tools/list` (id 2) are deliberately not recorded, since
+recording either would leave the ledger permanently unsettled — and
+`pump_daemon_to_host_suppresses_the_recorded_initialize_reply` now asserts the
+ledger settles once the owed reply has been written to the host.
+
+The Windows path itself remains UNVERIFIED LOCALLY: no MSVC toolchain exists on
+this host (`cargo xwin` fails on a missing `clang-cl`, there is no package
+manager, and uid is 1000), so only the `Windows` CI job and the CodeBuild
+`codegraph-rs-windows` project can confirm that `run_proxy` now returns there.
+What IS proven locally is the mechanism the fix depends on, and that Linux
+behaviour is unchanged.
+
+### Round 7 — final gate statuses
+
+Prose written FIRST, then `make fmt`, then the gates, so `fmt-check` sees the
+formatted ledger. Each command run separately, never joined with `&&`; the exit
+status below is the one the shell actually reported.
+
+| Command                                                     | Exit  | Result                                                                           |
+| ----------------------------------------------------------- | ----- | -------------------------------------------------------------------------------- |
+| `make fmt`                                                  | **0** | run after this prose, before the gates                                           |
+| `bash scripts/check-workspace-versions.sh`                  | **0** | workspace / `version.txt` / manifest all `0.40.4`; 10 packages                   |
+| `bash scripts/check-ci-gate.sh`                             | **0** | 16 truth-table cases; required = audit, test, windows; coverage excluded         |
+| `cargo test --locked -p codegraph-daemon`                   | **0** | **140 passed, 0 failed** over 11 targets; all four `reply_ledger_*` tests `ok`   |
+| `cargo test --locked -p codegraph-rs --test lease_lifetime` | **0** | **5 passed, 0 failed** — incl. `reader_lease_spans_stamp_check_through_last_row` |
+| `make ci CARGO='cargo --locked'` run 1                      | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`                |
+| `make ci CARGO='cargo --locked'` run 2                      | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`                |
+| `git diff --stat a0315da..HEAD -- reference/golden/`        | **0** | EMPTY — no golden byte changed                                                   |
+| `sha256sum Cargo.lock`                                      | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged   |
+
+The equivalence oracle left untracked `reference/golden/godot/colby.db-{wal,shm}`
+sidecars after each `make ci`; they are not gitignored and were removed before
+staging, so the working tree carried only the intended files at commit time.
+
+**Windows was NOT validated locally** and this ledger claims no such result — no
+MSVC toolchain exists on this host. Confirmation comes from the `Windows` GitHub
+Actions job and from the CodeBuild `codegraph-rs-windows` project, which runs
+`cargo test --workspace` without stopping at the first failing crate and so
+reports the full remaining picture in one pass.

From 478575d9c83873f17029eb996c16ad6d70684fdc Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Thu, 30 Jul 2026 00:15:10 +0800
Subject: [PATCH 83/91] docs: record the codebuild windows verification of the
 proxy teardown fix

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 86 +++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 60055eb..b98881a 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9559,3 +9559,89 @@ MSVC toolchain exists on this host. Confirmation comes from the `Windows` GitHub
 Actions job and from the CodeBuild `codegraph-rs-windows` project, which runs
 `cargo test --workspace` without stopping at the first failing crate and so
 reports the full remaining picture in one pass.
+
+### CodeBuild verification on a REAL Windows host — the fix is CONFIRMED
+
+Windows cannot be compiled on this host (`cargo xwin` fails on a missing
+`clang-cl`; no package manager; uid 1000), so the fix was validated on AWS
+CodeBuild (`us-east-2`, project `codegraph-rs-windows`), which runs
+`cargo test --workspace` and — unlike the GitHub `Windows` job's early exit —
+yields the COMPLETE remaining failure list in one pass.
+
+| Step                                                                  | Exit / Result                                                    |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `GIT_MASTER=1 git push cc feat/upstream-v1.5-portable-fixes`          | **0** — `5845f11..47ee705`, pre-push hook `✅ all checks passed` |
+| `aws codepipeline start-pipeline-execution --name codegraph-rust-ci`  | **0** — execution `f55f1270-9e07-43a6-a62f-df1666b1e009`         |
+| CodeBuild `codegraph-rs-windows:97aa74b8-d9b6-4759-aa9b-bd55f1311f13` | `FAILED` — but NOT on this fix; see below                        |
+
+The target under diagnosis PASSED:
+
+```
+Running tests\lease_lifetime.rs (target\debug\deps\lease_lifetime-7b5c80ba6d9b7683.exe)
+running 4 tests
+test lease_lifetime_child_process ... ok
+test writer_blocks_new_reads_without_sqlite_open ... ok
+test sqlite_snapshot_rejects_non_regular_artifact ... ok
+test reader_lease_spans_stamp_check_through_last_row ... ok
+test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 2.99s
+```
+
+2.99s for the whole binary, and 4s of wall clock between the target starting and
+finishing — against a 10s `WAIT`. That is the measured refutation of the
+"deadline too short" hypothesis: with the unbounded join removed, the Windows
+round trip fits inside the EXISTING deadline with room to spare. `WAIT` remains
+10s, untouched.
+
+This run also finally executed the whole workspace on Windows: **96 test targets
+ran, 105 `test result: ok`**, versus the GitHub job's early exit after the first
+failing crate. Everything the previous seven rounds could only hypothesize about
+is now measured.
+
+### The NINTH failure this unblocked (out of scope here, recorded for the next round)
+
+With the proxy no longer hanging, `cargo test --workspace` reached
+`-p codegraph-store --lib` and surfaced a NEW, unrelated Windows-only failure:
+
+```
+test connection::tests::current_writer_revalidates_lock_at_the_last_pre_open_checkpoint ... FAILED
+panicked at crates\codegraph-store\src\connection.rs:1218:25:
+snapshot read …\.codegraph-v2\displaced-at-write-open.lock:
+  The process cannot access the file because another process has locked a portion of the file. (os error 33)
+test result: FAILED. 93 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 3.07s
+```
+
+Mechanism, from the code: the test renames the STILL-LEASED permanent lock to
+`displaced-at-write-open.lock` (`connection.rs:1505`) and then snapshots the
+whole tree; `snapshot_tree`'s walk does `std::fs::read` on every regular file
+(`connection.rs:1217-1219`). The lease holds that file via
+`file.try_lock()` (`index_lease.rs:383`), which is `flock` on unix — ADVISORY,
+so a concurrent `read` succeeds — but `LockFileEx` on Windows, which is
+MANDATORY over a byte range, so the same `read` fails with
+`ERROR_LOCK_VIOLATION` (os error 33). The failure is in the test's snapshot
+oracle, not in the lease revalidation it is asserting (that assertion is never
+reached). This is a distinct root cause and is NOT addressed by this commit.
+
+### Round 7 — gate statuses, as the shell actually reported them
+
+Prose written FIRST, then `make fmt`, then the gates, so `fmt-check` sees the
+formatted ledger. Each command run separately, never joined with `&&`.
+
+| Command                                                     | Exit  | Result                                                                         |
+| ----------------------------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| `cargo build --locked -p codegraph-daemon`                  | **0** | clean                                                                          |
+| `cargo clippy --locked -p codegraph-daemon --all-targets`   | **0** | zero warnings                                                                  |
+| `cargo test --locked -p codegraph-daemon --lib`             | **0** | **109 passed, 0 failed** — incl. 4 new `reply_ledger_*` tests                  |
+| `cargo test --locked -p codegraph-rs --test lease_lifetime` | **0** | **5 passed, 0 failed** on Linux                                                |
+| `make fmt`                                                  | **0** | run after this prose, before the gates                                         |
+| `cargo fmt --all --check`                                   | **0** | clean                                                                          |
+| `make ci CARGO='cargo --locked'` run 1                      | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`              |
+| `make ci CARGO='cargo --locked'` run 2                      | **0** | `✅ All CI checks passed!` — 125 `test result: ok`, zero `FAILED`              |
+| `bash scripts/check-workspace-versions.sh`                  | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `bash scripts/check-ci-gate.sh`                             | **0** | 16 truth-table cases; required = audit, test, windows                          |
+| `git diff --stat a0315da..HEAD -- reference/golden/`        | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                                      | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+`git status --short` was clean before the work started (no foreign edits from
+another session) and after each CI run showed only the intended files, with no
+untracked `reference/golden/*/colby.db-{wal,shm}` sidecars. **Windows was NOT
+validated locally** — only the CodeBuild run above can and does confirm it.

From 2215b30c863a8cb670a61de3d9e581a6ed77fdfd Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Thu, 30 Jul 2026 22:44:22 +0800
Subject: [PATCH 84/91] test(store): tolerate windows mandatory lock refusal in
 snapshot oracles

---
 crates/codegraph-store/src/connection.rs      | 46 +++++++++++++-
 .../tests/index_state_publisher.rs            | 61 +++++++++++++-----
 .../tests/store_state_gates.rs                | 62 ++++++++++++++-----
 .../tests/writer_process_lifecycle.rs         | 41 ++++++++++--
 4 files changed, 174 insertions(+), 36 deletions(-)

diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index 930324e..d81c134 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -1183,6 +1183,48 @@ mod tests {
         Symlink(PathBuf),
     }
 
+    /// Windows `ERROR_LOCK_VIOLATION`.
+    ///
+    /// A byte-range lock taken through `File::try_lock` is ADVISORY on Unix, so
+    /// an unrelated `read` of the locked file always succeeds there. On Windows
+    /// the same lock is MANDATORY: any read overlapping the locked range is
+    /// refused outright with this code. Renaming a locked file does not release
+    /// the lock — the lock follows the handle — so a snapshot walking a
+    /// namespace can meet a still-locked file under its new name.
+    const ERROR_LOCK_VIOLATION: i32 = 33;
+
+    /// Read one regular file's bytes for a snapshot, tolerating exactly one
+    /// otherwise-fatal case: a mandatory Windows byte-range lock refusing a read
+    /// of an EMPTY file.
+    ///
+    /// `len` is the length from the `symlink_metadata` already taken for this
+    /// entry. Metadata queries are not byte-range-locked, so the length stays
+    /// observable while the lock is held, and a zero-length file has exactly one
+    /// possible content. Recording it as empty is therefore byte-exact AND
+    /// independent of whether the lock happened to be held at snapshot time —
+    /// which is what the equality assertions need, because a rejected
+    /// write-capable open DROPS the exclusive lease it consumed, so two
+    /// snapshots taken across that rejection observe the same file first locked
+    /// and then unlocked. Creation, removal and kind changes are still detected
+    /// because the entry is recorded exactly as the regular file it is.
+    ///
+    /// Every other read error still panics: a genuinely unreadable file is a
+    /// real fault, and a non-empty locked file has content that cannot be
+    /// observed at all, so silently substituting anything would be a lie.
+    fn snapshot_file_bytes(path: &Path, len: u64) -> Vec<u8> {
+        match std::fs::read(path) {
+            Ok(bytes) => bytes,
+            Err(error)
+                if cfg!(windows)
+                    && len == 0
+                    && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) =>
+            {
+                Vec::new()
+            }
+            Err(error) => panic!("snapshot read {}: {error}", path.display()),
+        }
+    }
+
     fn snapshot_tree(root: &Path) -> std::collections::BTreeMap<PathBuf, SnapshotKind> {
         fn walk(
             root: &Path,
@@ -1214,9 +1256,7 @@ mod tests {
                 let kind = if file_type.is_dir() {
                     SnapshotKind::Directory
                 } else if file_type.is_file() {
-                    SnapshotKind::File(std::fs::read(&path).unwrap_or_else(|error| {
-                        panic!("snapshot read {}: {error}", path.display())
-                    }))
+                    SnapshotKind::File(snapshot_file_bytes(&path, metadata.len()))
                 } else if file_type.is_symlink() {
                     SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
                         panic!("snapshot read_link {}: {error}", path.display())
diff --git a/crates/codegraph-store/tests/index_state_publisher.rs b/crates/codegraph-store/tests/index_state_publisher.rs
index 9584e97..721a6c5 100644
--- a/crates/codegraph-store/tests/index_state_publisher.rs
+++ b/crates/codegraph-store/tests/index_state_publisher.rs
@@ -111,6 +111,41 @@ enum SnapshotKind {
     Symlink(PathBuf),
 }
 
+/// Windows `ERROR_LOCK_VIOLATION`.
+///
+/// A byte-range lock taken through `File::try_lock` is ADVISORY on Unix, so an
+/// unrelated `read` of the locked file always succeeds there. On Windows the
+/// same lock is MANDATORY and any overlapping read is refused with this code.
+/// The publisher fixtures below hold a live EXCLUSIVE lease over the zero-length
+/// `index.lock` — including after renaming it aside, since the lock follows the
+/// handle — while they snapshot.
+const ERROR_LOCK_VIOLATION: i32 = 33;
+
+/// Read one regular file's bytes for a snapshot, tolerating exactly one
+/// otherwise-fatal case: a mandatory Windows byte-range lock refusing a read of
+/// an EMPTY file.
+///
+/// `len` is the length from the `symlink_metadata` already taken for this entry.
+/// Metadata queries are not byte-range-locked, so the length stays observable
+/// while the lock is held, and a zero-length file has exactly one possible
+/// content. Recording it as empty is therefore byte-exact AND independent of
+/// whether the lock happened to be held at snapshot time, so a `before`/`after`
+/// pair still compares equal across a lock release. Creation, removal and kind
+/// changes stay detectable because the entry is still recorded as the regular
+/// file it is. Every other read error panics: an unreadable file is a real fault,
+/// and a non-empty locked file has content that cannot be observed at all.
+fn snapshot_file_bytes(path: &Path, len: u64) -> Vec<u8> {
+    match std::fs::read(path) {
+        Ok(bytes) => bytes,
+        Err(error)
+            if cfg!(windows) && len == 0 && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) =>
+        {
+            Vec::new()
+        }
+        Err(error) => panic!("snapshot read {}: {error}", path.display()),
+    }
+}
+
 fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
     fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, SnapshotKind>) {
         let entries = std::fs::read_dir(directory)
@@ -133,22 +168,18 @@ fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
             let metadata = std::fs::symlink_metadata(&path)
                 .unwrap_or_else(|err| panic!("snapshot metadata {}: {err}", path.display()));
             let file_type = metadata.file_type();
-            let kind = if file_type.is_dir() {
-                SnapshotKind::Directory
-            } else if file_type.is_file() {
-                SnapshotKind::File(
-                    std::fs::read(&path)
-                        .unwrap_or_else(|err| panic!("snapshot read {}: {err}", path.display())),
-                )
-            } else if file_type.is_symlink() {
-                SnapshotKind::Symlink(
-                    std::fs::read_link(&path).unwrap_or_else(|err| {
+            let kind =
+                if file_type.is_dir() {
+                    SnapshotKind::Directory
+                } else if file_type.is_file() {
+                    SnapshotKind::File(snapshot_file_bytes(&path, metadata.len()))
+                } else if file_type.is_symlink() {
+                    SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|err| {
                         panic!("snapshot read_link {}: {err}", path.display())
-                    }),
-                )
-            } else {
-                panic!("snapshot unsupported entry kind: {}", path.display());
-            };
+                    }))
+                } else {
+                    panic!("snapshot unsupported entry kind: {}", path.display());
+                };
             assert!(
                 out.insert(relative, kind).is_none(),
                 "duplicate snapshot path"
diff --git a/crates/codegraph-store/tests/store_state_gates.rs b/crates/codegraph-store/tests/store_state_gates.rs
index ac11325..b16af68 100644
--- a/crates/codegraph-store/tests/store_state_gates.rs
+++ b/crates/codegraph-store/tests/store_state_gates.rs
@@ -241,6 +241,43 @@ enum SnapshotKind {
     Symlink(PathBuf),
 }
 
+/// Windows `ERROR_LOCK_VIOLATION`.
+///
+/// A byte-range lock taken through `File::try_lock` is ADVISORY on Unix, so an
+/// unrelated `read` of the locked file always succeeds there. On Windows the
+/// same lock is MANDATORY and any overlapping read is refused with this code.
+/// Every write-gate fixture below holds a live EXCLUSIVE lease over the
+/// zero-length `index.lock` while it snapshots, so the snapshot walker must
+/// survive that refusal.
+const ERROR_LOCK_VIOLATION: i32 = 33;
+
+/// Read one regular file's bytes for a snapshot, tolerating exactly one
+/// otherwise-fatal case: a mandatory Windows byte-range lock refusing a read of
+/// an EMPTY file.
+///
+/// `len` is the length from the `symlink_metadata` already taken for this entry.
+/// Metadata queries are not byte-range-locked, so the length stays observable
+/// while the lock is held, and a zero-length file has exactly one possible
+/// content. Recording it as empty is therefore byte-exact AND independent of
+/// whether the lock happened to be held at snapshot time — which the equality
+/// assertions need, because a rejected `open_for_write` DROPS the exclusive
+/// lease it consumed, so the `before` and `after` snapshots straddle a lock
+/// release. Creation, removal and kind changes stay detectable because the entry
+/// is still recorded as the regular file it is. Every other read error panics:
+/// an unreadable file is a real fault, and a non-empty locked file has content
+/// that cannot be observed at all.
+fn snapshot_file_bytes(path: &Path, len: u64) -> Vec<u8> {
+    match std::fs::read(path) {
+        Ok(bytes) => bytes,
+        Err(error)
+            if cfg!(windows) && len == 0 && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) =>
+        {
+            Vec::new()
+        }
+        Err(error) => panic!("snapshot read {}: {error}", path.display()),
+    }
+}
+
 fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
     fn walk(root: &Path, directory: &Path, out: &mut BTreeMap<PathBuf, SnapshotKind>) {
         let mut paths = std::fs::read_dir(directory)
@@ -262,20 +299,17 @@ fn snapshot_tree(root: &Path) -> BTreeMap<PathBuf, SnapshotKind> {
             let metadata = std::fs::symlink_metadata(&path)
                 .unwrap_or_else(|error| panic!("snapshot metadata {}: {error}", path.display()));
             let file_type = metadata.file_type();
-            let kind =
-                if file_type.is_dir() {
-                    SnapshotKind::Directory
-                } else if file_type.is_file() {
-                    SnapshotKind::File(std::fs::read(&path).unwrap_or_else(|error| {
-                        panic!("snapshot read {}: {error}", path.display())
-                    }))
-                } else if file_type.is_symlink() {
-                    SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
-                        panic!("snapshot read_link {}: {error}", path.display())
-                    }))
-                } else {
-                    panic!("snapshot unsupported entry kind: {}", path.display());
-                };
+            let kind = if file_type.is_dir() {
+                SnapshotKind::Directory
+            } else if file_type.is_file() {
+                SnapshotKind::File(snapshot_file_bytes(&path, metadata.len()))
+            } else if file_type.is_symlink() {
+                SnapshotKind::Symlink(std::fs::read_link(&path).unwrap_or_else(|error| {
+                    panic!("snapshot read_link {}: {error}", path.display())
+                }))
+            } else {
+                panic!("snapshot unsupported entry kind: {}", path.display());
+            };
             assert!(
                 out.insert(relative, kind).is_none(),
                 "duplicate snapshot path"
diff --git a/crates/codegraph-store/tests/writer_process_lifecycle.rs b/crates/codegraph-store/tests/writer_process_lifecycle.rs
index 7908557..f7358f7 100644
--- a/crates/codegraph-store/tests/writer_process_lifecycle.rs
+++ b/crates/codegraph-store/tests/writer_process_lifecycle.rs
@@ -102,6 +102,42 @@ fn snapshot_namespace(root: &Path) -> BTreeMap<PathBuf, NamespaceEntry> {
         .expect("snapshot namespace without path replacement")
 }
 
+/// Windows `ERROR_LOCK_VIOLATION`.
+///
+/// A byte-range lock taken through `File::try_lock` is ADVISORY on Unix, so an
+/// unrelated read of the locked file always succeeds there. On Windows the same
+/// lock is MANDATORY and any overlapping read is refused with this code. The
+/// contention fixtures below snapshot a namespace whose zero-length `index.lock`
+/// is exclusively held by a live HOLDER CHILD PROCESS.
+const ERROR_LOCK_VIOLATION: i32 = 33;
+
+/// Read one already-corroborated namespace file's bytes, tolerating exactly one
+/// otherwise-fatal case: a mandatory Windows byte-range lock refusing a read of
+/// an EMPTY file.
+///
+/// `len` is the length of the very handle being read, taken from the metadata
+/// this walker already corroborated against the path. Metadata queries are not
+/// byte-range-locked, so the length stays observable while the lock is held, and
+/// a zero-length file has exactly one possible content. Recording it as empty is
+/// therefore byte-exact AND independent of whether the lock happened to be held
+/// at snapshot time, so a `before`/`after` pair still compares equal across a
+/// lock release. Creation, removal and kind changes stay detectable because the
+/// entry is still recorded as the regular file it is. Every other read error
+/// panics: an unreadable file is a real fault, and a non-empty locked file has
+/// content that cannot be observed at all.
+fn read_namespace_file_bytes(file: &mut File, path: &Path, len: u64) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    match file.read_to_end(&mut bytes) {
+        Ok(_) => bytes,
+        Err(error)
+            if cfg!(windows) && len == 0 && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) =>
+        {
+            Vec::new()
+        }
+        Err(error) => panic!("read opened namespace file {}: {error}", path.display()),
+    }
+}
+
 fn snapshot_namespace_with_checkpoint<F>(
     root: &Path,
     mut checkpoint: F,
@@ -265,10 +301,7 @@ where
                 }
 
                 checkpoint(&path, SnapshotCheckpoint::RegularHandleCorroborated);
-                let mut bytes = Vec::new();
-                file.read_to_end(&mut bytes).unwrap_or_else(|error| {
-                    panic!("read opened namespace file {}: {error}", path.display())
-                });
+                let bytes = read_namespace_file_bytes(&mut file, &path, before_read.len());
                 let after_read = match fs::symlink_metadata(&path) {
                     Ok(metadata) => metadata,
                     Err(error) if error.kind() == std::io::ErrorKind::NotFound => {

From 344699ab32d27299c4c0953fafebe99d9575144e Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Thu, 30 Jul 2026 22:44:29 +0800
Subject: [PATCH 85/91] docs: record the round-eight windows snapshot
 lock-violation diagnosis

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 144 ++++++++++++++++++++++
 1 file changed, 144 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index b98881a..eb1319b 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9645,3 +9645,147 @@ formatted ledger. Each command run separately, never joined with `&&`.
 another session) and after each CI run showed only the intended files, with no
 untracked `reference/golden/*/colby.db-{wal,shm}` sidecars. **Windows was NOT
 validated locally** — only the CodeBuild run above can and does confirm it.
+
+## PR #173 CI round 8 — snapshot oracles read every file, and a Windows lease lock refuses that read (2026-07-30)
+
+### The failure and where CI reported it
+
+GitHub Actions run **30468205627**, `Windows` job, `cargo test --workspace`,
+`-p codegraph-store --lib`:
+
+```
+test connection::tests::current_writer_revalidates_lock_at_the_last_pre_open_checkpoint ... FAILED
+panicked at crates\codegraph-store\src\connection.rs:1218:25:
+snapshot read \\?\C:\…\.codegraph-v2\displaced-at-write-open.lock:
+  The process cannot access the file because another process has locked a portion of the file. (os error 33)
+test result: FAILED. 93 passed; 1 failed
+```
+
+The backtrace named `connection::tests::snapshot_tree::walk::closure$4` — the
+`std::fs::read` in `snapshot_tree`'s `SnapshotKind::File(...)` arm.
+
+### Diagnosis — advisory on Unix, MANDATORY on Windows
+
+Confirmed against the code, not assumed. Three facts compose:
+
+1. **What holds the lock.** `IndexLease::acquire_exclusive_existing` opens
+   `index.lock` and takes a kernel lock through `file.try_lock()`
+   (`crates/codegraph-store/src/index_lease.rs:383`). The locked `File` lives in
+   `LeaseInner` behind an `Arc`, and only `LeaseInner::drop` unlocks it
+   (`index_lease.rs:56-63`). So the lock is live for the whole lease lifetime.
+2. **Renaming does not release it.** The test renames the still-leased lock
+   (`connection.rs:1506`):
+   `std::fs::rename(paths.permanent_lock(), &displaced)`. A byte-range lock is a
+   property of the open file DESCRIPTION, not of the name, so the file now called
+   `displaced-at-write-open.lock` remains locked by the live lease.
+3. **The read is only legal on Unix.** `std::fs::File::try_lock` maps to
+   `flock`/`fcntl` on unix, whose locks are **ADVISORY** — an unrelated `read`
+   of a locked file always succeeds. On Windows it maps to `LockFileEx`, whose
+   locks are **MANDATORY** over a byte range: any read overlapping the locked
+   range is refused with `ERROR_LOCK_VIOLATION` (os error 33). `snapshot_tree`
+   reads the full content of every regular file it walks, so it necessarily
+   overlaps.
+
+The failing assertion was therefore never reached. The oracle died before the
+property under test (`open_for_write` revalidating the exact held handle at the
+last pre-open checkpoint) could be evaluated.
+
+### Verdict: TEST-ORACLE defect, not a production defect
+
+Unlike rounds 5 and 7, nothing in the shipped binary is wrong here. Production
+never reads the permanent lock's CONTENT — the lock file is a pure lock token.
+Verified by grep: the only `fs::read` of `paths.permanent_lock()` anywhere in the
+workspace is `index_lease.rs:768`, inside `#[cfg(test)]`, and it reads a
+COMPETING entry that the test asserts was never locked. Every non-test reference
+to `permanent_lock()` uses it for `open`/metadata/lock operations only, never for
+a content read.
+
+### The fix — normalize the one content a locked EMPTY file can have
+
+The lock file is zero bytes. A zero-length file has exactly ONE possible content,
+and `symlink_metadata` is not byte-range-locked, so the length stays observable
+even while the lock is held. The snapshot can therefore record `File(vec![])`
+without reading, and that record is byte-exact.
+
+Each affected walker gains a `snapshot_file_bytes(path, len)` helper that
+tolerates exactly one otherwise-fatal case:
+
+```rust
+fn snapshot_file_bytes(path: &Path, len: u64) -> Vec<u8> {
+    match std::fs::read(path) {
+        Ok(bytes) => bytes,
+        Err(error)
+            if cfg!(windows) && len == 0 && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) =>
+        {
+            Vec::new()
+        }
+        Err(error) => panic!("snapshot read {}: {error}", path.display()),
+    }
+}
+```
+
+Three guards, each load-bearing:
+
+- `cfg!(windows)` — on unix the locks are advisory, so this refusal is
+  IMPOSSIBLE there. Tolerating it on unix would hide a real fault.
+- `len == 0` — the only length whose content is knowable without reading. A
+  non-empty locked file has content that genuinely cannot be observed;
+  substituting anything for it would be a lie, so it still panics.
+- `raw_os_error() == Some(33)` — the specific `ERROR_LOCK_VIOLATION`, not a
+  blanket error swallow. `PermissionDenied`, `NotFound`, a sharing violation, or
+  an I/O error all still panic.
+
+Why this preserves the assertion, which is the whole point: the equality compares
+a snapshot taken INSIDE the `before_write_open` hook (lease live, lock held) with
+one taken AFTER `open_for_write_with` returned `Err` and consumed-and-dropped
+that lease (lock released). Reading would give `Err`/`Ok(vec![])` respectively —
+asymmetric. Normalizing to `vec![]` makes both sides observe the same value, so
+the assertion still proves "the rejection mutated nothing", and still detects
+creation, removal, and file⇄dir⇄symlink kind changes because the entry is
+recorded exactly as the regular file it is. Content changes of readable files —
+notably the FRESH `permanent_lock` written with `b"late replacement"`, which is
+NOT locked — are compared by content, unchanged.
+
+None of `#[ignore]`, deleting the test, `#[cfg(unix)]`-gating it, sleeping,
+retrying, or releasing the lease early was used; the last would have destroyed
+the property under test.
+
+### Audit — every walk-and-read helper, checked for a live lock
+
+`snapshot_tree`-shaped walkers are duplicated per test target, so the class had
+to be swept rather than fixed once. Method: for every file containing
+`read_dir`, locate the content read, then determine whether an exclusive lease
+(in-process or cross-process) can be live over a file inside the walked root at
+snapshot time.
+
+| File:line                                                                                                                                                                                                          | What it reads                                   | Live lock possible?                                                                                                                                                                                                            | Verdict                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| `codegraph-store/src/connection.rs:1217`                                                                                                                                                                           | every regular file under the project root       | **YES** — `lease` live inside `before_write_open`, then dropped by the rejected open                                                                                                                                           | **FIXED** (proven failure) |
+| `codegraph-store/tests/store_state_gates.rs:268`                                                                                                                                                                   | every regular file under the project root       | **YES** — 12 sites snapshot with a live `acquire_exclusive_existing` lease; `:1112` also renames it aside                                                                                                                      | **FIXED**                  |
+| `codegraph-store/tests/index_state_publisher.rs:137`                                                                                                                                                               | every regular file under the project root       | **YES** — `:378` renames the still-leased lock, then snapshots twice with the lease BORROWED                                                                                                                                   | **FIXED**                  |
+| `codegraph-store/tests/writer_process_lifecycle.rs:266`                                                                                                                                                            | every namespace file, via a corroborated handle | **YES** — `:783`/`:798` snapshot `current_root()` while a HOLDER CHILD PROCESS holds the lease                                                                                                                                 | **FIXED**                  |
+| `codegraph-store/src/uninit.rs:387`                                                                                                                                                                                | every regular file under the project root       | **NO** — every `snapshot(...)` call sits AFTER its `drop(lease)` (`:715→:716`, `:731→:733`); `:490` walks only the legacy namespace, which has no lock                                                                         | unchanged                  |
+| `codegraph-store/tests/index_state.rs:560`                                                                                                                                                                         | every regular file under a temp tree            | **NO** — the classifier fixtures write a `b"lock trap"` byte string as a PLAIN file and never acquire a lease                                                                                                                  | unchanged                  |
+| `codegraph-cli/tests/lease_lifetime.rs:633`                                                                                                                                                                        | `codegraph.db` + `-wal` + `-shm` ONLY           | **NO** — the lease lock is on `index.lock`, which this never touches; the `LeaseHookEnv` barrier stops the writer AFTER the kernel lock but BEFORE `Store::open_for_write` opens SQLite, so no SQLite range lock exists either | unchanged                  |
+| `codegraph-resolve/src/workspace_packages.rs`, `codegraph-extract/src/engine.rs`, `codegraph-bench/src/runner.rs`, `codegraph-cli/src/installer/targets/qoder.rs`, `codegraph-daemon/src/{spawn,http_registry}.rs` | source files / manifests / registry JSON        | **NO** — none walks an index namespace; no lease is ever live over their inputs                                                                                                                                                | unchanged                  |
+
+Residual risk, stated honestly: the four FIXED walkers are the ones where a live
+lock is reachable TODAY. The `codegraph-cli` integration tests have never been
+reached on Windows (`cargo test --workspace` had not gotten that far until round
+7), so if a future fixture snapshots a namespace while holding a lease, it will
+hit the same wall. The pattern to copy is `snapshot_file_bytes`.
+
+### Round 8 — gate statuses, as the shell actually reported them
+
+Prose written FIRST, then `make fmt`, then the gates, so `fmt-check` sees the
+formatted ledger. Each command run separately, never joined with `&&`.
+
+| Command                                                  | Exit  | Result                                                                         |
+| -------------------------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| `cargo test --locked -p codegraph-store --lib`           | **0** | **100 passed, 0 failed**                                                       |
+| `cargo test --locked -p codegraph-store`                 | **0** | **191 passed, 0 failed** across 9 targets                                      |
+| `cargo clippy --locked -p codegraph-store --all-targets` | **0** | zero warnings                                                                  |
+| `bash scripts/check-workspace-versions.sh`               | **0** | workspace / `version.txt` / manifest all `0.40.4`                              |
+| `bash scripts/check-ci-gate.sh`                          | **0** | 16 truth-table cases; only all-success exits 0                                 |
+| `git diff --stat 478575d..HEAD -- reference/golden/`     | **0** | EMPTY — no golden byte changed                                                 |
+| `sha256sum Cargo.lock`                                   | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |

From 8389c9ed1d20eef15de98775d0c4d9ae88636c7b Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Thu, 30 Jul 2026 23:15:14 +0800
Subject: [PATCH 86/91] test(store): assert lock length when windows refuses a
 locked-range read

---
 crates/codegraph-store/tests/index_lease.rs | 53 +++++++++++++++++++--
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/crates/codegraph-store/tests/index_lease.rs b/crates/codegraph-store/tests/index_lease.rs
index 4c45bed..f414207 100644
--- a/crates/codegraph-store/tests/index_lease.rs
+++ b/crates/codegraph-store/tests/index_lease.rs
@@ -73,6 +73,47 @@ fn lock_bytes(paths: &IndexPaths) -> Vec<u8> {
     std::fs::read(paths.permanent_lock()).expect("read permanent lock bytes")
 }
 
+/// Windows `ERROR_LOCK_VIOLATION`.
+///
+/// A byte-range lock taken through `File::try_lock` is ADVISORY on Unix, so an
+/// unrelated read of the locked file always succeeds there. On Windows the same
+/// lock is MANDATORY: a read overlapping an EXCLUSIVELY locked range is refused
+/// with this code, while a SHARED lock still permits reads and only denies
+/// writes.
+const ERROR_LOCK_VIOLATION: i32 = 33;
+
+/// Assert the permanent lock still carries `expected` while a lease may be live
+/// over it.
+///
+/// When the content is readable this is an exact byte comparison. When Windows
+/// refuses the read because the range is exclusively locked, the content cannot
+/// be observed at all, so this asserts the strongest thing that remains
+/// observable: the LENGTH, which `metadata` reports without taking the byte
+/// range. That is precisely the observation that refutes the failure mode these
+/// fixtures guard — an acquisition path truncating or rewriting the lock, which
+/// cannot preserve `expected.len()`. Each caller additionally re-asserts exact
+/// bytes through [`lock_bytes`] once the holder is released and no lock remains,
+/// so byte-exactness is still proven on every platform.
+fn assert_lock_bytes_preserved(paths: &IndexPaths, expected: &[u8]) {
+    let path = paths.permanent_lock();
+    match std::fs::read(&path) {
+        Ok(bytes) => assert_eq!(bytes, expected, "permanent lock bytes changed"),
+        Err(error) if cfg!(windows) && error.raw_os_error() == Some(ERROR_LOCK_VIOLATION) => {
+            let observed = std::fs::metadata(&path)
+                .unwrap_or_else(|error| {
+                    panic!("inspect exclusively locked permanent lock: {error}")
+                })
+                .len();
+            let expected_len = u64::try_from(expected.len()).expect("lock length fits u64");
+            assert_eq!(
+                observed, expected_len,
+                "permanent lock length changed while exclusively locked"
+            );
+        }
+        Err(error) => panic!("read permanent lock bytes: {error}"),
+    }
+}
+
 #[cfg(unix)]
 #[test]
 fn static_symlink_lock_is_rejected_without_using_the_external_target_as_authority() {
@@ -248,8 +289,9 @@ fn shared_processes_coexist_but_shared_blocks_exclusive() {
         run_probe(project.path(), "exclusive", SHORT_DEADLINE),
         "TIMED_OUT"
     );
-    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    assert_lock_bytes_preserved(&paths, LOCK_BYTES);
     holder.release();
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
 }
 
 #[test]
@@ -267,14 +309,16 @@ fn exclusive_process_blocks_shared_and_exclusive() {
         run_probe(project.path(), "exclusive", SHORT_DEADLINE),
         "TIMED_OUT"
     );
-    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    assert_lock_bytes_preserved(&paths, LOCK_BYTES);
     holder.release();
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
 
     assert_eq!(run_probe(project.path(), "shared", CHILD_WAIT), "ACQUIRED");
     assert_eq!(
         run_probe(project.path(), "exclusive", CHILD_WAIT),
         "ACQUIRED"
     );
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
 }
 
 #[test]
@@ -288,7 +332,7 @@ fn timeout_and_post_contention_cancellation_preserve_lock_bytes() {
         IndexLease::acquire_shared_existing(&paths, deadline_after(SHORT_DEADLINE), || false)
             .expect_err("exclusive holder must force bounded timeout");
     assert!(matches!(timeout, IndexLeaseError::TimedOut { .. }));
-    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    assert_lock_bytes_preserved(&paths, LOCK_BYTES);
 
     let checks = Cell::new(0_u8);
     let cancelled = IndexLease::acquire_shared_existing(&paths, deadline_after(CHILD_WAIT), || {
@@ -302,8 +346,9 @@ fn timeout_and_post_contention_cancellation_preserve_lock_bytes() {
         checks.get() >= 3,
         "the cancellation check must run after a busy try_lock"
     );
-    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
+    assert_lock_bytes_preserved(&paths, LOCK_BYTES);
     holder.release();
+    assert_eq!(lock_bytes(&paths), LOCK_BYTES);
 }
 
 #[test]

From cad3577e8348f35d84d491297e79c27e916ec3ea Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Thu, 30 Jul 2026 23:15:22 +0800
Subject: [PATCH 87/91] docs: record the codebuild round-eight confirmation and
 the tenth layer

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 113 ++++++++++++++++++++++
 1 file changed, 113 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index eb1319b..9b167f4 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9789,3 +9789,116 @@ formatted ledger. Each command run separately, never joined with `&&`.
 | `bash scripts/check-ci-gate.sh`                          | **0** | 16 truth-table cases; only all-success exits 0                                 |
 | `git diff --stat 478575d..HEAD -- reference/golden/`     | **0** | EMPTY — no golden byte changed                                                 |
 | `sha256sum Cargo.lock`                                   | **0** | `750ee84b48ef1fc988bf9efd1a75828d243734f9bc516e8671c4294183de9bb1` — unchanged |
+
+### CodeBuild verification on a REAL Windows host — the round-8 fix is CONFIRMED
+
+Pipeline execution `0d78fb13-8b3b-471f-87c8-c5da32092c32`, build
+`codegraph-rs-windows:47108464-72f4-4e5f-9e2c-125e82cf921a`, log stream
+`47108464-72f4-4e5f-9e2c-125e82cf921a`. Pipeline status **Failed**; `Linux`
+action **Succeeded**, `Windows` action **Failed** at `cargo test --workspace`
+(exit 101).
+
+The target test PASSED. `-p codegraph-store --lib` reported
+
+```
+test result: ok. 94 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 2.85s
+```
+
+versus round 7's `93 passed; 1 failed` — the same suite, one more passing test,
+zero failures. `current_writer_revalidates_lock_at_the_last_pre_open_checkpoint`
+now reaches and evaluates its assertion on Windows.
+
+### The TENTH layer this exposed — and an AUDIT GAP it exposed in round 8
+
+The COMPLETE `... FAILED` list from the run was two lines, both in a different
+target:
+
+```
+test timeout_and_post_contention_cancellation_preserve_lock_bytes ... FAILED
+test exclusive_process_blocks_shared_and_exclusive ... FAILED
+test result: FAILED. 9 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.94s
+```
+
+Both panicked at the SAME line with the SAME os error:
+
+```
+panicked at crates\codegraph-store\tests\index_lease.rs:73:43:
+read permanent lock bytes: Os { code: 33, kind: Uncategorized,
+  message: "The process cannot access the file because another process has locked a portion of the file." }
+  4: index_lease::lock_bytes  at .\tests\index_lease.rs:73
+```
+
+Same root cause, same class — and the round-8 audit MISSED it. The audit swept
+files containing `read_dir`, because the known instance was a directory walker.
+`tests/index_lease.rs` has no walker: `lock_bytes` reads the permanent lock
+DIRECTLY. Recorded plainly because it is the lesson: the class is "reads the
+content of a file that a live lease may hold", NOT "walks a directory".
+
+Two additional facts the run settled empirically, neither of which was
+assumable:
+
+- **`metadata` really is not byte-range-locked on Windows.** The round-8 fix
+  reads `symlink_metadata(...).len()` on the exclusively locked file and the
+  suite passed, so the length observation is sound.
+- **A SHARED `LockFileEx` range permits reads.**
+  `shared_processes_coexist_but_shared_blocks_exclusive` does a full `fs::read`
+  of the lock while a SHARED holder is live and PASSED. Only the two
+  EXCLUSIVE-holder fixtures failed. A shared lock denies writes, not reads.
+
+### The round-10 fix — assert what stays observable, then re-assert bytes after release
+
+`LOCK_BYTES` is 34 bytes, so the round-8 `len == 0` normalization cannot apply:
+the content of a non-empty exclusively locked file is genuinely unobservable.
+
+A new `assert_lock_bytes_preserved(paths, expected)` therefore compares bytes
+exactly when the read succeeds and, when Windows refuses it with
+`ERROR_LOCK_VIOLATION`, asserts the LENGTH via `metadata` instead — the strongest
+remaining observation, and precisely the one that refutes the failure mode these
+fixtures guard: an acquisition path truncating or rewriting the lock cannot
+preserve `expected.len()`. Any other read error still panics.
+
+To keep byte-exactness proven on EVERY platform rather than traded away, each of
+the three holder fixtures now ALSO asserts exact bytes through the strict
+`lock_bytes` AFTER `holder.release()`, which waits for the holder child to exit,
+so no lock remains. `exclusive_process_blocks_shared_and_exclusive` additionally
+re-asserts after its two post-release probe children have acquired and exited.
+Nothing mutates between the locked assertion and the release, so the post-release
+read proves the same property — and this is strictly MORE than the pre-existing
+unix-only coverage, which never read the lock unlocked at all.
+
+Call sites deliberately left on the strict `lock_bytes`: lines 227/236 (leases
+already dropped), 321 (`an_already_expired_deadline...`, nothing ever locked),
+163/212/220/243 (the acquisition FAILED, so no lock was taken). Those must keep
+panicking on a refusal, because there a refusal would be a real fault.
+
+### Audit, redone by the correct predicate
+
+Predicate this time: "reads the CONTENT of a file that a live lease — in-process
+or cross-process — may hold", regardless of whether a directory walk is involved.
+
+| File:line                                                                                                            | What it reads                              | Live lock possible?                                                                                                          | Verdict                    |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `codegraph-store/tests/index_lease.rs:73` (`lock_bytes`)                                                             | `index.lock` content, directly             | **YES** — 3 fixtures read it while a `Holder` CHILD holds shared or exclusive                                                | **FIXED** (proven failure) |
+| `codegraph-store/src/index_lease.rs:768`                                                                             | a COMPETING regular entry at the lock path | **NO** — the test asserts creation LOST the race and never locked that entry                                                 | unchanged                  |
+| `codegraph-store/tests/index_lease.rs:163/212/220/243`                                                               | external target / sibling / marker         | **NO** — every one follows a FAILED acquisition, which holds nothing                                                         | unchanged                  |
+| `codegraph-cli/tests/batch_m_uninit.rs:145`                                                                          | every regular file under `current_root`    | **NO** — snapshots run in the PARENT after `run_in`'s child CLI exited; `stage_lifecycle_state` drops its lease at scope end | unchanged                  |
+| `codegraph-store/src/rebuild.rs:1698/1712`                                                                           | `codegraph.db` bytes                       | **NO** — a live `FullRebuildRequired` authorization locks `index.lock`, not the DB, and holds no SQLite connection           | unchanged (Windows-passed) |
+| `codegraph-cli/tests/batch_m_failed_open_recovery.rs:723/733`                                                        | `codegraph.db` bytes                       | **NO** — the refused `sync_project_once` opens no write-capable SQLite                                                       | unchanged (Windows-passed) |
+| `codegraph-store/src/index_state_publisher.rs:649/768`                                                               | state-slot JSON                            | **NO** — slots are never locked; only `index.lock` is                                                                        | unchanged                  |
+| `codegraph-watch/src/sync.rs`, `codegraph-cli/src/main.rs`, `codegraph-cli/tests/batch_m_daemon_uninit_lifecycle.rs` | source files / profiles / pid file         | **NO** — none is a lease target                                                                                              | unchanged                  |
+
+Everything in the "unchanged (Windows-passed)" rows actually EXECUTED on Windows
+in this run and passed, so those verdicts are measured, not merely argued.
+
+### Round 8/10 — gate statuses, as the shell actually reported them
+
+| Command                                                     | Exit  | Result                                                                       |
+| ----------------------------------------------------------- | ----- | ---------------------------------------------------------------------------- |
+| `cargo test --locked -p codegraph-store --test index_lease` | **0** | **13 passed, 0 failed** on Linux                                             |
+| `cargo clippy --locked -p codegraph-store --all-targets`    | **0** | zero warnings                                                                |
+| `aws codepipeline start-pipeline-execution` (round 8 fix)   | **0** | `0d78fb13-8b3b-471f-87c8-c5da32092c32`                                       |
+| `aws codepipeline get-pipeline-execution` (11 polls)        | **0** | `InProgress` ×10, then **`Failed`** — Windows only, on the TENTH layer       |
+| `aws logs tail /aws/codebuild/codegraph-rs-windows`         | **0** | 4048 lines; store lib **94 passed / 0 failed**; exactly 2 `FAILED`, both new |
+
+**Windows was NOT validated locally** for this round-10 fix; only the next
+CodeBuild run can confirm it.

From cb3e16856f6fc42a247bb6e3d3c27b3050f3698a Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Fri, 31 Jul 2026 00:20:59 +0800
Subject: [PATCH 88/91] test(store): derive temp directory names from a
 monotonic per-process serial

---
 crates/codegraph-store/src/connection.rs          | 15 ++++++++++++++-
 .../codegraph-store/tests/bulk_index_pragmas.rs   | 14 +++++++++++++-
 crates/codegraph-store/tests/schema_parity.rs     | 14 +++++++++++++-
 3 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/crates/codegraph-store/src/connection.rs b/crates/codegraph-store/src/connection.rs
index d81c134..1f5f6c9 100644
--- a/crates/codegraph-store/src/connection.rs
+++ b/crates/codegraph-store/src/connection.rs
@@ -1174,8 +1174,20 @@ fn configure_connection_for_rebuild(
 
 #[cfg(test)]
 mod tests {
+    use std::sync::atomic::{AtomicU64, Ordering};
+
     use super::*;
 
+    /// Monotonic per-process serial that keeps every temp name in this module unique.
+    ///
+    /// A wall-clock timestamp alone is NOT sufficient. `SystemTime::now()` has
+    /// nanosecond resolution on Linux but is only updated at the system timer tick
+    /// on Windows (~15.6 ms), so two tests running concurrently in threads of ONE
+    /// process, hence one pid, can observe the SAME `as_nanos()` value. Every
+    /// builder here already carries a per-callsite label EXCEPT the late-lock base
+    /// below, which the serial makes unique by construction.
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
     #[derive(Debug, PartialEq, Eq)]
     enum SnapshotKind {
         Directory,
@@ -1501,8 +1513,9 @@ mod tests {
         }
 
         let base = std::env::temp_dir().join(format!(
-            "codegraph-conn-late-lock-replacement-{}-{}",
+            "codegraph-conn-late-lock-replacement-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()
diff --git a/crates/codegraph-store/tests/bulk_index_pragmas.rs b/crates/codegraph-store/tests/bulk_index_pragmas.rs
index 5a564d2..f9d4d92 100644
--- a/crates/codegraph-store/tests/bulk_index_pragmas.rs
+++ b/crates/codegraph-store/tests/bulk_index_pragmas.rs
@@ -1,7 +1,18 @@
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
 
 use codegraph_store::Store;
 
+/// Monotonic per-process serial that makes every [`TestDir`] name unique.
+///
+/// A wall-clock timestamp alone is NOT sufficient. `SystemTime::now()` has
+/// nanosecond resolution on Linux but is only updated at the system timer tick on
+/// Windows (~15.6 ms), so two of this target's tests — run concurrently in
+/// threads of ONE process, hence one pid — can observe the SAME `as_nanos()`
+/// value and derive the same directory name, making the second `create_dir` fail
+/// with `ERROR_ALREADY_EXISTS`. The serial cannot collide by construction.
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
 #[test]
 fn set_bulk_index_pragmas_drops_synchronous_to_off() {
     let dir = TestDir::new();
@@ -174,8 +185,9 @@ struct TestDir {
 impl TestDir {
     fn new() -> Self {
         let name = format!(
-            "codegraph-store-bulk-pragmas-{}-{}",
+            "codegraph-store-bulk-pragmas-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()
diff --git a/crates/codegraph-store/tests/schema_parity.rs b/crates/codegraph-store/tests/schema_parity.rs
index b38ac4a..def17d0 100644
--- a/crates/codegraph-store/tests/schema_parity.rs
+++ b/crates/codegraph-store/tests/schema_parity.rs
@@ -1,9 +1,20 @@
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
 
 use codegraph_store::Store;
 
 const GOLDEN_SCHEMA: &str = include_str!("../../../reference/golden/colby.schema.sql");
 
+/// Monotonic per-process serial that makes every [`TestDir`] name unique.
+///
+/// A wall-clock timestamp alone is NOT sufficient. `SystemTime::now()` has
+/// nanosecond resolution on Linux but is only updated at the system timer tick on
+/// Windows (~15.6 ms), so two of this target's tests — run concurrently in
+/// threads of ONE process, hence one pid — can observe the SAME `as_nanos()`
+/// value and derive the same directory name, making the second `create_dir` fail
+/// with `ERROR_ALREADY_EXISTS`. The serial cannot collide by construction.
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
 #[test]
 fn fresh_database_schema_matches_upstream_golden() {
     let tempdir = TestDir::new();
@@ -181,8 +192,9 @@ struct TestDir {
 impl TestDir {
     fn new() -> Self {
         let name = format!(
-            "codegraph-store-schema-parity-{}-{}",
+            "codegraph-store-schema-parity-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()

From 752ea01112ad9b79c6beb85cf9bcfd7a868e0ba6 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Fri, 31 Jul 2026 00:21:15 +0800
Subject: [PATCH 89/91] test(cli): derive installer temp directory names from a
 monotonic serial

---
 crates/codegraph-cli/src/installer/registry.rs   | 15 ++++++++++++++-
 crates/codegraph-cli/src/installer/shared.rs     | 16 +++++++++++++++-
 .../src/installer/targets/claude.rs              | 12 +++++++++++-
 3 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/crates/codegraph-cli/src/installer/registry.rs b/crates/codegraph-cli/src/installer/registry.rs
index 0802ebf..f5ba9d8 100644
--- a/crates/codegraph-cli/src/installer/registry.rs
+++ b/crates/codegraph-cli/src/installer/registry.rs
@@ -103,8 +103,20 @@ pub fn resolve_target_flag(
 
 #[cfg(test)]
 mod tests {
+    use std::sync::atomic::{AtomicU64, Ordering};
+
     use super::*;
 
+    /// Monotonic per-process serial that makes every [`temp_ctx`] base unique.
+    ///
+    /// A wall-clock timestamp alone is NOT sufficient. `SystemTime::now()` has
+    /// nanosecond resolution on Linux but is only updated at the system timer tick
+    /// on Windows (~15.6 ms), so two of this module's tests — run concurrently in
+    /// threads of ONE process, hence one pid — can observe the SAME `as_nanos()`
+    /// value and hand the installer the SAME `home`/`cwd`, letting one test read
+    /// the config the other wrote. The serial cannot collide by construction.
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
     /// The full registry id set, in load-bearing order (registry.rs:5-7).
     const ALL_IDS: &[&str] = &[
         "claude",
@@ -143,8 +155,9 @@ mod tests {
 
     fn temp_ctx() -> InstallContext {
         let base = std::env::temp_dir().join(format!(
-            "cg-registry-{}-{}",
+            "cg-registry-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()
diff --git a/crates/codegraph-cli/src/installer/shared.rs b/crates/codegraph-cli/src/installer/shared.rs
index c7d9884..6a28453 100644
--- a/crates/codegraph-cli/src/installer/shared.rs
+++ b/crates/codegraph-cli/src/installer/shared.rs
@@ -738,8 +738,21 @@ fn find_next_table_header(content: &str, from: usize) -> usize {
 
 #[cfg(test)]
 mod tests {
+    use std::sync::atomic::{AtomicU64, Ordering};
+
     use super::*;
 
+    /// Monotonic per-process serial that makes every [`tmp_path`] directory unique.
+    ///
+    /// A wall-clock timestamp alone is NOT sufficient. `SystemTime::now()` has
+    /// nanosecond resolution on Linux but is only updated at the system timer tick
+    /// on Windows (~15.6 ms), so two of this module's tests — run concurrently in
+    /// threads of ONE process, hence one pid — can observe the SAME `as_nanos()`
+    /// value and land in the SAME directory. `create_dir_all` does not error on
+    /// that, so the two tests silently share a directory and clobber each other's
+    /// fixture files. The serial cannot collide by construction.
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
     #[test]
     fn parses_jsonc_with_line_and_block_comments() {
         let text = r#"{
@@ -1018,8 +1031,9 @@ mod tests {
 
     fn tmp_path(name: &str) -> std::path::PathBuf {
         let dir = std::env::temp_dir().join(format!(
-            "cg-jsonc-{}-{}",
+            "cg-jsonc-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()
diff --git a/crates/codegraph-cli/src/installer/targets/claude.rs b/crates/codegraph-cli/src/installer/targets/claude.rs
index e74e23b..66e0ecc 100644
--- a/crates/codegraph-cli/src/installer/targets/claude.rs
+++ b/crates/codegraph-cli/src/installer/targets/claude.rs
@@ -400,12 +400,22 @@ pub static CLAUDE_TARGET: ClaudeCodeTarget = ClaudeCodeTarget;
 
 #[cfg(test)]
 mod tests {
+    use std::sync::atomic::{AtomicU64, Ordering};
+
     use super::*;
 
+    /// Monotonic per-process serial that makes every [`temp_ctx`] base unique.
+    ///
+    /// See `installer::registry::tests::NEXT_TEMP` for why a wall-clock timestamp
+    /// is not enough on Windows. Only one test calls this helper today, so it
+    /// cannot collide yet; the serial keeps that true when a second one is added.
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
     fn temp_ctx() -> InstallContext {
         let base = std::env::temp_dir().join(format!(
-            "codegraph-claude-skill-{}-{}",
+            "codegraph-claude-skill-{}-{}-{}",
             std::process::id(),
+            NEXT_TEMP.fetch_add(1, Ordering::Relaxed),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()

From ff9bf9f735a8cd062739eb87fa2fbef14cdfd320 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Fri, 31 Jul 2026 00:21:20 +0800
Subject: [PATCH 90/91] docs: record the round-nine windows temp-name collision
 diagnosis

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 107 ++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 9b167f4..0071f02 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9902,3 +9902,110 @@ in this run and passed, so those verdicts are measured, not merely argued.
 
 **Windows was NOT validated locally** for this round-10 fix; only the next
 CodeBuild run can confirm it.
+
+## PR #173 CI round 9 — a temp-directory name that is unique on Linux and collidable on Windows (2026-07-31)
+
+### Status of the evidence, stated first
+
+This round is the ONE fix in this ledger that was **derived rather than observed**.
+No CodeBuild log line has yet shown `ERROR_ALREADY_EXISTS` for a codegraph temp
+directory. The round-8/10 lease-lock fix (`8389c9e`) had not been validated on
+Windows either when this round was written, so a single CodeBuild run now carries
+both. Nothing below claims Windows validation that has not happened; the gate
+table at the end records what actually ran.
+
+### The mechanism — clock RESOLUTION, not clock skew
+
+Several test helpers build a temp-directory name out of `std::process::id()` plus
+`SystemTime::now().duration_since(UNIX_EPOCH).as_nanos()`. On Linux that is
+effectively collision-proof: `clock_gettime(CLOCK_REALTIME)` is served from the
+vDSO with true nanosecond resolution, so two calls microseconds apart differ.
+
+On Windows the same call reads the system time, which is only advanced at the
+system timer tick — nominally 15.625 ms, and NOT made finer by asking for
+nanoseconds. `as_nanos()` therefore returns the SAME value for every call inside
+one tick. Two `#[test]` functions in ONE test binary run as threads of ONE
+process, so `process::id()` is identical too. Both halves of the name can be
+equal, and:
+
+- with `create_dir`, the second caller fails outright with `ERROR_ALREADY_EXISTS`;
+- with `create_dir_all`, nothing fails — the two tests silently SHARE a directory
+  and clobber each other's fixture files, which is the worse outcome because it
+  surfaces as an unrelated assertion failure.
+
+A monotonic per-process `AtomicU64` serial removes the failure mode by
+construction: `fetch_add` returns a distinct value to every caller in the process
+regardless of what the clock does. The timestamp is retained — it still separates
+successive RUNS of the same binary — but it is no longer what carries uniqueness.
+
+### The audit, and the predicate that makes it decidable
+
+The naive predicate ("name built from pid + a timestamp") flags 186 `format!`
+sites and is useless. The decidable predicate is:
+
+> Can the SAME formatted name be produced TWICE inside one process?
+
+That is true only when the builder has no per-callsite discriminator AND is
+reached more than once. It is false for a one-off name inside a single `#[test]`
+(that body executes exactly once per process) and false for a helper whose name
+embeds a `{label}` / `{tag}` / `{test_name}` that differs per caller.
+
+Applying it: 52 of the 186 sites carry no discriminator, and 46 of those 52 sit
+directly inside a single `#[test]` body, so they cannot collide with themselves.
+The `{label}`-bearing helpers were checked mechanically for the remaining hole —
+the same label passed twice — and **no helper in the workspace is ever called
+twice with the same label**, so none of them collides either.
+
+That leaves six sites, all of them fixed here:
+
+| File:line                                           | How the name is built                     | Reached from                        | Two tests collide on Windows?                                                        | Verdict                   |
+| --------------------------------------------------- | ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- |
+| `codegraph-store/tests/schema_parity.rs:194`        | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **6** `#[test]` fns | **YES** — second `create_dir` gets `ERROR_ALREADY_EXISTS`                            | **FIXED** (serial added)  |
+| `codegraph-store/tests/bulk_index_pragmas.rs:176`   | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **7** `#[test]` fns | **YES** — same shape, same failure                                                   | **FIXED** (serial added)  |
+| `codegraph-cli/src/installer/shared.rs:1019`        | `pid` + `nanos`, `create_dir_all`         | `tmp_path`, **10** call sites       | **YES, silently** — dir is shared and `opencode.json` / `conf.json` are reused names | **FIXED** (serial added)  |
+| `codegraph-cli/src/installer/registry.rs:144`       | `pid` + `nanos`, dir created by installer | `temp_ctx`, **6** `#[test]` fns     | **YES, silently** — two tests get the same `home`/`cwd`                              | **FIXED** (serial added)  |
+| `codegraph-cli/src/installer/targets/claude.rs:405` | `pid` + `nanos`, dir created by installer | `temp_ctx`, **1** `#[test]` fn      | **not today** — one caller, so one execution                                         | hardened (helper shape)   |
+| `codegraph-store/src/connection.rs:1503`            | `pid` + `nanos`, `create_dir`             | one `#[test]` body, unique prefix   | **not today** — sibling builders all carry a `{label}`                               | hardened (named in brief) |
+
+The last two rows are stated as hardening, not as bug fixes, because the honest
+answer to the predicate is "no". They are cheap, they make the module uniform,
+and they stop the next caller added to either helper from reintroducing the
+class. Nothing else in the workspace was touched: adding serials to the 46
+single-execution sites would be churn with no failure mode behind it.
+
+### Why "it is only a test helper" was not assumed
+
+Two of the nine earlier layers in this ledger were PRODUCTION defects found under
+exactly that framing (`FlushFileBuffers` on a directory handle, `b71a5f1`; the
+named-pipe half-close that hung `run_proxy`, `47ee705`). Each of the six sites
+here was therefore checked for a production caller: all six are inside
+`#[cfg(test)]` modules or `tests/` targets, and `create_dir` / `create_dir_all`
+in production paths (`index_paths`, `rebuild`, `index_state_publisher`) either
+already carry a monotonic serial — `index_state_publisher::create_temp` uses
+`{serial:016x}` — or derive their names from the project identity rather than
+from a clock. No production name depends on clock resolution.
+
+### Round 9 — gate statuses, as the shell actually reported them
+
+| Command                                                      | Exit  | Result                                                         |
+| ------------------------------------------------------------ | ----- | -------------------------------------------------------------- |
+| `cargo test --locked -p codegraph-store`                     | **0** | **191 passed, 0 failed, 0 ignored** on Linux                   |
+| `cargo clippy --locked --workspace --all-targets -Dwarnings` | **0** | zero warnings                                                  |
+| `make ci CARGO='cargo --locked'` (1st)                       | **0** | `✅ All CI checks passed!` — **3021 passed, 0 failed** in 78 s |
+| `make ci CARGO='cargo --locked'` (2nd)                       | **0** | `✅ All CI checks passed!` — **3021 passed, 0 failed** in 59 s |
+| `bash scripts/check-workspace-versions.sh`                   | **0** | all crates on `0.40.4`                                         |
+| `bash scripts/check-ci-gate.sh`                              | **0** | 16 truth-table cases; only all-success exits 0                 |
+| `sha256sum Cargo.lock`                                       | **0** | `750ee84b…83de9bb1` — unchanged                                |
+| `git diff --stat cad3577..HEAD -- reference/golden/`         | **0** | **empty** — no golden byte moved                               |
+
+Ordering, stated so the exits above are not overread: both `make ci` runs executed
+on the code tree. The only change made afterwards was this table plus `make fmt`
+on it, re-verified by a third `make ci` recorded in the follow-up commit alongside
+the CodeBuild result. `make ci` leaves untracked `reference/golden/*/colby.db-{wal,shm}`
+sidecars behind (the equivalence oracle opens each golden DB); they are not
+gitignored and were removed before committing.
+
+**Windows is NOT validated locally** for this round; cross-compilation is
+unavailable in this environment (`cargo xwin` needs `clang-cl`, which cannot be
+installed here). Only a CodeBuild run on a real Windows host can confirm it, and
+that result is recorded in the follow-up commit.

From a23c37e4521cf35dabe95e4dc36e140ba162fc10 Mon Sep 17 00:00:00 2001
From: sunerpy <nkuzhangshn@gmail.com>
Date: Fri, 31 Jul 2026 00:57:30 +0800
Subject: [PATCH 91/91] docs: record the first windows-green codebuild run for
 rounds eight and nine

---
 docs/upstream-sync/V1_5_PORTABLE_FIXES.md | 63 ++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
index 0071f02..f22923f 100644
--- a/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
+++ b/docs/upstream-sync/V1_5_PORTABLE_FIXES.md
@@ -9960,8 +9960,8 @@ That leaves six sites, all of them fixed here:
 
 | File:line                                           | How the name is built                     | Reached from                        | Two tests collide on Windows?                                                        | Verdict                   |
 | --------------------------------------------------- | ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- |
-| `codegraph-store/tests/schema_parity.rs:194`        | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **6** `#[test]` fns | **YES** — second `create_dir` gets `ERROR_ALREADY_EXISTS`                            | **FIXED** (serial added)  |
-| `codegraph-store/tests/bulk_index_pragmas.rs:176`   | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **7** `#[test]` fns | **YES** — same shape, same failure                                                   | **FIXED** (serial added)  |
+| `codegraph-store/tests/schema_parity.rs:194`        | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **4** `#[test]` fns | **YES** — second `create_dir` gets `ERROR_ALREADY_EXISTS`                            | **FIXED** (serial added)  |
+| `codegraph-store/tests/bulk_index_pragmas.rs:176`   | `pid` + `nanos`, `create_dir`             | `TestDir::new`, **6** `#[test]` fns | **YES** — same shape, same failure                                                   | **FIXED** (serial added)  |
 | `codegraph-cli/src/installer/shared.rs:1019`        | `pid` + `nanos`, `create_dir_all`         | `tmp_path`, **10** call sites       | **YES, silently** — dir is shared and `opencode.json` / `conf.json` are reused names | **FIXED** (serial added)  |
 | `codegraph-cli/src/installer/registry.rs:144`       | `pid` + `nanos`, dir created by installer | `temp_ctx`, **6** `#[test]` fns     | **YES, silently** — two tests get the same `home`/`cwd`                              | **FIXED** (serial added)  |
 | `codegraph-cli/src/installer/targets/claude.rs:405` | `pid` + `nanos`, dir created by installer | `temp_ctx`, **1** `#[test]` fn      | **not today** — one caller, so one execution                                         | hardened (helper shape)   |
@@ -10009,3 +10009,62 @@ gitignored and were removed before committing.
 unavailable in this environment (`cargo xwin` needs `clang-cl`, which cannot be
 installed here). Only a CodeBuild run on a real Windows host can confirm it, and
 that result is recorded in the follow-up commit.
+
+### CodeBuild verification on a REAL Windows host — rounds 8/10 AND 9 are CONFIRMED
+
+Build `codegraph-rs-windows:d4d9c258-edfc-41c0-b2e5-57489afa6444`, resolved source
+version `ff9bf9f735a8cd062739eb87fa2fbef14cdfd320` — the exact tip pushed for this
+round — `buildStatus: SUCCEEDED`, 00:25:05 → 00:53:28 (+08:00), 28 minutes.
+
+Pipeline `codegraph-rust-ci` execution `ffad15d6-3959-4e79-85d6-7d21a7707faa`
+reached `Succeeded` after 28 `InProgress` polls. Every action succeeded:
+
+| Stage  | Action     | Status        |
+| ------ | ---------- | ------------- |
+| Source | CodeCommit | **Succeeded** |
+| Build  | Linux      | **Succeeded** |
+| Build  | Windows    | **Succeeded** |
+
+The COMPLETE list of `... FAILED` lines from the 4372-line Windows log is **EMPTY**
+— `grep -c FAILED` returned **0**. Aggregating all 125 `test result:` lines:
+**2927 passed, 0 failed, 0 ignored**, and not one of the 125 lines is anything
+other than `test result: ok`. This is the first Windows-green run on this branch;
+the previous nine rounds each ended with at least one `FAILED`.
+
+Both open rounds are settled by this single run:
+
+- **Round 8/10 (`8389c9e`) CONFIRMED.** The three fixtures that failed with
+  `ERROR_LOCK_VIOLATION` now pass: `timeout_and_post_contention_cancellation_preserve_lock_bytes
+... ok`, `exclusive_process_blocks_shared_and_exclusive ... ok`, and the
+  control `shared_processes_coexist_but_shared_blocks_exclusive ... ok`.
+  `tests\index_lease.rs` reports **11 passed / 0 failed** (13 on Linux; two are
+  `#[cfg(unix)]`).
+- **Round 9 (this round) CONFIRMED not to regress.** Every target holding a fixed
+  helper is green on Windows: `tests\schema_parity.rs` **4/0**,
+  `tests\bulk_index_pragmas.rs` **6/0**, `tests\installer.rs` **8/0**,
+  `tests\installer_jsonc.rs` **14/0**.
+
+An honest limit on what round 9 proves: because the collision needs two threads
+to land inside the same 15.6 ms tick, a green run does not prove the OLD names
+would have failed on this host — the defect was latent, and derived from the clock
+contract rather than observed in a log. What this run does establish is that the
+serial neither breaks nor perturbs anything, and that no name-collision failure
+remains in the workspace. The class is now closed by construction rather than by
+luck of scheduling.
+
+### Round 9 follow-up — gate statuses after the ledger update
+
+| Command                                              | Exit  | Result                                                          |
+| ---------------------------------------------------- | ----- | --------------------------------------------------------------- |
+| `make ci CARGO='cargo --locked'` (3rd, post-commit)  | **0** | `✅ All CI checks passed!` — **3021 passed, 0 failed** in 58 s  |
+| `GIT_MASTER=1 git push` (origin)                     | **0** | pre-push hook `✅ all checks passed`; `cad3577..ff9bf9f`        |
+| `GIT_MASTER=1 git push cc`                           | **0** | pre-push hook `✅ all checks passed`; `cad3577..ff9bf9f`        |
+| `aws codepipeline start-pipeline-execution`          | **0** | `ffad15d6-3959-4e79-85d6-7d21a7707faa`                          |
+| `aws codepipeline get-pipeline-execution` (29 polls) | **0** | `InProgress` ×28, then **`Succeeded`**                          |
+| `aws codepipeline list-action-executions`            | **0** | Source/Linux/**Windows** all `Succeeded`                        |
+| `aws codebuild batch-get-builds`                     | **0** | `SUCCEEDED` at `ff9bf9f7…`                                      |
+| `aws logs tail /aws/codebuild/codegraph-rs-windows`  | **0** | 4372 lines; **2927 passed / 0 failed**; **zero** `FAILED` lines |
+
+With Windows green, `CI Success` should now conclude for PR #173, whose other
+gates (`Test`, `Coverage`, `Security Audit`, `codecov/patch`, `codecov/project`)
+were already passing.