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

{sql_code_graph-1.2.2 → sql_code_graph-1.4.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,271 @@ 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.
+
+---
+
+## Kuzu → DuckDB Migration — Architecture Review (2026-06-05, v1.4.0)
+
+Reviewed `git diff master..HEAD` on `feat/duckdb-migration` (9 commits, 91 files,
+~3885+/2782-). Plan: [`plan/feature_kuzu_to_duckdb_migration.md`](plan/feature_kuzu_to_duckdb_migration.md).
+
+### Conformance verdict: SHIP (1 documentation fix + 1 dead-code cleanup recommended)
+
+Phases 1–5 delivered the specified deliverables. All five Phase-5 exit gates are met:
+the live DWH acceptance gate (index 1,391 files ~2.5 min; reindex ×3 no crash; column
+trace) passed today; perf guards green; parity fixture committed; symbol-deletion clean.
+Two non-blocking gaps (see below).
+
+### Plan conformance — deliverable check
+
+| Phase | Status | Notes |
+|---|---|---|
+| 1 — backend skeleton + schema | **PASS** | [`duckdb_backend.py`](src/sqlcg/core/duckdb_backend.py): 7 node + 12 edge tables, src/dst indexes, idempotent `init_schema` in one txn, real reentrant `transaction()`. |
+| 2 — bulk-upsert sink | **PASS** | `upsert_nodes_bulk`/`upsert_edges_bulk` via `INSERT OR REPLACE … SELECT unnest(?)` — one `execute()` per label/rel per batch. `_flush_row_batch` per-batch shape unchanged ([`indexer.py:90`](src/sqlcg/indexer/indexer.py)). |
+| 3 — query port + parity | **PASS** | Recursive-CTE traversal with depth + cycle guard ([`analyze.py:38`](src/sqlcg/cli/commands/analyze.py)); kind-filter ported as `LEFT JOIN … WHERE kind IS NULL OR IN ('table','external')`; parity fixture + test committed ([`tests/integration/test_duckdb_parity.py`](tests/integration/test_duckdb_parity.py)). `execute_cypher`→`execute_sql` renamed ([`tools.py:1616`](src/sqlcg/server/tools.py)). |
+| 4 — rebuild-in-transaction | **PASS (with deviation, see Concurrency)** | Drain body `with backend.transaction(): clear_all_tables(); index_repo()` ([`writer.py:363`](src/sqlcg/server/writer.py)); escalation machinery deleted; single R/W handle. |
+| 5 — cutover + perf | **PASS** | `kuzu_backend.py`/`neo4j_backend.py` deleted; `KuzuConfig`→`DbConfig` ([`config.py:14`](src/sqlcg/core/config.py)); `buffer_pool` flags removed; `uninstall.py` uses `Path.unlink` + `.wal` ([`uninstall.py:113`](src/sqlcg/cli/commands/uninstall.py)); version 1.4.0; kuzu/neo4j deps dropped. |
+
+**Gaps (non-blocking):**
+1. **Dead Kuzu fallback in the happy path** — [`indexer.py:1393–1423`](src/sqlcg/indexer/indexer.py)
+   `_expand_star_sources` keeps a `# Fallback path for Kuzu legacy backend` branch with inline
+   Cypher `MERGE` strings. Kuzu is deleted, so this branch is unreachable dead code that still
+   references a removed backend's dialect. Plan Tier-1 said cutover removes Kuzu-only code; this
+   is a leftover. Recommend deleting the `else` branch and the `isinstance(db, DuckDBBackend)`
+   guard (the only backend is DuckDB). Not a ship blocker (the live path is the DuckDB branch),
+   but it is exactly the "TODO/stub in the success path" class CLAUDE.md warns against.
+2. **`tests/e2e/test_dwh_e2e.py`** migrated on disk but never committed (correct per MEMORY:
+   feedback_dwh_e2e — gitignored). The double-reindex/perf acceptance was run manually today;
+   there is no committed CI guard for it. Accept (matches existing project policy).
+
+### Performance invariants — pass/fail (CLAUDE.md table)
+
+All guard tests green: `test_perf_scaling_guard`, `test_upsert_batch_invariant`,
+`test_bulk_upsert_invariant`, `test_T09_01_qualify_once` (11 passed).
+
+| Invariant | Verdict | Evidence |
+|---|---|---|
+| `qualify`/`build_scope` module-level import | **PASS** | `base.py` untouched (parser-side, backend-agnostic). |
+| `exp.expand()` file-level sources + `dependency_filter` | **PASS** | parser-side, untouched. |
+| `body_scope` built once per statement | **PASS** | untouched. |
+| Pure-literal skip | **PASS** | untouched. |
+| No `sources=` when scope present / `copy=False`+`trim_selects=False` | **PASS** | untouched. |
+| INSERT body copied once | **PASS** | untouched. |
+| `_upsert_parsed_file` uses bulk (not per-row) | **PASS** | sink re-pointed to `upsert_*_bulk`; no per-row path in flush. |
+| `_flush_row_batch` once-per-batch (not per-file) | **PASS** | [`indexer.py:162–176`](src/sqlcg/indexer/indexer.py): exactly 10 bulk calls per batch; DuckDB `upsert_*_bulk` issues **one** `execute()` per call ([`duckdb_backend.py:412`,`456`](src/sqlcg/core/duckdb_backend.py)). |
+
+**No reintroduced O(N²):** the bulk sink uses array-parameter `unnest`, one round-trip per
+label/rel. Read CTEs carry `WHERE reach.depth < d` + `NOT key = ANY(reach.path)` cycle guard
+([`analyze.py:57–58`](src/sqlcg/cli/commands/analyze.py)). `delete_nodes_for_file` is
+set-based DELETEs, no per-row loop. Edge tables indexed on both `src_key` and `dst_key`.
+One watch item: `array_append`/`= ANY(path)` cycle guard is O(path-length) per row, acceptable
+at depth≤100 but is the only place traversal cost grows with path depth — bounded by the depth cap.
+
+### Concurrency model — assessment
+
+**Reentrant `transaction()` ([`duckdb_backend.py:723`](src/sqlcg/core/duckdb_backend.py)):
+correct.** Depth-counted; only the outermost level emits BEGIN/COMMIT/ROLLBACK; nested calls
+join and re-raise so a failure anywhere rolls back the whole rebuild. This lets the drain wrap
+`clear_all_tables()` + `index_repo()` (which opens its own per-batch transactions) in one atomic
+unit. Verified by `test_mvcc_rebuild.py` (3 passed) and the C6 unit test.
+
+**`clear_all_tables()` preserving `SchemaVersion`: right call.** It truncates all node/edge
+tables but leaves the `SchemaVersion` row so the schema-gate survives a rebuild and
+`indexed_sha` is re-stamped by the indexer inside the same transaction
+([`indexer.py:504`](src/sqlcg/indexer/indexer.py)) — the SHA flips atomically with the graph.
+
+**DEVIATION — "readers never block" is not what shipped (but what shipped is SAFE).**
+The plan/design (§Concurrency, C3) sells DuckDB MVCC: readers on separate cursors see the OLD
+snapshot during a write txn and flip on COMMIT, so reads never block. The implementation does
+**not** use `con.cursor()` per read — `run_read` executes on the **single shared `self._conn`**
+([`duckdb_backend.py:476`](src/sqlcg/core/duckdb_backend.py)), and the server serializes every
+read and the drain through one `anyio` `backend_lock` ([`server.py:347`](src/sqlcg/server/server.py),
+[`writer.py:330`](src/sqlcg/server/writer.py)). Net effect: a `query` arriving mid-rebuild
+**waits** for the rebuild to finish rather than being served the old snapshot. This is *safe*
+(no torn read — the lock prevents a read on a connection with an open uncommitted BEGIN), but
+it forfeits the headline MVCC non-blocking-read benefit. For the full-rebuild path that holds
+the lock for the entire ~2.5 min index, **reads are unavailable for the rebuild duration.**
+Action: fix the plan/docstring claim, OR (better, follow-up) serve reads from `self._conn.cursor()`
+and drop the read side of `backend_lock` to realize the promised non-blocking reads.
+
+**Long-transaction risk in the drain body (lock duration / memory / partial-failure):**
+- *Lock duration:* the full rebuild holds both the OS-level DuckDB file lock and the in-process
+  `backend_lock` for the entire index (~2.5 min on the DWH). Cross-process this is fine (single
+  writer by design); in-process it blocks reads (above). Acceptable for a full rebuild; the real
+  fix is incremental reindex (Option 2, explicitly deferred).
+- *Memory:* one transaction spanning `clear_all_tables()` + all batch inserts means DuckDB holds
+  the rebuild's undo/WAL state until COMMIT. The plan's batch loop still runs, but per-batch
+  transactions are **subsumed** into the outer txn (reentrancy makes them no-ops), so there is
+  **no intermediate commit** — the OOM-prevention intent of `batch_size` is about parse working-set,
+  not write durability, so this is consistent with CLAUDE.md, but worth noting: write-side memory
+  is now one-transaction-wide, not one-batch-wide. The DWH (47k columns, 45k edges) committed in
+  ~2.5 min with no OOM, so empirically fine at current scale; flag for the 1,600-file ceiling.
+- *Partial-failure:* correct — a mid-rebuild raise rolls back to the prior graph (C6, tested).
+  Better than the old swap's corruption window.
+
+### Backend abstraction — assessment (no action requested)
+
+With kuzu/neo4j deleted, `GraphBackend` is a **single-impl ABC** — it now adds indirection
+without polymorphism. It still earns partial keep: (a) tests use an in-memory `:memory:`
+DuckDBBackend through the same interface; (b) the documented v2 roadmap (Snowflake
+ACCESS_HISTORY as a second lineage source) may want a second backend. But several smells:
+- ABC docstrings still say "Cypher for KùzuDB/Neo4j" ([`graph_db.py:121,133`](src/sqlcg/core/graph_db.py))
+  and "skipped by KuzuDB's MERGE semantics" (line 105) — stale, misleading now.
+- `clear_all_tables()` on the ABC with a `NotImplementedError` default ([`graph_db.py:248`](src/sqlcg/core/graph_db.py))
+  is the wrong shape now that only DuckDB implements it: a `NotImplementedError`-default method on
+  an ABC is a code smell (it is neither abstract-required nor universally provided). With one impl,
+  it should either be a plain method on `DuckDBBackend` (not on the ABC) or a proper `@abstractmethod`.
+  Recommend: move it off the ABC, or make it abstract. Low priority — cosmetic, single caller.
+- `transaction()`'s ABC no-op default that "logs a warning" is now dead (only DuckDB, which
+  overrides). Harmless.
+
+**Recommendation (do not act now):** keep the ABC for the v2 second-source path, but schedule a
+docstring de-Cypher pass and relocate `clear_all_tables` off the ABC. If v2 ACCESS_HISTORY is
+shelved, collapse the ABC into `DuckDBBackend` directly.
+
+### Release risk register for 1.4.0 (ranked likelihood × impact)
+
+1. **Reads blocked for the full ~2.5 min rebuild duration (HIGH likelihood × MED impact).**
+   The serialized single-connection model means MCP/CLI reads hang while a full `index`/`reindex`
+   drains. On the DWH that is ~2.5 min of read unavailability per rebuild. Users expecting the
+   plan's "non-blocking reads" will see hangs. Mitigation: cursor-per-read follow-up; for now,
+   document the behavior and rely on rebuild infrequency.
+2. **Dead Kuzu fallback branch ([`indexer.py:1393`](src/sqlcg/indexer/indexer.py)) (MED × LOW).**
+   Unreachable but references a deleted backend; a future reader may mistake it for a live path,
+   and it carries Cypher that no longer has an engine. Delete before/just after release.
+3. **One-transaction-wide write memory at the 1,600-file ceiling (LOW × MED).**
+   Proven fine at DWH scale (1,391 files); the CLAUDE.md target tops out at ~1,600. The whole
+   rebuild is one DuckDB transaction (per-batch commits subsumed), so peak WAL/undo is the full
+   graph. Measure headroom at 1,600 before declaring the perf budget closed.
+4. **No committed CI guard for double-reindex / perf (LOW × MED).**
+   The headline acceptance (double-reindex no-crash + lineage parity) was validated manually via
+   the gitignored e2e test. A regression would not be caught in CI. Accept per project policy, but
+   the committed `test_mvcc_rebuild.py` + parity fixture partially cover the rebuild path.
+5. **Stale "Cypher/Kuzu" references in docstrings/comments across server + indexer (LOW × LOW).**
+   Cosmetic; misleads future maintainers about the engine. Sweep in a docs pass.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.2.2
+Version: 1.4.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
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
-Requires-Dist: kuzu==0.11.3
+Requires-Dist: duckdb<2.0,>=1.0.0
 Requires-Dist: mcp<2.0,>=1.27.0
 Requires-Dist: pathspec>=0.12.1
 Requires-Dist: pydantic>=2.0
