fibers: M:1 scheduler core + suspending fiber-task async (B1.5a, B1.4a)

library/modules/std/sched.sx: a generic Fiber + Scheduler over the
proven naked swap_context on guarded mmap stacks --
init/spawn/yield_now/suspend_self/wake/run (B1.5a), then Task($R) +
go/wait/cancel, a truly-suspending nullary-thunk async layer (B1.4a).
go(work) runs a thunk as a real fiber; wait() parks the caller until it
completes. Self-contained in sched.sx (io.sx importing it would
duplicate the _fib_tramp global asm).

Hardened per adversarial review: wake guarded on .suspended (FIFO
corruption), suspend_self/yield_now guard a null current, loud
mmap/mprotect/OOM/deadlock bails, cancel skips not-yet-run work.
Closure-env + heap-Task leaks documented (bounded, default-GPA-invisible).

Examples: 1811 (round-robin), 1812 (suspend/wake + spurious-wake guard),
1813 (async interleave + await-suspend + cancel). Also files issue 0155
(scalar-pointer index panics codegen -- non-blocking, found in review).

examples/concurrency/1811-concurrency-fiber-scheduler.sx

@@ -0,0 +1,81 @@
+// Stream B1 (fibers) B1.5a — the M:1 cooperative fiber scheduler core, in pure
+// sx over `swap_context` (proven in 1807-1809). `Scheduler` drives N fibers,
+// each running a `body: Closure() -> void` on its own guarded `mmap` stack;
+// fibers cooperate by calling `yield_now`, which round-robins control back
+// through the scheduler loop.
+//
+// Round-robin demo: 3 fibers (A=0, B=1, C=2) each append their id to a shared
+// sequence buffer, yielding between each of 3 rounds. Because the scheduler
+// re-enqueues a yielding fiber at the TAIL (FIFO), the interleaving is the
+// deterministic round-robin order:
+//
+//   round 1:  A B C   (0 1 2)
+//   round 2:  A B C   (0 1 2)
+//   round 3:  A B C   (0 1 2)
+//
+//   → sequence: 0 1 2 0 1 2 0 1 2
+//
+// Outputs flow OUT of each fiber through pointers captured in its closure (the
+// shared `Shared` struct), since closure capture-by-value does not write back.
+// Every fiber must reach `.done` (asserted via a per-fiber done flag).
+//
+// aarch64-macOS-pinned (the scheduler's asm + guard-page mmap constants are
+// per-arch / Apple-specific): runs end-to-end on a matching host, ir-only on a
+// mismatch.
+#import "modules/std.sx";
+sched :: #import "modules/std/sched.sx";
+
+Shared :: struct {
+    seq: [16]i64;     // appended interleaving sequence
+    n: i64;           // count appended
+    done: [3]i64;     // per-fiber done flag (set right before the body returns)
+}
+
+append :: (sh: *Shared, v: i64) {
+    sh.seq[sh.n] = v;
+    sh.n = sh.n + 1;
+}
+
+main :: () -> i64 {
+    sh : Shared = ---;
+    sh.n = 0;
+    sh.done[0] = 0;  sh.done[1] = 0;  sh.done[2] = 0;
+
+    s := sched.Scheduler.init();
+    ps := @s;
+    psh := @sh;
+
+    // Three DIFFERENT fiber bodies (distinct captured ids), interleaving via
+    // yield_now. Each appends its id once per round for 3 rounds.
+    spawn_worker :: (ps: *sched.Scheduler, psh: *Shared, my_id: i64) {
+        ps.spawn(() => {
+            r := 0;
+            while r < 3 {
+                append(psh, my_id);
+                if r < 2 { ps.yield_now(); }   // cooperate between rounds
+                r = r + 1;
+            }
+            psh.done[my_id] = 1;
+        });
+    }
+
+    spawn_worker(ps, psh, 0);
+    spawn_worker(ps, psh, 1);
+    spawn_worker(ps, psh, 2);
+
+    s.run();
+
+    // Ordering contract: round-robin FIFO interleaving.
+    print("sequence:");
+    i := 0;
+    while i < sh.n {
+        print(" {}", sh.seq[i]);
+        i = i + 1;
+    }
+    print("\n");
+
+    print("spawned: {}\n", s.n_spawned);
+    print("done: {} {} {}\n", sh.done[0], sh.done[1], sh.done[2]);
+    print("all done: {}\n", sh.done[0] + sh.done[1] + sh.done[2]);
+    return 0;
+}

