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

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

@@ -478,7 +478,15 @@ both concrete backends override it — the blueprint does not enforce this.
 Risk: HIGH. A failed re-index leaves orphaned graph nodes that produce incorrect
 lineage results until the next full re-index.
 
-### 3.2 [HIGH] `CrossFileAggregator.resolve_pass2` re-opens files without error handling
+### 3.2 ~~[HIGH]~~ **RESOLVED (v1.2.1)** `CrossFileAggregator.resolve_pass2` re-opens files without error handling
+
+**Resolution (2026-06-02, v1.2.1, PR #48):** `resolve_pass2` was deleted entirely. It had
+zero production call sites — the production pass-2 path in `index_repo` reimplements the
+dep-filter + reparse logic inline (worker calls `parse_file(..., dependency_filter=...)`
+in [`pool.py`](src/sqlcg/indexer/pool.py)), and that path already handles file-read errors
+defensively. The dead method (and the four tests that exercised it) were the same
+test-measures-a-dead-path blind-spot class as #40. Tests realigned to drive `index_repo`
+end-to-end. See [`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) Phase 5.
 
 ```python
 def resolve_pass2(self, parser, parsed):
@@ -2947,4 +2955,324 @@ editor owns the stdio process lifecycle and v1.1 has no launcher to re-spawn it
   owner-only, but any same-uid local process can send `stop`/`reindex`).
 - **Freshness on every tool result by default** — v1.1 ships it gated/off to
   protect hot-path latency; default-on pending an overhead measurement.
+
+## 18. v1.2.1 — Lineage recall guards + canonical INSERT target + CTE filter fixes
+
+Review date: 2026-06-02 · Reconciled by: architect-planner · Branch:
+`feat/v1.2.1-bugfix` · PR #48 · Verdict: **PLAN-COMPLIANT (PASS)**
+
+> **Bundled release note (2026-06-02):** the v1.2.1 bugfix scope (this section) and the
+> downstream-sink `file:line` fix (§19.2) ship as a **single `v1.2.2` release** — the
+> lower `v1.2.1` tag is skipped (precedent: v1.1.2→v1.1.3). Both change sets live on
+> `feat/v1.2.1-bugfix` (PR #48, fast-forwarded to `b5bf7a3`); version is `1.2.2`. The
+> combined plan-compliance verdict (PASS, both scopes) is recorded in
+> [`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) → "Bundled v1.2.2 release compliance".
+
+Patch release fixing the residual user-facing lineage defects (#44 canonical-name
+split, #45 `file:line=?` + `cte_*` leak), repairing the v1.2.0 read-proxy filter
+regression (the #39 read-half), deleting the dead `resolve_pass2` (resolves §3.2),
+and landing the #40 user-surface regression-guard suite. Plan:
+[`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) (full phase-by-phase compliance log appended there).
+
+### 18.1 #44 — canonical INSERT-target resolution
+
+A new `CrossFileAggregator.canonical_by_bare` index (bare name → sole DDL `full_id`)
+plus `_ambiguous_bare` (names defined in >1 schema, never rewritten) is built in
+`register_pass1` from DDL tables only. It is threaded `index_repo` →
+`_upsert_file_batch` → `_build_file_rows`, where an unqualified / non-DDL INSERT
+target whose bare name resolves to a sole DDL canonical is rewritten to share that
+node's identity (`qualified` == DDL `full_id`, all fields derived from the canonical),
+keeping `kind:"table"`. The fix lands in the node-emission loop, **not** the deleted
+`resolve_pass2` and **not** the per-column lineage hot path — pure row-dict mutation,
+no new `execute()`. Degrades to a no-op when `canonical_by_bare is None`
+(single-file `reindex_file` / `resync_changed` paths) — known limitation, re-index is
+the migration path per CLAUDE.md.
+
+### 18.2 #45 — `file:line` recall + structural `cte_*` suppression
+
+- **#45.1**: `analyze upstream/downstream` now bind location from the source's
+  *outgoing* `COLUMN_LINEAGE` edge and aggregate `WITH … min(start_line), min(file_path)`
+  **before** `LIMIT 100`, so multi-hop sources carry a real `file:line` and the limit
+  counts distinct sources, not edge-fanout rows.
+- **#45.2**: chosen mechanism is **graph-truth, not a name heuristic** — unresolved
+  synthetic INSERT targets are emitted `kind:"derived"` (the #44 emission change), and
+  the restored `kind IN ['table','external']` read filter excludes them. No name-prefix
+  belt was needed.
+
+### 18.3 Two implementation invariants discovered during the fix
+
+Both are now load-bearing; recorded so a future refactor does not silently undo them.
+
+1. **KuzuDB: a `WHERE` clause inside `OPTIONAL MATCH` filters the match attempt, not
+   the surrounding row.** To filter rows on an optionally-matched node's property, an
+   explicit `WITH <carried>, t WHERE …` must follow. `analyze._kind_filter` uses this
+   form (`OPTIONAL MATCH (t:SqlTable {…}) WITH <alias>, t WHERE t.kind IS NULL OR …`).
+   The `IS NULL` branch is intentional: it keeps node-less physical sources (the #39
+   tail) while CTE/derived intermediates (`kind='cte'`/`'derived'`) are excluded.
+   Guarded by TC1/TC4 in [`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py).
+2. **`_flush_row_batch` dedup must prefer structural kinds over the default `'table'`.**
+   A CTE alias is emitted twice in a batch — first `kind='table'` (incidental source
+   reference) then `kind='cte'` (CTE destination). The pre-existing first-seen-wins
+   dedup kept the wrong one, defeating #45.2. New Rule 2: `{'cte','derived','external'}`
+   beats default `'table'` (Rule 1 — DDL provenance via `defined_in_file` — still takes
+   precedence). This logic lives in the documented `_flush_row_batch` perf hot path but
+   is pure dict comparison in the existing dedup loop — no change to flush cardinality,
+   batch/scaling guards stay green (CLAUDE.md performance invariants intact).
+
+### 18.4 Resolved / out-of-scope
+
+- **§3.2 `resolve_pass2`** — RESOLVED (deleted; see §3.2 update).
+- **Residual #38 (UNION-ALL sibling CTEs)** — already fixed in 1.1.3; live DWH
+  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** — **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)
+
+Source: live verification of the v1.2.1 fixes against the full DWH corpus
+(`../dwh`, 1,335 SQL files, clean index ~1:56). **The v1.2.1 fixes themselves
+PASSED** — both findings below are residual / design-limit behaviour surfaced by
+the run, not regressions in PR #48. Corpus graph snapshot (kind-typed `SqlTable`):
+2,222 `table` / 383 `cte` / 272 `derived`.
+
+### 19.1 [KEEP — LOW] Residual scratch-object leak into the default `analyze` surface
+
+**Measurement.** The #45.2 fix essentially closed the `cte_` leak it targeted:
+of nodes still typed `kind='table'`, only 3 carry a `cte_` prefix (vs 383 now
+correctly `kind='cte'`). The broader leak persists: **495 of 2,222 `table`-kind
+nodes (~22%) carry scratch-object name prefixes** — 471 `tmp_*`, 21 `temp_*`,
+3 `cte_*` — plus ~575 unqualified single-token nodes (a mix of real bare tables
+and CTE aliases). These surface in default (filtered) `analyze` output because the
+filter is correctly kind-based (graph-truth) but these aliases were never classified
+`cte`/`derived` at parse/aggregation time. This is the known #38 islands residual
+(s18.4 / `47 cte_insert islands`); the leak is now `tmp_*`-dominated, not
+`cte_*`-dominated. See memory `project_issue38_cte_filter_regression`.
+
+**Decision: KEEP as a future ticket, LOW priority.** Rationale tied to existing
+decisions:
+- The standing **"no name-prefix filtering"** decision (s18.2; CLAUDE.md) is correct
+  and stays. The fix therefore **cannot** live in the filter — it must happen at
+  **classification time** in the aggregator/parser, exactly like the #44 synthetic
+  INSERT-target → `kind='derived'` emission change (s18.1). A `CREATE [OR REPLACE]
+  TEMP/TRANSIENT TABLE tmp_x AS SELECT …` whose target is a scratch object should be
+  emitted `kind='derived'` at `_build_file_rows` time, the same place #44 already
+  rewrites node identity. 492/495 of the leak (`tmp_*`/`temp_*`) are this CTAS-into-
+  scratch shape — addressable by classifying on the parsed CTAS-into-temp statement
+  kind (DDL-derived structural truth), **not** on the name prefix.
+- **Non-goal for the ticket:** the ~575 unqualified single-token nodes. They are a
+  genuine mix of real bare tables and CTE aliases; auto-classifying them risks
+  hiding real physical tables from the default surface (a false-negative worse than
+  the current cosmetic leak). They stay `kind='table'` until a structural signal
+  (CTE membership, CTAS target) is available — never a name guess.
+
+**Risk/reward.** Reward: cleaner default `analyze` surface, ~22% fewer scratch
+intermediates leaking; closes the visible tail of #38. Risk: medium — must classify
+on parsed statement structure (TEMP/TRANSIENT CTAS target), and must not reclassify
+a real `tmp_`-named physical table that is read by a non-CTAS statement; needs a guard
+asserting a real table named `tmp_*` is still surfaced. Effort: medium (one emission
+site, reuses #44 plumbing, plus a behavioural guard). Below the open HIGH §3.x items
+and Finding 19.2 in the ranking. Recorded here; no plan stub drafted yet (pull when
+a lineage-coverage sprint next touches `_build_file_rows`).
+
+### 19.2 [RESOLVED in v1.2.2] `file:line='?'` on downstream terminal sinks
+
+**Measurement.** The #45.1 fix rebinds a result's location from its **outgoing**
+`COLUMN_LINEAGE` edge ("where is this column used as a source"). For *downstream*
+traces this means terminal sinks render `?`: a sink has no outgoing edge, so
+`min(q.start_line)`/`min(q.file_path)` are NULL. Corpus measurement: of 36,892
+distinct columns reachable as a downstream result, **29,827 (81%) are sinks → render
+`file:line='?'`**. The fix populates only the locatable 19%. Upstream is unaffected
+(an upstream source legitimately has an outgoing edge). The TC6 guard asserts non-null
+`file:line` on one specific *located* case, so it passed despite the 81%.
+
+**Decision: KEEP — pick up next.** This is a genuine bug, **not** deliberate
+semantics. Analysis tied to #45.1's own intent:
+- #45.1 chose the outgoing edge so a *source*'s location reads as "where it is
+  produced/consumed as a source" — correct for the **upstream** direction. The same
+  pattern was copied verbatim into the **downstream** query
+  ([`analyze.py`](src/sqlcg/cli/commands/analyze.py) lines 134–137, fallback 146–149):
+  `OPTIONAL MATCH (dst)-[dstedge]->()`. For a downstream *result*, the natural,
+  user-meaningful location is the query that **produced** the column — i.e. the
+  **incoming** edge `()-[dstedge]->(dst)`, not the outgoing one.
+- **Key lever (confirmed in code):** every one of the 36,892 columns has an incoming
+  `COLUMN_LINEAGE` edge by definition — that is how it became a downstream result —
+  and that producing query carries a real `start_line`/`file_path`. Flipping the two
+  downstream `OPTIONAL MATCH` arrows from `(dst)-[dstedge]->()` to
+  `()-[dstedge]->(dst)` binds location from the producing query, turning ~81% of `?`
+  rows into a real `file:line`. Upstream stays on the outgoing edge unchanged.
+
+**Risk/reward.** Reward: HIGH — ~81% of downstream result rows flip from `?` to a
+real `file:line` on a corpus this shape. Effort: LOW — a ~2-line arrow flip in two
+downstream queries (primary + bare-name fallback), no schema/index/perf change, no
+parser change. Risk: LOW and bounded — only the downstream direction; upstream and
+the kind-filter (s18.3) untouched. The one trap: TC6 passes today on a located case,
+so it does **not** catch the regression — the ticket must add a guard asserting a
+**terminal sink** (no outgoing edge) renders a real `file:line`, not `?`.
+Plan stub drafted: [`fix_downstream_sink_location.md`](plan/fix_downstream_sink_location.md).
+Suggested release: patch (1.2.2) or fold into the next lineage minor.
+
+**RESOLVED — shipped in v1.2.2 (bundled with v1.2.1; see §18 bundled-release note).**
+Both downstream queries in [`analyze.py`](src/sqlcg/cli/commands/analyze.py) (primary
+L134, bare-name fallback L146) now bind location from the **incoming**
+`()-[dstedge:COLUMN_LINEAGE]->(dst)` edge — the producing query — so terminal sinks
+carry a real `file:line`. Upstream (L77/L89) keeps the outgoing-edge binding, unchanged.
+Guarded by the TC6b terminal-sink test in
+[`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py),
+demonstrably RED on master before the fix.
+
+### 19.3 Cross-finding note
+
+Both findings share the v1.2.1 root theme: the *graph store* is correct (edges intact,
+kinds mostly right); the defects live in the **graph→user presentation layer**
+(filter classification for 19.1, location binding for 19.2) — the same blind-spot
+class as #38/#40 where anchors traversing raw edges pass while the user-facing query
+path is wrong. Any guard for either must drive the **user-facing `analyze` path**,
+not raw `COLUMN_LINEAGE` traversal.
+
+### 19.4 [KEEP — LOW] TC6b guard reconstructs the query instead of running `analyze downstream`
+
+Raised by the plan-reviewer on the §19.2 sink fix. The TC6b terminal-sink guard's helper
+`_downstream_filtered_query()` in
+[`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py)
+**reconstructs the downstream Cypher query string** rather than invoking
+`analyze.downstream()` end-to-end. It therefore can drift from the production query if
+[`analyze.py`](src/sqlcg/cli/commands/analyze.py) changes and the helper is not updated in
+lockstep — exactly the §19.3 blind-spot (a guard not driving the true user-facing path).
+The fix held for v1.2.2 (the helper mirrors the shipped query), but the divergence risk is
+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.1.3 → sql_code_graph-1.3.0}/CLAUDE.md

@@ -59,6 +59,27 @@ This project uses `uv`. Never activate a virtualenv manually, never use `pip`, n
 | Lint | `rtk uv run ruff check src tests` |
 | Format | `uv run ruff format src tests` |
 
+## Releasing (version bump + tag)
+
+Every feature/fix PR that ships bumps the version; after it merges to `master`, tag the release.
+Do **all** of this — the tag is the step most easily forgotten.
+
+1. **Bump the version** (in the feature branch, before the PR merges):
+   - [`pyproject.toml`](pyproject.toml) `version = "X.Y.Z"`
+   - [`src/sqlcg/__init__.py`](src/sqlcg/__init__.py) `__version__ = "X.Y.Z"`
+   - `uv lock` (refreshes the lockfile's own version entry)
+   - **SemVer**: new capability/surface → **minor** (`1.1.x` → `1.2.0`); bug fix only → **patch**.
+     No backward-compat shims, so an additive feature is still minor (not major) when nothing breaks.
+2. **Merge the PR to `master`** (squash or `--merge` per the existing `Merge #NN` history).
+3. **Tag the merge commit on `master`** — **annotated**, `v`-prefixed, message `vX.Y.Z — <one-line summary>`:
+   ```bash
+   git checkout master && git pull --ff-only origin master
+   git tag -a vX.Y.Z -m "vX.Y.Z — <summary>" <merge-commit-sha>
+   git push origin vX.Y.Z
+   ```
+   All existing tags are annotated and look like `v1.1.3` (never bare `1.1.3`). Confirm with
+   `git tag -l --format='%(contents)' vX.Y.Z` and verify it points at the master merge commit.
+
 ## Target scale — serve both ends of the spectrum
 
 This project must work correctly and comfortably at two very different scales:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.1.3
+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
@@ -267,6 +267,16 @@ sqlcg mcp restart                      # stop the server (client must respawn it
 sqlcg version                          # show installed version
 ```
 
+### Reads while the server is running (v1.2.0)
+
+KuzuDB allows a single writer, so while the MCP server is live it holds the
+database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+`gain`) automatically route their query through the running server over its
+control socket and return rows as usual — no flag, no config. When no server is
+running they open the database directly, exactly as before. If the server is
+mid-reindex the read waits for it to finish rather than failing with
+"Database is locked".
+
 ## Supported dialects
 
 sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot), so other dialects

{sql_code_graph-1.1.3 → sql_code_graph-1.3.0}/README.md

@@ -229,6 +229,16 @@ sqlcg mcp restart                      # stop the server (client must respawn it
 sqlcg version                          # show installed version
 ```
 
+### Reads while the server is running (v1.2.0)
+
+KuzuDB allows a single writer, so while the MCP server is live it holds the
+database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+`gain`) automatically route their query through the running server over its
+control socket and return rows as usual — no flag, no config. When no server is
+running they open the database directly, exactly as before. If the server is
+mid-reindex the read waits for it to finish rather than failing with
+"Database is locked".
+
 ## Supported dialects
 
 sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot), so other dialects

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

@@ -17,7 +17,7 @@ bash scripts/generate_cli_docs.sh
 | `watch` | Watch a directory and re-index on SQL file changes. |
 | `gain` | Show metrics and feedback analytics. |
 | `report` | Generate a metrics report with FP clusters and parse error patterns. |
-| `install` | Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json). |
+| `install` | Register sqlcg as an MCP server in Claude Code. |
 | `uninstall` | Uninstall sqlcg from Claude Code and optionally clean up resources. |
 | `version` | Show version. |
 | `db` | Database management commands |
@@ -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".
 
@@ -71,13 +78,16 @@ Schema aliases (staging schema → canonical schema) can be configured in
 | --- | --- | --- | --- | --- | --- |
 | --dialect, -d | TEXT | No | No |  | SQL dialect (or 'auto' to read from .sqlcg.toml) |
 | --dbt-manifest | PATH | No | No |  | Path to dbt manifest |
-| --timeout-per-file | INTEGER | No | No | 5 | Timeout per file in seconds |
+| --timeout-per-file | INTEGER | No | No | 10 | Timeout per file in seconds |
 | --buffer-pool-size | INTEGER | No | No | 0 | KuzuDB buffer pool size in MB (0 = default). Set to 256-512 on memory-constrained machines. |
 | --batch-size | INTEGER | No | No | 50 | Files per KuzuDB transaction in the upsert pass. Default 50 balances commit-overhead reduction (vs. legacy per-file commits) against per-batch memory cost. Lower values are safer for memory-constrained machines; higher values give marginal speedup at the cost of larger working sets. Set to 1 to reproduce legacy per-file commit behaviour. |
 | --no-ddl | BOOLEAN | No | No | False | Skip table-node upserts for DDL-only files |
 | --quiet, -q | BOOLEAN | No | No | False | Suppress summary console output |
+| --verbose, -v | BOOLEAN | No | No | False | Print parse warnings to stderr instead of log file |
 | --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`
 
@@ -106,7 +116,8 @@ build — run 'sqlcg db reset && sqlcg db init && sqlcg index <path>' to re-init
 | --dialect, -d | TEXT | No | No |  | SQL dialect (or 'auto' to read from .sqlcg.toml) |
 | --quiet, -q | BOOLEAN | No | No | False | Suppress summary output |
 | --batch-size | INTEGER | No | No | 50 | Files per KuzuDB transaction (same default as index command) |
-| --timeout-per-file | INTEGER | No | No | 5 | Per-file parse timeout in seconds |
+| --timeout-per-file | INTEGER | No | No | 10 | Per-file parse timeout in seconds |
+| --notify | BOOLEAN | No | No | False | If a server is live on this DB, route the reindex through the server (avoids lock contention). Falls back to direct write if no server is found. |
 
 ## `sqlcg watch`
 
@@ -181,7 +192,10 @@ If no metrics database exists, prints a message and exits 0.
 sqlcg install [OPTIONS]
 ```
 
-Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json).
+Register sqlcg as an MCP server in Claude Code.
+
+Runs ``claude mcp add -s user sql-code-graph <cmd> <args>`` when the
+``claude`` CLI is on PATH; otherwise writes ~/.claude.json directly.
 
 Also provisions a Claude skill file (SKILL.md) at the chosen location.
 Pass --scope project or --scope global to specify where the skill is written.
