sql-code-graph 1.2.2__tar.gz → 1.3.0__tar.gz

{sql_code_graph-1.2.2 → sql_code_graph-1.3.0}/ARCHITECTURE_REVIEW.md

@@ -3026,8 +3026,13 @@ Both are now load-bearing; recorded so a future refactor does not silently undo
   re-verification (80→47 `cte_insert` islands) recorded in the plan; the surviving 47
   are likely legitimately source-less computed measures, not a regression. Shape B of
   the #40 guard now asserts a computed-measure projection so a real gap there reds the guard.
-- **#28 server read-only-by-default + reindex escalation** — out of 1.2.1; recommended
-  as a separate minor (1.3.0). The read half is already handled by the v1.2.0 routing proxy.
+- **#28 server read-only-by-default + reindex escalation** — **IMPLEMENTED in 1.3.0**
+  (#29 single-writer queue + RO→RW escalation; plan
+  [`fix_issue_29_single_writer_queue.md`](plan/fix_issue_29_single_writer_queue.md)).
+  The read half was already handled by the v1.2.0 routing proxy; 1.3.0 adds the write half:
+  the server serves RO after a startup RW schema-ensure window, and escalates RO→RW only for
+  the duration of a single-writer drain. See §20 for the compliance postmortem and two
+  accepted/flagged deviations.
 - **`connected_clients` fidelity** — best-effort `1` today; no real counter.
 
 ## 19. v1.2.1 live DWH re-verification — two residual findings (2026-06-02)
@@ -3145,3 +3150,129 @@ The fix held for v1.2.2 (the helper mirrors the shipped query), but the divergen
 structural. **Future hardening:** replace the string-reconstruction helper with a
 `CliRunner`-based guard that runs the real `analyze downstream` command and asserts the
 rendered output. LOW priority; below §19.1 and the open §3.x items. No plan stub drafted.