examples/concurrency/1812-concurrency-fiber-suspend-wake.sx

@@ -0,0 +1,64 @@
+// Stream B1 (fibers) B1.5a — fiber park/resume via `suspend_self` + `wake`,
+// the off-queue half of the M:1 scheduler that FiberIo [B1.4] builds on.
+//
+// A running fiber that has nothing to do parks itself with `suspend_self`: it
+// leaves the round-robin queue entirely (unlike `yield_now`, which re-enqueues)
+// and only runs again when another fiber (or an I/O completion) calls `wake` on
+// it. Here fiber A records 10, parks, and is resumed by fiber B to record 11:
+//
+//   A: rec 10, suspend_self ──park──┐
+//   B: rec 20, wake(A), wake(A), rec 21
+//   A: ──resume──> rec 11
+//   → log: 10 20 21 11
+//
+// `wake` is GUARDED on `.suspended`: B's SECOND `wake(A)` is spurious (A is
+// already re-queued by then). An unguarded enqueue would re-link an
+// already-listed node and corrupt the FIFO (segfault); the guard makes a
+// double/spurious/stale wake a safe no-op. `suspended-left: 0` confirms every
+// park was balanced by a wake (an orphaned park would abort the scheduler).
+//
+// aarch64-macOS-pinned (the scheduler's per-arch asm + Apple mmap constants):
+// runs end-to-end on a matching host, ir-only on a mismatch.
+#import "modules/std.sx";
+sched :: #import "modules/std/sched.sx";
+
+// The shared state both fibers reach through (passed as `*Sh`). `parked` holds
+// the fiber-A handle that B wakes — kept here (rather than a separate
+// `**Fiber`) so the one `*Sh` carries everything the helper fns share.
+Sh :: struct { log: [16]i64; n: i64; parked: *sched.Fiber; }
+rec :: (sh: *Sh, v: i64) { sh.log[sh.n] = v; sh.n = sh.n + 1; }
+
+main :: () -> i64 {
+    sh : Sh = ---; sh.n = 0; sh.parked = null;
+    s := sched.Scheduler.init();
+    ps := @s; psh := @sh;
+
+    // Fiber A: record 10, park, then (after wake) record 11. Store A's handle in
+    // the shared state so B can wake it.
+    mk_a :: (ps: *sched.Scheduler, psh: *Sh) {
+        psh.parked = ps.spawn(() => {
+            rec(psh, 10);
+            ps.suspend_self();
+            rec(psh, 11);
+        });
+    }
+    // Fiber B: record 20, wake A (legit) + a spurious second wake (safe no-op),
+    // record 21.
+    mk_b :: (ps: *sched.Scheduler, psh: *Sh) {
+        ps.spawn(() => {
+            rec(psh, 20);
+            ps.wake(psh.parked);     // legitimate: A is parked
+            ps.wake(psh.parked);     // spurious: A is now .ready/queued — must no-op
+            rec(psh, 21);
+        });
+    }
+    mk_a(ps, psh);
+    mk_b(ps, psh);
+    s.run();
+
+    print("log:");
+    i := 0; while i < sh.n { print(" {}", sh.log[i]); i = i + 1; }
+    print("\n");
+    print("suspended-left: {}\n", s.n_suspended);
+    return 0;
+}

examples/concurrency/1813-concurrency-fiber-async-suspend.sx

