shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: goal shift — log-watcher (met) to web framework as library

Browse source 
- NEXT PLAN rewritten: iteration 17 is the goal slice (merge branch, spec/
  plan, kind = "library", internal/ WO-E1xx, framework reorg, gate list)
- previous NEXT PLAN retitled "Landed 2026-08-15 — the executable milestone";
  all six measured items were already done, board rows were stale
- board row 7: in-progress -> landed 2026-08-15 (ASan-clean, SIGTERM, fd-flat,
  soak, just log-watcher 7/0); iteration 07 story banner updated to match
  its plan doc's done banner
- in-progress table now carries iteration 17 spec/plan
- implementation order re-sequenced for framework goal: 17, 9c/9d, 9e, 8,
  9f, 11 (+ h2c unparks), 10, 12, then 14/9g demoted (skillhost no longer
  the driving workload), 13 + parked drain last
- story notes record the shift and the new order

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
shoney.arickathil 2026-08-20 02:04:41 +02:00
parent f59f4e3131
commit b32e8a5073
3 changed files with 93 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

128
docs/00-status.md
View file

@ -19,15 +19,44 @@ Statuses: ✅ **done** · 🔄 **in progress** · ⬜ **pending** · ⏸ **hold*
## ▶ NEXT PLAN
**Make log-watcher executable — nothing else.** The compile-and-run half of the
language track is met (2026-08-14): the sample compiles with zero diagnostics,
`woc build` produces a 106 KB standalone binary, and all three modes work —
`watch` alerts on a live file, `run` schedules a cron.d entry, `mcp` answers
JSON-RPC with all four tools returning `isError:false`. `just log-watcher`
gates it: 6 checks, 0 failures.
**The web framework becomes a first-class library — iteration 17.** The goal
shifted 2026-08-20: the previous NEXT PLAN ("make log-watcher executable —
nothing else") was met in full 2026-08-15 (milestone record below), and the
driving workload is now `docs/examples/writeonce-framework` consumed by
`docs/examples/web-app` through `[deps]`. Iteration 17's forks are settled
(decisions + framework/compiler/VM/GC impact in
[the iteration](stories/language-runtime-database/17-library-projects-internal.md));
what remains, in order:
What is left is the difference between "it runs" and "you can leave it
running", and every item below came from a measurement on the sample itself:
1. Merge the `web-framework` branch to master (iterations 15–17 docs + code,
local only).
2. Spec + plan from the settled decisions (prose only, per convention).
3. `kind = "library"` in `wo.toml` (default `"program"`): `woc <dir>` on a
library runs the FULL pipeline as a check — parse, typecheck, borrow
check, GC inference — with no entry required; an explicit build still
works when a `main` exists (dual lib+bin).
4. The `internal/` rule at the `[deps]` boundary: a consumer `use` of a dep
path containing the segment `internal` is a new WO-E1xx at the `use`,
naming the dependency; inside the dep it stays legal.
5. Framework reorg: request-parser and serve-loop plumbing move under
`internal/`; the public surface (`Handler`, `Middleware`, `App`,
`Req`/`Resp`, builders) does not move.
6. Gate: `just web-app` stays 14/0, plus new checks — library check without
an entry succeeds, a consumer `internal` import is refused, and the
iteration-16 `--emit` verification workaround is deleted.
The VM and GC are untouched by design — visibility is compile-time name
resolution, libraries compile whole-program into the consumer's image, and
GC inference stays whole-program (app usage may promote dep classes; that is
intended).
---
### Landed 2026-08-15 — the executable milestone (the previous NEXT PLAN)
"Make log-watcher executable" — the difference between "it runs" and "you
can leave it running". Every item came from a measurement on the sample
itself, and all six landed:
1. ~~The ownership pass does not know what the stdlib returns~~ — **done
2026-08-14**. The root cause was deeper than the table: `Text` was
@ -93,10 +122,12 @@ Story slice: [`docs/stories/language-runtime-database/07-logwatcher-proof.md`](s
- Iterations 8–12 (shard-actor runtime, database engine, `@table`/query, HTTP
layer, fibers, blue-green): unchanged, and unblocked by this plan.
The project is the **language track**: iterations 3 → 4 → 5 → 6 → 7, ending at
_compile and run log-watcher_, then the database engine (9/9b) and beyond. (The
prior Rust `wo` runtime was removed from the repo 2026-08-18 — see
[`discarded.md`](plan/discarded.md).)
The **language track**'s first goal — iterations 3 → 4 → 5 → 6 → 7, _compile
and run log-watcher_ — is met; the database engine (9/9b), deps (15), and the
web framework (16) landed on top of it. The goal is now the framework line:
iteration 17 first, then the runtime iterations that mature it (see
"Implementation order" under Pending). (The prior Rust `wo` runtime was
removed from the repo 2026-08-18 — see [`discarded.md`](plan/discarded.md).)
---
@ -115,7 +146,7 @@ that sequences its tasks. Read one, approve, then the next starts.
| 4 | [Single binary end-to-end](stories/language-runtime-database/04-single-binary-e2e.md) | ✅ (known gaps below) |
| 5 | [Language surface](stories/language-runtime-database/05-language-surface.md) | 🔄 grammar done; **`?T` forced handling ✅ + reject rows ✅ + WO-E205 ✅ (2026-08-18)**; `pub(read)`/`using`/`#if` still ⏸ |
| 6 | [Program mode + stdlib](stories/language-runtime-database/06-program-mode-stdlib.md) | ✅ (the surface log-watcher uses) |
| 7 | [log-watcher proof](stories/language-runtime-database/07-logwatcher-proof.md) | 🔄 **runs; executable in progress** |
| 7 | [log-watcher proof](stories/language-runtime-database/07-logwatcher-proof.md) | ✅ **landed 2026-08-15** — executable, not merely compilable: zero ASan leaks in all three modes, SIGTERM ends parked syscalls, fds flat, `LW_SOAK` gate; `just log-watcher` 7/0 |
| 7b | [Inferred GC + mark-sweep](stories/language-runtime-database/07b-inferred-gc-mark-sweep.md) | ✅ **landed 2026-08-18** — `@gc` gone (WO-E104), GC-ness inferred, RC replaced by incremental mark-sweep, `.wob` v4; supersedes iteration 2's RC memory model |
| 8 | [Shard-actor runtime](stories/language-runtime-database/08-shard-actor-runtime.md) | ⬜ |
| 9 | [Database engine](stories/language-runtime-database/09-database-engine.md) | 🔄 engine complete (storage/WAL/indexes/insert-update-delete); reads land with 9b |
@ -140,9 +171,10 @@ that sequences its tasks. Read one, approve, then the next starts.
| Track | Item | Where |
| -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Language | Iteration 7 — make log-watcher executable (leaks, stop signal, fd lifetime, soak) | [executable plan](plan/compiler/2026-08-14-logwatcher-executable.md) |
| Language | Iteration 17 — web framework as first-class library: spec/plan from the settled forks, then `kind = "library"` + `internal/` + framework reorg | [iteration 17](stories/language-runtime-database/17-library-projects-internal.md) |
Off-critical-path work is parked by explicit scope directive (2026-08-08).
Off-goal work is parked; the goal shifted 2026-08-20 from log-watcher (met)
to the web framework as a first-class library.
### Landed 2026-08-14 — the compile-and-run milestone
@ -305,40 +337,42 @@ The C proving-ground work (`exploration/c-runtime/`, phases A–F: 859k reads/s,
## Pending
### Implementation order (sequenced 2026-08-20)
### Implementation order (re-sequenced 2026-08-20 — framework goal)
Dependency-derived order for everything not yet landed. Rules that force it:
9f explicitly after 8 + 9e; 9c "precedes iteration 10"; 9d's plan folds into
9c's; 12 only after 9 + 10 (catalog to diff, HTTP to build on); 11 rides 8's
shard scheduler; h2c parked behind 8/9f/11; the post-12 parked list stays
parked by the 2026-08-08 scope directive.
The goal is the web framework as a first-class library, so the framework
line leads and the workload-driven extras (14, 9g) demote behind it.
Dependency rules that force the shape: 9f explicitly after 8 + 9e; 9c
"precedes iteration 10"; 9d's plan folds into 9c's; 12 only after 9 + 10
(catalog to diff, HTTP to build on); 11 rides 8's shard scheduler; h2c
parked behind 8/9f/11; the post-12 parked list stays parked by the
2026-08-08 scope directive. (Iteration 7 dropped from this list — landed
2026-08-15.)
1. **7 finish** — in progress (executable plan: leaks, stop signal, fd
lifetime, soak); the locked critical path ends here.
2. **17** — forks settled, compiler-driver-only, no runtime deps; kills the
framework's `--emit` wart while iteration 16 is fresh. (Merge the
`web-framework` branch first.)
3. **9g** — likely collapses to "confirm `len(query)` + add `exists`"; the
skillhost corpus already showed no new grammar; do before 14 consumes it.
4. **14** — skillhost port, the next driving workload (log-watcher's role for
host capabilities); stdlib-shaped, independent of shards;
bounded-subprocess gap first.
5. **9c then 9d** — finish the half-done branches (ipc-attach: manifest +
binding; keypair-auth: manifest) while DB context is warm; 9d folds into
9c's plan; both must precede 10.
6. **9e** — the measurement backbone; baseline single-shard BEFORE the
runtime restructure so 8/9f have numbers to sign against.
7. **8** — shard-actor; the big structural move; precondition (collector
settled, 7b) already met; unblocks 9f, 11, h2c.
8. **9f** — io_uring group-commit; explicitly after 8 + 9e.
9. **11** — fibers on the shard scheduler; keeps VM-core work contiguous
with 8/9f (same dispatch/io seams).
10. **10** — HTTP service layer; after 9c by its own precedence note;
lowers `service` blocks onto the iteration-16 framework.
11. **12** — blue-green; prerequisites 9 + 10 now exist.
12. **13 + parked drain** — metaprogramming (spec first), then h2c,
group-by, `pub(read)`/`using`/`#if`, ADT roster, WO-E225 — all held
behind 12 by the scope directive.
1. **17** — THE goal slice: `kind = "library"` + `internal/` + framework
reorg; forks settled, compiler-driver-only, no runtime deps. Merge the
`web-framework` branch first.
2. **9c then 9d** — finish the half-done branches (ipc-attach: manifest +
binding; keypair-auth: manifest) before they rot; 9d folds into 9c's
plan; both must precede 10.
3. **9e** — the measurement backbone; baseline single-shard BEFORE the
runtime restructure so 8/9f/11 sign against real numbers.
4. **8** — shard-actor; the framework's multi-core serving story; unblocks
9f, 11, h2c.
5. **9f** — io_uring group-commit; explicitly after 8 + 9e.
6. **11** — fibers; retires the framework's disclosed keep-alive limit (an
idle connection starving accept forced close-when-idle in iteration 16 —
parked fds fix it properly); with 8 + 9f done, **h2c unparks** (spec §C)
as the framework's HTTP/2 slice.
7. **10** — HTTP service layer; after 9c by its own precedence note;
`service` blocks lower onto the framework instead of a parallel stack.
8. **12** — blue-green; prerequisites 9 + 10 now exist; completes the
framework's deploy story.
9. **14 and 9g** — demoted with the goal shift: skillhost is no longer the
driving workload; 9g likely collapses to "confirm `len(query)` + add
`exists`" and precedes 14 when they run.
10. **13 + parked drain** — metaprogramming (spec first), then group-by,
`pub(read)`/`using`/`#if`, ADT roster, WO-E225 — held behind 12 by the
scope directive.
### Language track — sequenced, on the critical path

10
docs/stories/language-runtime-database/00-story.md
View file

@ -89,10 +89,12 @@ list, and a pointer to the plan document that already sequences its tasks.
- **Critical path (locked 2026-08-08): compile and run log-watcher.**
Iterations 3 → 4 → 5 → 6 → 7 are the committed line; nothing off that
line lands before iteration 7's acceptance. Then 7b, then 8–12 (with 9b after the database engine).
- **Implementation order re-sequenced 2026-08-20** for everything still
pending: 7-finish → 17 → 9g → 14 → 9c/9d → 9e → 8 → 9f → 11 → 10 → 12 →
13 + parked drain. Rationale and forcing dependencies live in
[`docs/00-status.md`](../../00-status.md) under "Implementation order".
- **Goal shifted 2026-08-20: log-watcher (iteration 7, landed 2026-08-15)
to the web framework as a first-class library.** Implementation order for
everything still pending: 17 → 9c/9d → 9e → 8 → 9f → 11 (+ h2c unparks) →
10 → 12 → 14/9g → 13 + parked drain. Rationale and forcing dependencies
live in [`docs/00-status.md`](../../00-status.md) under "Implementation
order".
- **Iteration 7b (inserted 2026-08-11)** sits after the critical path
deliberately: it delays nothing on the log-watcher line, and it must precede
iteration 8 because the collector should be settled before shards multiply.

14
docs/stories/language-runtime-database/07-logwatcher-proof.md
View file

@ -13,14 +13,12 @@
systems track's acceptance bar: nothing in a real daemon exceeded the
language.
> **Status (2026-08-14):** the compile-and-run half is **met** — the sample
> compiles with zero diagnostics, `woc build` produces a 106 KB standalone
> binary, and all three modes work (`watch` alerts, `run` schedules a cron.d
> entry, `mcp` answers JSON-RPC with all four tools returning `isError:false`).
> The remaining half is **executable**: under ASan both long-running modes leak
> (watch 128 B, run >1 MB in eight seconds), the MCP server never closes an
> accepted connection, and a server parked in `accept` ignores SIGTERM. That
> work is sequenced in
> **Status: ✅ landed 2026-08-15.** Compile-and-run met 2026-08-14 (zero
> diagnostics, 106 KB standalone binary, all three modes work); the
> executable half landed 2026-08-15 — zero ASan leaks in all three modes,
> SIGTERM ends parked syscalls, fds flat across 200 requests, and the
> `LW_SOAK` gate holds RSS/descriptors flat under sustained load.
> `just log-watcher`: 7 checks, 0 failures. The work is recorded in
> [`plan/compiler/2026-08-14-logwatcher-executable.md`](../../plan/compiler/2026-08-14-logwatcher-executable.md)
> and nothing else blocks this iteration.