From b03b1cff50c9b034ab8e77ebd920420b8f7d25f1 Mon Sep 17 00:00:00 2001 From: "shoney.arickathil" Date: Fri, 21 Aug 2026 05:10:39 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20stories=2008+11=20promoted=20to=20root?= =?UTF-8?q?=20=E2=80=94=20ready=20to=20implement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - code-verified ready: arc stages 1+2 merged to master; stage 3 concrete in plan (tasks 7-8); rt.db set on primary only (main.c), worker_late_init memsets rt — WO_T_DB hole real - 22/23/24/31 stay in refine/: open forks, no bench harness, no crypto builtins, chain-blocked - links fixed both directions; board doctrine names hold/ bucket Co-Authored-By: Claude Fable 5 --- docs/00-status.md | 7 ++++--- docs/plan/exploration/fibers/00-fibers.md | 4 ++-- .../language-runtime-database/00-story.md | 2 +- .../{refine => }/08-shard-actor-runtime.md | 14 +++++++------- .../{refine => }/11-fibers.md | 16 ++++++++-------- .../plans/2026-08-20-shard-fiber-arc.md | 4 ++-- .../specs/2026-08-20-shard-fiber-arc-design.md | 2 +- 7 files changed, 25 insertions(+), 24 deletions(-) rename docs/stories/language-runtime-database/{refine => }/08-shard-actor-runtime.md (92%) rename docs/stories/language-runtime-database/{refine => }/11-fibers.md (91%) diff --git a/docs/00-status.md b/docs/00-status.md index 5e58fbd..af28755 100644 --- a/docs/00-status.md +++ b/docs/00-status.md @@ -11,7 +11,8 @@ folders** — a doc stays where it was authored when its work lands; only its banner and this board change. ONE exception by directive (2026-08-20): story iteration files move physically — landed ones into `stories/language-runtime-database/done/`, brainstorm-needing ones into -`refine/`; in-flight/parked stay at the root. Every plan and phase doc opens with a +`refine/`, held ones into `hold/` (2026-08-21); ready/in-flight stay at +the root. Every plan and phase doc opens with a `> **Status:**` banner linking back here; normative contracts (`plan/oop-vm/`), exploration studies, reference docs and the discarded/learnings registers carry none by design. @@ -169,11 +170,11 @@ that sequences its tasks. Read one, approve, then the next starts. | 6 | [Program mode + stdlib](stories/language-runtime-database/done/06-program-mode-stdlib.md) | ✅ (the surface log-watcher uses) | | 7 | [log-watcher proof](stories/language-runtime-database/done/07-logwatcher-proof.md) | ✅ **landed 2026-08-15** — executable, not merely compilable: zero ASan leaks in all three modes, SIGTERM ends parked syscalls, fds flat, `LW_SOAK` gate; `just log-watcher` 7/0 | | 7b | [Inferred GC + mark-sweep](stories/language-runtime-database/done/07b-inferred-gc-mark-sweep.md) | ✅ **landed 2026-08-18** — `@gc` gone (WO-E104), GC-ness inferred, RC replaced by incremental mark-sweep, `.wob` v4; supersedes iteration 2's RC memory model | -| 8 | [Shard-actor runtime](stories/language-runtime-database/refine/08-shard-actor-runtime.md) | 🔄 arc stages 1+2 landed 2026-08-20 (branch concurrency-arc); stage 3 (transparent DB actor) = **first in the concurrency chain** | +| 8 | [Shard-actor runtime](stories/language-runtime-database/08-shard-actor-runtime.md) | 🔄 arc stages 1+2 landed 2026-08-20 (branch concurrency-arc); stage 3 (transparent DB actor) = **first in the concurrency chain** | | 9 | [Database engine](stories/language-runtime-database/done/09-database-engine.md) | 🔄 engine complete (storage/WAL/indexes/insert-update-delete); reads land with 9b | | 9b | [`@table`, relations, query](stories/language-runtime-database/done/09b-table-relations-query.md) | 🔄 query surface + relations + FK done (branch query-surface); group-by parked | | 19 | [Float + Bytes](stories/language-runtime-database/done/19-missing-scalar-types.md) | ✅ **landed 2026-08-20** — `.wob` v5: Float constant tag, field kinds 6/7, opcodes 34-41 (IEEE-quiet f64), builtins 70-83. Full stack: literals, arithmetic, `@table` column, WAL bit-exact replay, json fractions in / shortest-round-trip out, `?Float` reserved-NaN nil, total-order index (NaN last, `-0.0` == `+0.0`), Bytes + base64. No implicit Int/Float mixing (WO-E201); `float`/`trunc` are the only bridges. Proof: web-app price is a real Float (`{"price":9.99}`), `just web-app` 23/0; corpus 103/0 | -| 11 | [Fibers](stories/language-runtime-database/refine/11-fibers.md) | 🔄 stages 1+2 landed 2026-08-20 with 8 (`just fibers` 8/0); closes with the arc's stage 3 | +| 11 | [Fibers](stories/language-runtime-database/11-fibers.md) | 🔄 stages 1+2 landed 2026-08-20 with 8 (`just fibers` 8/0); closes with the arc's stage 3 | | 22 | [Durability, throughput, scale](stories/language-runtime-database/refine/22-durability-throughput-scale.md) | ⬜ needs a spec first — second in chain, after arc stage 3 | | 31 | [Actor lifecycle](stories/language-runtime-database/refine/31-actor-lifecycle.md) | ⬜ needs a spec first — third in chain (story written 2026-08-21) | | 24 | [chat: WebSocket workload](stories/language-runtime-database/refine/24-chat-websocket-workload.md) | ⬜ fourth in chain — the arc's acceptance; after 31 | diff --git a/docs/plan/exploration/fibers/00-fibers.md b/docs/plan/exploration/fibers/00-fibers.md index f1265d1..ad22dca 100644 --- a/docs/plan/exploration/fibers/00-fibers.md +++ b/docs/plan/exploration/fibers/00-fibers.md @@ -3,8 +3,8 @@ > Exploration/reference note (no status banner by board convention). > The normative decisions live in the arc spec > ([`2026-08-20-shard-fiber-arc-design.md`](../../../superpowers/specs/2026-08-20-shard-fiber-arc-design.md)) -> and iterations [8](../../../stories/language-runtime-database/refine/08-shard-actor-runtime.md) / -> [11](../../../stories/language-runtime-database/refine/11-fibers.md); this +> and iterations [8](../../../stories/language-runtime-database/08-shard-actor-runtime.md) / +> [11](../../../stories/language-runtime-database/11-fibers.md); this > page explains the WHY at doctrine depth. Written 2026-08-20, when this > file was also the target of a dangling reference from iteration 11 — > it exists now. diff --git a/docs/stories/language-runtime-database/00-story.md b/docs/stories/language-runtime-database/00-story.md index d897cb7..d6a728e 100644 --- a/docs/stories/language-runtime-database/00-story.md +++ b/docs/stories/language-runtime-database/00-story.md @@ -99,7 +99,7 @@ still pending IS the runtime-concurrency chain; order: | 10 | 9b | [`@table`, relations, query](done/09b-table-relations-query.md) | `@table` real storage; `ref`/`backlink`/`multi`; compiler-checked queries | | 11 | 15 | [deps: `wo.toml [deps]`](done/15-deps-package-manager.md) | exact-rev git deps + `wo.lock` + `.wo-deps`; flat-only, offline once locked | | 12 | 16 | [web framework](done/16-web-framework.md) | the `.wo` framework v1 (router, middleware, auth, all three body hooks) consumed via `[deps]` | -| 13 | 8+11 | [Shard-actor runtime](refine/08-shard-actor-runtime.md) · [Fibers](refine/11-fibers.md) | THE ARC (stages 1+2 landed 2026-08-20: fibers/budget/actors/io_uring plane; pinned shards, envelope sends, home-routed frees, WO-E222); stage 3 = transparent DB RPC. **Promoted above 22 (2026-08-21): stage 3 is a correctness hole, not an optimization** — worker shards are zero-initialized, so a DB statement off the primary traps `WO_T_DB`. | +| 13 | 8+11 | [Shard-actor runtime](08-shard-actor-runtime.md) · [Fibers](11-fibers.md) | THE ARC (stages 1+2 landed 2026-08-20: fibers/budget/actors/io_uring plane; pinned shards, envelope sends, home-routed frees, WO-E222); stage 3 = transparent DB RPC. **Promoted above 22 (2026-08-21): stage 3 is a correctness hole, not an optimization** — worker shards are zero-initialized, so a DB statement off the primary traps `WO_T_DB`. | | 14 | 22 | [Durability, throughput, scale](refine/22-durability-throughput-scale.md) | restart-persistence proof, benchmarks, ~1M rows — the baseline the arc and 23 sign against. It has never run, so every performance claim on this project is currently unsourced; runs after stage 3 so one campaign covers single- and multi-shard, plus the stage-2 mutex-inbox number. *(was 9e)* | | 15 | 30 | Observability, CI, fuzz *(no story file yet)* | **NEW** — runtime counters + a profiler hook, 22's harness wired to run per change instead of by hand, and a fuzz target on the parser and `.wob` loader. The whole proof-maturity gap had no iteration to point at. | | 16 | 19 | [Float + Bytes](done/19-missing-scalar-types.md) | **LANDED 2026-08-20** — `.wob` v5; the full stack: IEEE-quiet f64 through literals/VM/@table/WAL/json + Bytes as the binary carrier, no implicit mixing, total-order indexes. Unblocks 24 (WS frames) and the crypto fork (digests). *(was 20)* | diff --git a/docs/stories/language-runtime-database/refine/08-shard-actor-runtime.md b/docs/stories/language-runtime-database/08-shard-actor-runtime.md similarity index 92% rename from docs/stories/language-runtime-database/refine/08-shard-actor-runtime.md rename to docs/stories/language-runtime-database/08-shard-actor-runtime.md index 58ff6e8..7ff6471 100644 --- a/docs/stories/language-runtime-database/refine/08-shard-actor-runtime.md +++ b/docs/stories/language-runtime-database/08-shard-actor-runtime.md @@ -1,7 +1,7 @@ # Iteration 8 — shard-actor runtime (the 8+11 concurrency arc, part 1) > Format: fiberloom `product/story-iteration-template`. Part of -> [Story — one language, one runtime, one database, one binary](../00-story.md). +> [Story — one language, one runtime, one database, one binary](00-story.md). > > **REFINED 2026-08-20** (developer decisions, no code): iterations 8 and > 11 are **one arc** — the scheduler, fibers on it, then serving — because @@ -14,8 +14,8 @@ > > **RE-SEQUENCED 2026-08-21** (developer decision): the brainstorm → > spec → plan happened. The arc's plan of record is -> [`2026-08-20-shard-fiber-arc.md`](../../../superpowers/plans/2026-08-20-shard-fiber-arc.md) -> (spec: [`2026-08-20-shard-fiber-arc-design.md`](../../../superpowers/specs/2026-08-20-shard-fiber-arc-design.md)), +> [`2026-08-20-shard-fiber-arc.md`](../../superpowers/plans/2026-08-20-shard-fiber-arc.md) +> (spec: [`2026-08-20-shard-fiber-arc-design.md`](../../superpowers/specs/2026-08-20-shard-fiber-arc-design.md)), > and **stages 1+2 LANDED 2026-08-20** on branch `concurrency-arc` > (T1–T6, seven disclosed deviations recorded in the plan). Remaining > scope: **stage 3, the transparent DB actor** — a correctness fix, not @@ -108,19 +108,19 @@ - The VM's object header has carried a shard id since iteration 2 — no relayout. - **Gated by the benchmark:** landing the arc means re-running - [22](22-durability-throughput-scale.md) at the concurrency + [22](refine/22-durability-throughput-scale.md) at the concurrency scale it unlocks and recording the before/after delta; it is also - where [23](23-io-uring-commit.md) gets a thread to overlap + where [23](refine/23-io-uring-commit.md) gets a thread to overlap durability against. ## Proposed Solution Execute stage 3 of the plan of record -([`2026-08-20-shard-fiber-arc.md`](../../../superpowers/plans/2026-08-20-shard-fiber-arc.md)): +([`2026-08-20-shard-fiber-arc.md`](../../superpowers/plans/2026-08-20-shard-fiber-arc.md)): the DB-actor migration — engine calls off the owner shard become message sends with parked replies, closing the `WO_T_DB` hole. Stages 1+2 (scheduler, fibers, unified spawn/send, WO-E222 traced-send rejection, cross-shard envelopes with home-routed frees) landed 2026-08-20. After stage 3: 22 measures, then iteration 24 proves the arc. Actor lifecycle (request/response, backpressure, supervision, timers) is deliberately -NOT the arc's scope — it is [iteration 31](31-actor-lifecycle.md). +NOT the arc's scope — it is [iteration 31](refine/31-actor-lifecycle.md). diff --git a/docs/stories/language-runtime-database/refine/11-fibers.md b/docs/stories/language-runtime-database/11-fibers.md similarity index 91% rename from docs/stories/language-runtime-database/refine/11-fibers.md rename to docs/stories/language-runtime-database/11-fibers.md index 13ab2b3..3168030 100644 --- a/docs/stories/language-runtime-database/refine/11-fibers.md +++ b/docs/stories/language-runtime-database/11-fibers.md @@ -1,7 +1,7 @@ # Iteration 11 — fibers (the 8+11 concurrency arc, part 2) > Format: fiberloom `product/story-iteration-template`. Part of -> [Story — one language, one runtime, one database, one binary](../00-story.md). +> [Story — one language, one runtime, one database, one binary](00-story.md). > > **REFINED 2026-08-20** (developer decisions, no code): 8 and 11 ship as > **one arc** — the DB becomes an actor on an owner shard @@ -10,7 +10,7 @@ > 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](24-chat-websocket-workload.md) +> driving workload is [iteration 24: chat](refine/24-chat-websocket-workload.md) > — fiber-per-WebSocket-connection is the serving model that retires the > framework's close-when-idle keep-alive policy. > @@ -27,7 +27,7 @@ > move, round-robin placement, home-routed frees, WO-E222 on EVERY > spawn/send (placement makes any actor potentially remote), TID-verified > shard context. Deviations disclosed in the plan of record -> ([`2026-08-20-shard-fiber-arc.md`](../../../superpowers/plans/2026-08-20-shard-fiber-arc.md)): +> ([`2026-08-20-shard-fiber-arc.md`](../../superpowers/plans/2026-08-20-shard-fiber-arc.md)): > the inbox is a mutex-guarded list + eventfd (rings arrive only if > iteration 22 measures the mutex as a cost), the deterministic corpus > pins `WO_SHARDS=1`, two TSan races and one teardown SEGV fixed. @@ -95,12 +95,12 @@ ## Info -- Research note: [`docs/plan/exploration/fibers/00-fibers.md`](../../../plan/exploration/fibers/00-fibers.md) +- 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); +- 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 — REDUCED AGAIN 2026-08-21: the spawn surface, budget size/granularity (back-edge accounting — see the plan's livelock @@ -109,13 +109,13 @@ implementation. Still open: how a parked fiber's borrow state interacts with the shard's GC safepoints — tracked for stage 3 / the collector's next pass. Lifecycle surface (request/response, backpressure, - supervision, timers) is [iteration 31](31-actor-lifecycle.md)'s, not + supervision, timers) is [iteration 31](refine/31-actor-lifecycle.md)'s, not this story's. ## Proposed Solution - The plan exists and its fiber stages are landed: - [`2026-08-20-shard-fiber-arc.md`](../../../superpowers/plans/2026-08-20-shard-fiber-arc.md) + [`2026-08-20-shard-fiber-arc.md`](../../superpowers/plans/2026-08-20-shard-fiber-arc.md) (stages 1+2 complete 2026-08-20). This story closes when the arc's stage 3 lands and iteration 22 records the delta; the chat workload - ([iteration 24](24-chat-websocket-workload.md)) is the proof. + ([iteration 24](refine/24-chat-websocket-workload.md)) is the proof. diff --git a/docs/superpowers/plans/2026-08-20-shard-fiber-arc.md b/docs/superpowers/plans/2026-08-20-shard-fiber-arc.md index 78738af..2fa2ffa 100644 --- a/docs/superpowers/plans/2026-08-20-shard-fiber-arc.md +++ b/docs/superpowers/plans/2026-08-20-shard-fiber-arc.md @@ -37,8 +37,8 @@ every standing gate green before the next begins. **Architecture:** see the spec (normative): [`../specs/2026-08-20-shard-fiber-arc-design.md`](../specs/2026-08-20-shard-fiber-arc-design.md). -Stories: [8](../../stories/language-runtime-database/refine/08-shard-actor-runtime.md) · -[11](../../stories/language-runtime-database/refine/11-fibers.md). +Stories: [8](../../stories/language-runtime-database/08-shard-actor-runtime.md) · +[11](../../stories/language-runtime-database/11-fibers.md). **Tech Stack:** C11 libc-only (`wovm`), OCaml stdlib-only (`woc`), bash gates; TSan added to the corpus harness at stage 2. diff --git a/docs/superpowers/specs/2026-08-20-shard-fiber-arc-design.md b/docs/superpowers/specs/2026-08-20-shard-fiber-arc-design.md index f26319d..f4cb7f7 100644 --- a/docs/superpowers/specs/2026-08-20-shard-fiber-arc-design.md +++ b/docs/superpowers/specs/2026-08-20-shard-fiber-arc-design.md @@ -1,7 +1,7 @@ # The 8+11 concurrency arc — shards, fibers, actors: design > **Status: spec, awaiting review (2026-08-20).** The arc's decisions were -> settled in [iteration 8](../../stories/language-runtime-database/refine/08-shard-actor-runtime.md) +> settled in [iteration 8](../../stories/language-runtime-database/08-shard-actor-runtime.md) > (refined) and the brainstorm of 2026-08-20 (this document's Decisions). > Covers iterations 8 AND 11 as one arc; iteration 24 (chat) is its > acceptance workload and gets its own spec after this one. The plan