@@ -333,7 +347,7 @@ Find a table by name.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg find column`
 
@@ -347,7 +361,7 @@ Find a column by table.column reference.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg find pattern`
 
@@ -394,6 +408,8 @@ Trace upstream column lineage.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --depth | INTEGER | No | No | 5 | Maximum traversal depth |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
+| --include-intermediate | BOOLEAN | No | No | False | Include CTE/derived intermediate nodes |
 
 ## `sqlcg analyze downstream`
 
@@ -408,6 +424,8 @@ Trace downstream column lineage.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --depth | INTEGER | No | No | 5 | Maximum traversal depth |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
+| --include-intermediate | BOOLEAN | No | No | False | Include CTE/derived intermediate nodes |
 
 ## `sqlcg analyze impact`
 
@@ -421,7 +439,7 @@ Show all queries impacted by a table.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg analyze failures`
 
@@ -431,6 +449,9 @@ sqlcg analyze failures [OPTIONS]
 
 List files that failed to parse, with their dominant cause (E-code bucket).
 
+Valid --cause buckets (from highest to lowest severity):
+timeout, E8, E3, E2, E5, E1, qualify_failed, func_fallback, pure_ddl_skip.
+
 Requires a graph indexed with sqlcg >= v3 (schema version 3). Re-index
 with 'sqlcg db reset && sqlcg index <path>' if the graph was built with
 an earlier version.
@@ -439,7 +460,7 @@ an earlier version.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| --cause | TEXT | No | No |  | Filter by E-code bucket (e.g. E5, timeout) |
+| --cause | TEXT | No | No |  | Filter by E-code bucket. Valid values: timeout, E8, E3, E2, E5, E1, qualify_failed, func_fallback, pure_ddl_skip |
 | --limit | INTEGER | No | No | 100 | Maximum rows to return |
 
 ## `sqlcg analyze unused`
@@ -455,6 +476,7 @@ Find tables with no query references.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --threshold | INTEGER | No | No | 0 | Minimum reference count threshold |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg mcp`
 
