docs: Phase 11.12 — promote concurrent-writes-plan.md to canonical reference (SQLR-22)

[joaoh82]

Summary

• Closes plan-doc §10.9 (the docs slice). Phase 11 (concurrent writes via MVCC + BEGIN CONCURRENT, SQLR-22) is now shipped end-to-end through 11.12 — every shipped sub-phase had been updating the plan-doc piecemeal; this slice promotes the user-facing surface into one canonical reference.
• New runnable example at examples/rust/concurrent_writers.rs — two sibling Connections, interleaved BEGIN CONCURRENTs, exercising both the disjoint-row happy path and the same-row retry. Verified end-to-end: alice ends at 100 + 10 + 5 + 50 = 165.
• Every cross-reference in _index.md, supported-sql.md, embedding.md, roadmap.md, design-decisions.md, and examples/README.md updated to point at the canonical doc; the plan-doc stays as the historical design record with a redirect banner.

New canonical reference: docs/concurrent-writes.md

TL;DR  →  Why MVCC  →  Quick start  →  Conceptual model
       →  SQL surface  →  Embedding API  →  REPL multi-handle demo
       →  Error semantics  →  Durability + recovery  →  Limitations

Covers the full Phase 11 user-facing surface: version chains, logical clock, commit validation, snapshot reads, PRAGMA journal_mode, BEGIN CONCURRENT rules, sibling handles via Connection::connect, the retry loop shape, per-SDK error mapping (SqlriteStatus::Busy, sqlrite.BusyError, errorKind('Busy'), sqlrite.ErrBusy), the .spawn / .use / .conns REPL meta-commands, WAL log-record durability and reopen replay, and the limitations and explicitly-parked follow-ups.

Worked example

$ cargo run --example concurrent_writers
=== Disjoint-row commits both succeed ===
  account 1 (alice): 110
  account 2 (bob): 120

=== Same-row commits: A wins, B retries ===
  B lost the race: Busy: write-write conflict on accounts/1: another transaction
  committed this row at ts=7 (after our begin_ts=6); transaction rolled back,
  retry with a fresh BEGIN CONCURRENT
  account 1 (alice): 165
  account 2 (bob): 120

Cross-ref refresh

File	Change
docs/concurrent-writes-plan.md	Redirect banner at the top; "Status" updated to shipped through 11.11a; §10.9 annotated with what landed in 11.12
docs/_index.md	Phase 11 summary bullet refreshed; new "Concurrent writes" entry in the "Using SQLRite as a library" section
docs/supported-sql.md	PRAGMA journal_mode + BEGIN CONCURRENT sections gain a "see concurrent-writes.md" callout; the "Not yet supported" entry for BEGIN CONCURRENT removed
docs/embedding.md	Phase 11.4 section refreshed with canonical-doc + example pointer; "what's still ahead" turned into "what shipped after 11.4"
docs/roadmap.md	Active-frontier blurb enumerates every shipped sub-phase + the parked follow-ups; 11.12 entry promoted to ✅ shipped
docs/design-decisions.md	Phase 11 §12a–§12h gain a leading banner pointing readers at the canonical doc for the user-facing view
examples/README.md	New entry alongside quickstart + hybrid-retrieval

What's still open in Phase 11

• 11.10 — Indexes under MVCC (deferred-by-design, plan-doc §10.7; Turso explicitly punted on the same problem)
• 11.11b — "N concurrent writers" bench workload + Go SDK cross-pool sibling shape (carved out from the original 11.11)
• Checkpoint-drain follow-up — parked half of 11.9 — enables set_journal_mode(Mvcc → Wal) once MvStore can be drained

Test plan

• cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
• cargo test --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks — 615/615
• cargo fmt --all -- --check
• cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
• cargo doc --workspace --exclude sqlrite-desktop --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --no-deps
• cargo run --example concurrent_writers — verified retry path triggers and final balances are correct
• CI green

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rust-sqlite	Ready	Preview, Comment	May 11, 2026 10:07am