sqlrite 0.9.1__tar.gz → 0.10.0__tar.gz

{sqlrite-0.9.1 → sqlrite-0.10.0}/CLAUDE.md

@@ -16,6 +16,7 @@ SQLRite is a from-scratch SQLite-style embedded database written in Rust. It's p
 - `sqlrite-ffi/` — C ABI cdylib + generated `sqlrite.h` header. Backs the Go SDK and any C consumer.
 - `desktop/` — Tauri 2 + Svelte 5 GUI. Embeds the engine directly (no FFI hop).
 - `benchmarks/` — SQLR-4 / SQLR-16 bench harness. `Driver` trait + SQLRite + SQLite (rusqlite-bundled) drivers + criterion-driven workloads. Excluded from the default CI build/test/clippy/doc commands; run locally with `make bench` (or `make bench-duckdb`). See [docs/benchmarks-plan.md](docs/benchmarks-plan.md).
+- `web/` — marketing + docs site (Next.js 15 + Tailwind v4). Independent of the Cargo workspace; lives in-repo for now but is structured to lift into its own repository later. See [web/README.md](web/README.md).
 
 Architecture deep-dive: [docs/architecture.md](docs/architecture.md). The full doc index is [docs/_index.md](docs/_index.md).
 

{sqlrite-0.9.1 → sqlrite-0.10.0}/Cargo.lock

@@ -4799,7 +4799,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -4827,7 +4827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -4839,7 +4839,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "clap",
  "env_logger",
@@ -4856,7 +4856,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "cbindgen",
  "serde",
@@ -4866,7 +4866,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-mcp"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "clap",
  "libc",
@@ -4877,7 +4877,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "napi",
  "napi-build",
@@ -4887,7 +4887,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.9.1"
+version = "0.10.0"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.9.1 → sqlrite-0.10.0}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.9.1"
+version = "0.10.0"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -73,6 +73,15 @@ path = "examples/rust/quickstart.rs"
 name = "hybrid-retrieval"
 path = "examples/hybrid-retrieval/hybrid_retrieval.rs"
 
+# Phase 11.12 — BEGIN CONCURRENT retry-loop demo. Mints a sibling
+# Connection via `Connection::connect`, runs two concurrent
+# transactions (first disjoint, then same-row), and surfaces the
+# Busy / retry path. Run with `cargo run --example concurrent_writers`.
+# See `docs/concurrent-writes.md` for the conceptual walkthrough.
+[[example]]
+name = "concurrent_writers"
+path = "examples/rust/concurrent_writers.rs"
+
 [features]
 # Default build includes everything: the REPL binary (cli) and
 # POSIX/Windows advisory file locks on the Pager (file-locks).
@@ -141,4 +150,4 @@ fs2 = { version = "0.4", optional = true }
 # crate publishes to crates.io, and a path-only dep without a
 # version field fails the manifest verification step. See PR #58
 # retrospective in docs/roadmap.md.
-sqlrite-ask = { version = "0.9.1", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.10.0", path = "sqlrite-ask", optional = true }

{sqlrite-0.9.1 → sqlrite-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.9.1
+Version: 0.10.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.9.1 → sqlrite-0.10.0}/README.md

@@ -11,6 +11,8 @@ Rust-SQLite (SQLRite)
 > What I cannot create, I do not understand. 
 > — Richard Feynman
 
+📖 **Project website + docs:** the marketing + getting-started site is in [`web/`](web/) (Next.js 15 + Tailwind v4). Run `cd web && npm install && npm run dev` to preview locally; deploys to Vercel out of the box.
+
 
 <table style="width:100%">
 <tr>

{sqlrite-0.9.1 → sqlrite-0.10.0}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.9.1 → sqlrite-0.10.0}/docs/_index.md

@@ -16,7 +16,8 @@ A small, hand-written guide to the SQLRite codebase — how it's structured, how
 ## Using SQLRite as a library
 
 - [Embedding](embedding.md) — the public `Connection` / `Statement` / `Rows` API (Phase 5a) and where the non-Rust SDKs plug in (Phase 5b – 5g)
-- [`examples/`](../examples/) — runnable Rust quickstart (`cargo run --example quickstart`); language-specific subdirectories fill in as each 5x sub-phase lands
+- [Concurrent writes — MVCC + `BEGIN CONCURRENT`](concurrent-writes.md) — Phase 11 canonical reference: SQL surface, embedding API, SDK error mapping, REPL meta-commands, durability story, limitations. Design rationale lives in the [historical plan-doc](concurrent-writes-plan.md).
+- [`examples/`](../examples/) — runnable Rust quickstart (`cargo run --example quickstart`) + concurrent-writers retry-loop demo (`cargo run --example concurrent_writers`); language-specific subdirectories fill in as each 5x sub-phase lands
 
 ## Phase 7 — AI-era extensions
 