@@ -0,0 +1,83 @@
+// Stream B1 (fibers) B1.4a — a truly-SUSPENDING fiber-task async layer
+// (`go` / `wait` / `cancel`) over the M:1 scheduler, in pure sx. In contrast
+// with 1805's `context.io.async` (which runs each worker INLINE to completion
+// before returning a `.ready` future — no interleaving), here `s.go(work)` runs
+// `work` as a REAL fiber and `t.wait()` SUSPENDS the caller until that fiber
+// finishes, so a task that yields mid-body lets a sibling task run before the
+// first completes — genuine cooperative interleaving.
+//
+// `work` is a NULLARY thunk: any inputs are captured in the lambda at the call
+// site (no `..args` pack crosses the fiber boundary — that would hit issue 0156
+// Part 2). Outputs flow OUT through pointers captured in the thunk (the shared
+// `Log` struct), since closure capture-by-value does not write back.
+//
+// What this proves:
+//   - REAL suspend + interleave: task A records 1, YIELDS; task B then records 2
+//     and completes; A resumes, records 3, completes → interleave order 1 2 3.
+//   - awaited VALUES: A returns 42, B returns 100 (recorded after both waits).
+//     → sequence: 1 2 3 42 100.
+//   - cancel rides the `!` channel (model (a), like 1806): a canceled task's
+//     `wait()` raises `.Canceled`, taken by the `or` default → -99.
+//
+// `wait` must run inside a fiber (it parks `self.current`), so the "main task"
+// is itself a `s.spawn(...)` fiber that drives the two `go` tasks.
+//
+// aarch64-macOS-pinned (the scheduler's asm + guard-page mmap constants are
+// per-arch / Apple-specific): runs end-to-end on a matching host, ir-only on a
+// mismatch.
+#import "modules/std.sx";
+sched :: #import "modules/std/sched.sx";
+
+Log :: struct { seq: [16]i64; n: i64; }
+rec :: (l: *Log, v: i64) { l.seq[l.n] = v; l.n = l.n + 1; }
+
+main :: () -> i64 {
+    lg : Log = ---;
+    lg.n = 0;
+
+    s := sched.Scheduler.init();
+    ps := @s;
+    pl := @lg;
+
+    // The "main task" fiber: drives two real tasks, waits both, then exercises
+    // cancel. It runs as a fiber so `wait` has a `self.current` to park.
+    s.spawn(() => {
+        // Task A yields mid-body so B interleaves before A completes.
+        a := ps.go(() -> i64 => {
+            rec(pl, 1);
+            ps.yield_now();   // suspend A; B (already spawned) runs to completion
+            rec(pl, 3);
+            42
+        });
+        // Task B runs straight through (no yield).
+        b := ps.go(() -> i64 => {
+            rec(pl, 2);
+            100
+        });
+
+        // Wait both — suspends the main-task fiber until each completes.
+        va := a.wait() or { -1 };
+        vb := b.wait() or { -1 };
+        rec(pl, va);
+        rec(pl, vb);
+
+        // Cancel case: cancel before the worker runs; `wait` raises .Canceled,
+        // the `or` default (-99) is taken.
+        c := ps.go(() -> i64 => 7);
+        c.cancel();
+        rec(pl, c.wait() or { -99 });
+    });
+
+    s.run();
+
+    // Interleaving + value contract: 1 2 3 42 100, then the cancel default -99.
+    print("sequence:");
+    i := 0;
+    while i < lg.n {
+        print(" {}", lg.seq[i]);
+        i = i + 1;
+    }
+    print("\n");
+    print("spawned: {}\n", s.n_spawned);
+    return 0;
+}

examples/concurrency/expected/1811-concurrency-fiber-scheduler.build

@@ -0,0 +1 @@
+{ "target": "macos" }

examples/concurrency/expected/1811-concurrency-fiber-scheduler.exit

@@ -0,0 +1 @@
+0

examples/concurrency/expected/1811-concurrency-fiber-scheduler.stderr

@@ -0,0 +1 @@
+

examples/concurrency/expected/1811-concurrency-fiber-scheduler.stdout

@@ -0,0 +1,4 @@
+sequence: 0 1 2 0 1 2 0 1 2
+spawned: 3
+done: 1 1 1
+all done: 3

examples/concurrency/expected/1812-concurrency-fiber-suspend-wake.build

@@ -0,0 +1 @@
+{ "target": "macos" }

examples/concurrency/expected/1812-concurrency-fiber-suspend-wake.exit

@@ -0,0 +1 @@
+0

examples/concurrency/expected/1812-concurrency-fiber-suspend-wake.stderr

@@ -0,0 +1 @@
+

examples/concurrency/expected/1812-concurrency-fiber-suspend-wake.stdout

@@ -0,0 +1,2 @@
+log: 10 20 21 11
+suspended-left: 0

examples/concurrency/expected/1813-concurrency-fiber-async-suspend.build

@@ -0,0 +1 @@
+{ "target": "macos" }

examples/concurrency/expected/1813-concurrency-fiber-async-suspend.exit

@@ -0,0 +1 @@
+0

examples/concurrency/expected/1813-concurrency-fiber-async-suspend.stderr

@@ -0,0 +1 @@
+

examples/concurrency/expected/1813-concurrency-fiber-async-suspend.stdout

@@ -0,0 +1,2 @@
+sequence: 1 2 3 42 100 -99
+spawned: 4