From 64a47001907ec709393c9ea319c2b011c73770e2 Mon Sep 17 00:00:00 2001 From: "shoney.arickathil" Date: Sat, 22 Aug 2026 23:30:55 +0200 Subject: [PATCH] docs: reconcile story 34 + gates with merged master MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/00-dependency-graph.md | 6 +++--- docs/examples/writeonce-framework/README.md | 10 +++++----- .../refine/34-crypto-builtins.md | 18 ++++++++++-------- 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/00-dependency-graph.md b/docs/00-dependency-graph.md index ec3e29e..6aefa4c 100644 --- a/docs/00-dependency-graph.md +++ b/docs/00-dependency-graph.md @@ -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 diff --git a/docs/examples/writeonce-framework/README.md b/docs/examples/writeonce-framework/README.md index 4dd6220..588b043 100644 --- a/docs/examples/writeonce-framework/README.md +++ b/docs/examples/writeonce-framework/README.md @@ -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 diff --git a/docs/stories/language-runtime-database/refine/34-crypto-builtins.md b/docs/stories/language-runtime-database/refine/34-crypto-builtins.md index 4b060ab..e583676 100644 --- a/docs/stories/language-runtime-database/refine/34-crypto-builtins.md +++ b/docs/stories/language-runtime-database/refine/34-crypto-builtins.md @@ -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.