@@ -52,6 +53,9 @@ As of May 2026, SQLRite has:
 - A Tauri 2.0 + Svelte desktop app (Phase 2.5 complete)
 - AI-era extensions across the product surface (Phase 7 complete): VECTOR columns + HNSW indexes (7a-7d), JSON columns (7e), the `ask()` natural-language → SQL family across the REPL / desktop / Rust / Python / Node / Go / WASM (7g.1-7g.7), and the [`sqlrite-mcp`](mcp.md) Model Context Protocol server (7h + 7g.8)
 - Full-text search + hybrid retrieval (Phase 8 complete): FTS5-style inverted index with BM25 ranking + `fts_match` / `bm25_score` scalar functions + `try_fts_probe` optimizer hook + on-disk persistence with on-demand v4 → v5 file-format bump (8a-8c), a worked hybrid-retrieval example combining BM25 with vector cosine via raw arithmetic (8d), and a `bm25_search` MCP tool symmetric with `vector_search` (8e). See [`docs/fts.md`](fts.md).
+- SQL surface + DX follow-ups (Phase 9 complete, v0.2.0 → v0.9.1): DDL completeness — `DEFAULT`, `DROP TABLE` / `DROP INDEX`, `ALTER TABLE` (9a); free-list + manual `VACUUM` (9b) + auto-VACUUM (9c); `IS NULL` / `IS NOT NULL` (9d); `GROUP BY` + aggregates + `DISTINCT` + `LIKE` + `IN` (9e); four flavors of `JOIN` — INNER, LEFT, RIGHT, FULL OUTER (9f); prepared statements + `?` parameter binding with a per-connection LRU plan cache (9g); HNSW probe widened to cosine + dot via `WITH (metric = …)` (9h); `PRAGMA` dispatcher with the `auto_vacuum` knob (9i)
+- Benchmarks against SQLite + DuckDB (Phase 10 complete, SQLR-4 / SQLR-16): twelve-workload bench harness with a pluggable `Driver` trait, criterion-driven, pinned-host runs published. See [`docs/benchmarks.md`](benchmarks.md).
+- Phase 11 (concurrent writes via MVCC + `BEGIN CONCURRENT`, SQLR-22) is **shipped end-to-end** — `Connection` is `Send + Sync`; `Connection::connect()` mints sibling handles. `sqlrite::mvcc` exposes `MvccClock`, `ActiveTxRegistry`, `MvStore`, `ConcurrentTx`, and the `MvccCommitBatch` / `MvccLogRecord` WAL codec. WAL header v1 → v2 persisted the clock high-water mark; v2 → v3 added typed MVCC log-record frames. `PRAGMA journal_mode = mvcc;` opts a database into MVCC. `BEGIN CONCURRENT` writes commit-validate against `MvStore`, abort with `SQLRiteError::Busy`, and append a typed MVCC log-record frame to the WAL — covered by the same fsync as the legacy page commit. Reopen replays those frames into `MvStore` and seeds `MvccClock` past the highest committed `commit_ts`. Reads via `Statement::query` see the BEGIN-time snapshot. Per-commit GC + `vacuum_mvcc()` bound version-chain growth. C FFI / Python / Node / Go all propagate `Busy` / `BusySnapshot` as typed retryable errors *and* mint sibling handles that share backing state — Go's process-level path registry (Phase 11.11c) handles cross-`*sql.DB` sharing too. The `sqlrite` REPL ships `.spawn` / `.use` / `.conns` for interactive demos; the SQLR-16 benchmark suite adds `W13` (concurrent writers, mostly disjoint rows) as the Phase-11 differentiator workload. The only remaining items are deferred-by-design or foundation work: indexes under MVCC (11.10) and the checkpoint-drain follow-up (parked half of 11.9). **User-facing reference:** [`docs/concurrent-writes.md`](concurrent-writes.md); runnable example at [`examples/rust/concurrent_writers.rs`](../examples/rust/concurrent_writers.rs). Original design proposal: [`docs/concurrent-writes-plan.md`](concurrent-writes-plan.md).
 - A fully-automated release pipeline that ships every product to its registry on every release with one human action — Rust engine + `sqlrite-ask` + `sqlrite-mcp` to crates.io, Python wheels to PyPI (`sqlrite`), Node.js + WASM to npm (`@joaoh82/sqlrite` + `@joaoh82/sqlrite-wasm`), Go module via `sdk/go/v*` git tag, plus C FFI tarballs, MCP binary tarballs, and unsigned desktop installers as GitHub Release assets (Phase 6 complete)
 
 See the [Roadmap](roadmap.md) for the full phase plan.

{sqlrite-0.9.1 → sqlrite-0.10.0}/docs/benchmarks-plan.md

@@ -111,6 +111,16 @@ For W10/W11, the goal isn't to beat the comparators — they're battle-hardened
 
 For W12, no off-the-shelf comparator exists in a single embedded engine; the number stands on its own.
 
+### Group D — Concurrent writes (Phase 11.11b, the Phase-11 MVCC differentiator)
+
+| ID | Name | Shape | Comparator |
+|----|------|-------|------------|
+| W13 | Concurrent writers | 4 worker threads × 50 BEGIN/UPDATE/COMMIT cycles each, random rowid in `1..=1000` (≈ 0.4% collision per op), `UPDATE counters SET n = n + 1 WHERE id = ?` | SQLite (`BEGIN IMMEDIATE` + `busy_timeout = 5s` per-connection) |
+
+The headline workload Phase 11's MVCC machinery was designed for. SQLRite drives `BEGIN CONCURRENT` across sibling [`Connection::connect`](../docs/concurrent-writes.md) handles minted from the same process; SQLite drives `BEGIN IMMEDIATE` across separate `rusqlite::Connection` handles serializing through the WAL write lock. Both engines run the same retry-on-busy outer loop ([`is_retryable_busy`](../benchmarks/src/lib.rs) is engine-dispatched); only SQLRite actually exercises the retry path under this workload's shape — the contrast *is* the measurement.
+
+Workload parameters live in [`benchmarks/src/workloads/concurrent_writers.rs`](../benchmarks/src/workloads/concurrent_writers.rs) as named constants (`W13_PRELOAD_ROWS`, `W13_N_WORKERS`, `W13_TXS_PER_WORKER`). Bumping any of them is a workload-version bump under Q8.
+
 ---
 
 ## Metrics