@@ -471,6 +493,9 @@ MCP server commands
 | `setup` | Print or write MCP server config JSON. |
 | `start` | Start the MCP server. |
 | `best-practices` | Print MCP tool best-practices (the fact/heuristic boundary). |
+| `status` | Print server status JSON (connects to control socket). |
+| `stop` | Stop the running MCP server gracefully. |
+| `restart` | Stop the server. The client (editor) must respawn. |
 
 ## `sqlcg mcp setup`
 
@@ -480,6 +505,11 @@ sqlcg mcp setup [OPTIONS]
 
 Print or write MCP server config JSON.
 
+--print (default): print the JSON snippet for manual insertion.
+--write: write to ~/.claude.json under mcpServers.user (the correct path
+         for Claude Code — not settings.json, which Claude Code does not read
+         for MCP servers).
+
 ### Options
 
 | Option | Type | Required | Repeatable | Default | Description |
@@ -517,6 +547,77 @@ that have not installed the skill.
 | --- | --- | --- | --- | --- | --- |
 | _none_ |  |  |  |  |  |
 
+## `sqlcg mcp status`
+
+```bash
+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, 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:
+{"running": true, "degraded": "socket unavailable", ...}.
+
+R3 (stale socket): if the socket file exists but the server is not
+responding (ConnectionRefusedError / FileNotFoundError), falls through
+to the PID-file probe — never hangs or errors on a dead socket.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
+## `sqlcg mcp stop`
+
+```bash
+sqlcg mcp stop [OPTIONS]
+```
+
+Stop the running MCP server gracefully.
+
+Sends a ``stop`` op via the control socket; waits up to 5 s for the
+socket file to disappear (confirming clean exit).  Falls back to SIGTERM
+on the PID-file PID if the socket is unavailable.
+
+R3 (stale socket): ``ConnectionRefusedError`` / ``FileNotFoundError`` are
+caught — never hangs on a dead socket.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
+## `sqlcg mcp restart`
+
+```bash
+sqlcg mcp restart [OPTIONS]
+```
+
+Stop the server. The client (editor) must respawn.
+
+v1.1 cannot re-parent an editor-spawned stdio process.  This command
+stops the current server and prints guidance for the user to restart
+the MCP server via their editor's MCP configuration.
+
+True auto-restart (re-parenting stdio) is deferred to v1.2.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
 ## `sqlcg git`
 
 ```bash
@@ -542,6 +643,8 @@ Install git hooks for sqlcg integration.
 Writes a post-checkout hook that triggers incremental resync after branch switches
 and a post-merge hook that triggers resync after pulls/merges.
 Idempotent: running multiple times produces one hook entry per hook.
+The hooks embed the absolute path of the installing sqlcg binary so version skew
+between the installed binary and the hook command is avoided.
 
 ### Options