shoney.arickathil
566559cf70
- `resident: all | keys` replaces `resident: all | index`. Two reasons beyond taste: it kills the collision with the `index:` argument (`@table(index: [customer], resident: index)` read badly), and it puts both values on ONE axis — each now answers "what row data stays resident", where `all`/`index` mixed a quantity with a structure name - accurate as well as clearer: what stays resident is the id->offset map, the secondary indexes and the unique shadows — all key structures; row payloads are exactly what leaves. `resident: none` was rejected as overclaiming, since the indexes very much are resident - checked for collisions: neither `all` nor `keys` is a keyword or a builtin (`key_at`/`val_at` exist, bare `keys` does not) - the spec's wart note became a recorded decision; the rejected spelling is kept quoted so the rationale still reads - fixes a bug I introduced in the 2026-08-26 track move: all six moved iterations carried a banner reading "Part of [Story — the database beyond RAM]" whose link pointed at the LANGUAGE arc — correct target, lying text, the exact failure mode the link audit warned about. Banners now point at the databasev2 story, and the original "Part of" line says plainly which track the iteration was authored in before the move - linkcheck 0 broken / 0 anchors Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
---
|
|
track: databasev2
|
|
iteration: "7"
|
|
was_language_iteration: "33"
|
|
status: refine
|
|
---
|
|
|
|
# databasev2 7 — `WO_DATA=<path>.db`: the persistent store as one file
|
|
|
|
> **Moved 2026-08-26** from the language track, where this was iteration 33.
|
|
> Part of [Story — databasev2: the database beyond RAM](00-story.md). Content unchanged by
|
|
> the move; its dependencies are restated in that track index.
|
|
|
|
> Format: `product/story-iteration-template`. Part of
|
|
> [Story — one language, one runtime, one database, one binary](../language-runtime-database/00-story.md)
|
|
> — the track this iteration was authored in before the 2026-08-26 move.
|
|
>
|
|
> **Inserted 2026-08-22** (developer ask: "can the persistent db be in
|
|
> file.db form?"). The truth is already almost there: `WO_DATA=<dir>`
|
|
> holds exactly ONE file (`shard-0.wal`) — the entire persistent state,
|
|
> since the log is the whole store and no data pages exist. This iteration
|
|
> makes the surface say so: point `WO_DATA` at a file and THAT file is
|
|
> the store. Small, driver-only, independent of the concurrency chain.
|
|
|
|
## Goals
|
|
|
|
- **`WO_DATA=<path>` accepts a file path.** A path that is not an
|
|
existing directory is treated as THE wal file (`app.db`,
|
|
`store.wo.db` — the name is the operator's). The directory form stays
|
|
and keeps meaning `<dir>/shard-0.wal` — every existing deployment and
|
|
gate is byte-identical.
|
|
- **One file remains the whole truth at any core count** — stage 3 made
|
|
the WAL owner-shard-only (shard 0 is the sole writer), so nothing
|
|
multi-shard ever adds a second file.
|
|
- **The contract says it out loud**: `04-db-binding.md` documents the
|
|
file form, and documents honestly that the file is an append-only log
|
|
that grows until iteration 32 lands.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- **Given** `WO_DATA=/tmp/app.db` (no such directory), **when** a
|
|
program seeds, restarts, and verifies, **then** replay is byte-true
|
|
and `/tmp/app.db` is the only artifact on disk.
|
|
- **Given** `WO_DATA=<dir>` (existing directory), **when** the same
|
|
program runs, **then** behavior is byte-identical to today —
|
|
`<dir>/shard-0.wal`, every standing gate unchanged.
|
|
- **Given** the db-bench durability legs pointed at the file form,
|
|
**when** the restart proof and kill -9 battery run, **then** every
|
|
guarantee holds identically (the file IS the same WAL, only named by
|
|
the operator).
|
|
|
|
## Out Of Scope
|
|
|
|
- A paged database file (SQLite's shape) — still rejected; the
|
|
disk story is the WAL, full stop.
|
|
- Checkpoint/compaction — [iteration 32](03-wal-checkpoint.md)'s; its
|
|
rename-swap (write snapshot+tail to a NEW file, fsync, `rename()`
|
|
over the old) is exactly what keeps the single-file promise crash-safe
|
|
when it lands. 33 before or after 32 works; landing 33 first means
|
|
32's spec inherits the file form as a stated constraint.
|
|
- Multiple stores per process, attach-by-file — held iteration 20's
|
|
territory.
|
|
|
|
## Info
|
|
|
|
- The whole change is `runtime/src/main.c`'s hardcoded
|
|
`snprintf("%s/shard-0.wal", dir)` growing a stat-based fork
|
|
(directory → today's path; otherwise → the path itself), plus a gate
|
|
check and the binding-doc note. No engine, no WAL format, no
|
|
compiler.
|
|
- Fork for the (tiny) spec: what does a NONEXISTENT path mean? Leaning:
|
|
a path whose parent exists and that does not end in `/` is a file to
|
|
create; a trailing `/` or existing directory keeps the directory
|
|
form. Refusing ambiguity loudly (WO exit 2) beats guessing.
|
|
|
|
## Proposed Solution
|
|
|
|
Small enough for a bounded slice: brainstorm the one fork in chat,
|
|
implement driver + db-bench file-form leg + docs in one pass, gates
|
|
green. No plan document needed unless it grows.
|