@@ -30,8 +30,6 @@ Requires-Dist: typer>=0.9.0
 Requires-Dist: watchdog>=3.0.0
 Provides-Extra: dbt
 Requires-Dist: dbt-core>=1.7; extra == 'dbt'
-Provides-Extra: neo4j
-Requires-Dist: neo4j>=5.15.0; extra == 'neo4j'
 Provides-Extra: snowflake
 Requires-Dist: acryl-datahub<0.15.0,>=0.14.0; extra == 'snowflake'
 Description-Content-Type: text/markdown

{sql_code_graph-1.2.2 → sql_code_graph-1.4.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".
 
@@ -72,14 +79,14 @@ 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 | 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. |
+| --batch-size | INTEGER | No | No | 50 | Files per DuckDB 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`
 
@@ -211,7 +218,7 @@ sqlcg uninstall [OPTIONS]
 Uninstall sqlcg from Claude Code and optionally clean up resources.
 
 Step 1: Remove MCP registration from ~/.claude/settings.json
-Step 2: Optionally delete the KùzuDB graph database
+Step 2: Optionally delete the DuckDB graph database
 Step 3: Remove git hook sentinel block from .git/hooks/post-checkout
 Step 4: Remove sqlcg skill directory from ~/.claude/skills/sqlcg/ and
         <repo>/.claude/skills/sqlcg/
@@ -267,7 +274,7 @@ Initialise the graph database (idempotent).
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| --buffer-pool-size | INTEGER | No | No | 0 | KuzuDB buffer pool size in MB (0 = default). Set to 256-512 on memory-constrained machines. |
+| _none_ |  |  |  |  |  |
 
 ## `sqlcg db reset`
 
@@ -441,13 +448,6 @@ 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.
-
 ### Options
 
 | Option | Type | Required | Repeatable | Default | Description |
@@ -548,7 +548,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: