shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/language-runtime-database/06-program-mode-stdlib.md
shoney.arickathil c0b0dbb846 docs: audit all markdown against the code, fix findings, flatten status folders 
- README: shipped concurrency/HTTP/WebSockets sat in the roadmap as "not yet
  available"; "no package manager" contradicted [deps]; the deps example
  would not have compiled (the key IS the module name)
- runtime/README: leads with wovm, wo-rt.c demoted to a historical section;
  dropped 2 nonexistent recipes, crates/rt, @gc refcounting, 13 suites -> 18
- employee + log-watcher READMEs claimed "does not compile"; both are gates
- error catalog: +10 emitted codes incl WO-E250, the only diagnostic the
  shipped query surface raises; recorded why the sweep rotted
- language-surface: group-by parses, then the typechecker refuses it
- 00-code-review + 00-link-audit re-run; history kept, not rewritten
- 48 dead Rust-era exploration links de-linked rather than re-pointed (their
  prose names the retired plan by number); successor map -> discarded.md
- 08-project-structure: compiler/plan/ never existed; corpus has 9 dirs, 5 empty
- releasing.md: dropped a --draft step the workflow never had
- new docs/00-doc-audit.md: findings + disposition, incl one row where the
  audit was wrong and the doc it accused was right
- status folders removed: 34 stories flat, status only in frontmatter; 252
  links recomputed from resolved paths; board/board-views/structure retaught
- story 24 -> in-progress, since frontmatter is now the only truth
- new iteration 38: fs mutation verbs + net.connect, the two capability
  families no iteration owned
- new iteration 39: gofiber/fiber v3.5.0 parity study. The ledger called
  CSRF/sessions unblocked by iteration 34's HMAC, but the runtime has no
  source of randomness at all
- linkcheck skips .dev/.superpowers: 0 broken paths, 0 bad anchors

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 19:20:22 +02:00

3.1 KiB
Raw Blame History

iteration status
6 done

Iteration 6 — program mode + systems stdlib

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Status (2026-08-14): ✅ landed for the surface the driving workload uses — program mode (fn main(args: multi Text) -> Int, argv from the runtime, the return value as the exit code), the text/container builtins, and the OS half (fs, time, env, net, proc) with predeclared Stat/TimeParts/ Proc records, plus json encode/decode over .wob v2 class metadata. What the workload never calls was not written. Two lifetime defects found here are being fixed as part of plan/compiler/2026-08-14-logwatcher-executable.md: the runtime's own argv container is never freed, and blocking accept/read ignore the stop signal.

Goals

  • writeonce stops being server-only: a project with a free fn main(args) -> Int compiles as a CLI program with exit codes — the daemon/tool shape log-watcher represents.
  • Five typed builtin modules — fs, proc, net, time, json — give programs system access with no FFI hole: bounded reads, args-array-only process runs, TCP listen/accept, monotonic time, typed JSON decode.
  • Every handle is an owned object whose drop closes it: RAII from the ownership model, leaked fds impossible by construction.

Acceptance Criteria

  • What to achieve?
    • Given a program with fn main,
    • when wo run executes it and woc build packages it,
    • then the return value propagates as the process exit code in both forms, and SIGTERM flips env.stopping() without any callback machinery.
  • What to achieve?
    • Given the stdlib corpus against real resources (tempdir files, rename-simulated rotation, spawned trivial processes, loopback sockets),
    • when the suite runs under ASan,
    • then all fixtures pass, and the fd-battery fixture (open many handles in a loop) shows no fd-count growth.
  • What to achieve?
    • Given a JSON document missing optional fields or shaped wrongly,
    • when json.decode … as Record runs,
    • then missing optionals decode as nil, shape mismatches yield nil overall, and no trap fires — expected absence is data, not error.

Out Of Scope

  • The log-watcher sample itself (iteration 7 proves this slice).
  • UDP/TLS, fs mutation beyond append, signal callbacks, worker threads.

Info

  • One API, two disciplines: the same stdlib calls are blocking in program mode and loop-integrated on server shards — no async keyword exists.
  • Spec: docs/superpowers/specs/2026-08-01-systems-track-design.md Parts 2–3.

Proposed Solution

  • Execute the existing plan: docs/superpowers/plans/2026-08-01-program-mode-stdlib.md (program entry + env module, time, fs with inode stat + bounded read_at, proc.run with capped capture, net RAII handles, typed json, sys corpus battery in the oop-accept gate).