+
+## 20. v1.3.0 — Single-Writer Queue + RO→RW Escalation (#29 / #28) (2026-06-04)
+
+Implements the long-deferred §18.4 "#28 server read-only-by-default + reindex escalation"
+item. Plan: [`fix_issue_29_single_writer_queue.md`](plan/fix_issue_29_single_writer_queue.md).
+Branch `feat/fix-issue-29-single-writer-queue`, 8 commits (T-01…T-08). Test suite
+1009 passed / 7 skipped / 1 xfailed; pyright clean; ruff clean.
+
+### 20.1 What shipped (plan-compliance verdict)
+
+The five phases landed as planned. The hard invariants were honoured **in the
+control-socket / drain path**:
+
+- **B1 (no co-existence window)** — Steps 2.2 (drain task + escalation primitive) and 2.3
+  (retire the inline `reindex` op) landed in **one commit** (`62c19cd`). The `reindex` and
+  `index` socket-op handlers in [`server.py`](src/sqlcg/server/server.py) `_control_socket_task`
+  enqueue onto `WriterQueue` and never call `backend_ref()`; the drain task is the sole
+  backend consumer, resolving the backend under `backend_lock` via `escalate_to_rw`.
+- **B2 (shutdown vs. drain ordering)** — `_stop_watcher`
+  ([`server.py`](src/sqlcg/server/server.py) L394-410) sets `shutdown_requested` then
+  acquires `backend_lock` **before** `shutdown_backend()`; `de_escalate_to_ro`
+  ([`writer.py`](src/sqlcg/server/writer.py)) skips the RO reopen when the event is set.
+  Both guarantees (a)+(b) present.
+- **B3 (status framing atomic)** — server-side `status` framing (Step 4.1) and the CLI
+  recv-exactly parse (Step 4.2) shipped in one commit (`af2c85d`); `mcp_stop`'s
+  `s.recv(128)` and the unframed `stop` reply are untouched.
+- **W3 (`from=null`)** — the `reindex` op stores `from_sha=None`; the drain resolves the
+  stored SHA via `rw.get_indexed_sha()` and HEAD via `git rev-parse`, with an actionable
+  "no prior index" error on a never-indexed DB. The CLI refusal was removed.
+- **W5 (`done:true` sentinel)** — both server emit and CLI recv loops key off
+  `done == true`, not EOF; failure relays `ok:false, done:true, error:…`.
+- **W6 (`find_lock_holder` public)** — promoted in `kuzu_backend.py`, in-module call site
+  updated, imported by `writer.py`.
+- **W7 (drain exception handler)** — the drain's `except Exception` clears `_active`
+  (`mark_active_failed`), relays an `ok:false,done:true` terminal frame to waiters, and the
+  loop survives; `EscalationLockError` keeps its dedicated C3 path with the ERROR log.
+
+### 20.2 Deviation 1 — MCP `index_repo` tool inline escalation (FLAGGED — follow-up required)
+
+**What the developer added (not in the plan):** a `_serving_ro` flag +
+`_get_or_escalate_rw` / `_de_escalate_to_ro_from_tool` helpers in
+[`tools.py`](src/sqlcg/server/tools.py) so the MCP `index_repo` **tool** (invoked over the
+stdio transport, distinct from the CLI `index` socket op) escalates RO→RW inline when the
+server is serving RO.
+
+**Verdict: the intent is consistent with the single-writer model, but the implementation
+violates the plan's central invariant and leaks the write lock on failure. Track as a
+v1.3.x follow-up, not a release blocker (the happy path works and tests are green), but
+it must be fixed before it is relied on under concurrency.**
+
+Three concrete problems:
+
+1. **Escalation outside `backend_lock` (breaks B1/OD-7).** The plan's load-bearing invariant
+   is "once escalation exists, **no op may operate on a backend resolved outside
+   `backend_lock`**; the only backend consumer is the drain task." The MCP `index_repo` tool
+   escalates and writes with **no lock held** — a second path that can swap
+   `tools._backend` concurrently with a `query` op or a drain. This is exactly the class of
+   bug B1 was written to prevent.
+2. **RW-lock leak on the failure path.** `_de_escalate_to_ro_from_tool` is called only on the
+   success branch ([`tools.py`](src/sqlcg/server/tools.py) L613-614), **not in a `finally`**.
+   Any exception during `index_repo` / `upsert_node` / `run_read` / `upsert_edge` re-raises
+   (L634) with the backend still RW — the exclusive write lock stays held, blocking all
+   subsequent routed reads until the server is restarted. (Contrast the drain path, which
+   de-escalates in a `finally`.)
+3. **Dead `_set_backend_lock` / `_backend_lock`.** `_set_backend_lock`
+   ([`tools.py`](src/sqlcg/server/tools.py) L117) and the `_backend_lock` global are
+   **defined but never called** — a zero-value stub that looks like the intended lock plumbing
+   for the tool escalation but was never wired. This is the CLAUDE.md "every new method must
+   have a grep-confirmed call site" rule unmet, and the "function defined but never invoked"
+   smell.
+
+**Follow-up (recommended):** route the MCP `index_repo` tool write through the same
+`WriterQueue`/drain as the CLI `index` op (so there is genuinely one writer), or — minimally —
+acquire `backend_lock` for the escalation and move the de-escalation into a `finally`. There
+is **no test** for this path today (no test references `_get_or_escalate_rw` / `_serving_ro`),
+so the leak and the lock-bypass are unguarded. A regression test asserting (a) the tool
+escalates under the lock and (b) a raising `index_repo` de-escalates back to RO is required
+with the fix.
+
+### 20.3 Deviation 2 — Step 4.3 "queued behind N" display (ACCEPTED, minor)
+
+The plan's Step 4.3 specified that a client queued behind other work prints
+`queued behind: <op> (done/total files) — position N` before attaching to live progress.
+The developer implemented the `done:true` terminal sentinel and the progress-bar attach
+fully, but **omitted the "queued behind … position N" pre-active display**: the CLI receives
+the `{queued:true, position:N}` frame and the subsequent progress frames, but the queued
+frame is silently consumed (it carries no `files_total`, so the progress loop renders
+nothing for it) — see [`index.py`](src/sqlcg/cli/commands/index.py) L307-311.
+
+**Verdict: ACCEPTED as a cosmetic shortfall.** The functional contract (enqueue, attach,
+stream progress, terminate on `done:true`, exit non-zero on `ok:false`) is intact; only the
+human-readable "you are behind N others" hint is missing. The `position` is already on the
+wire, so completing it is a one-line render in the existing loop. Track as a polish item,
+not a correctness gap.
+
+### 20.4 Test-coverage gaps vs. the plan's Test Strategy (FLAGGED)
+
+The plan's Test Strategy enumerated several **deterministic** integration tests that were
+not implemented as test functions, even though
+[`test_single_writer_queue.py`](tests/integration/test_single_writer_queue.py)'s module
+docstring lists B2 / W3 among its coverage (the docstring overstates what is asserted):
+
+- **B2 stop-mid-drain** (in-flight write commits; `tools._backend is None` after shutdown,
+  no reopen-after-shutdown) — listed in the docstring, **no test function**.
+- **W3** arg-level assertion (`resync_changed(from=stored SHA, to=HEAD)`) and the
+  never-indexed "no prior index" error — **no test** (the drain code is present and exercised
+  indirectly by Scenario A, but the W3-specific arg/branch assertions are missing).
+- **W7** drain-body-raises → `_active` cleared + `ok:false,done:true` terminal frame + loop
+  survives — **no test**.
+- **Reads block during a drain** (OD-1, deterministic `anyio.Event` ordering) — **no test**.
+- **B1 structural guard** (the `reindex` op body contains no pre-lock `backend_ref()`,
+  mirroring the perf-invariant guard discipline) — **no test**.
+- **Escalation transition on real Kuzu** (second in-process RO holder forces
+  `EscalationLockError`) — **no test** (only the injected-`opener` unit tests cover retry).
+
+What **is** covered: fresh-DB init, stale-schema refusal (Step 1.4), `db reset` refusal
+(Step 3.4), framed `status` + `writer_queue` shape (Steps 4.1/4.2), metrics persisted +
+`SQLCG_METRICS=0` suppression (Step 4.5), the escalation retry/backoff + ERROR-log unit tests
+(Steps 1.2/4.4), the coalescing rules (Step 2.1), and the drain-runs-`resync_changed`-once
+invariant guard (Scenario A in `test_reindex_via_server.py`).
+
+**Verdict:** these are real plan deviations (the named deterministic guards were specified
+and not delivered), but the shipped behaviour is exercised indirectly and the suite is green,
+so they are **follow-up hardening**, not a ship blocker. They should be filed alongside the
+Deviation-1 fix — the B2/W7/reads-block tests in particular guard the exact concurrency
+contract that Deviation 1 currently bypasses.

