# CHECKPOINT-FIBERS — Stream B1 (fibers + Io + M:1 scheduler)

Companion to [PLAN-FIBERS.md](PLAN-FIBERS.md). Update after every step (one step at a time,
per the cadence rule). New corpus category: `18xx` concurrency.

## Last completed step
**B1.0a (`abi(.pure)` lock commit) — DONE.** Plumbed the `is_pure` flag end-to-end and made
emit bail loudly:
- IR `Function.is_pure: bool` ([inst.zig](../src/ir/inst.zig)) — set from `fd.abi == .pure`
  at both `declareFunction` decl sites ([decl.zig](../src/ir/lower/decl.zig)).
- `funcWantsImplicitCtx` returns false for `.pure` (mirrors the `.c` skip, decl.zig:515) —
  a `.pure` fn gets no synthetic `__sx_ctx`.
- Both body-lowering paths bypass `lowerValueBody` for `.pure`: lower the asm body as
  statements + cap with `unreachable` (a `.pure` body has no sx return — the asm rets
  itself; this avoids the implicit-return diagnostic).
- `emit_llvm` Pass 2 (~line 402) **bails loudly** when `func.is_pure`
  ("`abi(.pure)` function '…' LLVM emission not yet implemented") via `comptime_failed`
  (driver aborts nonzero) — NOT a framed body (whose epilogue would corrupt a context
  switch's SP-in ≠ SP-out).
- `examples/1800-concurrency-pure-asm.sx` — one host example (no `.build` pin; the bail is
  host-independent, fires before any asm/instruction selection), locked to the bail snapshot
  (exit 1, empty stdout, the loud diagnostic on stderr).
- **Naming:** the sx-facing name is **`pure`** throughout (field, diagnostic); LLVM's
  `naked` attribute is only the B1.0b lowering mechanism (per user direction — don't call
  the function "naked").
- `zig build && zig build test` green: **722 ran, 0 failed**.

## Current state
Stream A (atomics) is feature-complete (✅) and unblocks B2-channels. Stream B1: **B1.0a
landed**; the `abi(.pure)` ABI is plumbed but emit deliberately bails (B1.0b flips it to
real LLVM `naked` emission). No fibers/Io/scheduler code yet. Grounded floor facts:
- `context` is already an implicit `*Context` param (slot 0) + `push Context` is a stack
  `alloca` ⇒ **fiber-local for free**. Only shared root = `__sx_default_context` global
  (entry-point bind). B1.1 expected to be a **library convention** (spawn trampoline
  snapshots the spawner's ctx into slot 0), **likely zero compiler change** — probe first.
- Inline asm works end-to-end (lower→emit→JIT, aarch64 + x86_64) — the `.pure` body reuses it.

## Next step
**B1.0b (`abi(.pure)` real emission)** — per PLAN-FIBERS.md "Phases → B1.0 → B1.0b" and the
kickoff prompt at the bottom of that file. Replace the emit bail with LLVM's `naked`
attribute + asm-only body; pin `1800` aarch64 (run end-to-end → exit 42, capture `.ir`); add
x86_64 cross sibling `1801` (ir-only); add an `emit_llvm.test.zig` unit test asserting the
`naked` attr. Separate commit (cadence rule — B1.0a locked, B1.0b greens).

## Known issues / capability gaps
- **Orthogonal (not a B1 blocker):** default VALUES for comptime params don't bind on
  generic-struct methods (free-fn defaults DO work) — inherited from Stream A. Only matters
  if a B2 lib type wants a defaulted comptime param; atomics/fibers require explicit, so
  unaffected.
- **Issue 0144 (open, independent):** calling an unrecognized bodiless `#builtin` silently
  returns 0 / exit 0 — a silent-fallback footgun in the generic builtin-call path. Filed;
  leave for its own fix session unless prioritized. Not a B1 blocker.
- **Deferred design gap (documented):** the B1.4 event-loop `Io` does not yet cooperate with
  a platform UI run loop (CFRunLoop/NSRunLoop/ALooper); pinning gives thread-affinity, not
  run-loop integration — a §6 app-target concern, out of B1 scope.

## Decisions (Stream B1 specifics; surface locked in design §4 / §4.6)
- **The async runtime is sx LIBRARY code.** The compiler provides only: the general
  primitives (inline asm ✅, `abi(.pure)` naked [B1.0], atomics ✅) + fiber-safe codegen
  (`context` already fiber-local — B1.1). Schedulers, fibers, channels, futures, `Io`
  vtables, `mmap` stacks are all sx.
- **`abi(.pure)` is the real spelling of the design's `callconv(.naked)`** — postfix slot,
  `name :: (sig) -> Ret abi(.pure) { asm { … }; }`. B1.0 = carry it into IR + emit LLVM
  `naked` + skip prologue/ctx (mirror the existing `.c` skip), NOT extend the enum (it's
  already there, just inert).
- **`.pure` ≠ `.c`:** a `.c` epilogue would restore SP from the wrong stack across a context
  switch (SP-in ≠ SP-out by design). `.pure` = no prologue/epilogue/frame; the asm emits its
  own `ret`. This is why the switch must be `.pure`.
- **Naming:** sx-facing name is **`pure`** (field `is_pure`, the diagnostic). LLVM's `naked`
  function attribute is only the lowering mechanism (B1.0b) — do not call the function
  "naked" (user direction).
- **B1.0 snapshot scope:** a `.pure` body is raw per-arch asm; LLVM's `naked` attr text is
  arch-invariant. **B1.0a** = one host example locked to the emit bail (host-independent —
  fires before instruction selection; no `.build` pin). **B1.0b** = pin aarch64 + add an
  x86_64 cross sibling (`.build` target-gated, ir-only on mismatch), like the asm corpus
  split. The `.ir` proves the `naked` attr + asm emitted, NOT register-save correctness
  (that's B1.3's stress harness).
- **B1.1 grounded as library-only (pending probe):** push frames are stack-`alloca`'d and
  the implicit ctx rides slot 0, so a spawn trampoline can pass a snapshotted ctx with no
  compiler change. The design doc's "never raw TLS" guards a non-problem (context is not
  TLS). Probe to confirm before sizing any compiler work.
- **Test keystones (design §10):** the **B1.3 switch-stress harness** gates the
  context-switch (the one piece the deterministic `Io` can't test — §8.1.1, §10.7); the
  **B1.4 deterministic-sim `Io`** (calibrated against blocking `Io` — §8.1.3) gates all
  scheduling tests. Both must exist + be calibrated before the async tests they gate are
  trusted. `18xx` asserts program-emitted ordering contracts, not raw interleaving.

## Log
- **carve** — wrote PLAN-FIBERS.md + CHECKPOINT-FIBERS.md. Grounded the B1 compiler floor:
  `ABI.pure` inert (type_resolver.zig:237), IR `Function` has no naked flag (inst.zig:605),
  attribute API pattern (emit_llvm.zig:1339 nounwind), `.c` ctx-skip precedent
  (decl.zig:515), `push Context` stack-alloca + slot-0 implicit ctx (stmt.zig:1263,
  lower.zig:259), `__sx_default_context` root (decl.zig:2667/2815), inline-asm corpus
  (1645/1651). Corrected the design's `callconv(.naked)` → real `abi(.pure)` spelling and
  the B1.0 snapshot story. B1.1 grounded as likely library-only. Baseline green (721/0).
- **B1.0a** — plumbed `Function.is_pure` (set from `fd.abi == .pure` at both decl sites);
  `funcWantsImplicitCtx` skips `.pure` (no implicit ctx, like `.c`); both body-lowering
  paths bypass `lowerValueBody` for `.pure` (asm body + `unreachable` cap — no sx return);
  `emit_llvm` Pass 2 bails loudly on `func.is_pure`. `examples/1800-concurrency-pure-asm.sx`
  locked to the bail (exit 1 + diagnostic). Renamed `is_naked`→`is_pure` per user direction
  (sx says `pure`, not "naked"; LLVM `naked` attr is only the B1.0b mechanism). Suite green
  (722/0). **Next: B1.0b (real `naked` emission).**