From 801bf8f26a90ca5df05065e799188b166553a028 Mon Sep 17 00:00:00 2001
From: "shoney.arickathil" <shoney.john@outlook.com>
Date: Fri, 7 Aug 2026 19:36:49 +0200
Subject: [PATCH] language-runtime-database iterations

---
 .dev/README.md                                | 13 ++++
 CLAUDE.md                                     |  2 +-
 .../language-runtime-database/00-story.md     | 77 +++++++++++++++++++
 .../01-principles-doc.md                      | 49 ++++++++++++
 .../language-runtime-database/02-vm-core.md   | 54 +++++++++++++
 .../03-compiler-front.md                      | 54 +++++++++++++
 .../04-single-binary-e2e.md                   | 54 +++++++++++++
 .../05-language-surface.md                    | 53 +++++++++++++
 .../06-program-mode-stdlib.md                 | 54 +++++++++++++
 .../07-logwatcher-proof.md                    | 57 ++++++++++++++
 .../08-shard-actor-runtime.md                 | 51 ++++++++++++
 .../09-database-engine.md                     | 56 ++++++++++++++
 .../10-http-service.md                        | 53 +++++++++++++
 .../11-blue-green-deploy.md                   | 65 ++++++++++++++++
 14 files changed, 691 insertions(+), 1 deletion(-)
 create mode 100644 docs/stories/language-runtime-database/00-story.md
 create mode 100644 docs/stories/language-runtime-database/01-principles-doc.md
 create mode 100644 docs/stories/language-runtime-database/02-vm-core.md
 create mode 100644 docs/stories/language-runtime-database/03-compiler-front.md
 create mode 100644 docs/stories/language-runtime-database/04-single-binary-e2e.md
 create mode 100644 docs/stories/language-runtime-database/05-language-surface.md
 create mode 100644 docs/stories/language-runtime-database/06-program-mode-stdlib.md
 create mode 100644 docs/stories/language-runtime-database/07-logwatcher-proof.md
 create mode 100644 docs/stories/language-runtime-database/08-shard-actor-runtime.md
 create mode 100644 docs/stories/language-runtime-database/09-database-engine.md
 create mode 100644 docs/stories/language-runtime-database/10-http-service.md
 create mode 100644 docs/stories/language-runtime-database/11-blue-green-deploy.md

diff --git a/.dev/README.md b/.dev/README.md
index 1a4858d..96c3c08 100644
--- a/.dev/README.md
+++ b/.dev/README.md
@@ -15,6 +15,16 @@ recreates them for their own machine (commands below).
 | `llama-cache/` | `~/.cache/llama.cpp` | Downloaded GGUF weights (Qwen3-Coder-30B-A3B etc.). What `MODEL_PATH`/`start-local-agents.sh` resolve against. |
 | `llama-server.log` | `<llama.cpp checkout>/llama-server.log` | Live log of the background `llama-server` started by `prototypes/llama-moe-stream/start-local-agents.sh` — `tail -f` it to watch prompt processing and tok/s. |
 
+## references/ — related source trees
+
+`references/` holds read-only symlinks to source trees under `~/projects/`
+used as study material for the compiler/runtime work (same idea as the
+`reference/{linux,go}` links at the repo root):
+
+| Link | Points at | Why it's a reference |
+| --- | --- | --- |
+| `references/llvm-project/` | `~/projects/llvm-project` (shallow clone) | Compiler-architecture study for the OCaml `woc` compiler: pass pipelines (`llvm/lib/Passes/`), IR design (`llvm/docs/LangRef.md`), Clang's lexer/parser/sema layering (`clang/lib/{Lex,Parse,Sema}/`), diagnostics machinery (`clang/include/clang/Basic/Diagnostic*.td`). Study-only — writeonce does NOT link against LLVM (zero-dep doctrine; `woc` emits `.wob` bytecode, no LLVM backend). |
+
 Related, already at the repo root: project-level agent definitions go in
 `.opencode/agents/*.md` (opencode) and `.claude/agents/*.md` (Claude Code) —
 those are *committed* when they should be shared with the team, unlike these
@@ -30,6 +40,9 @@ ln -sfn "$HOME/.config/opencode"       opencode-config
 ln -sfn "$HOME/.local/share/opencode"  opencode-data
 ln -sfn "$HOME/.cache/llama.cpp"       llama-cache
 ln -sfn <your-llama.cpp-checkout>/llama-server.log llama-server.log
