shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/language-runtime-database/09-database-engine.md
shoney.arickathil c0b0dbb846 docs: audit all markdown against the code, fix findings, flatten status folders 
- README: shipped concurrency/HTTP/WebSockets sat in the roadmap as "not yet
  available"; "no package manager" contradicted [deps]; the deps example
  would not have compiled (the key IS the module name)
- runtime/README: leads with wovm, wo-rt.c demoted to a historical section;
  dropped 2 nonexistent recipes, crates/rt, @gc refcounting, 13 suites -> 18
- employee + log-watcher READMEs claimed "does not compile"; both are gates
- error catalog: +10 emitted codes incl WO-E250, the only diagnostic the
  shipped query surface raises; recorded why the sweep rotted
- language-surface: group-by parses, then the typechecker refuses it
- 00-code-review + 00-link-audit re-run; history kept, not rewritten
- 48 dead Rust-era exploration links de-linked rather than re-pointed (their
  prose names the retired plan by number); successor map -> discarded.md
- 08-project-structure: compiler/plan/ never existed; corpus has 9 dirs, 5 empty
- releasing.md: dropped a --draft step the workflow never had
- new docs/00-doc-audit.md: findings + disposition, incl one row where the
  audit was wrong and the doc it accused was right
- status folders removed: 34 stories flat, status only in frontmatter; 252
  links recomputed from resolved paths; board/board-views/structure retaught
- story 24 -> in-progress, since frontmatter is now the only truth
- new iteration 38: fs mutation verbs + net.connect, the two capability
  families no iteration owned
- new iteration 39: gofiber/fiber v3.5.0 parity study. The ledger called
  CSRF/sessions unblocked by iteration 34's HMAC, but the runtime has no
  source of randomness at all
- linkcheck skips .dev/.superpowers: 0 broken paths, 0 bad anchors

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 19:20:22 +02:00

2.9 KiB
Raw Blame History

iteration status
9 done

Iteration 9 — database engine

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

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.

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).