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

docs: active stories 08+11 into stories in-progress/ (slip fix)

Browse source 
- 08 landed in discarded/ by mis-drop, swept into prior commit with
  two dead links; corrected to stories/.../in-progress/ per intent
- 11 joins it (one arc, active slice)
- board doctrine: active stories bucket named; all links re-verified

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
shoney.arickathil 2026-08-21 06:21:33 +02:00
parent f691818c4b
commit 299b448181
8 changed files with 30 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/00-status.md
View file

@ -11,9 +11,11 @@ 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/`, held ones into `hold/` (2026-08-21); ready/in-flight stay at
the root. Second exception (2026-08-21): the active slice's one marker
doc lives in `docs/in-progress/` and is deleted when the slice lands. Every plan and phase doc opens with a
`refine/`, held ones into `hold/`, the active slice's stories into
`stories/language-runtime-database/in-progress/` (both 2026-08-21);
ready ones stay at the root. Second exception (2026-08-21): the active
slice's one marker doc lives in `docs/in-progress/` and is deleted when
the slice lands. 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.
@ -171,11 +173,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/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/in-progress/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/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/in-progress/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 |

4
docs/in-progress/2026-08-21-arc-stage-3.md
View file

@ -26,9 +26,9 @@ single- AND multi-shard honestly.
## Stories
- [8 — shard-actor runtime](../stories/language-runtime-database/08-shard-actor-runtime.md)
- [8 — shard-actor runtime](../stories/language-runtime-database/in-progress/08-shard-actor-runtime.md)
(stage 3 is its remaining scope)
- [11 — fibers](../stories/language-runtime-database/11-fibers.md)
- [11 — fibers](../stories/language-runtime-database/in-progress/11-fibers.md)
(substance landed stages 1+2; closes with this slice — note: `fs`
still blocks instead of parking, land it here or re-scope 11's
criterion explicitly at close)

4
docs/plan/exploration/fibers/00-fibers.md
View file

@ -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/08-shard-actor-runtime.md) /
> [11](../../../stories/language-runtime-database/11-fibers.md); this
> and iterations [8](../../../stories/language-runtime-database/in-progress/08-shard-actor-runtime.md) /
> [11](../../../stories/language-runtime-database/in-progress/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.

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

@ -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](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`. |
| 13 | 8+11 | [Shard-actor runtime](in-progress/08-shard-actor-runtime.md) · [Fibers](in-progress/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)* |

14
docs/stories/language-runtime-database/discarded/08-shard-actor-runtime.md → docs/stories/language-runtime-database/in-progress/08-shard-actor-runtime.md
View file

@ -1,7 +1,7 @@
# Iteration 8 — shard-actor runtime (the 8+11 concurrency arc, part 1)
> Format: `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
@ -15,8 +15,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
@ -109,19 +109,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](refine/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](refine/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](refine/31-actor-lifecycle.md).
NOT the arc's scope — it is [iteration 31](../refine/31-actor-lifecycle.md).

16
docs/stories/language-runtime-database/11-fibers.md → docs/stories/language-runtime-database/in-progress/11-fibers.md
View file

@ -1,7 +1,7 @@
# 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](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](refine/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](refine/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](refine/24-chat-websocket-workload.md)) is the proof.
([iteration 24](../refine/24-chat-websocket-workload.md)) is the proof.

4
docs/superpowers/plans/2026-08-20-shard-fiber-arc.md
View file

@ -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/08-shard-actor-runtime.md) ·
[11](../../stories/language-runtime-database/11-fibers.md).
Stories: [8](../../stories/language-runtime-database/in-progress/08-shard-actor-runtime.md) ·
[11](../../stories/language-runtime-database/in-progress/11-fibers.md).
**Tech Stack:** C11 libc-only (`wovm`), OCaml stdlib-only (`woc`), bash
gates; TSan added to the corpus harness at stage 2.

2
docs/superpowers/specs/2026-08-20-shard-fiber-arc-design.md
View file

@ -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/08-shard-actor-runtime.md)
> settled in [iteration 8](../../stories/language-runtime-database/in-progress/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