{sql_code_graph-1.2.2 → sql_code_graph-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.2.2
+Version: 1.3.0
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph

{sql_code_graph-1.2.2 → sql_code_graph-1.3.0}/docs/cli.md

@@ -62,6 +62,13 @@ sqlcg index [OPTIONS] PATH
 
 Index SQL files in a directory.
 
+When a server is live on this DB, the index is routed through the server's
+control socket so the DB is never opened directly (avoids lock contention).
+Use --detach to enqueue and return immediately (fire-and-forget).
+
+With no server live, falls back to the direct-write path unchanged
+(zero-config small-repo invariant).
+
 Schema aliases (staging schema → canonical schema) can be configured in
 .sqlcg.toml under sqlcg.schema_aliases, e.g. da_tmp = "da".
 
@@ -80,6 +87,7 @@ Schema aliases (staging schema → canonical schema) can be configured in
 | --debug | BOOLEAN | No | No | False | Show detailed log output during indexing |
 | --profile / --no-profile | BOOLEAN | No | No | False | Emit per-stage timing after indexing |
 | --include-working-tree | BOOLEAN | No | No | False | Index the working tree including uncommitted changes. Marks freshness as 'indexed with working-tree changes'. |
+| --detach | BOOLEAN | No | No | False | When routing through a live server, return immediately after enqueueing (fire-and-forget). Default is to wait for the index to complete. |
 
 ## `sqlcg reindex`
 
@@ -548,7 +556,12 @@ sqlcg mcp status [OPTIONS]
 Print server status JSON (connects to control socket).
 
 Returns JSON with fields: running, pid, db_path, indexed_sha, head_sha,
-stale_by_commits, connected_clients, uptime when a server is live.
+stale_by_commits, connected_clients, uptime, writer_queue when a server
+is live.
+
+The status response is length-prefixed framed (v1.3.0, B3) so large
+writer_queue payloads are received in full — the client uses the
+recv-exactly makefile+readline+read(n) pattern, NOT a single recv(4096).
 
 When no server is found: {"running": false}.
 When the PID file exists with a live process but the socket is unavailable:

sql_code_graph-1.3.0/plan/fix_issue29_live_test_followups.md

@@ -0,0 +1,442 @@
+# Feature Plan: #29 Live-Test Follow-up Fixes (fold into PR #51 / v1.3.0)
+
+## Summary
+Three correctness bugs (plus one cosmetic message fix) surfaced during live-DWH
+testing of the open PR #51 branch `feat/fix-issue-29-single-writer-queue`
+(v1.3.0 — single-writer queue + RO→RW escalation). These fold into the **unreleased**
+PR #51; the version stays **1.3.0** (no separate bump — see Version note below).
+
+Source of findings: GitHub issue [#29](https://github.com/Warhorze/sql-code-graph/issues/29)
+live-test comment. Bug B is already documented as an architecture follow-up in
+`ARCHITECTURE_REVIEW.md` §20.2 ("Deviation 1 — MCP `index_repo` tool inline escalation").
+
+## Version note (RESOLVED — stays 1.3.0)
+These are bug fixes to code that has **not yet shipped** (PR #51 has no reviews and is
+not merged). Per CLAUDE.md SemVer, the version stays **1.3.0** — there is no released
+1.3.0 to patch against, so no `1.3.1`. Do **not** bump `pyproject.toml` / `__init__.py`
+/ `uv.lock`. Decision confirmed (see Resolved Decisions §D1): fold into PR #51, version
+unchanged.
+
+## Scope
+
+### In Scope
+- **Bug A** — resolve `--dialect auto` (and any repo-config-derived client-side value)
+  **before** building the socket WriterRequest in `reindex.py` and `index.py`.
+- **Bug B** — store the path `init_backend(db_path)` received in a module-level variable
+  and use it for all escalation/de-escalation in `tools.py`; audit every `get_db_path()`
+  call in `tools.py` / `writer.py` / `server.py` for the same default-path leak.
+- **Bug C** — `install-hooks` upgrades an sqlcg-owned hook in place when the rendered
+  content differs from the current template; prints `Upgraded git hook: …`. True
+  idempotency (identical rendered content) stays a silent skip. Foreign-hook warning
+  path unchanged.
+- **Minor D** — reword the hook fallback message from "server busy/locked" to a
+  failure-agnostic "reindex failed".
+- Regression tests for A, B, C, D that assert **observable output** (payload contents,
+  default-path untouched, stdout message, hook file content).
+
+### Non-Goals
+- **The kuzu 0.11.3 `KU_UNREACHABLE` crash** (csr_node_group.cpp:411 on a second
+  consecutive reindex). It reproduces on the direct no-server path on a fresh DB →
+  upstream/pre-existing, tracked separately in the issue comment. **No kuzu upgrade,
+  no DB-suspect guard in this plan.**
+- The **deeper §20.2 escalation-architecture fixes** (escalation outside `backend_lock`,
+  RW-lock leak on the `index_repo` failure path, the dead `_set_backend_lock` /
+  `_backend_lock` stub). Bug B as scoped by the maintainer is *narrow*: "use the init
+  path, audit `get_db_path`". §20.2 demands more. See "Design — Bug B" for the boundary
+  and the explicit decision; the full §20.2 remediation is **out of scope here** and
+  remains a tracked v1.3.x follow-up (resolved decision D3).
+- No version bump (see Version note).
+- **Performance invariants are untouched.** None of these fixes go near
+  [`base.py`](src/sqlcg/parsers/base.py) or [`indexer.py`](src/sqlcg/indexer/indexer.py)
+  hot paths. The diff is confined to two CLI commands, `tools.py`, `git.py`, and tests.
+  The developer must confirm `git diff --stat` shows zero changes to `base.py` and to
+  `indexer.py`'s `_extract_column_lineage` / `_upsert_parsed_file` / `_build_file_rows`
+  / `_flush_row_batch`.
+
+## Design
+
+### Bug A — `--dialect auto` leaks through the routed reindex/index
+
+**Root cause (verified in code):**
+- [`reindex.py`](src/sqlcg/cli/commands/reindex.py) calls
+  `_try_route_reindex_via_server(... dialect=dialect ...)` at **lines 86-93**, which sends
+  `payload["dialect"] = dialect` (line 227). The `if dialect == "auto": dialect = get_dialect(path)`
+  resolution is at **lines 98-99 — AFTER** the routing call. So when a server is live the
+  WriterRequest carries the literal `"auto"`.
+- [`index.py`](src/sqlcg/cli/commands/index.py) has the **same ordering bug**:
+  `_try_route_index_via_server(... dialect=dialect ...)` at **lines 113-118**
+  (payload at line 230) runs **before** the `if dialect == "auto"` resolution at
+  **lines 155-156**. The routed full index *appeared* correct in live testing only
+  because the synthetic DDL happened to parse acceptably; the code order is still wrong
+  and must be fixed for parity.
+
+**Server-side confirmation (no fix needed there):** the drain loop
+([`writer.py`](src/sqlcg/server/writer.py) lines 528-605) passes `req.dialect`
+verbatim to `index_repo` / `resync_changed`. There is no server-side `auto` resolution
+— the server cannot resolve `auto` because `get_dialect(path)` reads the repo's
+`.sqlcg.toml` and that is a client-side concern. The fix **must** be client-side.
+`"Unknown dialect 'auto'"` is raised downstream by sqlglot's dialect lookup once the
+literal `"auto"` reaches the parser.
+
+**Fix:** in **both** `reindex.py` and `index.py`, move the
+`if dialect == "auto": dialect = get_dialect(path)` resolution **above** the
+`_try_route_*_via_server(...)` call so the routing payload always carries a concrete
+dialect (or an explicit `None`/named dialect the user passed). After the move:
+- `reindex.py`: resolve dialect right after `path = path.resolve()` (line 78), before
+  line 86. `get_dialect` is already imported in the function-local import at line 73.
+- `index.py`: resolve dialect right after `path = path.resolve()` (line 110), before
+  line 113. `get_dialect` is already imported at module level (line 19).
+- The duplicate resolution further down (reindex.py 98-99, index.py 155-156) is then
+  **removed** (it becomes dead — the value is already resolved). Confirm via grep that
+  exactly one `if dialect == "auto"` remains per file, and it is before the route call.
+
+**Boundary note:** "auto" is the only repo-config-derived value carried in the payload
+today (`root`, `from`, `to`, `wait` are not config-derived). No other client-side
+`.sqlcg.toml` lookup needs hoisting. Document this so the developer does not over-reach.
+
+### Bug B — RW escalation ignores the path `init_backend()` received
+
+**Root cause (verified in code):**
+- [`tools.py`](src/sqlcg/server/tools.py) `init_backend(db_path)` (line 128) opens the
+  backend on `path = db_path or str(get_db_path())` (line 151) but stores **only**
+  `_backend` and `_serving_ro` (lines 168-169). The `path` is **not** retained.
+- The MCP tool `index_repo` (line 547) recomputes `db_path_str = str(get_db_path())`
+  (**line 579**) and passes that to `_get_or_escalate_rw` (line 581) and
+  `_de_escalate_to_ro_from_tool` (line 614). So escalation opens whatever
+  `get_db_path()` returns — i.e. the default `~/.sqlcg/graph.db` — **not** the DB
+  `init_backend` actually opened.
+
+**Live impact (reproduced):** `tests/e2e/test_mcp_tools.py` does
+`init_backend(str(tmp_path / "test.db"))` (line 30) then `index_repo(...)` (line 33).
+The escalation opened the user's real `~/.sqlcg/graph.db`, wrote
+`tests/fixtures/synthetic` into it during a pytest run, and held the live DB lock —
+blocking a real server start.
+
+**Fix:**
+1. Add a module-level variable `_init_db_path: str | None = None` next to `_backend`
+   / `_serving_ro` (tools.py lines 101-114).
+2. In `init_backend`, set `_init_db_path = path` (the resolved `db_path or
+   str(get_db_path())`) under the existing `global` declaration (line 150 — add
+   `_init_db_path` to it).
+3. In `shutdown_backend` (line 181), reset `_init_db_path = None` alongside the other
+   globals (add to the `global` at line 187).
+4. Add a private accessor `_escalation_db_path() -> str` that returns `_init_db_path`
+   when set, else `str(get_db_path())` (preserves the no-`init_backend` direct-call
+   path used by some unit tests). **This is a new function — it MUST have a grep-confirmed
+   call site before the PR opens** (the `index_repo` tool is its call site; see step).
+5. In `index_repo` (line 579), replace `db_path_str = str(get_db_path())` with
+   `db_path_str = _escalation_db_path()`. The downstream `_get_or_escalate_rw(db_path_str, …)`
+   (581) and `_de_escalate_to_ro_from_tool(db_path_str)` (614) then use the init path.
+
+**Audit of every `get_db_path()` call (verified list):**
+| File:line | Context | Verdict |
+|---|---|---|
+| `tools.py:14` | import | n/a |
+| `tools.py:151` | `init_backend` fallback when `db_path is None` | **correct** — this is the source of truth; capture it into `_init_db_path` |
+| `tools.py:579` | `index_repo` escalation | **LEAK — fix** (step 5) |
+| `writer.py` `escalate_to_rw` / `de_escalate_to_ro` | take `db_path: str` as a parameter; the drain passes the `drain_loop(db_path=…)` argument (writer.py 510-511, 628-629) | **correct** — drain path threads the real db_path; do not change |
+| `server.py:140,221` | status reply `db_path` display | display-only; reflects `db_path or _get_db_path()` from the server CLI arg — **correct** |
+| `server.py:509,525` | `_run_with_control` resolves `_db_path_obj = Path(db_path) if db_path else get_db_path()` and threads it into `drain_loop` | **correct** — the drain receives the server's actual db_path |
+
+So the **only** leak is `tools.py:579` (the MCP `index_repo` tool). The drain/CLI-op
+path is already correct because `db_path` is threaded as a parameter, not re-fetched.
+
+**§20.2 boundary (explicit):** this fix corrects the *path* used by the existing
+`index_repo` tool escalation. It does **not** move escalation under `backend_lock`, does
+**not** add a `finally`-based de-escalation, and does **not** wire/remove the dead
+`_set_backend_lock` / `_backend_lock` stub. Those are the §20.2 remediation, scoped out
+here (resolved decision D3). The Bug B fix makes the tool target the correct DB; it does not claim
+to make the tool concurrency-safe.
+
+### Bug C — `install-hooks` silently refuses to upgrade old sqlcg hooks
+
+**Root cause (verified in code):** [`git.py`](src/sqlcg/cli/commands/git.py)
+`_install_single_hook` (line 91): when the file exists and `spec.sentinel in existing_content`
+(line 103), it returns silently (line 105). The sentinel string (e.g.
+`# sqlcg post-checkout hook`) is **identical across versions**, so a v1.2.x hook (no
+`--notify`, blocks `git checkout` ~2 min against a live server) survives a v1.3.0
+`install-hooks` with exit 0 and no output.
+
+**Fix:** the sentinel proves sqlcg ownership. When the sentinel is present:
+- Render the current template: `script = spec.script_template.format(sqlcg_bin=sqlcg_bin)`
+  (this already happens at line 99). The rendered script embeds the resolved binary path,
+  so **the comparison MUST be against the fully rendered `script`**, not the raw template.
+- If `existing_content == script` → identical → **silent skip** (true idempotency, R9).
+- If `existing_content != script` → sqlcg-owned but stale → **overwrite** (`write_text` +
+  `chmod(0o755)`) and print `[green]Upgraded git hook:[/green] .git/hooks/<filename>`.
+
+When the sentinel is **absent** (foreign hook) → the existing warning + manual-append
+path (lines 106-118) is **unchanged**.
+
+**Comparison subtlety:** `existing_content` is the raw file text; `script` is the
+rendered template. A hook installed by a different sqlcg version differs in the command
+line (e.g. missing `--notify`, or the old "server busy/locked" message — see Minor D),
+so the `!=` will fire and trigger the upgrade. A hook installed by the *current* binary
+from the *same* resolved path is byte-identical → silent skip. Note the binary path is
+embedded, so two installs from different binary locations will (correctly) re-render and
+upgrade.
+
+### Minor D — misleading hook fallback message
+
+**Root cause (verified in code):** both hook templates in `_HOOKS`
+([`git.py`](src/sqlcg/cli/commands/git.py) lines 36-37 post-checkout, lines 53 & 56
+post-merge) print `sqlcg: graph not updated (server busy/locked) -- run 'sqlcg mcp status'`
+on **any** reindex non-zero exit, including a KuzuDB storage crash (KU_UNREACHABLE), which
+has nothing to do with the server being busy.
+
+**Fix:** reword all three occurrences to a failure-agnostic message:
+`sqlcg: graph not updated (reindex failed) -- run 'sqlcg mcp status'`.
+
+**Interaction with Bug C:** changing the template text changes the **rendered** content,
+so every previously-installed hook (with the old message) now differs from the new
+template → Bug C's upgrade path will (correctly) overwrite it on the next `install-hooks`.
+This is the intended behaviour and is exactly why C and D ship together. The
+`test_git_hooks_notify.py` content guards
+([`tests/unit/test_git_hooks_notify.py`](tests/unit/test_git_hooks_notify.py)) assert the
+old "server busy/locked" string — they MUST be updated to the new wording (see Test
+Strategy; not a regression, a deliberate text change).
+
+### Docs impact
+`docs/cli.md` is auto-generated by
+[`scripts/generate_cli_docs.sh`](scripts/generate_cli_docs.sh) from **command docstrings
+and option metadata only**. Verified: it does **not** embed `install-hooks` stdout
+messages nor the hook template text (the `install-hooks` section at docs/cli.md:635-653
+is the docstring + the `--repo` option). Bug C changes only **stdout** (a new
+`console.print`), and Minor D changes only the **hook template string** — neither touches
+a docstring or an option. **No `docs/cli.md` regeneration is required.** The developer
+must confirm by diffing: `bash scripts/generate_cli_docs.sh` then `git diff docs/cli.md`
+must show **no change**. (If it does, a docstring was inadvertently touched — investigate.)
+
+## Implementation Steps
+
+### Phase 1: Bug A — client-side dialect resolution before routing
+**Step 1.1**: In `reindex.py`, move `if dialect == "auto": dialect = get_dialect(path)`
+to immediately after `path = path.resolve()` (after line 78, before the route call at
+line 86). Remove the now-dead resolution at lines 98-99.
+- Files: [`reindex.py`](src/sqlcg/cli/commands/reindex.py)
+- Acceptance: `_try_route_reindex_via_server` receives a resolved dialect; grep shows
+  exactly one `if dialect == "auto"` in the file, positioned before line ~86.
+
+**Step 1.2**: In `index.py`, move `if dialect == "auto": dialect = get_dialect(path)`
+to immediately after `path = path.resolve()` (after line 110, before the route call at
+line 113). Remove the now-dead resolution at lines 155-156.
+- Files: [`index.py`](src/sqlcg/cli/commands/index.py)
+- Acceptance: `_try_route_index_via_server` receives a resolved dialect; grep shows
+  exactly one `if dialect == "auto"` in the file, positioned before line ~113.
+
+### Phase 2: Bug B — escalation uses the init path
+**Step 2.1**: Add `_init_db_path: str | None = None` module global (tools.py ~line 114);
+set it in `init_backend` (add to `global` at 150; assign after computing `path` at 151);
+reset to `None` in `shutdown_backend` (add to `global` at 187).
+- Files: [`tools.py`](src/sqlcg/server/tools.py)
+- Acceptance: `init_backend(p)` then reading the module global returns `p`;
+  `shutdown_backend()` clears it.
+
+**Step 2.2**: Add `_escalation_db_path() -> str` returning `_init_db_path or str(get_db_path())`.
+Replace `db_path_str = str(get_db_path())` at line 579 with `db_path_str = _escalation_db_path()`.
+- Files: [`tools.py`](src/sqlcg/server/tools.py)
+- Acceptance: grep shows `_escalation_db_path` defined once and called at exactly one
+  site (`index_repo`); no behavioural change when `init_backend` was never called
+  (falls back to `get_db_path()`).
+
+### Phase 3: Bug C + Minor D — hook upgrade + reworded message
+**Step 3.1 (Minor D)**: Reword the fallback message in all three template occurrences
+to `sqlcg: graph not updated (reindex failed) -- run 'sqlcg mcp status'`.
+- Files: [`git.py`](src/sqlcg/cli/commands/git.py) (lines 36-37, 53, 56)
+- Acceptance: no occurrence of `server busy/locked` remains in `git.py`.
+
+**Step 3.2 (Bug C)**: In `_install_single_hook`, replace the silent-skip branch (lines
+103-105) with: if sentinel present and `existing_content == script` → silent return; if
+sentinel present and content differs → `write_text(script)` + `chmod(0o755)` + print
+`Upgraded git hook: .git/hooks/<filename>`. Foreign-hook branch unchanged.
+- Files: [`git.py`](src/sqlcg/cli/commands/git.py)
+- Acceptance: identical rendered content → no output, file unchanged; sentinel-present
+  stale content → file overwritten with current `script`, "Upgraded git hook:" printed;
+  no-sentinel file → unchanged warning path.
+
+### Phase 4: Tests + verification
+**Step 4.1**: Bug A regression — assert the WriterRequest never carries `"auto"`.
+**Step 4.2**: Bug B regression — `init_backend(tmp)` + escalating `index_repo` must not
+touch the default path.
+**Step 4.3**: Bug C/D tests — upgrade overwrites stale hook + prints; idempotent skip;
+foreign warning unchanged; new message present.
+**Step 4.4**: In `test_git_hooks_notify.py`, add a new negative assertion that
+  `"server busy/locked"` does NOT appear in any hook template. No existing guard
+  asserts the old wording (current tests cover `--notify`, `>&2`, and `|| true`
+  absence only), so nothing needs updating — only the new negative assertion is added.
+  Also add a positive assertion that all templates contain `"(reindex failed)"`.
+**Step 4.5**: Run perf invariant guards + full suite + ruff + pyright; confirm
+`git diff --stat` excludes `base.py` and indexer hot paths; confirm
+`generate_cli_docs.sh` produces no `docs/cli.md` diff.
+
+## Test Strategy
+
+### Unit tests
+- **Bug A** (`tests/integration/`, new file `test_dialect_auto_resolution.py` — these
+  tests require a live Unix-socket thread to capture the on-wire payload and belong in
+  `tests/integration/`, not `tests/unit/`): call
+  `reindex_cmd(..., dialect="auto")` and `index_cmd(..., dialect="auto")` with a live
+  fake socket server (reuse the in-process accept pattern from
+  [`tests/integration/test_reindex_via_server.py`](tests/integration/test_reindex_via_server.py)
+  lines 114-255 — a thread that accepts, reads the framed payload, decodes JSON). Assert
+  `json.loads(payload)["dialect"] != "auto"` and equals `get_dialect(repo_root)` (use a
+  fixture repo with a `.sqlcg.toml` declaring e.g. `dialect = "postgres"` so the assertion
+  is non-vacuous — `assert payload["dialect"] == "postgres"`). Add the symmetric index
+  case. **Observable assertion: the exact dialect string on the wire.**
+- **Bug B** (`tests/unit/` or `tests/e2e/test_mcp_tools.py`): `init_backend(str(tmp_path /
+  "test.db"))`, then call `index_repo(fixture)`. Assert the default path is never touched.
+  Two complementary observable checks (use both):
+  1. `monkeypatch` `sqlcg.server.tools.get_db_path` to a sentinel that **raises** if called
+     during escalation (proves `_escalation_db_path` used `_init_db_path`, not
+     `get_db_path()`). Note `init_backend` itself calls `get_db_path` only on the
+     `db_path is None` branch — since we pass a path, it must not be called at all in this
+     test → the raising sentinel is safe across the whole call.
+  2. Record the default `~/.sqlcg/graph.db` mtime (or its non-existence) before and after;
+     assert unchanged / still-absent. Guards the live-observed symptom directly.
+  **Teardown requirement**: call `shutdown_backend()` after `index_repo` returns (e.g.
+  in a `finally` block or pytest fixture teardown) so the `_init_db_path` module global
+  is reset between tests. Without this, a later `init_backend(None)` call in a subsequent
+  test inherits the stale path and produces a misleading pass.
+- **Bug C** (`tests/unit/test_git_hooks.py` — existing, extend it): three cases —
+  (a) pre-write a stale sqlcg hook (sentinel + old "server busy/locked" text), run
+  `install-hooks`, assert file now equals the current rendered template AND stdout contains
+  `Upgraded git hook:`; (b) write the current rendered hook, run again, assert no output and
+  byte-identical file (idempotency); (c) write a foreign hook (no sentinel), assert the
+  warning path fires and the file is unchanged. **Observable: file content + captured stdout.**
+- **Minor D** (`tests/unit/test_git_hooks_notify.py` — existing): add a new
+  negative assertion that no hook template contains `"server busy/locked"`. No
+  existing guard asserts the old wording (current tests only check `--notify`, `>&2`,
+  and absence of `|| true`), so nothing needs updating — only two assertions are added:
+  one asserting all templates contain `"(reindex failed)"` and one asserting none
+  contain `"server busy/locked"`.
+
+### Integration / e2e
+- The existing [`tests/integration/test_reindex_via_server.py`](tests/integration/test_reindex_via_server.py)
+  and `tests/e2e/test_mcp_tools.py` must stay green; `test_mcp_tools.py` is the file that
+  surfaced Bug B live, so its green state after the fix is itself a guard.
+
+### Invariant guards (must stay green, untouched)
+[`test_perf_scaling_guard.py`](tests/unit/test_perf_scaling_guard.py),
+[`test_T09_01_qualify_once.py`](tests/unit/test_T09_01_qualify_once.py),
+[`test_bulk_upsert_invariant.py`](tests/unit/test_bulk_upsert_invariant.py),
+[`test_upsert_batch_invariant.py`](tests/unit/test_upsert_batch_invariant.py).
+
+## Acceptance Criteria
+- [ ] **A**: With a live server, `sqlcg reindex --dialect auto <repo>` sends a WriterRequest
+      whose `dialect` is the resolved dialect (never `"auto"`); same for `sqlcg index
+      --dialect auto`. Regression test asserts the on-wire payload.
+- [ ] **A**: Each of `reindex.py` / `index.py` has exactly one `if dialect == "auto"`
+      block, positioned before the socket-route call.
+- [ ] **B**: `init_backend(tmp)` followed by an escalating `index_repo` never opens,
+      writes, or locks the default `~/.sqlcg/graph.db`. Regression test proves it via a
+      raising-sentinel monkeypatch AND an mtime/absence check.
+- [ ] **B**: `_escalation_db_path` has exactly one grep-confirmed call site.
+- [ ] **B**: every `get_db_path()` call in `tools.py`/`writer.py`/`server.py` is either
+      the captured init source (tools.py:151), a display value, or threaded as a parameter
+      — the audit table holds.
+- [ ] **C**: `install-hooks` over a stale sqlcg-owned hook overwrites it and prints
+      `Upgraded git hook: .git/hooks/<name>`; over an identical hook it is silent and the
+      file is byte-unchanged; over a foreign (no-sentinel) hook it prints the unchanged
+      warning and leaves the file untouched.
+- [ ] **C**: the upgrade comparison is against the fully **rendered** template (binary
+      path embedded), not the raw template.
+- [ ] **D**: no hook template prints "server busy/locked"; all three print
+      `(reindex failed)`. `test_git_hooks_notify.py` updated accordingly.
+- [ ] Version stays 1.3.0 (no bump to `pyproject.toml` / `__init__.py` / `uv.lock`).
+- [ ] `git diff --stat` shows no change to `base.py` or to `indexer.py`'s hot-path methods.
+- [ ] `bash scripts/generate_cli_docs.sh` yields no `docs/cli.md` diff.
+- [ ] Full suite + ruff + pyright clean; the four invariant guards green.
+
+## Risks and Mitigations
+| Risk | Mitigation |
+|---|---|
+| Bug B fix mistaken for full §20.2 remediation | Plan explicitly scopes Bug B to "use init path + audit"; §20.2 lock/finally/stub work is out of scope (resolved decision D3). Acceptance criteria do not claim concurrency safety. |
+| Bug C upgrade compares raw template, not rendered → false "identical" or false "upgrade" | Step 3.2 + acceptance criterion mandate comparing the rendered `script`; binary path is embedded. |
+| Minor D text change unexpectedly fails existing hook-content tests | Step 4.4 updates `test_git_hooks_notify.py` deliberately; this is an intended text change, not a regression. |
+| Bug A: removing the second `auto` resolution leaves a stale path on a code path that bypasses routing | The route call returns early when handled; the direct path now relies on the hoisted resolution. Both reindex.py and index.py keep exactly one resolution that runs unconditionally before routing — verified the route call does not consume/clear `dialect`. |
+| Hoisting `get_dialect` in `reindex.py` uses the function-local import | `get_dialect` is already in the line-73 import tuple; the hoisted call sits after that import. Confirm the import precedes the new call site. |
+
+## Rollout / Rollback
+- All four fixes fold into PR #51 (no separate PR, no separate version). Per MEMORY
+  "Separate PRs, don't fold": this PR has **no reviews yet**, so folding follow-up fixes
+  for the same unreleased feature into it is appropriate (the rule targets folding new
+  work into an *already-reviewed* PR).
+- Rollback: revert the four commits; the v1.3.0 single-writer feature is unaffected
+  (these are additive corrections).
+
+### Resolved Decisions (2026-06-04 — shepherd, user-approved)
+All three pre-implementation questions are resolved. None blocks implementation.
+
+- **D1 — Version stays 1.3.0, no bump.** These fixes fold into the unreleased v1.3.0
+  PR #51 (no reviews yet). Do not touch `pyproject.toml` / `__init__.py` / `uv.lock`.
+  See Version note above.
+- **D2 — Bug C overwrite prints a line (not silent).** On the sentinel-present /
+  content-differs upgrade path, print `Upgraded git hook: .git/hooks/<name>`. Silent
+  upgrades of executable hooks are worse than one line of output. True idempotency
+  (identical rendered content) remains a silent skip.
+- **D3 — §20.2 escalation-architecture remediation stays OUT of scope.** This plan
+  covers bugs A-D only. The deeper `ARCHITECTURE_REVIEW.md` §20.2 work — (a) escalation
+  outside `backend_lock`, (b) RW-lock leak on the `index_repo` failure path (no
+  `finally`), (c) the dead `_set_backend_lock` / `_backend_lock` stub — remains a tracked
+  separate v1.3.x follow-up. The §20.2 cross-reference is retained in Non-Goals and
+  Design — Bug B so the linkage is not lost.
+
+## Plan Compliance — 2026-06-04 — PASS
+
+Compliance check run by architect-planner against commits `8e1e09b` (Bug A),
+`45643c8` (Bug B), `29d21ee` (Bug C + Minor D), with test setup in `1d4db7a`.
+Diff base `daa7389..HEAD`, excluding plan-docs commits (`5dce5d4`, `05ac62d`,
+`7936818`).
+
+**Verdict: PASS — all steps implemented as planned; no deviations.**
+
+### Step-by-step verification
+
+- **Step 1.1 / 1.2 (Bug A)** — PASS. `if dialect == "auto": dialect = get_dialect(path)`
+  hoisted above the route call in both files; the duplicate lower resolution removed.
+  Grep confirms exactly one `auto` block per file, positioned before the route call
+  (`reindex.py:84`, `index.py:116`).
+- **Step 2.1 (Bug B globals)** — PASS. `_init_db_path: str | None = None` added; set in
+  `init_backend` (added to `global`, assigned after `path = db_path or str(get_db_path())`);
+  reset to `None` in `shutdown_backend` (added to `global`).
+- **Step 2.2 (Bug B accessor)** — PASS. `_escalation_db_path()` defined once, returns
+  `_init_db_path or str(get_db_path())`; called at exactly one site (`tools.py:607` in
+  `index_repo`), replacing `str(get_db_path())`. Grep-confirmed single call site.
+- **Step 3.1 (Minor D)** — PASS. All three template occurrences reworded to
+  `(reindex failed)`; zero `server busy/locked` remain in `git.py`.
+- **Step 3.2 (Bug C)** — PASS. Silent-skip branch replaced: identical rendered `script`
+  → silent return; sentinel-present + differing content → `write_text(script)` +
+  `chmod(0o755)` + `Upgraded git hook:` print. Comparison is against the fully rendered
+  `script` (binary path embedded), per D2. Foreign-hook warning path unchanged.
+- **Steps 4.1–4.4 (tests)** — PASS. All acceptance tests assert observable output, not
+  weakened:
+  - Bug A: asserts exact on-wire `payload["dialect"]` (`postgres` / `snowflake`) — non-vacuous.
+  - Bug B: raising-sentinel monkeypatch AND default-DB mtime/absence check, with
+    `shutdown_backend()` teardown to reset the global (per plan).
+  - Bug C: three cases (stale→upgrade+print, identical→silent+byte-unchanged,
+    foreign→warning+unchanged) assert file content + captured stdout.
+  - Minor D: negative (`no "server busy/locked"`) + positive (`"(reindex failed)"`)
+    assertions added in both `test_BugC_hook_upgrade.py` and `test_git_hooks_notify.py`.
+- **Step 4.5 (verification)** — PASS:
+  - Full suite (`--ignore=tests/benchmarks`): 1026 passed, 7 skipped, 3 xfailed, 0 failures.
+  - 9 acceptance tests: all green (2 Bug A + 2 Bug B + 5 Bug C/D).
+  - ruff: clean. pyright: 0 errors / 0 warnings.
+  - `bash scripts/generate_cli_docs.sh` → `docs/cli.md`: no diff.
+  - `git diff --stat`: `base.py` and `indexer.py` UNTOUCHED.
+
+### Resolved-decision verification
+
+- **D1 (version stays 1.3.0)** — HONORED. No diff to `pyproject.toml`,
+  `src/sqlcg/__init__.py`, or `uv.lock`.
+- **D2 (Bug C prints, not silent; idempotency stays silent)** — HONORED. Upgrade prints
+  `Upgraded git hook:`; identical rendered content is a silent skip.
+- **D3 (§20.2 remediation out of scope)** — HONORED. Bug B fix changes only the escalation
+  *path*; it does not move escalation under `backend_lock`, does not add a `finally`-based
+  de-escalation, and does not wire or remove the dead `_set_backend_lock` /
+  `_backend_lock` stub (still present, untouched).
+
+### Scope
+
+In-scope files only: `git.py`, `index.py`, `reindex.py`, `tools.py`, and tests
+(`test_dialect_auto_resolution.py`, `test_BugB_escalation_uses_init_path.py`,
+`test_BugC_hook_upgrade.py`, `test_git_hooks_notify.py`). No out-of-scope source touched.

{sql_code_graph-1.2.2 → sql_code_graph-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-code-graph"
-version = "1.2.2"
+version = "1.3.0"
 description = "SQL code graph analyzer and lineage tracer"
 readme = "README.md"
 requires-python = ">=3.12"