shoney.arickathil c0b0dbb846 docs: audit all markdown against the code, fix findings, flatten status folders

- README: shipped concurrency/HTTP/WebSockets sat in the roadmap as "not yet
  available"; "no package manager" contradicted [deps]; the deps example
  would not have compiled (the key IS the module name)
- runtime/README: leads with wovm, wo-rt.c demoted to a historical section;
  dropped 2 nonexistent recipes, crates/rt, @gc refcounting, 13 suites -> 18
- employee + log-watcher READMEs claimed "does not compile"; both are gates
- error catalog: +10 emitted codes incl WO-E250, the only diagnostic the
  shipped query surface raises; recorded why the sweep rotted
- language-surface: group-by parses, then the typechecker refuses it
- 00-code-review + 00-link-audit re-run; history kept, not rewritten
- 48 dead Rust-era exploration links de-linked rather than re-pointed (their
  prose names the retired plan by number); successor map -> discarded.md
- 08-project-structure: compiler/plan/ never existed; corpus has 9 dirs, 5 empty
- releasing.md: dropped a --draft step the workflow never had
- new docs/00-doc-audit.md: findings + disposition, incl one row where the
  audit was wrong and the doc it accused was right
- status folders removed: 34 stories flat, status only in frontmatter; 252
  links recomputed from resolved paths; board/board-views/structure retaught
- story 24 -> in-progress, since frontmatter is now the only truth
- new iteration 38: fs mutation verbs + net.connect, the two capability
  families no iteration owned
- new iteration 39: gofiber/fiber v3.5.0 parity study. The ledger called
  CSRF/sessions unblocked by iteration 34's HMAC, but the runtime has no
  source of randomness at all
- linkcheck skips .dev/.superpowers: 0 broken paths, 0 bad anchors

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-26 19:20:22 +02:00

4 KiB

Raw Blame History

iteration	status	chain
24	in-progress	4

Iteration 24 — chat: the WebSocket pub/sub driving workload

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

Inserted 2026-08-20 (concurrency-chain refinement): the 8+11 arc's driving workload, the role log-watcher played for iterations 3–7. Needs its spec AFTER the arc's — it lands at the arc's end and proves it.

RE-SEQUENCED 2026-08-21: fourth in the chain, stage 3 → 22 → 31 → 24 → 23 → 32 — chat cannot be written honestly before iteration 31 (request/response, bounded mailboxes, actor death, timers). Iteration 19 LANDED 2026-08-20, so Bytes is available for frame parse/serialize.

Why this iteration exists

Everything the framework ledger parks behind concurrency — WebSockets, pub/sub, streaming, per-request cancellation, the keep-alive parking retirement — needs a workload that actually exercises long-lived connections and cross-shard broadcast, or the arc ships mechanism without proof. Chat is the smallest honest such workload: rooms, N concurrent clients, fan-out on every message, presence on connect/disconnect — one binary, no broker.

Goals

docs/examples/chat: rooms + broadcast + presence over WebSocket, served by the framework through [deps] exactly as the web-app is.
Framework grows the WS mechanism in pure .wo: the HTTP/1.1 upgrade handshake (Sec-WebSocket-Accept needs SHA-1/base64 — the crypto-builtin fork's first real consumer), frame parse/serialize (text, close, ping), fiber-per-connection serving (iteration 11), and in-memory channels whose delivery is cross-shard message send (iteration 8).
The arc's acceptance teeth: 1k concurrent clients across shards, broadcast latency measured, starvation-free under one hot room, SIGTERM drains every connection cleanly.

Acceptance Criteria (draft — the spec after the arc refines)

Given two clients in one room on DIFFERENT shards, when one sends, then the other receives the frame (cross-shard ownership-move delivery), and a third client in another room receives nothing.
Given 1k connected clients with one hot sender, when the reduction budget preempts, then every room keeps making progress (no starvation) on one OS thread per core, verified by TID.
Given SIGTERM with clients connected, when the server drains, then every connection gets a close frame, every fiber unwinds its drop maps (ASan zero leaks), and the process exits 0.
Given the web-app running beside chat features, when the standing gates run, then nothing regresses — HTTP and WS share the serve loop honestly.

Out Of Scope

Message persistence/history (a @table an app adds if it wants — not the workload's point); auth beyond the existing bearer mechanism; permessage compression; binary frames beyond echo coverage; wss (TLS stays at the proxy — the proxy story extends to WS pass-through, documented).

Info

Dependencies: the 8+11 arc (fibers + cross-shard send — stages 1+2 landed 2026-08-20, stage 3 pending), iteration 31 (request/response, backpressure, death, timers — the mechanisms rooms and presence are made of), iteration 19 (LANDED 2026-08-20 — Bytes carries the frames), the crypto builtins fork (SHA-1 for the upgrade handshake — note: the ledger's crypto slice lists SHA-256/512; the WS handshake specifically needs SHA-1, so the builtin set must include it), and the framework's parse seam (upgrade is an HTTP request until it isn't).
Unparks on landing: the framework ledger's WebSocket/pub-sub rows and the iteration-18 rejection note ("pub/sub REJECTED until 8/11").

Proposed Solution

Brainstorm → spec → plan after the arc's spec exists; the arc's plan and this iteration's are written against each other (the arc names chat as its acceptance, chat names the arc as its substrate).

4 KiB Raw Blame History Unescape Escape