writeonce/docs/stories/language-runtime-database/06-program-mode-stdlib.md

2.3 KiB
Raw Blame History

Iteration 6 — program mode + systems stdlib

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

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).