shoney.arickathil
1fe808b7a4
- `readiness: ready | refine` is a SECOND axis, orthogonal to status.
`ready` = the brainstorm is complete and the decisions are LOCKED (a spec
approved, or the forks explicitly confirmed). `refine` = open forks remain
and it cannot be planned yet
- `status: refine` RETIRED because it carried both meanings at once, so a held
iteration with an approved spec (language 18, 26) was indistinguishable from
one nobody had thought about. status is now purely where the WORK is:
done | in-progress | pending | hold — `pending` was already the board's own
rendering word, so nothing new was invented
- all 47 iterations classified from EVIDENCE in their own text, not by guess:
"the four forks are SETTLED" / "spec + plan approved" / "Approved spec:" for
ready; "Forks the spec must settle" / "no spec exists yet" for refine. Every
shipped iteration is ready by definition. 19 done, 5 in-progress, 15
pending, 8 hold; 27 ready, 20 refine
- two iterations moved refine -> in-progress rather than -> pending: language
31 and 34 are absorbed into 24 and work on them is literally happening, which
the board already showed as 🔄 while their frontmatter said otherwise. That
disagreement is now gone
- board legend, board-views' frontmatter contract, and two new Dataview
queries updated — the useful one being `readiness: ready AND status:
pending`, the startable set
WHAT THE NEW AXIS IMMEDIATELY SURFACED: of 15 pending iterations, exactly ONE
is startable — databasev2 4, io_uring group-commit, whose forks were confirmed
settled 2026-08-20. Everything else pending needs a brainstorm first. That was
invisible while one key carried both meanings, and it is now on the board.
Also caught by the sweep, unrelated to readiness but found by cross-checking
frontmatter against the board: SIX duplicate rows. Every iteration moved into
databasev2 was still listed in the LANGUAGE pending table under its retired id
(23, 32, 33, 20, 21, 27) as well as its new one. Stale copies removed. And two
databasev2 rows made claims the sweep contradicts — iteration 1 was billed
"startable today" while its forks are open, and 6 still called itself the
ceiling-raiser after 2 took that role.
Docs only. linkcheck 0 broken / 0 anchors.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
86 lines
4 KiB
Markdown
86 lines
4 KiB
Markdown
---
|
||
iteration: "24"
|
||
status: in-progress
|
||
readiness: ready
|
||
chain: 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](00-story.md).
|
||
>
|
||
> **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](31-actor-lifecycle.md) (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](31-actor-lifecycle.md)
|
||
(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).
|