@@ -127,9 +137,10 @@ Keep tight. The task brief lists many candidates; the suite measures these:
 Explicitly **not** measured in v1:
 
 - **CPU%.** Noisy on a shared machine, redundant with wall-clock for single-threaded workloads.
-- **Concurrency curves.** Engine is single-writer by design (Phase 4e). No concurrent-writer workload is meaningful until that changes.
 - **Network I/O.** All targets are in-process.
 
+**Updated post-Phase 11.11b:** Group D's `W13` (concurrent writers) lifts the single-writer caveat — SQLRite now has a real multi-writer story via `BEGIN CONCURRENT`, and W13 measures it directly against SQLite's single-writer baseline. Full concurrency-curve sweeps (varying `N` workers and collision rate) are a clean follow-up; v1 reports a single representative point.
+
 ---
 
 ## Methodology
@@ -190,7 +201,8 @@ benchmarks/
 │       ├── join.rs        — W9
 │       ├── vector.rs      — W10
 │       ├── fts.rs         — W11
-│       └── hybrid.rs      — W12
+│       ├── hybrid.rs      — W12
+│       └── concurrent_writers.rs — W13 (Phase 11.11b)
 ├── benches/
 │   └── suite.rs           — single criterion entry point that fans out
 ├── scripts/
@@ -264,11 +276,18 @@ Add the `duckdb-rs` driver under a `--features duckdb` flag. Wire only into Grou
 
 **Exit criterion:** `docs/benchmarks.md` exists, the README has a "Benchmarks" section pointing at it, the first dated results JSON is committed.
 
-### Post-9.6 ideas (parked)
+### 9.7 — Group D concurrent writers (Phase 11.11b, shipped)
+
+Adds `W13` (concurrent writers, mostly-disjoint rows) under a new Group D. The `Driver` trait grows three optional methods (`connect_sibling`, `concurrent_begin_sql`, `is_retryable_busy`) with defaults that make sense for engines without an MVCC story; SQLRite overrides all three. SQLite gains a `busy_timeout = 5s` pragma at open so its `BEGIN IMMEDIATE` blocks rather than fails on contention. The workload lives in [`benchmarks/src/workloads/concurrent_writers.rs`](../benchmarks/src/workloads/concurrent_writers.rs).
+
+**Exit criterion:** W13 runs under both drivers, correctness gate passes (`SUM(n) == n_workers * txs_per_worker` after a sample), and the JSON envelope picks up `W13.v1` rows for both drivers.
+
+### Post-9.7 ideas (parked)
 
 - **libSQL driver** if/when we want a non-extension vector competitor for W10.
 - **Per-PR regression detector.** A GitHub Action that runs the bench on a self-hosted runner and posts a comment if any workload regresses >20% from the last `main` baseline.
-- **Concurrency workloads** if/when SQLRite gains true multi-writer support.
+- **Concurrency curves for W13.** Sweep `N` workers (1, 2, 4, 8, 16) and `K` rows (10, 100, 1k, 10k) to chart SQLRite-MVCC's scaling envelope vs SQLite's serial baseline. v1 reports a single representative point; the sweep is a clean follow-up.
+- **W13b hot-row contention.** Same workload, `K = 10` rows instead of 1000 — collision probability climbs to ~40% per op, exercising the retry loop hard. Useful for stressing the GC + retry path under adversarial contention.
 - **Larger datasets (10M, 100M).** v1 is sized for fast iteration on a laptop. A "release-blocker run" config could 100× the row counts.
 
 ### Total scope estimate

{sqlrite-0.9.1 → sqlrite-0.10.0}/docs/concurrent-writes-plan.md

@@ -1,8 +1,16 @@
 # Concurrent writes plan — MVCC + `BEGIN CONCURRENT`
 
