From a80356c3d86080ec434560d836ad07ba211dae9c Mon Sep 17 00:00:00 2001 From: "shoney.arickathil" Date: Thu, 20 Aug 2026 04:13:49 +0200 Subject: [PATCH] docs: dependency graphs for iterations + framework features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/00-dependency-graph.md: three mermaid graphs — story iterations (hard edges only; 18 is the only spec-approved node with all prerequisites green), framework v1 ledger items (three recurring gates: net seams, crypto fork, iterations 8/11; nine slices startable today in any order), framework v2 internals (cache/flags independent, transaction{} is the critical path, jobs compose on it) - maintenance rule: node classes update in the same change as board rows - board links the graph up top; spec 18 banner -> APPROVED, plan next Co-Authored-By: Claude Opus 5 (1M context) --- docs/00-dependency-graph.md | 178 ++++++++++++++++++ docs/00-status.md | 6 +- .../2026-08-20-memory-db-features-design.md | 3 +- 3 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 docs/00-dependency-graph.md diff --git a/docs/00-dependency-graph.md b/docs/00-dependency-graph.md new file mode 100644 index 0000000..003a6f8 --- /dev/null +++ b/docs/00-dependency-graph.md @@ -0,0 +1,178 @@ +# Dependency graphs — iterations and framework features + +> Companion to [00-status.md](00-status.md) (states live THERE; this page +> carries the edges). An arrow `A --> B` means **A must exist before B**. +> Use it to pick the next implementation: anything whose incoming arrows +> are all green is startable today. Updated 2026-08-20. + +## 1. Story iterations + +Hard dependencies only — edges that force order. The CHOSEN order among +startable nodes (9e before 8 so the restructure has a baseline; 9c/9d +before 10 goes 9c-first because 9d folds into 9c's plan) lives in +00-status.md's "Implementation order". + +```mermaid +flowchart TD + classDef done fill:#1a7f37,color:#fff,stroke:none + classDef parked fill:#6e7781,color:#fff,stroke:none + classDef specd fill:#0969da,color:#fff,stroke:none + classDef open fill:#eac54f,color:#000,stroke:none + + I7["7 log-watcher proof"]:::done + I7b["7b inferred GC + mark-sweep"]:::done + I9["9 database engine"]:::done + I9b["9b @table + query"]:::done + I15["15 deps package manager"]:::done + I16["16 web framework v1 core"]:::done + + I17["17 library kind + internal/ (PARKED, spec+plan ready)"]:::parked + I18["18 framework v2: transaction{} + cache/flags/jobs (spec APPROVED)"]:::specd + + I9c["9c cross-program tables (half-built)"]:::open + I9d["9d keypair attach auth (half-built)"]:::open + I9e["9e durability + throughput baseline"]:::open + I8["8 shard-actor runtime"]:::open + I9f["9f io_uring group-commit"]:::open + I10["10 HTTP service layer"]:::open + I11["11 fibers"]:::open + I12["12 blue-green deploy"]:::open + I13["13 metaprogramming @derive"]:::open + I14["14 skillhost workload (demoted)"]:::open + I9g["9g query grammar corpus (likely collapses)"]:::open + H2C["h2c HTTP/2 cleartext (spec §C)"]:::open + + I15 --> I17 + I16 --> I17 + I9 --> I18 + I16 --> I18 + I9 --> I9c + I9c --> I9d + I9c --> I10 + I16 --> I10 + I9b --> I9e + I7b --> I8 + I9e --> I9f + I8 --> I9f + I8 --> I11 + I9 --> I12 + I10 --> I12 + I8 --> H2C + I9f --> H2C + I11 --> H2C + I9g --> I14 + I7 --> I14 +``` + +Reading it: **18 is the only spec-approved open node with all +prerequisites green** — it is the next implementation. After 18: 9c/9d +and 9e are startable in parallel-in-principle (order chosen: 9c/9d +first, half-built branches rot). 13 has no incoming edges but is +scope-directive-parked behind 12. 17 unparks whenever directed — its +prerequisites landed and its spec+plan sit on branch `library-internal`. + +## 2. Framework v1 — remaining ledger items + +What each open ledger row waits on. Three gates recur: **net seams** +(runtime `net` builtins), the **crypto fork** (the language has no +bitwise operators — hashes become C runtime builtins or bit ops land +first; brainstorm before the slice), and **runtime iterations 8/11**. + +```mermaid +flowchart TD + classDef gate fill:#8250df,color:#fff,stroke:none + classDef ready fill:#1a7f37,color:#fff,stroke:none + classDef blocked fill:#eac54f,color:#000,stroke:none + + READY["startable today, pure .wo"]:::ready + CORS["CORS middleware"]:::ready + SECH["security-headers middleware"]:::ready + HOSTV["host validation"]:::ready + STRICT["strict-parsing audit (dup/conflicting Content-Length)"]:::ready + WILD["wildcard segments *rest"]:::ready + PREC["specificity precedence"]:::blocked + GROUPS["route groups"]:::ready + CTX["req.ctx bag"]:::ready + XFF["X-Forwarded-For/-Proto parsing"]:::ready + ACCEPT["Accept-driven negotiation"]:::ready + + NETSEAM["GATE: net runtime seams (timeouts, unix socket, peer address)"]:::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)"]:::gate + SHA["SHA-256/512, HMAC, CRC32"]:::blocked + ETAG["ETag + conditional requests"]:::blocked + COOKIE["signed cookies"]:::blocked + CSRF["CSRF"]:::blocked + SESS["session integrity"]:::blocked + HOOKV["webhook verification"]:::blocked + JWT["JWT HS256 (HARD STOP after)"]:::blocked + + RT811["GATE: iterations 8/11 (shards, fibers)"]:::gate + STREAM["body streaming + backpressure"]:::blocked + SRESP["streaming responses + commit point"]:::blocked + CANCEL["per-request cancellation"]:::blocked + PUBSUB["pub/sub + WebSockets"]:::blocked + + RADIX["radix-tree routing"]:::blocked + I9E2["9e measures the linear scan"]:::gate + + WILD --> PREC + NETSEAM --> TMOUT + NETSEAM --> UNIX + NETSEAM --> PEERV + CRYPTO --> SHA + SHA --> ETAG + SHA --> COOKIE + SHA --> CSRF + SHA --> SESS + SHA --> HOOKV + SHA --> JWT + RT811 --> STREAM + RT811 --> SRESP + RT811 --> CANCEL + RT811 --> PUBSUB + I9E2 --> RADIX +``` + +The green column (CORS, security headers, host validation, strict-parsing +audit, wildcards, route groups, `req.ctx`, XFF parsing, Accept +negotiation) needs nothing — each is a framework-v1 slice startable in +any order, gated by `just web-app`. + +## 3. Framework v2 (iteration 18) — internal order + +```mermaid +flowchart TD + classDef piece fill:#0969da,color:#fff,stroke:none + classDef indep fill:#1a7f37,color:#fff,stroke:none + classDef later fill:#eac54f,color:#000,stroke:none + + TXN["transaction{} (engine undo log + language block)"]:::piece + JOBS["jobs.wo: wf_jobs + enqueue + JobRunner + idle() drain"]:::piece + DEMO["web-app demo: transactional order+confirm, GET /jobs, flags route"]:::piece + CACHE["cache.wo: TTL + FIFO"]:::indep + FLAGS["flags.wo: wf_flags + read-through map"]:::indep + TPRMW["txn-per-request middleware (v1 ledger's storage row)"]:::later + FIBJ["fiber-scheduled jobs"]:::later + I11B["iteration 11"]:::later + + TXN --> JOBS + JOBS --> DEMO + FLAGS --> DEMO + TXN --> TPRMW + I11B --> FIBJ + JOBS --> FIBJ +``` + +Cache and flags have no dependencies — they can land first as warm-up +slices; `transaction { }` is the critical path (the only engine + +language work), jobs compose on it, the demo and gate close it out. + +## Maintenance rule + +When an iteration or slice lands, update its node's class here in the +same change that moves the board row — the two documents answer +different questions (status vs. edges) and drift kills both. diff --git a/docs/00-status.md b/docs/00-status.md index 07ec889..4005b07 100644 --- a/docs/00-status.md +++ b/docs/00-status.md @@ -1,5 +1,9 @@ # Status board — what is done, what is next +Edges live in [00-dependency-graph.md](00-dependency-graph.md) — mermaid +graphs of iteration and feature dependencies; anything with all-green +incoming arrows is startable. This board carries the STATES. + The single place to learn where this project stands. Organised in six buckets: **stories** (the narrative arc), **in progress**, **done**, **pending**, **discarded**, **learnings**. The buckets are **sections of this board, not @@ -177,7 +181,7 @@ that sequences its tasks. Read one, approve, then the next starts. | 15 | [deps: `wo.toml [deps]`](stories/language-runtime-database/15-deps-package-manager.md) | ✅ **landed 2026-08-18** (branch web-framework): [deps] inline tables, git-binary fetch, wo.lock pinning, offline-when-locked, --update-deps, WO-E106/E107; `just deps-accept` 8/0 | | 16 | [web framework](stories/language-runtime-database/16-web-framework.md) | ✅ **landed 2026-08-19** — writeonce-framework (HTTP/1.1 + router + Handler/Middleware) consumed by web-app through [deps]; h2c parked (§C) behind 8/9f/11. **v1 polish landed 2026-08-20** (branch framework-v1): get/post/put/delete_ helpers, 405+Allow, HEAD, Logging middleware, set_header; `just web-app` 16/0; fixed the interp-borrowed-field emitter crash en route. **Auth-in-core landed 2026-08-20**: http/auth.wo (Bearer/Basic, ct_eq, req.principal), web-app dogfoods BearerAuth, gate 17/0 | | 17 | [library projects + `internal/`](stories/language-runtime-database/17-library-projects-internal.md) | ⏸ **PARKED 2026-08-20** (developer directive; framework v1 first) — forks settled, spec + plan approved and ready on branch `library-internal`: kind = "library" key; Go internal/ rule, dep-boundary-only; lib+bin dual; VM/GC untouched by design | -| 18 | [framework v2: memory-rich features](stories/language-runtime-database/18-memory-db-features.md) | 🔄 **spec written 2026-08-20, awaiting review** ([spec](superpowers/specs/2026-08-20-memory-db-features-design.md)): TTL cache + @table flags + durable job queue (drain-on-request) + `transaction { }` over the WAL's staged batch; pub/sub REJECTED until 8/11 | +| 18 | [framework v2: memory-rich features](stories/language-runtime-database/18-memory-db-features.md) | 🔄 **spec APPROVED 2026-08-20, plan next** ([spec](superpowers/specs/2026-08-20-memory-db-features-design.md)): TTL cache + @table flags + durable job queue (drain-on-request) + `transaction { }` over the WAL's staged batch; pub/sub REJECTED until 8/11 | --- diff --git a/docs/superpowers/specs/2026-08-20-memory-db-features-design.md b/docs/superpowers/specs/2026-08-20-memory-db-features-design.md index 60d8b39..e77bc31 100644 --- a/docs/superpowers/specs/2026-08-20-memory-db-features-design.md +++ b/docs/superpowers/specs/2026-08-20-memory-db-features-design.md @@ -4,7 +4,8 @@ > the framework README's status ledger; this spec is what the embedded > store adds on top of it. > -> **Status: spec, awaiting review (2026-08-20).** Decisions were settled in +> **Status: APPROVED 2026-08-20** (developer review). Plan next. +> Decisions were settled in > [the iteration](../../stories/language-runtime-database/18-memory-db-features.md); > this spec makes them buildable. The plan follows after review. > Board: [docs/00-status.md](../../00-status.md).