shoney.arickathil
2a4c304378
- done/ (11): 1, 2, 3, 4, 6, 7, 7b, 9, 9b, 15, 16 — landed iterations (9/9b remainders live in the post-12 drain list, not in the files) - refine/ (8): 9c, 9d, 9e, 9f, 9g, 11, 13, 14 — everything marked "no spec yet / brainstorm before planning" - root keeps: 00-story (index), 05 (partial, plan 8 open), 8/10/12 (specs or plans exist), 17 (parked, spec+plan approved), 18 (next) - every cross-reference re-pathed and VERIFIED resolving: board, specs, plans, employee-list README, story table, intra-story links (moved files' relative links deepened one level; done/7b's 9e pointer now crosses to refine/) - pre-existing dead link noted, not touched: refine/11-fibers.md points at docs/plan/exploration/fibers/00-fibers.md which does not exist (predates the move) Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# Iteration 9 — database engine
|
|
|
|
> Format: `product/story-iteration-template`. Part of
|
|
> [Story — one language, one runtime, one database, one binary](../00-story.md).
|
|
|
|
## Goals
|
|
|
|
- The language's oldest promise executes on the new runtime: every class is
|
|
a table. `insert` and `select` stop trapping (`DB_STUB` retires) and run
|
|
against class-shaped row storage inside the VM's shards.
|
|
- Data survives anything: a typed write-ahead log with ack-after-fsync,
|
|
parallel boot replay, and a crash battery proving no committed row is
|
|
ever lost and no half-applied transaction ever visible.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- What to achieve?
|
|
- **Given** a class annotated `@table` and a method inserting rows,
|
|
- **when** the method runs,
|
|
- **then** the insert is WAL-logged before acknowledgment, visible to
|
|
subsequent `select`, and the pricing fixture that previously trapped
|
|
`DB_STUB` now passes with real data.
|
|
- What to achieve?
|
|
- **Given** kill -9 at arbitrary points during committed writes,
|
|
- **when** the process reboots and replays,
|
|
- **then** every acknowledged commit is present, no unacknowledged
|
|
partial write is visible, and replay across shards completes without
|
|
manual steps.
|
|
- What to achieve?
|
|
- **Given** a `@unique` field and a duplicate insert,
|
|
- **when** it executes,
|
|
- **then** the insert traps with the unique-violation code and
|
|
secondary indexes remain consistent (maintained only through the
|
|
engine's row choke points).
|
|
|
|
## Out Of Scope
|
|
|
|
- Cypher/document query paradigms and `LIVE` subscriptions (the query
|
|
layer's later phases; `prototypes/wo-db` stays the reference).
|
|
- Cross-shard 2PC transactions; Postgres mirroring (exists on the Rust
|
|
side; ports after parity).
|
|
|
|
## Info
|
|
|
|
- Doctrine: RAM is authoritative; the WAL makes it durable; indexes drift
|
|
unless writes go through the row API — the Rust runtime learned this
|
|
lesson, the C engine enforces it.
|
|
- The wo-db overlap manifest keeps the C++ prototype and this engine
|
|
answer-compatible where features overlap.
|
|
- **Ownership/GC analysis (2026-08-15):** the engine and the VM heap are two
|
|
memory worlds crossed only by copy — rows store no VM pointers, GC-managed
|
|
values in stored fields are a compile error, and everything a query returns
|
|
is copied out — so the collector never traces rows and the engine never
|
|
counts references. The full analysis (row views as borrows without a
|
|
runtime net, cursor stability, GC-pause interaction) lives in the 9b
|
|
design's section 6:
|
|
[`2026-08-15-table-relations-query-design.md`](../../../superpowers/specs/2026-08-15-table-relations-query-design.md).
|
|
|
|
## Proposed Solution
|
|
|
|
- Execute the existing plan: `docs/superpowers/plans/2026-08-01-db-engine-binding.md`
|
|
(class-shaped row slabs with a choke-point row API, typed WAL + parallel
|
|
replay + crash battery, insert execution, doctrine-enforced indexes +
|
|
`@unique` trap, select subset, db corpus).
|