writeonce/docs/stories/language-runtime-database/refine/11-fibers.md

Iteration 11 — fibers (the 8+11 concurrency arc, part 2)

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

REFINED 2026-08-20 (developer decisions, no code): 8 and 11 ship as one arc — the DB becomes an actor on an owner shard (iteration 8's decision), so serving shards must PARK on cross-shard replies, which is this iteration. The spawn-surface question below is SETTLED: one unified actor-address surface (spawn returns an address, fiber or remote alike; send moves ownership; same-heap sends take the cheap path). The arc's driving workload is iteration 24: chat — fiber-per-WebSocket-connection is the serving model that retires the framework's close-when-idle keep-alive policy.

STAGE-1 SUBSTANCE LANDED 2026-08-20 (branch concurrency-arc): reduction-budget fibers (back-edge accounting — the livelock lesson is in the plan's deviations), spawn/send/actor M, one-message-at-a- time delivery, main-return reap, fiber-trap isolation, and parked net/time builtins on the io_uring-first per-shard I/O plane (WO_IO=uring|epoll, epoll fallback proven). Demonstrated by docs/examples/fibers (just fibers 8/0). The shard-context criteria (TID assertions, cross-shard sends, blue-green drain reuse) close with the arc's stage 2.

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 26's blue-green drain reuses exactly this unwind path.)
• What to achieve?
  • Given TRACED objects (GC-ness inferred since 7b) referenced only from a parked fiber's frames,
  • when the per-shard mark-sweep collector scans,
  • then parked fibers' frames are roots exactly as the live frame stack is (vm_gc_roots grows fiber awareness) — nothing live is collected, nothing dead survives. (Originally said @gc; restated 2026-08-20 in inference terms.)

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 — 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; iteration 8's scheduler is the substrate this extends.
• Open questions to settle in the spec — REDUCED 2026-08-20: the spawn surface is settled (the unified actor address, iteration 8 decision 2). Still open for the arc's spec: budget size and check granularity, parked-fiber drop semantics, run-queue fairness (FIFO v1), and how a parked fiber's borrow state interacts with the shard's GC safepoints.

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.