sqlrite 0.9.0__tar.gz → 0.10.0__tar.gz

{sqlrite-0.9.0 → 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.0 → sqlrite-0.10.0}/Cargo.lock

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

{sqlrite-0.9.0 → 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.0"
+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.0", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.10.0", path = "sqlrite-ask", optional = true }

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

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

{sqlrite-0.9.0 → 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>
@@ -167,6 +169,7 @@ sqlrite> DELETE FROM users WHERE age < 30;
 | `UPDATE` | Multi-column `SET`; `WHERE`; UNIQUE + type enforcement; arithmetic in assignments (`SET age = age + 1`) |
 | `DELETE` | `WHERE` predicate or full-table delete |
 | `BEGIN` / `COMMIT` / `ROLLBACK` | Real transactions, snapshot-based; WAL-backed commit; single-level (no savepoints); auto-rollback if `COMMIT`'s disk write fails |
+| `PRAGMA auto_vacuum` | Read (`PRAGMA auto_vacuum;`) returns the trigger threshold as a single-row result set; set (`PRAGMA auto_vacuum = 0.5;` / `= OFF;` / `= NONE;`) tunes or disables auto-VACUUM at the SQL layer for SDK / FFI / MCP consumers |
 
 Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 
@@ -305,7 +308,7 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [x] **7a — `VECTOR(N)` column type** *(v0.1.10)*: dense f32 vectors with bracket-array literal syntax (`[0.1, 0.2, ...]`); file format bumped to v4
 - [x] **7b — Distance functions** *(v0.1.11)*: `vec_distance_l2/cosine/dot` + `ORDER BY <expr> LIMIT k` so KNN queries work end-to-end
 - [x] **7c — Bounded-heap top-k optimization** *(v0.1.12)*
-- [x] **7d — HNSW ANN index** *(v0.1.13–15)*: `CREATE INDEX … USING hnsw (col)`; recall@10 ≥ 0.95 at default `M=16, ef_construction=200, ef_search=50`; persisted as a `KIND_HNSW` cell tree
+- [x] **7d — HNSW ANN index** *(v0.1.13–15, +SQLR-28)*: `CREATE INDEX … USING hnsw (col) [WITH (metric = '<l2|cosine|dot>')]`; recall@10 ≥ 0.95 at default `M=16, ef_construction=200, ef_search=50`; persisted as a `KIND_HNSW` cell tree, with the metric round-tripping through the synthesized `sqlrite_master` SQL
 - [x] **7e — JSON column type + path queries** *(v0.1.16)*: `JSON` / `JSONB` columns stored as canonical text; `json_extract` / `json_type` / `json_array_length` / `json_object_keys`; `$.key`, `[N]`, chained JSONPath subset
 - [x] **7g.1 — `sqlrite-ask` crate** *(v0.1.18)*: foundational natural-language → SQL via the [Anthropic API](https://docs.anthropic.com/) (Sonnet 4.6 by default), prompt-cached schema dump, sync `ureq` HTTP.
 - [x] **7g.2 — REPL `.ask` + dep-direction flip** *(v0.1.19)*: `.ask <question>` meta-command with `Run? [Y/n]` confirmation. The wiring required dropping the engine dep from `sqlrite-ask` (cargo cycle) — `sqlrite-ask` is now pure over `&str` schemas; the `Connection`/`Database` integration moved to the engine's new `ask` feature. Public surface for callers: `use sqlrite::{Connection, ConnectionAskExt}`.

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

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

{sqlrite-0.9.0 → 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.0 → sqlrite-0.10.0}/docs/architecture.md

@@ -104,6 +104,7 @@ The engine never depends on the SDK crates; the SDK crates each depend on the en
 | [`src/sql/hnsw.rs`](../src/sql/hnsw.rs) | Standalone HNSW algorithm — insert / search / layer assignment / beam search. Phase 7d.1. |
 | [`src/sql/fts/`](../src/sql/fts/) | Full-text search — standalone tokenizer, BM25 scorer, and in-memory `PostingList` inverted index. Wired into the executor via the `fts_match` / `bm25_score` scalar functions and the `try_fts_probe` optimizer hook. Phase 8a-8b; persistence in 8c. See [`docs/fts.md`](fts.md). |
 | [`src/sql/json.rs`](../src/sql/json.rs) | JSON column type + path-extraction functions (`json_extract`, `json_type`, `json_array_length`, `json_object_keys`). Phase 7e. |
+| [`src/sql/pragma.rs`](../src/sql/pragma.rs) | `PRAGMA` dispatcher (SQLR-13). `try_parse_pragma` peeks at the SQL token stream before sqlparser sees it and routes any `PRAGMA …` shape to `execute_pragma`. First pragma wired up: `auto_vacuum` (read + set, with `OFF` / `NONE` to disable). Add new pragmas as a single arm in `execute_pragma`. |
 | [`src/sql/pager/`](../src/sql/pager/) | On-disk file format and I/O — see [file-format.md](file-format.md) and [pager.md](pager.md) for details. WAL + checkpointer + shared/exclusive lock modes (Phase 4a-4e) live here. |
 
 ## Flow of a SQL statement

{sqlrite-0.9.0 → 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.0 → sqlrite-0.10.0}/docs/benchmarks.md

@@ -90,7 +90,7 @@ A few methodology notes that change how you read the table.
 - `Statement::query_with_params(&[Value])` / `Statement::execute_with_params(&[Value])` — bind `?` placeholders at execute time without re-running sqlparser.
 - `Value::Vector(Vec<f32>)` as a first-class bind type — the 4 KB query vector for W10 is now bound directly instead of being re-lexed every iteration. The HNSW probe optimizer still recognizes the bound shape, so the algorithmic shortcut keeps firing.
 
-The bench harness `Driver::query_one` / `query_all` paths route through `prepare_cached` + the bound API. Every workload's `WorkloadId.version` was bumped `v1 → v2` in lockstep — old JSON envelopes keep the v1 tag and stay readable, but cross-version comparisons require an explicit acknowledgment in the comparison script. The next official pinned-host run will land the post-binding numbers; treat the v1 row above as "before" and watch this section for the "after" once republished.
+The bench harness `Driver::query_one` / `query_all` paths route through `prepare_cached` + the bound API. Every workload's `WorkloadId.version` was bumped `v1 → v2` in lockstep — old JSON envelopes keep the v1 tag and stay readable, but cross-version comparisons require an explicit acknowledgment in the comparison script. The headline table below carries the v2 numbers from the post-SQLR-23 republished run (SQLR-25); the retired v1 baseline lives in the historical section underneath.
 
 **Where DuckDB is misleading.** Per-PK-probe single-row OLTP queries (W9) are SQLite's home turf, not DuckDB's. The plan flags this as "apples-to-oranges"; we still publish the number because the directional comparison is informative.
 
@@ -100,29 +100,53 @@ The bench harness `Driver::query_one` / `query_all` paths route through `prepare
 
 ## Headline numbers
 
-Median latency from the first official pinned-host run — [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json), Apple M1 Pro / macOS 23.5.0, criterion defaults (3 s warm-up, 5 s measurement, 100 samples on light workloads / 10 samples on heavy ones — see the JSON envelope's per-sample `samples` field). Only medians here; the JSON carries 95 % CIs, mean, std-dev, ops/s.
+Median latency from the post-SQLR-23 pinned-host run — [`benchmarks/results/2026-05-08-apple-ac84d560.json`](../benchmarks/results/2026-05-08-apple-ac84d560.json), Apple M1 Pro / macOS 23.5.0, criterion defaults (3 s warm-up, 5 s measurement, 100 samples on light workloads / 10 samples on heavy ones — see the JSON envelope's per-sample `samples` field). Only medians here; the JSON carries 95 % CIs, mean, std-dev, ops/s.
 
 | Workload | SQLRite | SQLite (WAL+NORMAL) | DuckDB | Notes |
 |---|---|---|---|---|
-| **W1** read-by-PK | 9.87 µs | 2.05 µs | — | ~5× — parser tax |
-| **W2** range-100 | 23.99 ms | 60.50 µs | — | ~400× — full-scan vs index range probe |
-| **W2** range-1k | 24.92 ms | 585.21 µs | — | ~43× |
-| **W2** range-10k | 30.15 ms | 6.24 ms | — | ~5× — converges as scan dominates |
-| **W3** bulk insert (100k/txn) | 1.029 s | 166.43 ms | — | ~6.2× |
-| **W4** single-row insert | 6.76 ms | 9.78 µs | — | **~691× ⚠️** SQLR-18 |
-| **W5** mixed OLTP | 55.63 ms | 9.96 µs | — | **~5,580× ⚠️** SQLR-18 |
-| **W6** index lookup | 10.45 µs | 2.50 µs | — | ~4× — parser tax |
-| **W7** SUM (1M rows) | 109.47 ms | 31.14 ms | 468.74 µs | DuckDB ~66× faster than SQLite |
-| **W8** GROUP BY card-10 | 201.80 ms | 438.09 ms | 761.40 µs | DuckDB ~575× faster than SQLite |
-| **W8** GROUP BY card-1k | 1.372 s | 251.13 ms | 871.80 µs | DuckDB ~288× faster than SQLite |
-| **W8** GROUP BY card-100k | _skipped_ | 238.96 ms | 19.58 ms | **SQLRite skipped ⚠️** SQLR-19; DuckDB ~12× faster than SQLite |
-| **W9** INNER JOIN (10k×10k) | 34.25 s | 2.23 µs | 699.23 µs | **~15M× ⚠️** SQLR-20; DuckDB ~313× slower than SQLite (analytical-engine OLTP weakness) |
-| **W10** vector top-10 (brute-force, 10k×384) | 138.66 ms | — | — | parser cost dominates |
-| **W10** vector top-10 (HNSW) | 126.81 ms | — | — | masked by parser cost |
-| **W11** BM25 top-10 (1k docs) | 1.079 ms | 25.03 µs | — | ~43× |
-| **W12** hybrid (1k docs) | 713.53 µs | — | — | RAG headline |
-
-> The **canonical run** is [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json). The `dirty=true` flag in the commit metadata reflects the working-tree state when 9.6 PR was being authored (this doc + README updates uncommitted at run time); the **measurements themselves only depend on the bench binary**, which was built from the committed bench-9.5-duckdb tip. Subsequent official runs land alongside this file with their own date / host / commit.
+| **W1** read-by-PK | 3.92 µs | 2.09 µs | — | ~1.9× — gap closed by SQLR-23 (was ~4.8× in v1) |
+| **W2** range-100 | 24.27 ms | 66.62 µs | — | ~364× — full-scan vs index range probe |
+| **W2** range-1k | 26.64 ms | 649.30 µs | — | ~41× |
+| **W2** range-10k | 30.73 ms | 7.01 ms | — | ~4.4× — converges as scan dominates |
+| **W3** bulk insert (100k/txn) | 606.20 ms | 183.96 ms | — | ~3.3× — 100k INSERT plan parsed once, not per-row (was ~6.2× in v1) |
+| **W4** single-row insert | 6.57 ms | 11.35 µs | — | **~579× ⚠️** SQLR-18 |
+| **W5** mixed OLTP | 58.00 ms | 9.65 µs | — | **~6,010× ⚠️** SQLR-18 |
+| **W6** index lookup | 4.04 µs | 2.56 µs | — | ~1.6× — gap closed by SQLR-23 (was ~4.2× in v1) |
+| **W7** SUM (1M rows) | 103.62 ms | 31.57 ms | 478.78 µs | DuckDB ~66× faster than SQLite |
+| **W8** GROUP BY card-10 | 197.32 ms | 366.52 ms | 949.75 µs | DuckDB ~386× faster than SQLite |
+| **W8** GROUP BY card-1k | 1.380 s | 240.64 ms | 1.039 ms | DuckDB ~232× faster than SQLite |
+| **W8** GROUP BY card-100k | _skipped_ | 239.72 ms | 22.93 ms | **SQLRite skipped ⚠️** SQLR-19; DuckDB ~10× faster than SQLite |
+| **W9** INNER JOIN (10k×10k) | 30.30 s | 2.16 µs | 484.97 µs | **~14M× ⚠️** SQLR-20; DuckDB ~225× slower than SQLite (analytical-engine OLTP weakness) |
+| **W10** vector top-10 (brute-force, 10k×384) | 120.88 ms | — | — | compute-bound; modest ~13% drop vs v1 |
+| **W10** vector top-10 (HNSW) | **2.40 ms** | — | — | **~53× faster than v1** ⭐ — SQLR-23 + SQLR-28 unmasked the index; HNSW now ~50× faster than brute-force |
+| **W11** BM25 top-10 (1k docs) | 501.63 µs | 23.65 µs | — | ~21× — `fts_match` / `bm25_score` no longer re-parsed (was ~43× in v1) |
+| **W12** hybrid (1k docs) | 607.90 µs | — | — | RAG headline (~15% faster than v1) |
+
+> The **canonical v2 run** is [`benchmarks/results/2026-05-08-apple-ac84d560.json`](../benchmarks/results/2026-05-08-apple-ac84d560.json). It supersedes the v1 baseline (table below) end-to-end: every workload was rerun on the same canonical Apple M1 Pro host after [SQLR-23](https://github.com/joaoh82/rust_sqlite/pulls?q=SQLR-23) bumped `WorkloadId.version` from `v1 → v2` in lockstep (W10 → `v3` after [SQLR-28](https://github.com/joaoh82/rust_sqlite/pulls?q=SQLR-28) widened the HNSW probe to cosine + dot). The `dirty=true` flag reflects the working-tree state at run time (this doc update + the new envelope itself uncommitted); the **measurements themselves only depend on the bench binary**, which was built from the clean `ac84d560` tip. Subsequent official runs land alongside this file with their own date / host / commit.
+
+### Historical (v1, retired)
+
+The pre-SQLR-23 baseline from [`benchmarks/results/2026-05-07-apple-9ffd55a5.json`](../benchmarks/results/2026-05-07-apple-9ffd55a5.json), retained so the methodology shift is visible. The v1→v2 jump is not an algorithmic improvement — it's the bench-driver methodology change (per-iter `inline_params` → `prepare_cached` + bound `?` parameters; `Value::Vector` for HNSW-eligible KNN). Cross-version comparisons (`W1.v1` vs `W1.v2`) are flagged in the comparison script per Q8; the [`compare.py`](../benchmarks/scripts/compare.py) v1↔v2 report walks each one.
+
+| Workload | SQLRite (v1) | SQLite (v1) | DuckDB (v1) |
+|---|---|---|---|
+| **W1** read-by-PK | 9.87 µs | 2.05 µs | — |
+| **W2** range-100 | 23.99 ms | 60.50 µs | — |
+| **W2** range-1k | 24.92 ms | 585.21 µs | — |
+| **W2** range-10k | 30.15 ms | 6.24 ms | — |
+| **W3** bulk insert (100k/txn) | 1.029 s | 166.43 ms | — |
+| **W4** single-row insert | 6.76 ms | 9.78 µs | — |
+| **W5** mixed OLTP | 55.63 ms | 9.96 µs | — |
+| **W6** index lookup | 10.45 µs | 2.50 µs | — |
+| **W7** SUM (1M rows) | 109.47 ms | 31.14 ms | 468.74 µs |
+| **W8** GROUP BY card-10 | 201.80 ms | 438.09 ms | 761.40 µs |
+| **W8** GROUP BY card-1k | 1.372 s | 251.13 ms | 871.80 µs |
+| **W8** GROUP BY card-100k | _skipped_ | 238.96 ms | 19.58 ms |
+| **W9** INNER JOIN (10k×10k) | 34.25 s | 2.23 µs | 699.23 µs |
+| **W10** brute-force | 138.66 ms | — | — |
+| **W10** HNSW | 126.81 ms | — | — |
+| **W11** BM25 top-10 (1k docs) | 1.079 ms | 25.03 µs | — |
+| **W12** hybrid (1k docs) | 713.53 µs | — | — |
 
 ---
 

{sqlrite-0.9.0 → 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.)**
 
 ---