+mkdir -p references
+git clone --depth 1 https://github.com/llvm/llvm-project.git ~/projects/llvm-project
+ln -sfn "$HOME/projects/llvm-project"  references/llvm-project
 ```
 
 (`claude-project`: Claude Code names the directory after the repo's absolute
diff --git a/CLAUDE.md b/CLAUDE.md
index 2441a7a..e97efe2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,7 +33,7 @@ The repo holds three cuts of the same project plus one research reference:
 
 There is also **`prototypes/wo-db/`** — a ~2k-line **C++ prototype** of the query-layer engine (SQL + Cypher + document paths, `RETURNING` aliases, `LIVE` stub). It keeps its `wo-db` directory name (C++ project, separate from the Rust crate `db`). It's the reference implementation the Rust port follows; `make test` still passes.
 
-And **`prototypes/wo-rt-c/`** — a single-file **C reference of the runtime layer** (edge-triggered epoll loop, signalfd shutdown, non-blocking listener, in-RAM store over minimal HTTP; libc only). It's the runtime-layer sibling of `wo-db`: each block maps one-to-one to a `crates/rt/src/runtime/` module (table in its README). `make` builds it; `just rt-c-demo` exercises it. Its evolution into a multi-threaded io_uring RAM-database runtime (thread-per-core, mmap arena, WAL dual-write, recovery, ACID) is phased A–F in `docs/plan/exploration/c-runtime/00-plan.md`, with the one-address architecture trace beside it (`01-architecture.md`) — the proving ground for plans 09–12. **Documentation belongs under `docs/`** — prototype/crate directories keep only their orientation README.
+And **`runtime/`** — a single-file **C reference of the runtime layer** (edge-triggered epoll loop, signalfd shutdown, non-blocking listener, in-RAM store over minimal HTTP; libc only). It's the runtime-layer sibling of `wo-db`: each block maps one-to-one to a `crates/rt/src/runtime/` module (table in its README). `make -C runtime` builds it; `just rt-c-demo` exercises it. Its evolution into a multi-threaded io_uring RAM-database runtime (thread-per-core, mmap arena, WAL dual-write, recovery, ACID) is phased A–F in `docs/plan/exploration/c-runtime/00-plan.md`, with the one-address architecture trace beside it (`01-architecture.md`) — the proving ground for plans 09–12. **Documentation belongs under `docs/`** — prototype/crate directories keep only their orientation README. One recorded exception: the compiler track's plan documents live in `compiler/plan/` (architecture map + plans 2, 3, 8).
 
 ## Commands
 
diff --git a/docs/stories/language-runtime-database/00-story.md b/docs/stories/language-runtime-database/00-story.md
new file mode 100644
index 0000000..ab823b7
--- /dev/null
+++ b/docs/stories/language-runtime-database/00-story.md
@@ -0,0 +1,77 @@
+# Story — one language, one runtime, one database, one binary
+
+> Format: fiberloom `product/story-template` (tech-unit standard artifact).
+> Sources consulted: fiberloom `tech-unit/framework`, `product/story-template`, `product/story-iteration-template`.
+
+**AS** a developer building and operating my own products end to end
+
+**I WANT** a new programming language — with arithmetic, ownership-based memory safety, and garbage collection where I opt in — whose compiler, runtime, and database ship as a single never-stopping Linux binary that can update its own code in place
+
+**TO** write an application once and run it forever: no external stack to assemble, no database server to operate, and deployments that swap code inside the running process with instant rollback.
+
+## User Value
+
+- One artifact is the whole system: the language's runtime owns the data,
+  serves the API, and carries its own source — the "which commit is prod
+  running?" class of questions disappears.
+- Memory safety without a GC tax: Rust-shaped borrowing (single owner,
+  second-class borrows) checked mostly at compile time, with per-class `@gc`
+  opt-in collected per shard — no global pause exists by construction.
+- Updates are blue-green **inside** the runtime: propose, approve, compile
+  in-process, atomic switch, previous version resident for instant rollback.
+- The runtime is a recipe box: once language + runtime + database exist, a
+  web framework arrives as a `.wo` library composing runtime capabilities —
+  the recorded next story.
+
+## Background & Constraints
+
+writeonce today is a declarative Rust-based runtime (Stage 2). This story
+evolves it into an object-oriented language (`woc` OCaml compiler, `wovm` C
+VM) per the approved specs: C as the runtime's basis (libc only), no
+inheritance ever, mutable value semantics for borrowing, shard-per-core
+concurrency with ownership-moving messages, RAM-authoritative data under a
+WAL, and the blue-green VM pair for in-runtime deployment. Target OS is
+Linux; kernel primitives are the framework. The Rust runtime retires only at
+parity. Constraints: OCaml stdlib only, C libc only; docs live under
+`docs/`; prose-only planning artifacts (no implementation code in stories or
+iterations); no commits by agents — drafts go to `.dev/commit.md`.
+
+## Iterations (review in this order)
+
+| # | Iteration | Delivers |
+| --- | --- | --- |
+| 1 | [Principles doc](01-principles-doc.md) | `docs/00-principles.md` — the doctrine page every later slice links back to |
+| 2 | [VM core](02-vm-core.md) | `wovm`: `.wob` loader, register interpreter, arena, borrow word, `@gc` collector |
+| 3 | [Compiler front](03-compiler-front.md) | `woc`: lexer → parser → typechecker → ownership pass, diagnostics |
+| 4 | [Single binary end-to-end](04-single-binary-e2e.md) | emitter + conformance corpus + `woc build` self-contained binary |
+| 5 | [Language surface](05-language-surface.md) | Haxe-parity adoptions: switch, records, optionals, try/catch, statics, modules… |
+| 6 | [Program mode + stdlib](06-program-mode-stdlib.md) | `fn main`, exit codes, `fs`/`proc`/`net`/`time`/`json` builtins |
+| 7 | [log-watcher proof](07-logwatcher-proof.md) | the driving workload compiled and detecting silent deaths live |
+| 8 | [Shard-actor runtime](08-shard-actor-runtime.md) | thread-per-core shards, per-shard heaps, ownership-move messaging |
+| 9 | [Database engine](09-database-engine.md) | class-shaped tables, typed WAL + recovery, `insert`/`select` execute |
+| 10 | [HTTP service layer](10-http-service.md) | `service` blocks route to VM methods; REST parity with Stage 2 |
+| 11 | [Blue-green deploy](11-blue-green-deploy.md) | two VM slots, in-runtime compile, atomic switch, resident rollback |
+
+Review protocol: the developer reads one iteration, approves or amends;
+the next starts only after approval. Each iteration is an unsplittable
+value slice with its own acceptance criteria (Given/When/Then), out-of-scope
+list, and a pointer to the plan document that already sequences its tasks.
+
+## Related Links
+
+- OOP core spec: `docs/superpowers/specs/2026-08-01-oop-compiler-vm-design.md`
+- Systems track spec: `docs/superpowers/specs/2026-08-01-systems-track-design.md`
+- Blue-green spec: `docs/superpowers/specs/2026-08-03-blue-green-vm-design.md`
+- Sample+principles spec: `docs/superpowers/specs/2026-08-07-logwatcher-sample-and-principles-design.md`
+- Plan documents: `docs/superpowers/plans/` (plans 1–10), `compiler/plan/` (2, 3, 8 + architecture)
+- Roadmap map: `docs/08-project-structure.md` (build sequence)
+- Behavioral reference workload: `~/projects/log-watcher` (Haxe daemon)
+
+## Notes
+
+- Acceptance criteria live in each iteration file; this story frames the
+  outcome.
+- Recorded future stories, deliberately outside this one: the web framework
+  as a `.wo` library over the recipe-box runtime; UI (`##ui` SSR + live
+  patches); script-based destructive schema migrations; MCP/agent wrapper
+  over the management plane.
diff --git a/docs/stories/language-runtime-database/01-principles-doc.md b/docs/stories/language-runtime-database/01-principles-doc.md
new file mode 100644
index 0000000..3b147b6
--- /dev/null
+++ b/docs/stories/language-runtime-database/01-principles-doc.md
@@ -0,0 +1,49 @@
+# Iteration 1 — the principles doc
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The repo gains `docs/00-principles.md`: one page stating the twelve
+  writeonce principles — the doctrine every later iteration links back to
+  instead of re-arguing.
+- The twelve: one binary is the whole system; zero dependencies (kernel
+  primitives only); memory safety without a GC tax (MVS ownership, opt-in
+  `@gc`, per-shard collection); no inheritance ever; thread-per-core shards
+  with ownership moves; the runtime never stops (blue-green slots, embedded
+  source); RAM authoritative + WAL durable; samples force the grammar;
+  Linux is the target; capabilities are typed builtins (no FFI); plain
+  diagnostics are the product; the runtime is a recipe box.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** a new contributor opening `docs/`,
+    - **when** they read `docs/00-principles.md`,
+    - **then** each principle is a short statement plus a one-line why plus
+      a link to the spec or doc that enforces it, and no principle
+      contradicts a locked spec decision.
+- What to achieve?
+    - **Given** CLAUDE.md's "Where to read next" list,
+    - **when** the iteration lands,
+    - **then** it contains one pointer line to the principles doc and
+      nothing else about it changed.
+
+## Out Of Scope
+
+- Rewriting or relocating existing doctrine text in specs/plans — the doc
+  links, it does not duplicate.
+- Any `.wo` example content (iterations 2+ own code-adjacent artifacts).
+
+## Info
+
+- `docs/` numbering starts at `01-problem.md`; the `00-` slot is free and
+  reads as "start here".
+- Spec governing this slice: `docs/superpowers/specs/2026-08-07-logwatcher-sample-and-principles-design.md` §3.
+
+## Proposed Solution
+
+- Author the page with the twelve principles in the order listed in the
+  governing spec; verify every link resolves; add the CLAUDE.md pointer
+  line; record the commit draft in `.dev/commit.md`.
diff --git a/docs/stories/language-runtime-database/02-vm-core.md b/docs/stories/language-runtime-database/02-vm-core.md
new file mode 100644
index 0000000..0678d44
--- /dev/null
+++ b/docs/stories/language-runtime-database/02-vm-core.md
@@ -0,0 +1,54 @@
+# Iteration 2 — VM core (`wovm`)
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## 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).
diff --git a/docs/stories/language-runtime-database/03-compiler-front.md b/docs/stories/language-runtime-database/03-compiler-front.md
new file mode 100644
index 0000000..7b32f93
--- /dev/null
+++ b/docs/stories/language-runtime-database/03-compiler-front.md
@@ -0,0 +1,54 @@
+# Iteration 3 — compiler front (`woc`)
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- An OCaml, stdlib-only compiler front end: `.wo` source becomes a typed
+  AST with ownership annotations, or plain, precise diagnostics — the
+  half of the language the developer converses with.
+- Ownership errors read like sentences naming both sites ("moved at
+  pricing.wo:14, used at pricing.wo:17") — the ergonomics bet that makes
+  MVS beat Rust for this audience.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** the pricing-demo classes,
+    - **when** `woc` runs its front pipeline (lex → parse → typecheck →
+      ownership),
+    - **then** `--dump-ast` output matches the golden file and zero
+      diagnostics are emitted.
+- What to achieve?
+    - **Given** a file violating ownership rules (move-after-use, borrow
+      escape, double exclusive borrow),
+    - **when** it compiles,
+    - **then** each violation reports a stable `WO-E###` code with both
+      source sites, and one bad declaration does not stop diagnosis of the
+      rest of the file.
+- What to achieve?
+    - **Given** a class that satisfies an interface structurally,
+    - **when** typechecking runs,
+    - **then** satisfaction is recognized with no `implements` declaration,
+      and per-method `self` mutability is inferred (reads shared, writes
+      exclusive).
+
+## Out Of Scope
+
+- Bytecode emission and running anything (iteration 4).
+- The Haxe-parity adoptions (iteration 5) — milestone grammar only.
+
+## Info
+
+- Newline-significant lexing and the identifier gotchas mirror
+  `crates/rt`'s lexer — grammar parity is a stated contract.
+- Architecture map: `compiler/plan/architecture.md` (pipeline, module
+  contracts, study references).
+
+## Proposed Solution
+
+- Execute the existing plan: `compiler/plan/2026-08-01-woc-compiler-front.md`
+  (diagnostics module, lexer, declaration/statement/expression parsers with
+  skip-on-block, typechecker with field-kind derivation, MVS ownership pass
+  producing the four emitter tables, driver + error catalog).
diff --git a/docs/stories/language-runtime-database/04-single-binary-e2e.md b/docs/stories/language-runtime-database/04-single-binary-e2e.md
new file mode 100644
index 0000000..7496cf0
--- /dev/null
+++ b/docs/stories/language-runtime-database/04-single-binary-e2e.md
@@ -0,0 +1,54 @@
+# Iteration 4 — single binary end-to-end
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The two halves meet: `woc` emits `.wob` images the VM's loader accepts,
+  a conformance corpus pins language behavior from both sides, and
+  `woc build` produces the story's headline artifact — one self-contained
+  executable.
+- This is the milestone where "a new language with arithmetic and garbage
+  collection" is demonstrably real: source in, running binary out.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** the pricing demo's logic subset,
+    - **when** `woc` compiles it on a developer laptop,
+    - **then** compilation finishes in under 100 ms and `wovm` runs the
+      resulting module with correct output.
+- What to achieve?
+    - **Given** the three-kind conformance corpus (runs with expected
+      stdout; must-fail-compile with expected `WO-E###`; must-trap with
+      expected trap code),
+    - **when** the harness runs the full suite,
+    - **then** every fixture lands in its expected bucket and ASan/Valgrind
+      report zero errors across the suite.
+- What to achieve?
+    - **Given** `woc build` on a sample project,
+    - **when** the produced binary is copied to a machine with no OCaml, no
+      compiler, nothing but Linux,
+    - **then** it runs with no arguments and behaves identically.
+
+## Out Of Scope
+
+- Anything beyond the milestone grammar (iteration 5 grows the surface).
+- Hot reload / deployment mechanics (iteration 11 — but the self-exec
+  trailer this iteration ships is its foundation).
+
+## Info
+
+- The loader's validation battery is the executable spec: every image
+  `emit` produces must round-trip through it — the golden rule both
+  test suites enforce.
+- The corpus becomes the spine every later iteration extends (lang, sys,
+  db, actor fixture kinds already scaffolded under `tests/corpus/`).
+
+## Proposed Solution
+
+- Execute the existing plan: `compiler/plan/2026-08-01-wob-emit-e2e-single-binary.md`
+  (emitter with ownership lowering + drop maps + vtables, corpus harness,
+  pricing corpus, ownership/trap corpora, gc pump e2e, `woc build` trailer,
+  `just oop-accept` gate over the five spec success criteria).
diff --git a/docs/stories/language-runtime-database/05-language-surface.md b/docs/stories/language-runtime-database/05-language-surface.md
new file mode 100644
index 0000000..34c6d23
--- /dev/null
+++ b/docs/stories/language-runtime-database/05-language-surface.md
@@ -0,0 +1,53 @@
+# Iteration 5 — language surface (Haxe-parity adoptions)
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The language grows from milestone grammar to a daily-driver surface: the
+  systems-track verdict table's every **adopt** row — switch expressions,
+  typedef records with `?fields`, `?T` optionals with null-narrowing,
+  enum payload variants, try/catch/throw over traps, `static` members,
+  `abstract` newtypes, `using` extensions, `use` modules, `is`, `pub` /
+  `pub(read)`, `#if` build flags, string interpolation, loop control.
+- Every **reject** row (inheritance, `Dynamic`, `cast`, macros, FFI…)
+  refuses with a diagnostic citing doctrine — the language's boundaries are
+  as deliberate as its features.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** the verdict table in the systems-track spec,
+    - **when** the corpus runs,
+    - **then** every adopt row has at least one golden fixture and one
+      must-fail fixture passing, and every reject row that would parse
+      produces its doctrine-citing diagnostic.
+- What to achieve?
+    - **Given** a switch over a union missing one variant and lacking
+      `default`,
+    - **when** it compiles,
+    - **then** the diagnostic names exactly the missing variants.
+- What to achieve?
+    - **Given** the three fenced VM changes (catch frames, variant objects,
+      boxed scalar optionals),
+    - **when** they land,
+    - **then** the format doc is updated in the same change and all prior
+      trap fixtures still pass byte-for-byte.
+
+## Out Of Scope
+
+- Stdlib modules and program mode (iteration 6).
+- Any new VM capability beyond the three fenced changes.
+
+## Info
+
+- Normative table: `docs/superpowers/specs/2026-08-01-systems-track-design.md` Part 1.
+- Order inside the plan matters: modules first (everything imports through
+  them), data shapes before optionals, rejects last.
+
+## Proposed Solution
+
+- Execute the existing plan: `compiler/plan/2026-08-01-haxe-parity-language.md`
+  (nine tasks, each shipping its fixtures and error-catalog entries in the
+  same task).
diff --git a/docs/stories/language-runtime-database/06-program-mode-stdlib.md b/docs/stories/language-runtime-database/06-program-mode-stdlib.md
new file mode 100644
index 0000000..e45a79e
--- /dev/null
+++ b/docs/stories/language-runtime-database/06-program-mode-stdlib.md
@@ -0,0 +1,54 @@
+# Iteration 6 — program mode + systems stdlib
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- writeonce stops being server-only: a project with a free
+  `fn main(args) -> Int` compiles as a CLI program with exit codes — the
+  daemon/tool shape log-watcher represents.
+- Five typed builtin modules — `fs`, `proc`, `net`, `time`, `json` — give
+  programs system access with no FFI hole: bounded reads, args-array-only
+  process runs, TCP listen/accept, monotonic time, typed JSON decode.
+- Every handle is an owned object whose drop closes it: RAII from the
+  ownership model, leaked fds impossible by construction.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** a program with `fn main`,
+    - **when** `wo run` executes it and `woc build` packages it,
+    - **then** the return value propagates as the process exit code in both
+      forms, and SIGTERM flips `env.stopping()` without any callback
+      machinery.
+- What to achieve?
+    - **Given** the stdlib corpus against real resources (tempdir files,
+      rename-simulated rotation, spawned trivial processes, loopback
+      sockets),
+    - **when** the suite runs under ASan,
+    - **then** all fixtures pass, and the fd-battery fixture (open many
+      handles in a loop) shows no fd-count growth.
+- What to achieve?
+    - **Given** a JSON document missing optional fields or shaped wrongly,
+    - **when** `json.decode … as Record` runs,
+    - **then** missing optionals decode as nil, shape mismatches yield nil
+      overall, and no trap fires — expected absence is data, not error.
+
+## Out Of Scope
+
+- The log-watcher sample itself (iteration 7 proves this slice).
+- UDP/TLS, fs mutation beyond append, signal callbacks, worker threads.
+
+## Info
+
+- One API, two disciplines: the same stdlib calls are blocking in program
+  mode and loop-integrated on server shards — no `async` keyword exists.
+- Spec: `docs/superpowers/specs/2026-08-01-systems-track-design.md` Parts 2–3.
+
+## Proposed Solution
+
+- Execute the existing plan: `docs/superpowers/plans/2026-08-01-program-mode-stdlib.md`
+  (program entry + env module, time, fs with inode stat + bounded
+  `read_at`, proc.run with capped capture, net RAII handles, typed json,
+  sys corpus battery in the `oop-accept` gate).
diff --git a/docs/stories/language-runtime-database/07-logwatcher-proof.md b/docs/stories/language-runtime-database/07-logwatcher-proof.md
new file mode 100644
index 0000000..1503f72
--- /dev/null
+++ b/docs/stories/language-runtime-database/07-logwatcher-proof.md
@@ -0,0 +1,57 @@
+# Iteration 7 — log-watcher proof workload
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The language's driving workload runs for real: the Haxe log-watcher
+  daemon (~1,200 lines) re-expressed file-for-file in `.wo` at
+  `docs/examples/log-watcher/`, compiled by `woc`, detecting a silent
+  death on a live file.
+- The README mapping table's "could not express" column is empty — the
+  systems track's acceptance bar: nothing in a real daemon exceeded the
+  language.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** the eight-file `.wo` port (logtail, watcher, cron, probes,
+      supervisor, mcp, tools, main),
+    - **when** `woc` compiles the sample and the ported fixture groups run,
+    - **then** compilation is clean and every fixture mirrors its named
+      Haxe test case with matching behavior.
+- What to achieve?
+    - **Given** the built sample running `watch` against a growing
+      tempfile,
+    - **when** the feed ends with an error line and the quiet period
+      elapses,
+    - **then** exactly one detection line appends to the JSONL sink —
+      the original's measured behavior, reproduced.
+- What to achieve?
+    - **Given** the README mapping table,
+    - **when** the iteration closes,
+    - **then** every row names its `.hx` sibling and deliberate
+      divergences, and the could-not-express column is empty.
+
+## Out Of Scope
+
+- The sqlite-backed minilog tools — expressible when iteration 9's SQL
+  lands; recorded as scoped-out, not inexpressible.
+- New language or stdlib features: a gap found here is a defect report
+  against iterations 5/6, and this iteration stops until it's resolved.
+
+## Info
+
+- The `.wo` files may be authored docs-first ahead of this iteration
+  (spec `2026-08-07-logwatcher-sample-and-principles-design.md`); this
+  iteration is where they must actually compile and run.
+- The pure-core discipline (tail state machine, cron math, MCP `handle`
+  socket-free and clock-injected) is preserved — the original's best
+  design decision.
+
+## Proposed Solution
+
+- Execute the existing plan: `docs/superpowers/plans/2026-08-01-log-watcher-sample.md`
+  (five tasks: tail state machine, cron, probes+supervisor, MCP subset,
+  main + README + live acceptance scenario in the `oop-accept` gate).
diff --git a/docs/stories/language-runtime-database/08-shard-actor-runtime.md b/docs/stories/language-runtime-database/08-shard-actor-runtime.md
new file mode 100644
index 0000000..38e66f8
--- /dev/null
+++ b/docs/stories/language-runtime-database/08-shard-actor-runtime.md
@@ -0,0 +1,51 @@
+# Iteration 8 — shard-actor runtime
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The runtime scales past one core the doctrine way: pinned thread-per-core
+  shards, each owning its own heap and event loop; cross-shard
+  communication is a message send that **moves ownership** — shared mutable
+  state never exists.
+- The language grows `spawn` and message send; garbage collection stays
+  per-shard, so no global pause appears at any core count.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** a program spawning actors across shards,
+    - **when** an owned object is sent to another shard,
+    - **then** the sender can no longer touch it (compile-time move), the
+      receiver owns it, and its eventual free routes back to its
+      allocation-home arena.
+- What to achieve?
+    - **Given** debug builds with shard-ownership asserts,
+    - **when** the deterministic actor corpus runs under ASan and TSan,
+    - **then** zero races, zero leaks, and identical output across runs.
+- What to achieve?
+    - **Given** a `@gc` reference,
+    - **when** code attempts to send it cross-shard,
+    - **then** the compiler rejects it — aliased references cannot cross
+      heap boundaries.
+
+## Out Of Scope
+
+- Fibers/green threads (recorded in the blue-green vision §3; extends this
+  scheduler later).
+- Cross-shard transactions (the database iteration's 2PC concern, later).
+
+## Info
+
+- The C reference (`runtime/wo-rt.c`, phases A–F) is the substrate: epoll
+  loops, eventfd mail, the machinery this iteration lifts into `wovm`.
+- The VM's object header has carried a shard id since iteration 2 — no
+  relayout.
+
+## Proposed Solution
+
+- Execute the existing plan: `docs/superpowers/plans/2026-08-01-shard-actor-vm-runtime.md`
+  (pinned-worker scheduler, shard-stamped heaps, MPSC mailbox rings + mail
+  eventfds, send-as-move with home-routed frees, gc pacing per tick,
+  spawn/send surface, actor corpus).
diff --git a/docs/stories/language-runtime-database/09-database-engine.md b/docs/stories/language-runtime-database/09-database-engine.md
new file mode 100644
index 0000000..e326e15
--- /dev/null
+++ b/docs/stories/language-runtime-database/09-database-engine.md
@@ -0,0 +1,56 @@
+# Iteration 9 — database engine
+
+> Format: fiberloom `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.
+
+## 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).
diff --git a/docs/stories/language-runtime-database/10-http-service.md b/docs/stories/language-runtime-database/10-http-service.md
new file mode 100644
index 0000000..9a2a2b7
--- /dev/null
+++ b/docs/stories/language-runtime-database/10-http-service.md
@@ -0,0 +1,53 @@
+# Iteration 10 — HTTP service layer
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The single binary serves: `service rest` blocks compile to routes and the
+  runtime answers HTTP from its shards — hand-rolled HTTP and JSON, zero
+  libraries, per the dependency doctrine.
+- The new stack reaches feature parity with the Rust runtime's Stage 2
+  REST surface — the concrete bar the retirement decision measures
+  against.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** the blog sample's `service` declarations,
+    - **when** the compiled binary boots and `reference/rest/blog.rest`
+      runs against it,
+    - **then** every request in the smoke file answers as documented —
+      including the intentional 501/405/404 responses.
+- What to achieve?
+    - **Given** a method call arriving over REST that traps (borrow
+      violation, abort, unique violation),
+    - **when** the response returns,
+    - **then** exactly one trap-to-HTTP table governs the mapping (e.g.
+      conflict-shaped 409s) and the structured error body carries the trap
+      record — the same trap surface everywhere, now over the wire.
+- What to achieve?
+    - **Given** transports declared at boot,
+    - **when** the runtime starts under systemd socket activation or with
+      zero listeners,
+    - **then** both boot correctly — a runtime is not tied to a port.
+
+## Out Of Scope
+
+- WebSocket/live subscriptions and UI (the parked `##ui` story).
+- The management plane endpoints (iteration 11 builds them on this
+  machinery).
+
+## Info
+
+- Route declarations ride the `.wob` format as a versioned section — a
+  coordinated format bump, the pattern later sections follow.
+- The C reference's phase-C HTTP machine is the porting source.
+
+## Proposed Solution
+
+- Execute the existing plan: `docs/superpowers/plans/2026-08-01-http-service-layer.md`
+  (per-shard http module, hand-rolled JSON codec, service-block route
+  section, Stage-2-parity CRUD, method RPC with the trap table, blog.rest
+  smoke).
diff --git a/docs/stories/language-runtime-database/11-blue-green-deploy.md b/docs/stories/language-runtime-database/11-blue-green-deploy.md
new file mode 100644
index 0000000..bb80970
--- /dev/null
+++ b/docs/stories/language-runtime-database/11-blue-green-deploy.md
@@ -0,0 +1,65 @@
+# Iteration 11 — blue-green in-runtime deployment
+
+> Format: fiberloom `product/story-iteration-template`. Part of
+> [Story — one language, one runtime, one database, one binary](00-story.md).
+
+## Goals
+
+- The story's closing promise: the running binary updates its own code.
+  Two fixed VM slots (activity alternating); a proposal pipeline —
+  propose → approve → in-runtime compile → additive schema migration →
+  load → health → atomic switch — with the previous version staying
+  resident as the instant rollback target.
+- The developer drives it remotely: `wo remote pull / propose / diff /
+  approve / rollback / status` over a loopback management transport,
+  every stage streaming live and WAL-audited.
+
+## Acceptance Criteria
+
+- What to achieve?
+    - **Given** a running fixture app and an additive code+schema change,
+    - **when** the developer proposes and approves it,
+    - **then** the deploy completes with zero dropped requests (in-flight
+      work drains on the old slot), and the binary's embedded source
+      trailer matches the new active version afterward.
+- What to achieve?
+    - **Given** a failure at any pipeline stage (compile diagnostic,
+      destructive-change rejection, load failure, health failure, drain
+      timeout),
+    - **when** it occurs,
+    - **then** the active slot keeps serving untouched, the failure is
+      visible in the SSE stream and the WAL trail, and a destructive
+      change was rejected at propose time naming the offending
+      declaration.
+- What to achieve?
+    - **Given** a completed deploy,
+    - **when** `wo remote rollback` runs,
+    - **then** the previous version serves again in under one second with
+      no compile and no data change — additive-only migration guarantees
+      old code runs correctly against the migrated schema.
+- What to achieve?
+    - **Given** kill -9 during COMPILING / MIGRATING / SWITCHING /
+      trailer-rewrite,
+    - **when** the unit restarts,
+    - **then** it serves one consistent version and the WAL shows whole
+      migrations only.
+
+## Out Of Scope
+
+- Script-based/destructive migrations, in-runtime editing workspace,
+  MCP/agent wrapper over the management plane — all recorded follow-ups.
+- Fibers (the vision's §3; a scheduler concern, not a deploy concern).
+
+## Info
+
+- Approved spec: `docs/superpowers/specs/2026-08-03-blue-green-vm-design.md`;
+  its implementation plan is deliberately authored only after iterations
+  9–10 ship (prerequisites: a catalog to diff, HTTP machinery to build on).
+- VMs own code; the engine owns data — the separation that makes the
+  switch cheap and rollback unconditional.
+
+## Proposed Solution
+
+- Author the implementation plan from the approved spec once iterations
+  9–10 land, then execute it (slots, deploy state machine, additive
+  differ, management surface + SSE, `wo remote` verbs, crash battery).