From 97adff7980b916c483c7231f7448835103136bca Mon Sep 17 00:00:00 2001 From: "shoney.arickathil" Date: Mon, 10 Aug 2026 09:58:52 +0200 Subject: [PATCH] docs: story iterations 11-12 (fibers, blue-green deploy) --- .../language-runtime-database/11-fibers.md | 78 +++++++++++++++++++ .../12-blue-green-deploy.md | 68 ++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 docs/stories/language-runtime-database/11-fibers.md create mode 100644 docs/stories/language-runtime-database/12-blue-green-deploy.md diff --git a/docs/stories/language-runtime-database/11-fibers.md b/docs/stories/language-runtime-database/11-fibers.md new file mode 100644 index 0000000..2e34316 --- /dev/null +++ b/docs/stories/language-runtime-database/11-fibers.md @@ -0,0 +1,78 @@ +# Iteration 11 — fibers (green threads on the shard scheduler) + +> Format: fiberloom `product/story-iteration-template`. Part of +> [Story — one language, one runtime, one database, one binary](00-story.md). + +## Goals + +- Concurrency **inside** a shard the doctrine way: cooperative fibers + scheduled by the VM — a fiber is the interpreter state wovm already + isolates (register windows + frame stack + pc), made per-fiber. One + kernel task per core stays the rule; thousands of fibers run above it + where the kernel tops out at hundreds of threads (CFS O(log N), + ~8 MiB + ~20 µs per thread vs an arena-allocated fiber context). +- **Preemption by reduction budget**, the Erlang shape: the dispatch loop + counts down and parks the fiber at zero — no signals, no safepoints, no + stack copying, deterministic replay. +- **Blocking builtins park instead of block** on server shards: the same + `net`/`time`/`fs` calls that block the thread in program mode hand their + fd to the shard's epoll/io_uring loop and resume on completion. One API, + same source text, no async/await, no function coloring — ever. +- Cross-fiber sends follow the iteration 8 rule — ownership moves — on the + cheaper same-heap path. + +## Acceptance Criteria + +- What to achieve? + - **Given** a shard running thousands of spawned fibers with one hot + compute loop among them, + - **when** the reduction budget expires, + - **then** the hot fiber parks, every other fiber makes progress + (starvation-free corpus fixture), and output is identical across + runs (deterministic scheduling). +- What to achieve? + - **Given** a fiber blocked in a stdlib builtin on a server shard, + - **when** the completion arrives on the shard's event loop, + - **then** the fiber resumes with the result while the shard served + other fibers in the interim — one OS thread, verified by TID. +- What to achieve? + - **Given** a parked fiber at shard shutdown, + - **when** the shard unwinds it, + - **then** every drop map runs (ASan zero leaks) — parked fibers die + as cleanly as trapped ones. (Iteration 12's blue-green drain reuses + exactly this unwind path.) +- What to achieve? + - **Given** `@gc` objects referenced only from a parked fiber's frames, + - **when** the per-shard cycle collector scans, + - **then** fiber stacks are roots — nothing live is collected, nothing + dead survives. + +## Out Of Scope + +- Fiber migration across shards (ownership doctrine forbids it; cross-shard + is a message send, iteration 8). +- Priorities, timers, structured-concurrency policy — recipe-box + capabilities for a later `.wo` library, not runtime policy. +- Program mode: stays single-fiber in v1 (blocking legal, log-watcher + needs nothing more). +- async/await keyword — permanently rejected surface, not deferred. + +## Info + +- Research note: [`docs/plan/exploration/fibers/00-fibers.md`](../../plan/exploration/fibers/00-fibers.md) + — kernel's-eye evidence (task_struct costs, CFS collapse at high task + counts) and the precedent survey (BEAM reductions adopted; Go stack + copying and Tokio coloring rejected; Loom's park-under-blocking-API + matches the stdlib posture). +- Vision origin: [blue-green vision §3](../../plan/exploration/blue-green-vm/00-vision.md); + iteration 8's scheduler is the substrate this extends. +- Open questions to settle in the spec: spawn surface (handle vs actor + address), budget size and check granularity, parked-fiber drop + semantics, run-queue fairness (FIFO v1). + +## Proposed Solution + +- No implementation plan exists yet — this iteration starts with the + brainstorming → spec → writing-plans chain (the superpowers path every + prior iteration followed), then executes that plan. The research note + above is the brainstorm's entry material. diff --git a/docs/stories/language-runtime-database/12-blue-green-deploy.md b/docs/stories/language-runtime-database/12-blue-green-deploy.md new file mode 100644 index 0000000..968ce1d --- /dev/null +++ b/docs/stories/language-runtime-database/12-blue-green-deploy.md @@ -0,0 +1,68 @@ +# Iteration 12 — 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 — including parked fibers — drains on the old slot through + iteration 11's unwind path), 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. +- New scheduler work — fibers landed in iteration 11; this iteration's + drain unwinds parked fibers through 11's shutdown path, it does not + extend it. + +## 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).