docs: story iterations 11-12 (fibers, blue-green deploy)

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.

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