shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

language-runtime-database iterations

Browse source
This commit is contained in:
shoney.arickathil 2026-08-07 19:36:49 +02:00
parent 5e61b91308
commit 2986c3c906
14 changed files with 691 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
.dev/README.md
View file

@ -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-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. | | `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 Related, already at the repo root: project-level agent definitions go in
`.opencode/agents/*.md` (opencode) and `.claude/agents/*.md` (Claude Code) — `.opencode/agents/*.md` (opencode) and `.claude/agents/*.md` (Claude Code) —
those are *committed* when they should be shared with the team, unlike these 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/.local/share/opencode" opencode-data
ln -sfn "$HOME/.cache/llama.cpp" llama-cache ln -sfn "$HOME/.cache/llama.cpp" llama-cache
ln -sfn <your-llama.cpp-checkout>/llama-server.log llama-server.log 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 (`claude-project`: Claude Code names the directory after the repo's absolute

2
CLAUDE.md
View file

@ -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. 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 ## Commands

77
docs/stories/language-runtime-database/00-story.md Normal file
View file

@ -0,0 +1,77 @@
# Story — one language, one runtime, one database, one binary
> Format: `product/story-template` (tech-unit standard artifact).
> Sources consulted: `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.

49
docs/stories/language-runtime-database/01-principles-doc.md Normal file
View file

@ -0,0 +1,49 @@
# Iteration 1 — the principles doc
> Format: `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`.

54
docs/stories/language-runtime-database/02-vm-core.md Normal file
View file

@ -0,0 +1,54 @@
# Iteration 2 — VM core (`wovm`)
> Format: `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).

54
docs/stories/language-runtime-database/03-compiler-front.md Normal file
View file

@ -0,0 +1,54 @@
# Iteration 3 — compiler front (`woc`)
> Format: `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).

54
docs/stories/language-runtime-database/04-single-binary-e2e.md Normal file
View file

@ -0,0 +1,54 @@
# Iteration 4 — single binary end-to-end
> Format: `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).

53
docs/stories/language-runtime-database/05-language-surface.md Normal file
View file

@ -0,0 +1,53 @@
# Iteration 5 — language surface (Haxe-parity adoptions)
> Format: `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).

54
docs/stories/language-runtime-database/06-program-mode-stdlib.md Normal file
View file

@ -0,0 +1,54 @@
# Iteration 6 — program mode + systems stdlib
> Format: `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).

57
docs/stories/language-runtime-database/07-logwatcher-proof.md Normal file
View file

@ -0,0 +1,57 @@
# Iteration 7 — log-watcher proof workload
> Format: `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).

51
docs/stories/language-runtime-database/08-shard-actor-runtime.md Normal file
View file

@ -0,0 +1,51 @@
# Iteration 8 — shard-actor runtime
> Format: `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).

56
docs/stories/language-runtime-database/09-database-engine.md Normal file
View file

@ -0,0 +1,56 @@
# 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.
## 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).

53
docs/stories/language-runtime-database/10-http-service.md Normal file
View file

@ -0,0 +1,53 @@
# Iteration 10 — HTTP service layer
> Format: `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).

65
docs/stories/language-runtime-database/11-blue-green-deploy.md Normal file
View file

@ -0,0 +1,65 @@
# Iteration 11 — blue-green in-runtime deployment
> Format: `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).