docs: reconcile story 34 + gates with merged master

- story 34: premise fixed — iteration 36 landed bitwise/hex, digests
  and HMAC now expressible in pure .wo; C-builtin vs pure-.wo is the
  story's brainstorm call, not an impossibility
- dependency graph: crypto gate names story 34; net-seam gate names
  story 35; radix gate corrected — 22 benched the DB, router scan
  still unmeasured, perf-targets entry first
- framework README ledger: timeouts/unix/peer rows point at story 35;
  ETag row at story 34; path-matching row repointed off iteration 22

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
shoney.arickathil 2026-08-22 23:30:55 +02:00
parent ee018f06e2
commit 64a4700190
3 changed files with 18 additions and 16 deletions

View file

@ -160,12 +160,12 @@ flowchart TD
XFF["X-Forwarded-For/-Proto parsing"]:::ready
ACCEPT["Accept-driven negotiation"]:::ready
NETSEAM["GATE: net runtime seams (timeouts, unix socket, peer address)"]:::gate
NETSEAM["GATE: net runtime seams (timeouts, unix socket, peer address) — story 35 owns"]:::gate
TMOUT["read/write/idle timeouts"]:::blocked
UNIX["unix socket binding"]:::blocked
PEERV["trusted-proxy PEER verification"]:::blocked
CRYPTO["GATE: crypto fork — C builtins vs language bit ops (brainstorm); digests want iteration 19's Bytes"]:::gate
CRYPTO["GATE: story 34 crypto — C builtins vs pure-.wo (bitwise landed with 36, both possible; brainstorm decides); carriers (Bytes, base64) landed with 19"]:::gate
SHA["SHA-256/512, HMAC, CRC32"]:::blocked
ETAG["ETag + conditional requests"]:::blocked
COOKIE["signed cookies"]:::blocked
@ -175,7 +175,7 @@ flowchart TD
JWT["JWT HS256 (HARD STOP after)"]:::blocked
RADIX["radix-tree routing"]:::blocked
I9E3["GATE: 22 measures the linear scan"]:::gate
I9E3["GATE: router scan unmeasured — 22's harness landed but benched the DB, not the router; perf-targets entry first"]:::gate
STORAGE["storage-integration rows: migrations (future story), eager loading + tenant roots (query-surface work, 9-series)"]:::blocked

View file

@ -82,16 +82,16 @@ first (pure `.wo` cannot express it yet).
| --- | --- |
| HTTP/1.1 parsing | 🔶 parses + 400-and-survive; STRICT ambiguity rejection (duplicate/conflicting `Content-Length`, oversize checks beyond BODY_MAX) not audited — hardening slice |
| Keep-alive | ✅ pipelined-serve / close-when-idle (arc landed 2026-08-21; retirement of close-when-idle rides iteration 24's fiber-per-connection slice) |
| Read/write/idle timeouts | 🔧 `net` has no timeout surface — runtime seam, then a framework knob |
| Read/write/idle timeouts | 🔧 `net` has no timeout surface — story 35 owns the seam (park_deadline infra already exists for sleeps), then a framework knob |
| Request size limits | ✅ BODY_MAX bounds headers AND body |
| Unix socket binding | 🔧 `net.listen` is TCP-only — runtime seam |
| Unix socket binding | 🔧 `net.listen` is TCP-only — story 35 owns the seam |
| Graceful SIGTERM | ✅ in-flight request completes (blocking model), listener + fds closed, storage is per-commit durable (WAL fdatasync — nothing to checkpoint) |
### Routing
| Item | State |
| --- | --- |
| Path matching | 🔶 linear scan, first-match-wins; a radix tree is a performance slice that waits for iteration 22 to MEASURE it first |
| Path matching | 🔶 linear scan, first-match-wins; a radix tree waits on a MEASUREMENT first — 22's harness landed (benched the DB, not the router); needs a perf-targets register entry |
| Method dispatch · path params · 404 · 405+`Allow` | ✅ |
| Wildcards | ⬜ only `:param` today; `*rest` capture is a candidate slice |
| Precedence rules | 🔶 registration order IS the rule (documented); specificity-based precedence unneeded until wildcards exist |
@ -104,10 +104,10 @@ first (pure `.wo` cannot express it yet).
| Case-insensitive headers · query parsing | ✅ (names lowercased on read) |
| JSON · form-urlencoded · multipart | ✅ all three hooks (`json.decode`, `form_values`, `multipart_parts`) |
| Content negotiation | 🔶 `media_type(req)` covers the request side; `Accept`-driven response negotiation ⬜ |
| Trusted-proxy client IP | 🔶 `X-Forwarded-For/-Proto` parsing is expressible (candidate slice); VERIFYING the peer is the trusted proxy needs a peer-address runtime seam 🔧 |
| Trusted-proxy client IP | 🔶 `X-Forwarded-For/-Proto` parsing is expressible (candidate slice); VERIFYING the peer is the trusted proxy needs a peer-address seam 🔧 — story 35 owns it |
| Status/header setting · redirects | ✅ builders + `set_header` |
| Lazy body streaming + backpressure · streaming responses · explicit commit point | ⏸ UNBLOCKED by the arc (8/11 landed 2026-08-21) — stays parked until its own slice |
| ETag + conditional requests | ⬜ candidate; wants the crypto slice's hashing |
| ETag + conditional requests | ⬜ candidate; wants story 34's digests (bitwise landed with 36 — pure-`.wo` vs C-builtin is 34's brainstorm) |
### Context & middleware

View file

@ -9,13 +9,14 @@ status: refine
> [Story — one language, one runtime, one database, one binary](../00-story.md).
>
> **Inserted 2026-08-22** — the framework ledger's oldest unowned gap
> gets an owner. The language has NO bitwise operators (a settled
> surface decision), so digests cannot be written in `.wo`; the
> ledger's recorded resolution stands: hand-rolled C builtins in the
> runtime — the libc-only doctrine permits hand-rolled crypto, and the
> code is bounded and well-specified. Off the concurrency chain but
> **gates chain position 4**: iteration 24's WebSocket handshake needs
> SHA-1 before chat can land.
> gets an owner. PREMISE UPDATE (same day, post-merge): iteration 36
> landed bitwise `& | ^ << >>` + hex literals, so digests ARE now
> expressible in pure `.wo` — the original "no bitwise" impossibility
> is gone. The fork is now a real choice for this story's brainstorm:
> hand-rolled C builtins (bounded, fast, libc-only doctrine permits) vs
> pure-`.wo` (no runtime surface growth; interpreter-speed hashing).
> Off the concurrency chain but **gates chain position 4**: iteration
> 24's WebSocket handshake needs SHA-1 before chat can land.
## Why this iteration exists
@ -37,7 +38,8 @@ only the digests are missing.
existing builtin).
- **HMAC-SHA256** (`key: Bytes, msg: Bytes -> Bytes`) — the one
composition real services need (signed tokens, webhook signatures);
writing HMAC in `.wo` is impossible for the same no-bitwise reason.
expressible in `.wo` since iteration 36's bitwise set — C-builtin vs
pure-`.wo` is this story's brainstorm call.
- **Test vectors are the acceptance**: FIPS 180 / RFC 2202 / RFC 4231
vectors in a corpus fixture — a digest that "looks right" is worth
nothing.