# PLAN-POST-METATYPE — program plan for the async-first roadmap (everything after metatype)

Sequences every remaining stream after [PLAN-METATYPE.md](PLAN-METATYPE.md). This is the
**program-level** plan; each stream below is carved into its own
`PLAN-<STREAM>.md` + `CHECKPOINT-<STREAM>.md` (full step detail + kickoff prompt)
**when reached**, exactly as metatype was. Rationale, the comptime type-construction
design, risk ranking (§8.1), and the testing strategy (§10) all live in the design-of-record:
[../design/execution-evolution-roadmap.md](../design/execution-evolution-roadmap.md).

**Cadence (IMPASSIBLE), every stream:** no commit both adds a test AND makes it pass
(lock, or xfail→green); `zig build && zig build test` green after every step; never
regenerate snapshots while red. On an unrelated compiler bug → file `issues/NNNN`,
mark the stream checkpoint BLOCKED, stop (CLAUDE.md rule).

**Ordering = async-first** (design §7): the async story needs no JIT spine, so the
JIT/FFI cluster comes after. New corpus categories: `17xx` atomics, `18xx` concurrency.

## Stream order (post-metatype)

| # | Stream | Roadmap steps | Depends on | Notes |
|---|--------|---------------|-----------|-------|
| **A** | Atomics | N1 (1) | — | independent foundation; gates B-parallel + channels |
| **B** | Async runtime | 4–12 | metatype, A (for channels) | the bulk; likely splits into B1 (runtime) + B2 (channels/cancel/stdlib) when carved |
| **C** | Parallel schedulers | 13–14 | A, B | N×(M:1) → M:N |
| **D** | Comptime JIT/FFI | 15–18 | — (independent of async) | S1 → C1 → C2 → C3 |
| **E** | Hot-reload (deferred) | 19–22 | D (S1/S2) | S2 → R1 → R2 → R3 |

A and D are independent of each other and of B's core; B is the spine of the async
story. **Recommended execution order: A → B → C → D → E** (async-first; D can slot
earlier if FFI/`#compiler`-collapse becomes a priority).

---

## Stream A — ATOMICS (N1)  ·  `PLAN-ATOMICS.md` when carved

**Goal:** LLVM atomic codegen — the net-new emit primitive. Surface = `Atomic($T)`
wrapper + `Ordering` enum (locked, design §4.6). Some IR/inference scaffolding exists;
**lowering is absent**.

**Phases:**
- A.0 `Atomic($T)` + `Ordering` lib types + `load`/`store` → LLVM `load atomic`/`store
  atomic` with orderings.
- A.1 RMW: `fetch_add/sub/and/or/xor` + `fetch_min/max` → `atomicrmw` (no `nand`).
- A.2 `compare_exchange`/`_weak` → `cmpxchg` (returns **`?T`, null = success**).
- A.3 `swap` + `fence(.ordering)`.

**Gates:** unit `emit_llvm.test.zig` (correct op + ordering emission); corpus `17xx`
single-thread (deterministic); **arch-gated x86_64 + aarch64 `.ir`** (orderings lower
differently — x86 vs LL/SC). **Out of snapshot scope, state loudly:** ordering
*semantics* under weak memory (`.ir` proves the keyword emitted, not correctness).

---

## Stream B — ASYNC RUNTIME (steps 4–12)  ·  splits into `PLAN-FIBERS.md` + `PLAN-CHANNELS.md`

The colorblind, stackful, pure-sx async runtime (design §4). Compiler floor is small;
the runtime is sx lib. Likely carved as two PLANs:

### B1 — Fibers + Io + M:1 (the runtime; `PLAN-FIBERS.md`)
- B1.0 **`callconv(.naked)`** — extend `CallConv {default, c}` (types.zig:169) + skip
  prologue/epilogue lowering. (Net-new; gates the context-switch.)
- B1.1 **Repointable-`context` codegen** — lower `context` as a swappable indirection
  (never raw TLS) + per-fiber stack-limit. **Prerequisite of B1.3, not a successor.**
- B1.2 **A1 — `Io` interface + `context.io` + `Future` + `cancel()` API** (protocol/
  vtable threaded like `Allocator`).
- B1.3 **A2 — fiber runtime**: `callconv(.naked)` context-switch asm (per-arch),
  bootstrap, `mmap` stacks. **sx lib, not a compiler builtin** (design §4 A2).
- B1.4 **A3 — `Io` impls: blocking → deterministic-sim (KEYSTONE) → event-loop**
  (kqueue/epoll/io_uring). Build the deterministic `Io` *before* the event loop — it
  is the test harness (§10.1).
- B1.5 **A5·M:1 scheduler** — validates the whole colorblind stack end-to-end.

**Gates:** deterministic-`Io` **calibrated** against blocking `Io` (don't trust an
uncalibrated oracle — §8.1.3); corpus `18xx` under deterministic `Io`; **A2
switch-stress test** (scribble every callee-saved reg + canary, deep fiber chains,
verify post-resume — §10.7) + arch-gated run tests. A2 is the highest-corruption-risk
piece (§8.1.1).

