sx/current/PLAN-IO-UNIFY.md

PLAN-IO-UNIFY — fold the fiber scheduler behind context.io, re-home race

Why

Today there are two parallel async stacks:

stack	behind context.io?	real suspension?	cancellation channel
io.sx async/await/cancel/Future	yes (impl Io for CBlockingIo)	no — runs the worker inline to completion	suspend_raw -> ! / IoErr.Canceled (designed, unused)
sched.sx go/wait/cancel/race (just landed)	no	yes (swap_context fibers)	none — suspend_self -> void

context.io is structurally Zig's std.Io (an Io protocol carried implicitly in Context — better ergonomics than Zig's explicit io: param), and the roadmap (§A5, §4.6) already says the fiber scheduler should be one of its Io vtables and that race is context.io.race(..) over Futures. The just-landed race on sched.Scheduler over *Task is the proven LOGIC at the wrong LAYER.

Goal: make the fiber Scheduler an impl Io, lift async/await/cancel/race onto the Io protocol so they run colorblind under either impl, and let cancellation fall out of the existing suspend_raw -> ! contract (the "true cancellation, model A" the user picked — already the interface's design). One async stack, behind context.io.

The fiber → Io mapping (the crux)

Io :: protocol { spawn_raw, suspend_raw -> !, ready, poll, now_ms, arm_timer } (core.sx). Map each onto the existing fiber primitives in sched.sx (spawn/suspend_self/wake/sleep/block_on_fd/run):

Io method	fiber realization
spawn_raw(entry, arg, opts) -> *void	spawn a fiber whose body invokes entry(arg) (raw C-ABI thunk, not a closure — see Bridge below). Returns the *Fiber as the opaque handle.
suspend_raw(park) -> !	suspend_self(), then on resume CHECK the current task's cancel flag and raise IoErr.Canceled if set. park.handle = the *Fiber to re-ready. This is the cancellation delivery point.
ready(park)	wake(park.handle as *Fiber) (already guarded on .suspended).
arm_timer(deadline_ms, park) -> *void	arm a Timer{deadline, fiber=park.handle} (today's sleep minus the self-suspend); return the timer handle so a cancel can evict it.
poll(deadline_ms) -> i64	ONE iteration of the run loop: drain ready, then fire the earliest timer / block on fds up to deadline_ms. Returns the next pending deadline (or sentinel when idle).
now_ms() -> i64	the virtual clock_ms (deterministic), NOT a wall clock — keeps 1817/1821-style tests reproducible.

Scheduler.run() stays as the explicit DRIVER (the top-level loop that calls poll to quiescence), installed via push Context { io = xx scheduler } { … s.run(); } — exactly the existing sched examples, just with the scheduler now reachable as context.io.

Status (2026-06-28)

• Phase 5 — CONVERGE: retire the bespoke fiber async API. DONE. Io unification COMPLETE. The bespoke Task layer (Task/TaskState/TaskErr/go/wait/ cancel(Task) + Scheduler.task_allocs and its deinit handling, ~130 lines) is removed from sched.sx. There is now ONE async stack: context.io.async/ await/cancel/race/sleep over the Io protocol, with the Scheduler as the fiber Io's engine + driver (spawn/yield_now/suspend_self/wake/run/ block_on_fd stay as the raw primitives). Migrated the four go/wait users to context.io: 1813 (interleave + cancel), 1817 (m1 end-to-end sum=123), 1819 (double-AWAIT loud-abort via the Future one-awaiter guard), 1820 (deinit — the go/task_allocs tasks dropped; it now exercises timers/io_waiters/kq cleanup, freed=2/live=3). race stays in sched.sx (needs meta.sx). Updated readme.md (the user-facing async section now documents context.io.async/await/race/ sleep) and the stale sched.go/sched.Task comments in io.sx. Suite 854/0; no .ir churn (the Task removal touched no snapshotted IR); migrated examples byte-identical on aarch64-macOS + aarch64-linux. PLAN-IO-UNIFY Phases 0–5 all complete — the two parallel async stacks are now one, behind context.io.

• Phase 4 — race over Futures via context.io.race. DONE. Re-homed the proven first-wins race from sched.race(*Task) onto *Future handles + the Io protocol; the old Task-based race is REPLACED (ufcs overload-by-receiver is rejected — "duplicate top-level decl" — and only 1821 used it).

  • Protocol affordance: added Io.current_park() -> ParkToken (the running fiber as a token, captured WITHOUT parking) so race can register the SAME coordinator across N futures' park slots, then park once via suspend_raw; any completion readys it. Scheduler returns {self.current} (bails outside a fiber); CBlockingIo returns {null} (race never parks there — futures born .ready). The await comment already anticipated this fan-in.
  • race (ufcs (io: Io, futures: $T) -> RaceResult(T), in sched.sx — it needs meta.sx's make_enum/make_variant, and pulling that into the io.sx prelude part-file would cycle): winner scan → register+park → deregister → make_variant the winner → Phase-3 cancel each loser (NO join). RaceResult reused unchanged (*Future(R) projects field 0 value → R).
  • Winner-time return: with true cancellation the parked losers stop at their next suspend (their timers evicted by cancel's wake), so race returns at the winner's virtual time, not the slowest loser's. 1821 re-pointed to context.io.async + context.io.race: winner a=111, losers .canceled, completion log ONLY task 1 @ 10ms, final clock 10ms (was 30 under the old cooperative join). Byte-identical on aarch64-macOS + aarch64-linux. Suite 853/0; .ir churn (current_park vtable method) regenerated, only 1821 stdout changed otherwise.

• Phase 3 — TRUE cancellation via suspend_raw -> !. DONE. A cancelled async worker now abandons its body at its next suspend instead of running to completion. Pieces:

  • Cancel-flag back-ref (D4 — back-ref pointer, chosen): SpawnOpts.cancel_flag: *void (core.sx) + Fiber.cancel_flag: *void (sched.sx), set from opts.cancel_flag in Scheduler.spawn_raw. async passes xx @f.canceled (the Future.canceled Atomic(bool) erased to *void).
  • Delivery: Scheduler.suspend_raw checks fiber_canceled(self.current) (a *Atomic(bool) load) PRE-park (raise without parking — no deadlock if cancel landed before the worker ran) and POST-resume (cancel landed while parked), raising error.Canceled (a bare -> !; set inferred). cancel(f) flips the sticky flag, marks .canceled, and ready(.{handle=f.task})s the worker.
  • Worker is failable Closure() -> ($R, !): the async completion closure f.value = worker() catch { … } (the captured-failable-closure-call the Phase-3-prereq fix enabled) marks .canceled/.failed and wakes the awaiter; the worker's post-suspend side effects never run. New failable io.sleep(ms) (arm_timer + try suspend_raw) is the cancellation point.
  • Compiler gap fixed: a -> ! fn whose only error source is try-ing a protocol method (io.suspend_raw) was wrongly flagged "declared ! but never errors". collectErrorSites (error_analysis.zig) now sets a dyn flag for a try of a non-identifier callee (opaque error channel), suppressing the warning.
  • Two UAFs found by adversarial review and FIXED: (1) cancel-before-park orphaned io.sleep's armed timer → suspend_raw's pre-park raise now evicts the current fiber's timer/waiter first. (2) cancel(f) woke a possibly-reaped worker → now only wakes when was_pending (.pending before the store).
  • Migrated 1805/1806/1824 to failable workers. Lock: examples/concurrency/1825-concurrency-fiber-cancel-suspend.sx (seq: 1 -99 — post-suspend line never runs). Validated byte-identical on aarch64-macOS host AND aarch64-linux container (1824 + 1825). Suite 853/0. Expected .ir churn (SpawnOpts layout) regenerated; no non-.ir snapshot changed.

• Phase 3 PREREQUISITE — captured-failable-closure call typing. DONE. The async completion closure (b.run = () => { f.value = worker() catch {…} }) captures a failable worker and consumes its error channel; the free-variable capture analysis (collectCaptures in src/ir/lower/closure.zig) did not descend into the error-handling / context / asm / multi-assign nodes, so worker was never captured — inside the lambda it resolved against an empty scope and typed as .unresolved (catch/try then rejected it). Fixed: added try_expr, catch_expr, onfail_stmt, raise_stmt, multi_assign, push_stmt, comptime_expr, insert_expr, spread_expr, asm_expr arms to collectCaptures. Adversarially reviewed (captures resolve, locals correctly excluded, no false-positive captures, 851/0). Lock: example examples/closures/0314-closures-capture-failable-call.sx (catch + try over a captured failable closure; pure language feature, host-only). The push_stmt arm also fixes the previously-noted "free-var analysis doesn't descend into a nested push Context {…}" gap. Phase 3 is now unblocked.

  • Two PRE-EXISTING, orthogonal bugs surfaced during review (neither blocked Phase 3): (1) calling a closure stored in a struct data field typed as unresolved (value → garbage; failable → can't catch) — RESOLVED (issues/0201): CallResolver.plan gained a closure/fn-pointer field arm and the lowering closure-field arm now also handles bare .function fields; regression examples/closures/0315-closures-struct-field-call.sx. (2) asm write-through place through a deref (asm { … "+r" -> @(p.*) }) fails LLVM verification — repros with NO closure (independent of capture analysis); possibly an unsupported deref-place form rather than a confirmed bug, not filed.

Status (2026-06-27)

• Phase 0 — fibers inherit the spawn-time context. DONE (2f2d7f1d). Discovered during Phase 1: a fiber body ran under __sx_default_context (the abi(.c) fib_dispatch dropped the implicit context), so a scheduler installed as context.io was invisible inside a worker. Fixed: Scheduler.spawn snapshots context → Fiber.dctx; fib_dispatch re-pushes it. Behavior-preserving (suite 828/0), no cross-fiber leak (context is parameter-threaded per stack). Lock: example 1822.
• Phase 1 — impl Io for Scheduler. DONE (5c30bfe0, hardened da7dd1f1). Six methods over the fiber primitives; spawn_raw bridges the erased (*void)->void worker thunk via an fn-ptr round-trip. Lock: example 1823 (spawn→arm→suspend→ready→resume entirely through context.io, deterministic). Adversarial review fixed: arm_timer/spawn_raw null guards, poll fd-pending abort + deadline_ms doc, stale fib_dispatch comment.
• Resolved design decisions: D1 = direct impl Io for Scheduler (chosen). D2 = now_ms returns the virtual clock_ms (deterministic) — a real-clock variant is later. D4 = deferred to Phase 3.
• Phase 2 — async/await colorblind over the fiber Io. DONE (967aed67, hardened ada8d162). async heap-allocs a *Future, boxes a completion closure in a monomorphic ThunkBox, and submits via io.spawn_raw (inline under CBlockingIo, a fiber under the scheduler); await parks via suspend_raw until ready. Protocol changed to suspend_raw(park: *ParkToken) (write-back of the awaiter). Workers are nullary (call-site capture). Migrated 1805/1806; adopted push .{ … }. Lock: example 1824 (deferral visible: 1 2 10 20 123). Review fixed: one-awaiter await guard; documented the Future allocator-lifetime contract + that cancel doesn't stop an already-spawned worker (Phase 3).
  • Resolved D2 (ParkToken): suspend_raw(*ParkToken) write-back (chosen over a registry). ready() liveness (CONCERN 6): safe for single async/await (awaiter is suspended, not reaped, when readied); race fan-in must still deregister (Phase 4).
  • Carried to convergence: async should capture the scheduler's long-lived allocator (like sched.go's own_allocator) instead of the call-site context.allocator — needs a protocol affordance; documented as a contract for now.
• Open for later phases:
  • ParkToken↔fiber binding. ready(park) needs park.handle = the awaiter *Fiber. The scheduler knows self.current at suspend; the cleanest is suspend_raw(park: *ParkToken) writing park.handle = self.current before parking (a small protocol change: the materializer installs thunks by name/order, signature-agnostic — verified low-risk). Decide vs a token→fiber registry.
  • ready() liveness (review CONCERN 6). Casting a stale/reaped *Fiber handle and wake-ing it is a latent UAF once real await runs — wake's .suspended value-check on freed bytes is luck, not safety. Phase 2 must guarantee single-ready / deregistration (mirror the bespoke-race deregister).
• Out-of-scope compiler bug found by review (not filed yet): closure free-var analysis does not descend into a nested push Context {…} block inside a closure body — a var used only there reports unresolved. Phase 0 sidesteps it (capture is at the Fiber level, not via closure), so it does NOT block the unification; worth an issues/ entry in a separate session.

Phases (each: implement → lock with an example → zig build test green → both platforms)

1. impl Io for Scheduler (the vehicle). Implement the six methods over the fiber primitives. Add a Fiber.canceled/task back-ref so suspend_raw can raise on resume. Keep CBlockingIo intact. Lock: install the fiber Io into context.io, run a root fiber that suspend_raws and is ready()'d — asserts real park/resume through the protocol (not inline). Bridge (the one fiddly bit): async's generic Closure(..$args) -> $R worker → spawn_raw's raw entry/arg. Box the worker thunk on the heap; entry is a C-ABI (env: *void) -> void invoke-thunk (mirrors fib_dispatch), arg is the env.

2. async/await over the fiber Io (real interleaving). Under a suspending Io, async calls spawn_raw and returns a PENDING Future($R) (no longer born .ready); the spawned body fills f.value/f.state and ready(f.park)s the awaiter. await(f) checks .ready else suspend_raw(f.park) then returns/raises — the suspending sibling of today's immediate await. CBlockingIo keeps the run-inline path (degenerate, still correct). Lock: two context.io.async tasks interleave under the fiber Io (the io.sx layer, replacing the bespoke sched.go).

3. True cancellation via suspend_raw -> !. cancel(f) flips f.canceled AND ready(f.park)s / wakes the worker fiber so its NEXT suspend_raw raises IoErr.Canceled. The worker's suspends (await, a future io.sleep) propagate via try/!; the worker body unwinds, the future ends .canceled, its post-cancel side-effects DON'T run. This is the model-A "true cancellation" — now delivered through the protocol, not bespoke. Lock: a cancelled task's work stops at its next suspend (assert via a shared log: the post-suspend line never prints).

4. race over Futures — context.io.race((a: fa, b: fb)). Re-home the proven race logic (winner scan, deregister-all-on-wake, structured cancel+join of losers) from sched.race(*Task tuple) onto *Future handles + the Io protocol. The type-level machinery ports UNCHANGED — RaceResult($T), make_variant, the tuple reflection (GAP 1/2, all landed) — only the runtime swaps *Task→*Future and suspend_self→suspend_raw/ready. Cancellation of losers now uses Phase 3 (their next suspend raises), so race returns at WINNER-time, not slowest-loser-time. Lock: re-point 1821 at context.io.race; assert winner value + losers' work stopped (not merely flagged).

5. Converge — retire the bespoke fiber async API. Fold sched.go/wait/cancel/race into the io.sx layer; Scheduler stays as the fiber Io's engine + driver. Migrate 1811–1821 to the context.io API. One async stack, all behind the protocol. Update the roadmap/checkpoints.

Open decisions (need a call before/within the phase noted)

• D1 (Phase 1) — impl Io for Scheduler vs a FiberIo wrapper. Direct impl makes context.io BE the scheduler (xx scheduler as the Io value, stateful receiver — mirrors the allocator xx local rule). A wrapper adds a level but decouples the public Io vtable from the scheduler internals. Lean: direct impl (simplest, matches the allocator convention).
• D2 (Phase 1) — virtual vs real clock under the fiber Io. Tests need the deterministic virtual clock (clock_ms); a real deployment wants time.mono_ms. Thread it as a Scheduler mode, or two Io impls (FiberIo virtual-clock for tests, real-clock for prod). Lean: a clock: enum { virtual; real } field so one impl serves both; tests pin .virtual.
• D3 (Phase 2) — Future(void) (issue 0150 SIGTRAP). A void-result task can't build Future(void) today. Defer (race/async target non-void), or fix the void struct-field path. Lean: defer, gate with a diagnostic.
• D4 (Phase 3) — where the cancel flag lives. The Future already has canceled: Atomic(bool); the fiber needs to reach it from suspend_raw. Give Fiber a *Atomic(bool) back-ref to its future's flag (set at spawn_raw), so suspend_raw consults it with no per-suspend lookup. Lean: back-ref pointer.

Validation (every phase)

• zig build && zig build test green (full corpus).
• New/changed 18xx examples byte-identical on aarch64-macOS host AND aarch64-linux container (deterministic virtual clock).
• Adversarial review of each phase (worker + read-only reviewer), per the session workflow.

What this supersedes

• sched.sx's bespoke go/wait/cancel/race (Phase 5 retires them; the proven logic moves onto the protocol). The just-landed race (commit 9099735e) is the reference logic for Phase 4, not the final home.
• PLAN-RACE.md's "race on sched.Scheduler" framing — this plan moves it onto context.io per the roadmap's §A5 / §4.6 design-of-record.