shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/language-runtime-database/02-vm-core.md
shoney.arickathil 1fe808b7a4 docs(stories): add readiness, retire status: refine, sweep all 47 iterations 
- `readiness: ready | refine` is a SECOND axis, orthogonal to status.
  `ready` = the brainstorm is complete and the decisions are LOCKED (a spec
  approved, or the forks explicitly confirmed). `refine` = open forks remain
  and it cannot be planned yet
- `status: refine` RETIRED because it carried both meanings at once, so a held
  iteration with an approved spec (language 18, 26) was indistinguishable from
  one nobody had thought about. status is now purely where the WORK is:
  done | in-progress | pending | hold — `pending` was already the board's own
  rendering word, so nothing new was invented
- all 47 iterations classified from EVIDENCE in their own text, not by guess:
  "the four forks are SETTLED" / "spec + plan approved" / "Approved spec:" for
  ready; "Forks the spec must settle" / "no spec exists yet" for refine. Every
  shipped iteration is ready by definition. 19 done, 5 in-progress, 15
  pending, 8 hold; 27 ready, 20 refine
- two iterations moved refine -> in-progress rather than -> pending: language
  31 and 34 are absorbed into 24 and work on them is literally happening, which
  the board already showed as 🔄 while their frontmatter said otherwise. That
  disagreement is now gone
- board legend, board-views' frontmatter contract, and two new Dataview
  queries updated — the useful one being `readiness: ready AND status:
  pending`, the startable set

WHAT THE NEW AXIS IMMEDIATELY SURFACED: of 15 pending iterations, exactly ONE
is startable — databasev2 4, io_uring group-commit, whose forks were confirmed
settled 2026-08-20. Everything else pending needs a brainstorm first. That was
invisible while one key carried both meanings, and it is now on the board.

Also caught by the sweep, unrelated to readiness but found by cross-checking
frontmatter against the board: SIX duplicate rows. Every iteration moved into
databasev2 was still listed in the LANGUAGE pending table under its retired id
(23, 32, 33, 20, 21, 27) as well as its new one. Stale copies removed. And two
databasev2 rows made claims the sweep contradicts — iteration 1 was billed
"startable today" while its forks are open, and 6 still called itself the
ceiling-raiser after 2 took that role.

Docs only. linkcheck 0 broken / 0 anchors.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-27 16:54:45 +02:00

2.1 KiB
Raw Blame History

iteration status readiness
2 done ready

Iteration 2 — VM core (wovm)

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

Goals

  • A C, libc-only virtual machine that loads a .wob bytecode module and executes method calls with the language's memory model enforced: owned objects with deterministic drops, runtime borrow checks at residual sites, and @gc classes collected without stop-the-world pauses.
  • Arithmetic and text operations execute correctly — the language's first observable behavior.

Acceptance Criteria

  • What to achieve?
    • Given a hand-assembled .wob fixture with arithmetic and method calls,
    • when wovm loads and runs it,
    • then output matches the fixture's expectation and a corrupted image is rejected by the loader before any instruction executes.
  • What to achieve?
    • Given a fixture that acquires conflicting exclusive borrows,
    • when it runs,
    • then the VM traps with the borrow-violation code, unwinds running every drop, and ASan/Valgrind report zero leaks on both success and trap paths.
  • What to achieve?
    • Given a cyclic @gc object graph that becomes garbage,
    • when the collector's budgeted ticks run,
    • then the cycle is freed within the configured budget and no pause exceeds the configured slice.

Out Of Scope

  • The OCaml compiler (iteration 3) — fixtures here are assembled by the test tool, not compiled.
  • Threads, shards, mailboxes (iteration 8); any DB or HTTP capability.

Info

  • The 16-byte object header reserves a shard id now so iteration 8 needs no relayout.
  • Format contract: docs/plan/oop-vm/00-wob-format.md twinned with runtime/src/wob.h; ~40-op register instruction set, computed-goto dispatch.

Proposed Solution

  • Execute the existing plan: docs/superpowers/plans/2026-08-01-wob-format-and-vm-core.md (16 TDD tasks: arena, object model, borrow word, RC + cycle collector, test assembler, validating loader, interpreter, drop-map unwinding, builtins, CLI + just gate).