### B2 — Channels + cancellation + stdlib (`PLAN-CHANNELS.md`)
- B2.0 **N3 — channels** (`Channel($T)`; `recv → RecvResult($T)` tagged union built via
  **metatype** type-fn) + fiber-aware `Mutex`/`WaitGroup` (atomic fast-path from A).
- B2.1 **A6 — cancellation** = `.canceled` in the existing `!` channel (model a); per-
  fiber atomic flag (A); every `io.*` a cancellation point; structured cancel-and-join;
  **masked during cleanup**. Rides ERR (`try`/`onfail`/`defer`).
- B2.2 **A4 — stdlib I/O rework** — fs/socket/process onto `context.io`.

**Gates:** `18xx` under deterministic `Io`; cancellation cleanup asserted via stdout
ordering; `RecvResult` exercises the metatype primitives.

---

## Stream C — PARALLEL SCHEDULERS (steps 13–14)  ·  `PLAN-PARALLEL.md`

- C.0 **N×(M:1)** — per-thread M:1 loops + `std/thread.sx` spawn; shared state uses A
  atomics; **errno-capture discipline + `context`-fiber-local** become mandatory.
- C.1 **M:N** — work-stealing (thread-safe steal queues + migration); **pinning** API
  (`pin = .main | .any | .on(thread)`). M:N is **committed, not deferred** — just last.

**Gates:** data races aren't snapshottable → **stress harness** (run-N / TSan-style),
*loudly* out of corpus scope (§10.2). **Named `context`-fiber-local + errno migration
test** (M:1 can't exercise migration — §10.7).

---

## Stream D — COMPTIME JIT / FFI (steps 15–18)  ·  `PLAN-JIT.md`

Independent of async; can move earlier if `#compiler`→`extern` / bundler cleanup is
prioritized.

- D.0 **S1 — persistent JIT executor** (long-lived ORC LLJIT + host-triple emitter +
  fragment cache, plumbed into the interp). Foundational for C1/C3.
- D.1 **C1 — real comptime FFI = LLVM single ABI authority** (per-signature JIT
  calling-thunks via S1 + trampoline fast-path). Adversarial **layout cases** (over-
  aligned/empty structs, aarch64 small-struct split, `bool` — §8.1.6).
- D.2 **C2 — `#compiler`→`extern` collapse** (hooks → exported C symbols via C1; delete
  `compiler_call`/Registry). Gate: bundler corpus byte-identical pre/post.
- D.3 **C3 — comptime asm via host-JIT** (un-bail `inline_asm`; lift→JIT→cache).
  `06xx` host-arch `#run` asm + `11xx` cross-arch loud-bail diagnostic.
- (S2 only if a path hits TLS/constructors — see Stream E.)

**Gates:** S1 lifecycle + cache unit tests; C1 behavior-lock trampoline cases →
xfail/green `12xx` float/struct/aggregate returns.

---

## Stream E — HOT-RELOAD (deferred) (steps 19–22)  ·  `PLAN-HOTRELOAD.md`

Deferred; R1-vs-R2 chosen at pickup. Design constraint (not optional): runtime +
long-lived fibers stay **persistent**, only **leaf logic** reloads (can't hot-swap code
with live suspended fibers).

- E.0 **S2 — ORC C++ shim** (`MachOPlatform` + redirectable symbols). **Highest risk
  (§8.1.5):** only C++ in the tree, prior spike failed on `_Thread_local`, macOS-
  specific — **Linux/Windows + non-Mac TLS/ctor JIT have no named plan yet.**
- E.1 **R1 — dylib hot-reload** (only needs shipped `export`; sidesteps S2).
- E.2 **R2 — JIT-resident hot-reload** (S1 + S2; ORC indirection stubs).
- E.3 **R3 — incremental compilation** (perf enabler; coarse per-file v1 first).

**Gates (when picked up):** state-survival test; the live-suspended-fiber-into-stale-
module hazard; S2 TLS + C-constructor JIT test per host OS (the exact prior-spike case).

---

## Cross-cutting (applies across streams)

- **Testing keystone:** the deterministic-sim `Io` (B1.4) must exist + be calibrated
  before *any* async test is trusted (§10.1).
- **Top risks to watch (§8.1):** A2 context-switch correctness (B1.3), minted-enum →
  match codegen (de-risked, metatype stream), deterministic-`Io` oracle calibration,
  `context`-fiber-local/errno (C), S2 (E), C1 args-buffer layout (D).
- **The compiler floor stays small, but deep:** atomics, `callconv(.naked)`, repointable-
  `context` codegen, `declare`/`define`/`type_info` (metatype stream), the S1 JIT spine.
  Everything else — schedulers, fibers, channels, the bundler — is sx lib.

## Carving protocol

When a stream is reached: copy this section into `current/PLAN-<STREAM>.md`, expand the
phases to xfail→green steps with file anchors (from the design doc's anchor list), add
a `CHECKPOINT-<STREAM>.md`, and write a Phase-0-scoped kickoff prompt (mirror
PLAN-METATYPE's). Update [CHECKPOINT-METATYPE.md](CHECKPOINT-METATYPE.md)/this file's status as
streams complete.