-**Status:** proposal, not yet scheduled. Drafted 2026-05-07.
+> 📘 **Looking for the user-facing reference?** This is the original
+> design proposal, kept as the historical record of the decisions
+> that shaped Phase 11. For the shipped surface — SQL, embedding API,
+> SDK error mapping, REPL meta-commands, durability story,
+> limitations — read [**`concurrent-writes.md`**](concurrent-writes.md)
+> first; come back here when you want the *why* and the
+> sequencing discussion.
+
+**Status:** shipped end-to-end through Phase 11.11a (May 2026); a small set of follow-ups remain explicitly parked — see the [roadmap](roadmap.md#phase-11--concurrent-writes-via-mvcc--begin-concurrent-sqlr-22-in-flight--see-concurrent-writes-planmd). Drafted 2026-05-07.
 **Inspiration:** [Turso](https://turso.tech) — a SQLite-compatible engine, written in Rust, that implements multi-version concurrency control to lift SQLite's single-writer ceiling. See [`turso/core/mvcc/`](https://github.com/tursodatabase/turso/tree/main/core/mvcc) and the [Turso concurrent-writes docs](https://docs.turso.tech/tursodb/concurrent-writes).
-**Tracks:** SQLR-?? (Marvin) — to be filed alongside this doc.
+**Tracks:** [SQLR-22](https://app.marvinapp.io/) (Marvin).
 
 This document proposes adding **multi-version concurrency control (MVCC)** and a **`BEGIN CONCURRENT`** transaction mode to SQLRite, enabling multiple writers in the same process to make progress in parallel under snapshot isolation, with row-level write-write conflict detection at commit. It is intentionally a *plan* — there is no code yet.
 
@@ -270,9 +278,11 @@ Goal: more than one `Connection` can target the same `Database` within a process
 
 ### Phase 10.5 — Checkpoint + crash recovery
 
-- Extend the checkpointer to drain MVCC log records into pager-level updates before folding the WAL into the main file.
-- Crash recovery: on open, replay WAL log records into `MvStore`, then replay pager-level commit frames as today.
-- Tests: kill the process mid-MVCC-commit (between log-record append and version-chain push), reopen, verify the committed transaction is visible and the half-written one is not.
+> **Status (roadmap 11.9 — May 2026):** The crash-recovery half landed in roadmap Phase 11.9. WAL format is bumped to v3; commits append a typed `MvccCommitBatch` frame before the legacy save's fsync; reopen replays those frames into `MvStore` and seeds `MvccClock` past the highest `commit_ts`. The checkpoint-drain half — folding MVCC log records into pager-level updates and re-enabling the `Mvcc → Wal` journal-mode downgrade — is the remaining slice and stays parked for a follow-up.
+
+- ~~Extend the checkpointer to drain MVCC log records into pager-level updates before folding the WAL into the main file.~~ *Deferred — see status note above.*
+- Crash recovery: on open, replay WAL log records into `MvStore`, then replay pager-level commit frames as today. **(Shipped — 11.9.)**
+- Tests: kill the process mid-MVCC-commit (between log-record append and version-chain push), reopen, verify the committed transaction is visible and the half-written one is not. **(Shipped — 11.9 covers the clean-drop case which exercises the same recovery codepath; a real OS-kill test is parked with the checkpoint-drain follow-up.)**
 
 ### Phase 10.6 — Garbage collection
 
@@ -294,9 +304,11 @@ Index maintenance under MVCC is hard enough that Turso explicitly punted on it.
 
 ### Phase 10.9 — Docs
 
-- Promote this plan to `docs/concurrent-writes.md` (the canonical user-facing reference), keeping `concurrent-writes-plan.md` as the historical design document.
-- Update [roadmap.md](roadmap.md), [`docs/_index.md`](_index.md), [supported-sql.md](supported-sql.md), [embedding.md](embedding.md), [design-decisions.md](design-decisions.md).
-- Add a worked example under `examples/rust/concurrent_writers.rs`.
+> **Status (roadmap 11.12 — May 2026):** Shipped. The canonical user-facing reference at [`docs/concurrent-writes.md`](concurrent-writes.md) covers the SQL surface, embedding API, SDK error mapping, REPL meta-commands, durability story, and limitations as of Phase 11.11a. This plan-doc is now the historical record. Cross-references in `_index.md`, `supported-sql.md`, `embedding.md`, and `design-decisions.md` point at the canonical doc; a runnable example lives at [`examples/rust/concurrent_writers.rs`](../examples/rust/concurrent_writers.rs).
+
+- Promote this plan to `docs/concurrent-writes.md` (the canonical user-facing reference), keeping `concurrent-writes-plan.md` as the historical design document. **(Shipped — 11.12.)**
+- Update [roadmap.md](roadmap.md), [`docs/_index.md`](_index.md), [supported-sql.md](supported-sql.md), [embedding.md](embedding.md), [design-decisions.md](design-decisions.md). **(Shipped — 11.12.)**
+- Add a worked example under `examples/rust/concurrent_writers.rs`. **(Shipped — 11.12.)**
 
 ---
 

sqlrite-0.10.0/docs/concurrent-writes.md

@@ -0,0 +1,340 @@
+# Concurrent writes — MVCC + `BEGIN CONCURRENT`
+
+User-facing reference for SQLRite's multi-version concurrency control. For the original design discussion + sequencing decisions, see [`concurrent-writes-plan.md`](concurrent-writes-plan.md); this doc covers the *shipped* surface as of Phase 11.11a (May 2026).
+
+---
+
+## TL;DR
+
+```sql
+PRAGMA journal_mode = mvcc;            -- once per database
+BEGIN CONCURRENT;
+UPDATE accounts SET balance = balance - 50 WHERE id = 1;
+UPDATE accounts SET balance = balance + 50 WHERE id = 2;
+COMMIT;                                -- may return Busy → caller retries
+```
+
+Two writers on *disjoint* rows now make progress in parallel; two writers on the *same* row see the second commit fail fast with [`SQLRiteError::Busy`](../src/error.rs), which the caller retries. The data structure backing this is a per-row in-memory version chain ([`MvStore`](../src/mvcc/store.rs)) sitting in front of the existing pager; the on-disk format is unchanged — durability piggybacks on the WAL via a new `MvccCommitBatch` frame (Phase 11.9). Reads inside a `BEGIN CONCURRENT` transaction see a stable BEGIN-time snapshot.
+
+The story is the same one Turso ships with `--experimental-mvcc`, narrowed for SQLRite's single-process scope.
+
+---
+
+## Why MVCC
+
+SQLite (and pre-Phase-11 SQLRite) serializes every writer through a single exclusive lock. Two writers touching *unrelated rows* still wait on each other — the lock is page- or file-granularity, not row-granularity. For workloads where most writes don't actually conflict, that's throughput left on the table.
+
+Phase 11 replaces the lock-for-the-whole-transaction model with **optimistic concurrency control**: writes run against a per-transaction snapshot; the engine only checks for conflicts at `COMMIT`, and only on the row IDs the transaction actually touched. The shape is straight out of [Hekaton (Larson et al., VLDB 2011)](https://www.microsoft.com/en-us/research/wp-content/uploads/2011/01/main-mem-cc-techreport.pdf).
+
+What you get:
+
+- **Disjoint-row writers run in parallel.** A `BEGIN CONCURRENT` on connection A and one on connection B can both progress; commit ordering is decided by a process-wide logical clock, not by lock acquisition.
+- **Snapshot-isolated reads.** A reader inside `BEGIN CONCURRENT` sees the database as it was at BEGIN time, regardless of what other writers commit in the meantime.
+- **Row-level conflict detection.** The unit of conflict is `(table, rowid)`, not a page or a table.
+- **Same on-disk format.** Existing `.sqlrite` files open unchanged. The toggle is `PRAGMA journal_mode = mvcc;`.
+
+What you don't get (v0; see [Limitations](#limitations)):
+
+- Cross-process MVCC. The version index is in-memory only; multi-process writers still serialize through the pager's `flock`.
+- `CREATE INDEX` while `journal_mode = mvcc`. Index maintenance under MVCC is Phase 11.10 (deferred-by-design).
+- DDL inside `BEGIN CONCURRENT`. Rejected with a typed error; commit your DDL outside the concurrent transaction.
+
+---
+
+## Quick start
+
+```sql
+-- 1. Opt the database into MVCC. Per-database setting; survives reopens.
+PRAGMA journal_mode = mvcc;
+
+-- 2. Multi-row update inside a concurrent transaction.
+BEGIN CONCURRENT;
+INSERT INTO orders (id, customer, total) VALUES (1, 'alice', 100);
+UPDATE inventory SET stock = stock - 1 WHERE sku = 'WIDGET-A';
+COMMIT;
+
+-- 3. If two concurrent transactions touch the same row, the second
+--    commit fails with Busy. Retry with a fresh BEGIN CONCURRENT.
+```
+
+The same end-to-end thing from Rust:
+
+```rust
+use sqlrite::{Connection, SQLRiteError};
+
+let mut conn = Connection::open("orders.sqlrite")?;
+conn.execute("PRAGMA journal_mode = mvcc")?;
+
+loop {
+    conn.execute("BEGIN CONCURRENT")?;
+    conn.execute("INSERT INTO orders (id, customer, total) VALUES (1, 'alice', 100)")?;
+    conn.execute("UPDATE inventory SET stock = stock - 1 WHERE sku = 'WIDGET-A'")?;
+    match conn.execute("COMMIT") {
+        Ok(_) => break,
+        Err(e) if e.is_retryable() => {
+            conn.execute("ROLLBACK").ok();
+            continue;
+        }
+        Err(e) => return Err(e.into()),
+    }
+}
+# Ok::<(), sqlrite::SQLRiteError>(())
+```
+
+[`SQLRiteError::is_retryable`](../src/error.rs) covers both `Busy` (write-write conflict at commit) and `BusySnapshot` (the snapshot the read path expected has been GC'd) — see [Error semantics](#error-semantics).
+
+A complete runnable version of this loop lives in [`examples/rust/concurrent_writers.rs`](../examples/rust/concurrent_writers.rs).
+
+---
+
+## Conceptual model
+
+### The version chain
+
+For every `(table, rowid)` SQLRite has touched under `BEGIN CONCURRENT`, the [`MvStore`](../src/mvcc/store.rs) holds an ordered chain of `RowVersion`s:
+
+```
+                 begin=ts1                 begin=ts3                  begin=ts7
+                 end=Some(ts3)             end=Some(ts7)              end=None
+                ┌────────────┐           ┌────────────┐             ┌────────────┐
+   rowid 42  ─→ │ Present {  │ ──next──→ │ Present {  │ ──next────→ │ Tombstone   │
+                │  balance:  │           │  balance:  │             │ (DELETE)   │
+                │   100      │           │   150      │             │            │
+                │ }          │           │ }          │             │            │
+                └────────────┘           └────────────┘             └────────────┘
+```
+
+A version is **visible** to a transaction with begin-timestamp `T` when `begin <= T < end` (the textbook snapshot-isolation rule). New writes push a new head onto the chain at commit time, capping the previous latest version's `end` to the new `commit_ts`.
+
+### Timestamps come from a process-wide logical clock
+
+[`MvccClock`](../src/mvcc/clock.rs) is an `AtomicU64` that hands out `begin_ts` at `BEGIN CONCURRENT` and `commit_ts` at the start of validation. The clock's high-water mark is persisted in the WAL header (Phase 11.2's WAL v2) and seeded past the highest replayed `commit_ts` on reopen (Phase 11.9), so timestamps don't reuse the same value across restarts.
+
+### Commit-time validation
+
+When a `BEGIN CONCURRENT` transaction commits, the engine:
+
+1. Allocates a `commit_ts` from the clock.
+2. Walks the write-set. For each `(table, rowid)`, if any committed version's `begin > tx.begin_ts`, somebody else superseded us → return `SQLRiteError::Busy`.
+3. Otherwise, for each row in the write-set, push a new `RowVersion` onto the chain at `commit_ts`, capping the previous latest's `end`.
+4. Append an `MvccCommitBatch` frame to the WAL; the legacy page-commit's fsync covers it (Phase 11.9).
+5. Mirror the writes into `Database::tables` so the legacy read path stays correct after commit.
+6. Drop the transaction's `TxHandle` and run a per-commit GC sweep over the write-set's chains.
+
+### Reads
+
+Reads via [`Statement::query`](../src/connection.rs) (Phase 11.5) consult `MvStore` first when a `BEGIN CONCURRENT` is open on the connection. If the row has a version visible at the transaction's `begin_ts`, that's the answer; otherwise the read falls through to the legacy table → pager path. This means a reader inside `BEGIN CONCURRENT` sees a consistent BEGIN-time snapshot for as long as the transaction is open.
+
+Reads *outside* `BEGIN CONCURRENT` still go through the legacy path — they see the latest committed state, exactly as before Phase 11. That's the keystone of the design: nothing about the existing non-concurrent codepath changed; MVCC is layered on top, opt-in.
+
+---
+
+## SQL surface
+
+### `PRAGMA journal_mode`
+
+| Form | Effect |
+|---|---|
+| `PRAGMA journal_mode;` | Read — returns the current mode as a single-row `wal` / `mvcc` result |
+| `PRAGMA journal_mode = mvcc;` | Switch this database into MVCC mode |
+| `PRAGMA journal_mode = wal;` | Switch back to the legacy WAL-backed pager |
+
+Case-insensitive on both the pragma name and the value. Quoted values (`'mvcc'`) work; numeric values are rejected. Unknown modes return a typed error.
+
+The setting is **per-database**, not per-connection — every [`Connection::connect`](#sibling-handles) sibling sees the same value. Switching `Mvcc → Wal` is rejected if `MvStore` carries committed versions; call [`Connection::vacuum_mvcc`](#vacuum_mvcc) first to drain the store.
+
+### `BEGIN CONCURRENT`
+
+Opens a concurrent transaction. Requires `PRAGMA journal_mode = mvcc;` first.
+
+```sql
+BEGIN CONCURRENT;
+-- DML against the per-tx snapshot
+SELECT … ;     -- sees BEGIN-time state
+INSERT … ;
+UPDATE … ;
+DELETE … ;
+COMMIT;        -- or ROLLBACK
+```
+
+Rules (each surfaces as a typed error):
+
+- Plain `BEGIN CONCURRENT` against a `Wal`-mode database is rejected.
+- Nested transactions (`BEGIN CONCURRENT` inside an open one, or `BEGIN` inside one) are rejected.
+- DDL inside `BEGIN CONCURRENT` is rejected — `CREATE TABLE`, `CREATE INDEX`, `DROP TABLE`, `DROP INDEX`, `ALTER TABLE`, `VACUUM` all bounce, the transaction stays open so the caller can `ROLLBACK`.
+- Read-only databases reject `BEGIN CONCURRENT`.
+
+`COMMIT` may surface `SQLRiteError::Busy` or `SQLRiteError::BusySnapshot`. The transaction is dropped on either; the caller's loop should `continue` after a `ROLLBACK`.
+
+### `COMMIT` / `ROLLBACK`
+
+Inside an open `BEGIN CONCURRENT`, plain `COMMIT` validates the write-set and either commits or returns `Busy`. Plain `ROLLBACK` drops the per-tx state and returns control. Both also work outside `BEGIN CONCURRENT` (they fall through to the legacy single-writer transaction control).
+
+---
+
+## Embedding API
+
+### Sibling handles
+
+A single `Connection::open` is the only path that touches the file. Mint additional handles with [`Connection::connect`](../src/connection.rs):
+
+```rust
+let primary = Connection::open("orders.sqlrite")?;
+let secondary = primary.connect();
+let tertiary  = primary.connect();
+```
+
+Every sibling shares the same `Arc<Mutex<Database>>`. Each sibling can hold its own independent `BEGIN CONCURRENT` — that's the whole point of multi-handle MVCC. Sibling handles are `Send + Sync`, so it's safe to send them across threads.
+
+Sibling propagation across each SDK (Phase 11.7 + 11.8):
+
+| SDK | Sibling API | Retryable-error type |
+|---|---|---|
+| C FFI | `sqlrite_connect_sibling(existing, out)` | `SqlriteStatus::Busy` / `BusySnapshot`; `sqlrite_status_is_retryable` |
+| Python | `conn.connect()` | `sqlrite.BusyError` / `sqlrite.BusySnapshotError` (both subclass `SQLRiteError`) |
+| Node.js | `db.connect()` | `errorKind(message)` returns `'Busy'` / `'BusySnapshot'` / `'Other'` |
+| Go | `database/sql` pool + cross-pool path registry (Phase 11.11c) | `errors.Is(err, sqlrite.ErrBusy)` / `ErrBusySnapshot`; `sqlrite.IsRetryable(err)` |
+| WASM | *(deferred — single-threaded runtime)* | *(deferred)* |
+
+For Go, every `sql.Open("sqlrite", path)` against a file-backed read-write DB routes through a process-level path registry (Phase 11.11c) — multiple `sql.Open` calls for the same canonical path mint sibling handles off a shared primary, so each `*sql.DB`'s pool can issue its own `BEGIN CONCURRENT` against the same backing engine. `:memory:` opens stay isolated by design; read-only opens (via `sqlrite.OpenReadOnly`) take a shared lock and bypass the registry. See [`sdk/go/README.md`](../sdk/go/README.md#multi-handle-reads--writes-phase-1111c) for the runnable cross-pool example.
+
+### The retry loop
+
+The canonical shape is the same in every language:
+
+```rust
+loop {
+    conn.execute("BEGIN CONCURRENT")?;
+    conn.execute(/* writes */)?;
+    match conn.execute("COMMIT") {
+        Ok(_) => break,
+        Err(e) if e.is_retryable() => {
+            conn.execute("ROLLBACK").ok();
+            continue;
+        }
+        Err(e) => return Err(e.into()),
+    }
+}
+```
+
+SQLRite intentionally **does not** ship an automatic-backoff retry helper — the right policy (immediate retry, exponential backoff, capped attempts, jittered, etc.) depends on the workload. The retryable-error classification is the only piece the SDK guarantees.
+
+### `Connection::vacuum_mvcc` <a id="vacuum_mvcc"></a>
+
+Per-commit GC sweeps the write-set's chains automatically. For a deterministic full drain (memory-pressure testing, debug snapshots, `Mvcc → Wal` downgrade prep), call [`conn.vacuum_mvcc()`](../src/connection.rs) — returns the count of versions reclaimed across the whole store. Both paths are safe against in-flight readers: a reader inside `BEGIN CONCURRENT` keeps every version its `begin_ts` snapshot still needs visible.
+
+---
+
+## REPL multi-handle demo (Phase 11.11a)
+
+The `sqlrite` REPL ships with three meta-commands for interactive MVCC demos. The prompt always shows the active handle (`sqlrite[A]>`, `sqlrite[B]>`):
+
+| Command | Effect |
+|---|---|
+| `.spawn` | Mint a sibling handle off the active one and switch to it |
+| `.use NAME` | Switch the active handle (case-insensitive); errors with the list of valid names on miss |
+| `.conns` | List every handle, mark the active one with `*`, tag handles in an open `BEGIN CONCURRENT` |
+
+End-to-end demo:
+
+```text
+sqlrite[A]> PRAGMA journal_mode = mvcc;
+sqlrite[A]> CREATE TABLE t (id INTEGER PRIMARY KEY, v INTEGER);
+sqlrite[A]> INSERT INTO t (id, v) VALUES (1, 0);
+sqlrite[A]> .spawn
+Spawned sibling handle 'B' and switched to it. 2 handles open.
+sqlrite[B]> .use A
+sqlrite[A]> BEGIN CONCURRENT;
+sqlrite[A]> UPDATE t SET v = 100 WHERE id = 1;
+sqlrite[A]> .conns
+2 handle(s):
+  * A (BEGIN CONCURRENT)
+    B
+sqlrite[A]> .use B
+sqlrite[B]> BEGIN CONCURRENT;
+sqlrite[B]> UPDATE t SET v = 200 WHERE id = 1;
+sqlrite[B]> COMMIT;
+sqlrite[B]> .use A
+sqlrite[A]> COMMIT;
+An error occured: Busy: write-write conflict on t/1: another transaction
+committed this row at ts=3 (after our begin_ts=1); transaction rolled
+back, retry with a fresh BEGIN CONCURRENT
+sqlrite[A]> .use B
+sqlrite[B]> SELECT * FROM t;
++----+-----+
+| id | v   |
++----+-----+
+| 1  | 200 |
++----+-----+
+```
+
+---
+
+## Error semantics
+
+| Variant | When | Retryable |
+|---|---|---|
+| `SQLRiteError::Busy` | A `BEGIN CONCURRENT` `COMMIT` lost the validation race — some other transaction superseded one of our row writes after our `begin_ts` | yes |
+| `SQLRiteError::BusySnapshot` | A snapshot the read path expected has been GC'd; surfaces from `Statement::query` when a long-lived reader's `begin_ts` predates the GC watermark | yes |
+| Any other variant | Programming error or storage failure — not retryable | no |
+
+`SQLRiteError::is_retryable()` is the single classifier — every SDK's retryable-error helper is a wrapper over the same predicate.
+
+---
+
+## Durability and recovery
+
+### WAL log records (Phase 11.9)
+
+Every successful `BEGIN CONCURRENT` commit writes **two** WAL records: the legacy per-page commit frames *and* a new typed `MvccCommitBatch` frame distinguished by the sentinel `page_num = u32::MAX`. The MVCC frame is appended buffered; the legacy save's commit-frame fsync covers both — so a crash between commits either keeps both writes or loses both.
+
+The MVCC frame body encodes `commit_ts + record stream` (per-record: op tag, table name, rowid, optional column-value pairs). The encoder caps each batch at 4 KiB (the frame body size); multi-frame batches for very large transactions are a deferred follow-up.
+
+### Reopen replay
+
+`pager::open_database` walks every recovered MVCC frame and re-pushes the row versions into `MvStore` via `MvStore::push_committed`. The `MvccClock` is seeded past `max(WAL header's clock_high_water, max(commit_ts among replayed batches))` so post-restart transactions can never hand out a regressed `begin_ts`.
+
+### What's parked
+
+The checkpoint half of plan-doc §10.5 — folding MVCC log records back into pager-level updates so a WAL truncate doesn't lose them, and re-enabling the `Mvcc → Wal` journal-mode downgrade once the store is drainable — is the remaining slice. The legacy save mirror still covers durability of the visible row state on the read path, so the gap is foundation work, not a correctness regression.
+
+### WAL format version
+
+| Version | Adds |
+|---|---|
+| v1 | Pre-Phase-11 baseline. Reads cleanly today. |
+| v2 (Phase 11.2) | `clock_high_water: u64` in the WAL header (bytes 24..32) |
+| v3 (Phase 11.9) | MVCC log-record frames (`page_num = u32::MAX`) |
+
+Decoders accept v1..=v3. A v2 reader on a v3 WAL emits a clean "unsupported WAL format version" diagnostic instead of silently dropping MVCC frames.
+
+---
+
+## Limitations
+
+- **`CREATE INDEX` is rejected while `journal_mode = mvcc`.** Index maintenance under MVCC is Phase 11.10 (deferred-by-design — Turso explicitly punted on the same problem).
+- **DDL inside `BEGIN CONCURRENT` is rejected.** Run DDL outside the concurrent transaction, then begin a fresh one.
+- **Cross-process MVCC is out of scope.** The version index is in-memory only; multi-process writers still serialize through the pager's `flock(LOCK_EX)`. SQLRite has no shared-memory coordination file.
+- **No automatic backoff in retry helpers.** Callers pick the policy.
+- **FTS / HNSW indexes are not maintained inside `BEGIN CONCURRENT`.** The per-row commit-apply path covers B-tree secondary indexes only; tables under MVCC writers shouldn't have FTS or HNSW indexes attached if you need the search index to stay current.
+- **`AUTOINCREMENT` is not specifically guarded** — two concurrent INSERTs that each allocate the same rowid surface as `Busy` at the second commit. The plan's "reject AUTOINCREMENT under MVCC" gate is a clean follow-up.
+- **Memory growth is bounded only via GC.** Per-commit sweeps + `vacuum_mvcc()` cover most cases; for adversarial workloads where readers hold long-lived `begin_ts` snapshots, the chains can grow until the longest-lived reader closes.
+- **Bottom-up B-tree rebuild on every save.** The architectural mismatch flagged in the plan-doc still applies. MVCC amortizes the rebuild to checkpoint time only once the checkpoint-drain follow-up lands; until then, every concurrent commit's mirror write to `Database::tables` triggers the legacy `save_database` rebuild path. Fine for v0 workloads; will matter at scale.
+
+---
+
+## See also
+
+- [`docs/concurrent-writes-plan.md`](concurrent-writes-plan.md) — original design proposal + sequencing decisions. Historical; the current doc reflects shipped reality.
+- [`docs/supported-sql.md`](supported-sql.md) — full SQL reference; the `PRAGMA journal_mode` and `BEGIN CONCURRENT` sections cross-link here.
+- [`docs/embedding.md`](embedding.md) — embedding API + multi-handle examples.
+- [`docs/file-format.md`](file-format.md) — WAL frame layout, MVCC log-record body, clock-high-water field.
+- [`docs/design-decisions.md`](design-decisions.md) §12a–§12h — the design notes accumulated across Phase 11 sub-phases.
+- [`docs/roadmap.md`](roadmap.md#phase-11--concurrent-writes-via-mvcc--begin-concurrent-sqlr-22-in-flight--see-concurrent-writes-planmd) — phase-by-phase shipped vs deferred status.
+- [`examples/rust/concurrent_writers.rs`](../examples/rust/concurrent_writers.rs) — runnable retry-loop example.
+
+External:
+
+- [Turso concurrent writes](https://docs.turso.tech/tursodb/concurrent-writes) — the direct inspiration; we cite their issues throughout the plan-doc.
+- [Hekaton (Larson et al., VLDB 2011)](https://www.microsoft.com/en-us/research/wp-content/uploads/2011/01/main-mem-cc-techreport.pdf) — the optimistic MVCC paper Turso (and now SQLRite) builds on.
+- [Hermitage anomaly test suite](https://github.com/ept/hermitage) — snapshot-isolation conformance bar; SQLRite has not yet ported these (a clean follow-up).