Summary

This issue tracks the review and acceptance of ZEP-0002: Structured Async.

Proposal

ZEP-0002 proposes a fiber-based, zero-infection concurrency model for zag:

• Functions are just functions — no async keyword, no Io parameter, no signature changes
• Fibers (user-space threads, 8KB stack, grow on demand) scheduled on a work-stealing OS thread pool (one thread per core)
• zag.Scope for structured concurrency — all tasks guaranteed to complete before scope exits
• zag.checkCancel() reads fiber-local cancellation state — no parameter threading
• Single-threaded fallback (ZAG_THREADS=1) for embedded/test contexts

Why not the Zig Io parameter approach?

The Io-as-parameter model (Zig upstream PR #25592) is still viral — every function that does I/O must accept and thread an Io parameter through its entire call chain. Change a leaf function to need I/O? Refactor everything above it. This is function coloring by another name.

zag's position: concurrency lives at the call site, not in function types.

Key design decisions up for discussion

1. Fibers vs stackless coroutines — we chose fibers (stackful) for zero infection. Trade-off: memory (8KB/fiber min vs ~0 for stackless). Is 2026 hardware sufficient to make this a non-issue?
2. zag.spawn (detached) vs scope-only spawning — should detached spawns exist at all, or should everything go through zag.Scope?
3. error.Cancelled vs a distinct cancel type — risk of accidental catch-all handling?
4. zag.Channel(T) in Phase 1 or deferred — scope of this ZEP vs a separate actor/message-passing ZEP?

Council review status

Initial council review complete — do not advance to Review yet. 6 findings logged in the ZEP. See the Council Review Notes section.

Status

Draft — revisions in progress before moving to Review.