Skip to content

Commit 61d8d10

Browse files
joaoh82claude
andauthored
docs: refresh design-decisions.md for Phase 3c–6e state of the world (#24)
The original doc was written somewhere around Phase 3a–3b and never updated as the engine grew. Most glaringly: - Decision #10 still said "No transactions yet" — Phase 4f landed real BEGIN/COMMIT/ROLLBACK with snapshot-based rollback months ago. - Decision #5 ("bincode for on-disk encoding") called Phase 3c a "future refactor" — it shipped; bincode is gone from Cargo.toml entirely. - Decision #3 ("Single-file database") promised the WAL for "Phase 4" as if it were distant — it's live, the sidecar `.sqlrite-wal` is the default commit path. - Decision #6 predicted an LRU page cache in Phase 3d that didn't actually happen (still whole-file-in-RAM today). - Decision #4 ("Header written last on save") said "Once WAL lands this becomes obsolete" — partly right; both paths still exist for different call sites. Also missing: every architectural decision that shipped after Phase 3b — cell-based encoding (3c), B-Tree structure (3d), secondary indexes as separate B-Trees (3e), POSIX flock for concurrency (4a/4e), WAL frames + checkpointer (4b–4d), snapshot-based rollback (4f), engine lib-plus-bin split (2.5 / 5a), Arc<Mutex> for Send+Sync (2.5), SDKs layered over a single C FFI shim (5b–5g), WASM crate outside the workspace, lockstep versioning (6), two-workflow release flow (6d), and the `sqlrite-engine` crate-name workaround (crates.io had `sqlrite` taken). Rewrite the whole doc: - Group decisions by layer (Parser / Storage / Concurrency & durability / Query execution / Packaging / Process) so a reader can find what they need without scrolling through chronological noise. - Every decision now has Decision / Why / Cost as a consistent structure, with optional Artifact or Design detail blocks for the things that matter. - 22 decisions total, up from 11. - New "Still to decide" section captures known debt: case sensitivity, projection expressions, composite indexes, bounded page cache. When one of these turns into a real choice with an answer it can graduate up into the numbered list. Every new claim cross-checked against src/ during the rewrite: Arc<Mutex<HashMap>> confirmed in db/table.rs; bincode confirmed absent from Cargo.toml; crate name split confirmed in root Cargo.toml; pager's on_disk + staged + wal_cache + read-order precedence confirmed in pager/pager.rs; WASM workspace exclusion comment confirmed in root Cargo.toml. Pure docs — no engine changes. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 3a9e047 commit 61d8d10

1 file changed

Lines changed: 194 additions & 42 deletions

File tree

0 commit comments

Comments
 (0)