shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/language-runtime-database/done/02-vm-core.md
shoney.arickathil 2a4c304378 docs: stories foldered by state — done/ and refine/ 
- 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>
2026-08-20 04:33:24 +02:00

2.1 KiB
Raw Blame History

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