feat: US-012 - Document the SQLite read-mode write-mode invariant

Author: NathanFlurry

CLAUDE.md

@@ -109,6 +109,7 @@ docker-compose up -d
 - SQLite VFS file handles must enforce their reader or writer role; reader-owned handles fail closed on mutating callbacks.
 - Native SQLite single-statement work should route through the native execute path; keep `exec` as the multi-statement compatibility path.
 - Native SQLite manual transactions keep an idle writer open until autocommit returns; route subsequent work through the writer instead of reader classification.
+- Native SQLite read mode may hold multiple read-only connections, while write mode must hold exactly one writable connection and no readers; TypeScript must not be the routing policy boundary.
 - For NAPI bridge wiring (TSF callback layout, cancellation tokens, `#[napi(object)]` rules), see `docs-internal/engine/napi-bridge.md`.
 
 ## Agent Working Directory

docs-internal/engine/SQLITE_OPTIMIZATIONS.md

@@ -20,6 +20,7 @@ Range page-read protocol details live in `.agent/specs/sqlite-range-page-read-pr
 - `sqlite-storage` reassembles large chunked logical values with one bounded chunk-prefix range read by default; `RIVETKIT_SQLITE_OPT_BATCH_CHUNK_READS=false` selects serial 10 KB chunk gets for comparison runs.
 - `sqlite-storage` caches decoded DELTA/SHARD LTX blobs across repeated reads by default, with `RIVETKIT_SQLITE_OPT_DECODED_LTX_CACHE=false` preserving per-read decode behavior.
 - `sqlite-storage` compaction folds DELTA pages into SHARD blobs for steadier read behavior.
+- The native read-mode/write-mode SQLite connection manager routes read-only statements to pooled read-only connections and routes writes, transactions, and fallbacks through exclusive write mode. Read-pool v1 closes readers before writes and does not pin per-reader head txids.
 
 ## Recommended Optimizations
 
@@ -31,7 +32,6 @@ Range page-read protocol details live in `.agent/specs/sqlite-range-page-read-pr
 - Return SQLite meta from `sqlite-storage::get_pages(...)` instead of doing a second META read in pegboard-envoy.
 - Persist capped VFS preload hints on sleep/close and feed them into `OpenConfig` on the next actor start.
 - Add a bulk or range page-read protocol so cold scans do not require page-list request loops.
-- Add a read-mode/write-mode SQLite connection manager for parallel read-only queries; read mode may hold multiple read-only connections, while write mode must close readers and hold exactly one writable connection.
 - Reduce storage read amplification from whole-blob LTX decode further with page-frame-addressable storage.
 - Benchmark compacted and un-compacted cold reads separately.
 

docs-internal/engine/sqlite-vfs.md

@@ -31,3 +31,10 @@ The native VFS uses the same 4 KiB chunk layout and KV key encoding as the WASM
 - SQLite VFS aux-file create/open paths mutate `BTreeMap` state under one write lock with `entry(...).or_insert_with(...)`. Avoid read-then-write upgrade patterns.
 - SQLite VFS v2 storage keys use literal ASCII path segments under the `0x02` subspace prefix with big-endian numeric suffixes so `scan_prefix` and `BTreeMap` ordering stay numerically correct.
 - SQLite v2 slow-path staging writes encoded LTX bytes directly under DELTA chunk keys. Do not expect `/STAGE` keys or a fixed one-chunk-per-page mapping in tests or recovery code.
+
+## Read-mode/write-mode connection manager
+
+- The native connection manager is the SQLite read/write routing policy boundary. TypeScript and NAPI wrappers forward calls to native execution and must not decide routing from SQL text.
+- Read mode may hold multiple read-only SQLite connections against one shared VFS context. Write mode must hold exactly one writable SQLite connection and no reader connections.
+- Entering write mode stops admitting new readers, waits for active readers to release, closes idle readers, then opens or reuses the single writable connection.
+- Read-pool v1 intentionally does not let readers continue during writes and does not pin per-reader head txids or snapshots. Any future design that overlaps readers with writers must add explicit snapshot fencing.

scripts/ralph/prd.json

@@ -207,7 +207,7 @@
         "Typecheck passes"
       ],
       "priority": 12,
-      "passes": false,
+      "passes": true,
       "notes": ""
     }
   ]

scripts/ralph/progress.txt

@@ -16,6 +16,7 @@ Started: Wed Apr 29 04:23:03 AM PDT 2026
 - TypeScript SQLite migration hooks should run inside native `writeMode` so setup queries use the writer connection and do not create readers.
 - SQLite read-pool rollout config lives in `sqlite-storage::optimization_flags`; build `NativeConnectionManagerConfig` from `sqlite_optimization_flags()` and use `RIVETKIT_SQLITE_OPT_READ_POOL_ENABLED=false` for single-writer compatibility.
 - Kitchen-sink SQLite real-world benchmark reporting should include read-pool route counters alongside VFS counters so parallel-read and read-write-transition workloads expose manager behavior.
+- Native SQLite read-pool v1 closes readers before writes and does not pin per-reader head txids; TypeScript/NAPI wrappers must treat native execution as the routing policy boundary.
 
 ## 2026-04-29 04:27:40 PDT - US-001
 - Implemented native SQLite statement classification with readonly detection, trailing-statement detection, authorizer action capture, and conservative reader eligibility.
@@ -259,3 +260,20 @@ Started: Wed Apr 29 04:23:03 AM PDT 2026
   - Fence-mismatch tests need to clear the VFS page caches after setup so the stale reader is forced to fetch through the engine and observe the replacement generation.
   - Native VFS registration tests can affect later tests because SQLite's VFS list is process-global; drop the stale registration before the replacement registration during cleanup.
 ---
+## 2026-04-29 06:05:43 PDT - US-012
+- Documented the SQLite read-mode/write-mode connection manager invariant in internal VFS docs, including exclusive write mode, no reader/write overlap, and the native routing policy boundary.
+- Moved the read-mode/write-mode manager tracker entry from recommended work into existing optimizations.
+- Preserved the reusable invariant in the root agent notes for future SQLite changes.
+- Files changed:
+  - `AGENTS.md`
+  - `docs-internal/engine/sqlite-vfs.md`
+  - `docs-internal/engine/SQLITE_OPTIMIZATIONS.md`
+  - `scripts/ralph/prd.json`
+  - `scripts/ralph/progress.txt`
+- Checks:
+  - `cargo check -p rivetkit-sqlite`
+- **Learnings for future iterations:**
+  - Read-pool v1 intentionally avoids reader/writer overlap instead of pinning per-reader head txids or snapshots.
+  - Internal SQLite docs are the right home for cross-layer invariants; keep the optimization tracker limited to benchmark and performance status.
+  - Root `AGENTS.md` already has a SQLite Package section for short reusable constraints that should apply across future implementation work.
+---