docs(roadmap): phase 2 done; record the thread-local-guard rule; sharpen the channel fast-follow rationale (cross-thread std MutexGuard release is UB)

ROADMAP_v0.5.md

@@ -12,6 +12,12 @@ Guiding rules established this cycle:
   two slot locks at once). Any new lock states its position in this order.
 - **No unwind inside a runtime critical section.** The stop sentinel only
   fires at lock-free observation points.
+- **Never hold a thread-local guard across a possible switch point.** An
+  actor can be preempted at any allocation and resume on a different OS
+  thread; a live `RefCell` borrow (or std `MutexGuard`) then pairs its
+  acquire/release across two threads' locals — count underflow / UB.
+  `with_runtime`, `with_shared`, and every `RawMutex` guard disable
+  preemption for exactly this reason (phase 2 found this the hard way).
 
 ---
 
@@ -30,32 +36,32 @@ Split independent concerns out of `SharedState` so the global lock guards less.
 
 `SharedState` now holds only: `slots`, `free_list`, `run_queue`, `root_pid`.
 
-## Phase 2 — Slot table split  (NEXT, the big correctness step)
+## Phase 2 — Slot table split  ✅ DONE
 Make slot lookup lock-free and per-slot state independently mutable.
-- [ ] Fixed slab: `Box<[SlotCell; max_actors]>`, slots never move → stable
+- [x] Fixed slab: `Box<[Slot]>`, slots never move → stable
       addresses, lock-free index. **Assert on exhaustion** with a panic message
       naming `Config::max_actors(n)` as the fix. Default `max_actors = 16_384`.
       (Mental note: must become unbounded or configurable-bounded later — see
       "Deferred" below. Do not let the fixed cap calcify into an assumption.)
-- [ ] Per-slot `generation: AtomicU32` outside the lock for cheap stale-PID
-      rejection.
-- [ ] Per-slot CAS state machine replacing `state` + `pending_unpark`:
-      `Parked / Queued / Running / RunningNotified / Done` in one `AtomicU8`.
-      `unpark` = CAS Parked→Queued (then push) or Running→RunningNotified;
-      park-return = CAS Running→Parked, else re-queue. Eliminates the
-      lost-wakeup bool by turning the race window into a state.
-- [ ] `sp` → relaxed `AtomicUsize` (happens-before carried by queue
-      release-push / acquire-pop).
-- [ ] Per-slot raw non-poisoning mutex (spin-then-futex, Linux; embedded-
-      friendlier than `std::sync::Mutex`) for the cold collections: `waiters`,
-      `monitors`, `links`, `supervisor_channel`, `outcome`, `pending_io_result`,
-      `outstanding_handles`. Guard enters `NoPreempt`.
-- [ ] Free list → its own structure (lock-free Treiber stack or striped).
-- [ ] `finalize_actor` link cascade: lock peers one at a time (leaf rule);
-      write the acyclicity argument next to it.
-- [ ] `live_actors` / `io_outstanding` → atomics; termination = both zero +
-      queue empty. Finalize decrements `live` strictly *after* all wakeups it
-      produced are enqueued — document this ordering as the correctness crux.
+- [x] Generation packed INTO the state word (better than the planned separate
+      `AtomicU32`): one `AtomicU64 = (gen << 32) | state`, so the gen check is
+      atomic with every transition — no ABA, no spurious unparks, by CAS.
+- [x] Per-slot CAS state machine `Vacant/Queued/Running/RunningNotified/
+      Parked/Done` replacing `state` + `pending_unpark`. Also fixed a latent
+      lost wakeup in the Blocking-IO completion path (result set for a
+      still-Running actor without a flag).
+- [x] `sp` → relaxed `AtomicUsize`; stop flag + first-resume closure as
+      `AtomicPtr`s — resume path fully lock-free.
+- [x] Per-slot raw non-poisoning futex mutex (`src/raw_mutex.rs`) for the
+      cold collections. Guard enters `NoPreempt`.
+- [x] Free list → `RawMutex<Vec<u32>>` (a leaf lock). Treiber/striped only if
+      the phase-4 spawn-storm bench shows contention — revisit then.
+- [x] `finalize_actor` link cascade locks peers one at a time; acyclicity
+      argument written at the site. `link()` registers target-first with the
+      race argument at the site.
+- [x] `live_actors` atomic; termination = io_out == 0 (read pre-queue-lock)
+      && queue empty && live == 0; decrement-last ordering documented as the
+      correctness crux at the site.
 
 ## Phase 3 — Pluggable run queue + bench shootout
 - [ ] Extract `RunQueue` behind a `type RunQueue = ...` alias selected at
@@ -92,9 +98,13 @@ Make slot lookup lock-free and per-slot state independently mutable.
 - **Channel mutex migration.** `channel::Inner<T>` is `Arc<Mutex<_>>` of the
   same poison class as the old shared lock; `recv_match` even runs a user
   predicate under it. The Phase-1 `check_cancelled` gating already removes the
-  unwind *source* globally, so channels are safe today — but migrating the
-  channel to the raw non-poisoning mutex (Phase 2) is a clean follow-up rather
-  than bundled into the run-path rework.
+  unwind *source* globally, so channels are poison-safe today — but phase 2
+  surfaced a second, sharper reason to migrate: the std `MutexGuard` is held
+  with preemption ENABLED, so a timeslice switch inside a channel critical
+  section migrates the actor and unlocks the pthread mutex from a different
+  OS thread — technically UB (Linux futexes happen to tolerate it). The
+  `RawMutex` guard disables preemption and is cross-thread-release sound by
+  construction. Migrate as the first post-v0.5 change.
 
 ## Deferred / explicitly out of scope for v0.5
 - **Unbounded / configurable-bounded actor count.** v0.5 ships a fixed slab