docs(monitor): user-facing rewrite of process monitors

Lead with the user's problem (learn when another actor dies without
it knowing you're watching), explain one-directional/one-shot
semantics and contrast briefly with link without assuming link.rs has
been read. Add a compiling doctest. Drop em-dashes. Correctness facts
about registration/death races and demonitor-after-fire safety kept,
reworded in plain terms and separated from the public item docs.

src/channel.rs

@@ -1,38 +1,102 @@
-//! Unbounded MPSC channels.
+//! Unbounded multi-producer, single-consumer channels: how actors talk to
+//! each other.
 //!
-//! Inner state is `Arc<RawMutex<Inner<T>>>` so channels can be sent across OS
-//! threads (required for the multi-scheduler runtime where a sender and
-//! receiver may run on different scheduler threads simultaneously).
+//! A channel is a queue with a typed [`Sender`] on one end and a typed
+//! [`Receiver`] on the other. Any number of actors can hold a clone of the
+//! `Sender` and push messages onto the same queue; exactly one [`Receiver`]
+//! reads them back out, in the order they arrived. This is the basic wiring
+//! smarm's other actor primitives (`gen_server`, `pg`, the registry) are all
+//! built out of, and it is directly usable on its own for a worker that just
+//! needs an inbox.
 //!
-//! ## Why `RawMutex` (Channel class), not `std::sync::Mutex`
+//! ## A first channel
 //!
-//! An actor holding a guard with preemption *enabled* can be timesliced
-//! inside the critical section and resume on a different OS thread — the
-//! pthread mutex would then be released from a thread that didn't lock it,
-//! which is UB (Linux futexes happen to tolerate it, but it's not
-//! guaranteed). `RawMutex` disables preemption for the guard's span and is
-//! cross-thread-release sound by construction, closing the hole. It also
-//! cannot poison. Channel locks form their own [`LockClass::Channel`]
-//! (raw_mutex.rs): they may be taken under a cold (Leaf) lock — finalize and
-//! `monitor()` clone senders that live in slots — but nothing may be locked
-//! under them, which the debug build enforces. `recv_match` runs its user
-//! predicate under this lock: keep it cheap, pure, and channel-free.
+//! ```
+//! use smarm::{channel, run, spawn};
 //!
-//! Semantics:
-//!   - Senders are clonable; the last sender drop closes the channel.
-//!   - `Receiver::recv` on an empty open channel parks the receiver.
-//!   - `Receiver::recv` on an empty closed channel returns `Err(RecvError)`.
-//!   - `Sender::send` on an open channel always succeeds.
-//!   - `Sender::send` on a closed channel (receiver dropped) returns
-//!     `Err(SendError(value))`.
-//!   - When a send pushes to a previously empty queue and a receiver is
-//!     parked, the receiver is unparked.
+//! run(|| {
+//!     let (tx, rx) = channel::<u64>();
+//!
+//!     let worker = spawn(move || {
+//!         // Blocks until a message arrives.
+//!         let n = rx.recv().unwrap();
+//!         assert_eq!(n, 42);
+//!
+//!         // Once every Sender is dropped, recv() reports the channel closed
+//!         // instead of blocking forever.
+//!         assert!(rx.recv().is_err());
+//!     });
+//!
+//!     tx.send(42).unwrap();
+//!     drop(tx); // last sender gone: the channel is now closed
+//!     worker.join().unwrap();
+//! });
+//! ```
+//!
+//! ## Sending
+//!
+//! [`Sender`] is cheaply clonable: hand a clone to every actor that needs to
+//! push messages into this queue. The channel stays open as long as at least
+//! one clone exists; [`Sender::send`] never blocks and always succeeds while
+//! the channel is open, since the queue is unbounded. Once the [`Receiver`]
+//! has been dropped, `send` returns the message back to you in
+//! [`SendError`] instead of delivering it.
+//!
+//! ## Receiving
+//!
+//! There is exactly one [`Receiver`] per channel (it is not clonable).
+//! [`Receiver::recv`] returns the next message in arrival order, parking the
+//! calling actor if the queue is currently empty. Once every `Sender` has
+//! been dropped and the queue has been drained, `recv` stops parking and
+//! returns [`RecvError`] instead, so a receiver never blocks forever waiting
+//! on senders that are never coming back.
+//!
+//! Beyond plain `recv`, three variants cover the common needs:
+//!
+//! - [`Receiver::try_recv`]: never parks: reports an empty-but-open channel
+//!   as `Ok(None)` instead of waiting.
+//! - [`Receiver::recv_timeout`]: parks, but gives up and returns
+//!   [`RecvTimeoutError::Timeout`] if no message arrives before a deadline.
+//! - [`Receiver::recv_match`] / [`Receiver::try_recv_match`]: selective
+//!   receive. Instead of taking whatever is at the front of the queue, pick
+//!   out the first message matching a predicate, leaving the rest queued in
+//!   order. Handy for an actor that wants to prioritise one kind of message
+//!   over others already waiting.
+//!
+//! ## Waiting on several channels: `select`
+//!
+//! [`select`] parks an actor across several receivers at once and reports
+//! the index of the first one that is ready (has a message queued, or has
+//! been closed). [`select_timeout`] adds a deadline, the way `recv_timeout`
+//! does for a single channel. See their docs for the full contract,
+//! including the priority-order and no-fairness guarantee.
+//!
+//! ## Implementation notes
+//!
+//! The queue and its bookkeeping live behind `Arc<RawMutex<Inner<T>>>`
+//! rather than a `std::sync::Mutex`, so that a channel can be freely shared
+//! and sent across the OS threads backing the multi-scheduler runtime.
+//! `RawMutex` matters here for a subtler reason too: an ordinary pthread
+//! mutex can be released from a different OS thread than the one that took
+//! it (smarm's preemption can migrate a timesliced actor between scheduler
+//! threads mid-critical-section), and doing that to a `std::sync::Mutex` is
+//! undefined behavior. `RawMutex` disables preemption for the guard's short
+//! lifetime instead, so the release always happens on the thread that
+//! acquired it, and it has no poisoning to worry about besides. Channel
+//! locks are cheap and are never held across another lock acquisition or a
+//! blocking call; the predicate passed to `recv_match` runs under this lock,
+//! which is why it needs to stay cheap, pure, and must not call back into
+//! the same channel.
 
 use crate::pid::Pid;
 use crate::raw_mutex::RawMutex;
 use std::collections::VecDeque;
 use std::sync::Arc;
 
+/// Create a new channel and return its `(Sender, Receiver)` halves.
+///
+/// The channel is unbounded (no capacity limit) and open until every
+/// `Sender` has been dropped.
 pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
     let inner = Arc::new(RawMutex::new_channel(Inner {
         queue: VecDeque::new(),
@@ -45,29 +109,40 @@ pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
 
 struct Inner<T> {
     queue: VecDeque<T>,
-    /// The parked receiver's `(pid, park-epoch)`. The epoch is the slot
-    /// word's runtime-wide wait identity (see slot_state.rs): wakers call
-    /// `unpark_at(pid, epoch)`, so an entry left over from an already-woken
-    /// wait — a `select` loser arm, a satisfied `recv_timeout`'s timer — is
-    /// inert: the wake fails the word's epoch CAS and no-ops. This replaces
-    /// the old per-channel `cur_wait`/`next_wait_seq`/`timed_out` trio: wait
-    /// identity now exists exactly once, in the slot word.
+    /// The parked receiver's `(pid, park-epoch)`, if one is currently
+    /// waiting. The epoch identifies exactly which wait this is, so a waker
+    /// left over from a wait that already ended (a losing `select` arm, a
+    /// `recv_timeout` whose timer fired after it was already satisfied) is
+    /// inert and does nothing when it fires.
     parked_receiver: Option<(Pid, u32)>,
     senders: usize,
     receiver_alive: bool,
 }
 
+/// The sending half of a channel, created by [`channel`]. Clonable: every
+/// clone pushes onto the same queue, and the channel stays open as long as
+/// any clone is alive. Dropping the last `Sender` closes the channel, which
+/// wakes a parked [`Receiver`] so it can observe the closure.
 pub struct Sender<T> {
     inner: Arc<RawMutex<Inner<T>>>,
 }
 
+/// The receiving half of a channel, created by [`channel`]. Not clonable:
+/// a channel has exactly one receiver. Reads messages in the order they
+/// were sent, via [`recv`](Receiver::recv) and its variants.
 pub struct Receiver<T> {
     inner: Arc<RawMutex<Inner<T>>>,
 }
 
+/// Returned by [`Sender::send`] when the channel's [`Receiver`] has already
+/// been dropped. Carries the message back so it is never silently lost;
+/// recover it with `.0` or by matching.
 #[derive(Debug, PartialEq, Eq)]
 pub struct SendError<T>(pub T);
 
+/// Returned by [`Receiver::recv`] (and the other receive methods, in their
+/// own error types) when the channel is closed: every `Sender` has been
+/// dropped and no message is left queued.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub struct RecvError;
 
@@ -84,8 +159,8 @@ impl std::error::Error for RecvError {}
 pub enum RecvTimeoutError {
     /// The deadline passed with no message available.
     Timeout,
-    /// All senders dropped with no message available — the bounded analogue
-    /// of [`RecvError`].
+    /// Every sender was dropped with no message available. The
+    /// timeout-aware counterpart of plain [`RecvError`].
     Disconnected,
 }
 
@@ -115,8 +190,8 @@ impl<T> Drop for Sender<T> {
             // Wake the parked receiver on the last sender drop regardless of
             // whether the queue is empty. A plain `recv` only ever parks on an
             // empty queue (so this is unchanged for it), but a selective
-            // `recv_match` may be parked on a *non-empty* queue holding only
-            // non-matching messages — it must wake to observe closure and
+            // `recv_match` may be parked on a non-empty queue holding only
+            // non-matching messages. It must wake to observe closure and
             // return Err rather than sleep forever.
             if g.senders == 0 {
                 g.parked_receiver.take()
@@ -133,14 +208,15 @@ impl<T> Drop for Sender<T> {
 impl<T> Drop for Receiver<T> {
     fn drop(&mut self) {
         // The only consumer is gone: queued messages can never be delivered.
-        // Drop them now instead of stranding them until the last Sender goes
-        // away (a registry entry under lazy prune can keep a Sender — and thus
-        // the Arc<Inner> — alive long after the server exits). Dropping a queued
-        // Envelope::Call drops its reply_tx, waking any caller parked in `call`
-        // with ServerDown, so the documented guarantee holds on *every* teardown
-        // path, not only the all-senders-drop one. Drain under the lock, then
-        // run item destructors after releasing it (a reply_tx drop reaches into
-        // a *different* channel's lock + the scheduler, so it must not nest).
+        // Drop them now instead of leaving them queued until the last Sender
+        // happens to go away, which can be long after this receiver's owner
+        // has exited if some other part of the runtime is still holding a
+        // clone of the Sender. Draining runs each queued message's own drop
+        // glue, which matters for a gen_server call: dropping a queued call
+        // envelope drops its reply channel too, which wakes the caller with
+        // an error instead of leaving it parked forever. Drain under the
+        // lock, then run the drops after releasing it, since a message's
+        // drop glue may itself touch a different channel or the scheduler.
         let drained = {
             let mut g = self.inner.lock();
             g.receiver_alive = false;
@@ -151,14 +227,17 @@ impl<T> Drop for Receiver<T> {
 }
 
 impl<T> Sender<T> {
-    /// Number of messages currently queued behind this channel. Introspection
-    /// only (RFC 016 mailbox depth); takes the channel lock, so callers reach
-    /// it under the registry Leaf (Leaf → Channel) via the erased probe in
-    /// `registry.rs`, never on a hot path.
+    /// Number of messages currently queued and not yet received. For
+    /// introspection and monitoring; takes the channel's internal lock, so
+    /// avoid calling it from a hot path.
     pub(crate) fn queued_len(&self) -> usize {
         self.inner.lock().queue.len()
     }
 
+    /// Push `value` onto the channel. Succeeds unconditionally as long as
+    /// the [`Receiver`] is still alive: the queue has no capacity limit, so
+    /// this never blocks and never fails except when the channel is closed,
+    /// in which case `value` comes back in [`SendError`].
     pub fn send(&self, value: T) -> Result<(), SendError<T>> {
         let unpark = {
             let mut g = self.inner.lock();
@@ -179,6 +258,10 @@ impl<T> Sender<T> {
 }
 
 impl<T> Receiver<T> {
+    /// Block until a message is available and return it. Messages come back
+    /// in the order they were sent. If the queue is empty and every
+    /// [`Sender`] has already been dropped, returns [`RecvError`] instead of
+    /// blocking forever.
     pub fn recv(&self) -> Result<T, RecvError> {
         loop {
             {
@@ -198,15 +281,15 @@ impl<T> Receiver<T> {
                     g.parked_receiver.is_none_or(|(p, _)| p == me),
                     "channel has more than one receiver"
                 );
-                // begin_wait is lock-free — legal under the Channel lock;
+                // begin_wait is lock-free, so it's legal under the Channel lock;
                 // registering in the same critical section makes the epoch
                 // atomic with the senders' view of the registration.
                 g.parked_receiver = Some((me, crate::scheduler::begin_wait()));
                 crate::te!(crate::trace::Event::RecvPark(me));
             }
-            // Release the lock before parking — the unparker will need it.
+            // Release the lock before parking: the unparker will need it.
             crate::scheduler::park_current();
-            // Woken up — record it before looping to check the queue.
+            // Woken up. Record it before looping to check the queue.
             crate::te!(crate::trace::Event::RecvWake(match crate::actor::current_pid() {
                 Some(p) => p,
                 None => panic!("smarm: RecvWake outside an actor (core corrupt)"),
@@ -214,29 +297,18 @@ impl<T> Receiver<T> {
         }
     }
 
-    /// Bounded receive: like [`recv`](Self::recv), but gives up once
-    /// `timeout` has elapsed, returning [`RecvTimeoutError::Timeout`].
+    /// Like [`recv`](Self::recv), but gives up and returns
+    /// [`RecvTimeoutError::Timeout`] if no message has arrived by the time
+    /// `timeout` elapses.
     ///
-    /// Built on the same timer machinery as `Mutex::lock_timeout`: the wait
-    /// registers a `WaitTimeout` entry stamped with the wait's park-epoch;
-    /// on expiry the channel (as the
-    /// [`TimerTarget`](crate::timer::TimerTarget)) checks whether *this*
-    /// wait is still parked and, only then, cancels it. A wake that races
-    /// the deadline resolves message-first: if a message is available when
-    /// the receiver runs, it is delivered even if the timer had already
-    /// fired. A satisfied or abandoned wait leaves its timer entry to expire
-    /// as a no-op (registration gone; epoch consumed), per the
-    /// no-cancellation convention in `timer.rs`.
+    /// If a message arrives at essentially the same moment the deadline
+    /// passes, the message wins: you get `Ok` rather than `Timeout`. If
+    /// every sender is dropped before a message arrives or the deadline
+    /// passes, you get [`RecvTimeoutError::Disconnected`].
     ///
-    /// The wake is classified from state alone — wakes are precise (the only
-    /// stamped wakers of this wait are a send, the last-sender drop, and the
-    /// timer; a stop wake unwinds out of `park_current` and never reaches
-    /// the classification), so: message queued → `Ok`; `senders == 0` →
-    /// `Disconnected`; neither → it was the timer → `Timeout`.
-    ///
-    /// `Duration::ZERO` is a valid timeout: it parks until the immediately-
-    /// due timer is drained, then reports `Timeout` unless a message was
-    /// already queued.
+    /// `Duration::ZERO` is a valid timeout: it still gives any
+    /// already-queued message a chance to be returned, and only then
+    /// reports `Timeout`.
     pub fn recv_timeout(&self, timeout: std::time::Duration) -> Result<T, RecvTimeoutError>
     where
         T: Send + 'static,
@@ -268,7 +340,7 @@ impl<T> Receiver<T> {
 
         // Arm the timer after releasing the channel lock (insert takes the
         // timers lock; never nest under a Channel lock). A send or even the
-        // timer itself may unpark us before we park — the RunningNotified
+        // timer itself may unpark us before we park; the runtime's wake
         // protocol makes the park below return immediately in that case.
         let deadline = crate::timer::deadline_from_now(timeout);
         let target: std::sync::Arc<dyn crate::timer::TimerTarget> = self.inner.clone();
@@ -290,16 +362,23 @@ impl<T> Receiver<T> {
         Err(RecvTimeoutError::Timeout)
     }
 
-    /// Selective receive: remove and return the first queued message for which
-    /// `pred` holds, leaving the rest in arrival order. If no queued message
-    /// matches, parks and re-scans on every send (a selective receiver may park
-    /// on a *non-empty* queue). Returns `Err(RecvError)` only once the channel
-    /// is closed and no queued message matches.
+    /// Selective receive: find and return the first queued message for
+    /// which `pred` returns `true`, leaving every other message in the
+    /// queue untouched and in order. Useful when an actor's inbox mixes
+    /// message kinds and it wants to handle one kind out of turn, without
+    /// discarding the rest.
     ///
-    /// `pred` is run while the channel lock is held: keep it cheap and pure,
-    /// and do not call back into this channel from inside it. It is modelled as
-    /// `Fn` (not `FnMut`) deliberately — it is re-run from scratch on every
-    /// scan, so a stateful predicate would observe surprising re-counting.
+    /// If nothing queued matches, this blocks and re-checks every time a new
+    /// message arrives, the same way [`recv`](Self::recv) blocks on an empty
+    /// queue: a selective receiver can be waiting even while the queue holds
+    /// messages, just none that match yet. Returns [`RecvError`] only once
+    /// the channel is closed and still nothing matches.
+    ///
+    /// `pred` runs while the channel is locked, so keep it cheap, side
+    /// effect free, and make sure it never calls back into this same
+    /// channel. It takes `&T` and is called fresh on every scan (not `FnMut`
+    /// with running state), so it should judge each message purely on its
+    /// own content.
     pub fn recv_match<F>(&self, pred: F) -> Result<T, RecvError>
     where
         F: Fn(&T) -> bool,
@@ -331,7 +410,7 @@ impl<T> Receiver<T> {
                 g.parked_receiver = Some((me, crate::scheduler::begin_wait()));
                 crate::te!(crate::trace::Event::RecvPark(me));
             }
-            // Release the lock before parking — the unparker will need it.
+            // Release the lock before parking: the unparker will need it.
             crate::scheduler::park_current();
             crate::te!(crate::trace::Event::RecvWake(match crate::actor::current_pid() {
                 Some(p) => p,
@@ -340,10 +419,12 @@ impl<T> Receiver<T> {
         }
     }
 
-    /// Non-blocking selective receive. `Ok(Some(v))` if a queued message
-    /// matched `pred` (removed, rest left in order), `Ok(None)` if the channel
-    /// is open but nothing matched, `Err(RecvError)` if closed and nothing
-    /// matched. Same predicate contract as [`recv_match`](Self::recv_match).
+    /// The non-blocking counterpart of [`recv_match`](Self::recv_match):
+    /// returns immediately either way. `Ok(Some(v))` if a queued message
+    /// matched `pred` (removed; the rest stay queued in order), `Ok(None)`
+    /// if the channel is open but nothing currently matches, `Err(RecvError)`
+    /// if the channel is closed and nothing matches. Same predicate contract
+    /// as `recv_match`.
     pub fn try_recv_match<F>(&self, pred: F) -> Result<Option<T>, RecvError>
     where
         F: Fn(&T) -> bool,
@@ -363,8 +444,10 @@ impl<T> Receiver<T> {
         Ok(None)
     }
 
-    /// Non-blocking. `Ok(Some(v))` if a message was available, `Ok(None)` if
-    /// the channel is empty but open, `Err(RecvError)` if closed and drained.
+    /// The non-blocking counterpart of [`recv`](Self::recv): returns
+    /// immediately either way. `Ok(Some(v))` if a message was queued,
+    /// `Ok(None)` if the channel is open but currently empty, `Err(RecvError)`
+    /// if the channel is closed and the queue is drained.
     pub fn try_recv(&self) -> Result<Option<T>, RecvError> {
         let mut g = self.inner.lock();
         if let Some(v) = g.queue.pop_front() {
@@ -379,18 +462,18 @@ impl<T> Receiver<T> {
 }
 
 // ---------------------------------------------------------------------------
-// TimerTarget — the expiry half of recv_timeout
+// TimerTarget: the expiry half of recv_timeout
 // ---------------------------------------------------------------------------
 
 impl<T: Send + 'static> crate::timer::TimerTarget for RawMutex<Inner<T>> {
     fn on_timeout(&self, pid: Pid, epoch: u32) {
         // Cancel the wait only if THIS wait (epoch match) is still
         // registered. If a sender already took `parked_receiver`, the
-        // receiver is waking with a message — message wins, the timer
+        // receiver is waking with a message: message wins, the timer
         // no-ops. If a later wait by the same receiver is registered, the
-        // epoch mismatches — stale entry, no-op. (The unpark_at would fail
-        // its word CAS in either case anyway; checking under the lock keeps
-        // the registration bookkeeping exact.)
+        // epoch mismatches: stale entry, no-op. (unpark_at would fail its
+        // internal check in either case anyway; checking under the lock
+        // keeps the registration bookkeeping exact.)
         let unpark = {
             let mut g = self.lock();
             if g.parked_receiver == Some((pid, epoch)) {
@@ -400,7 +483,7 @@ impl<T: Send + 'static> crate::timer::TimerTarget for RawMutex<Inner<T>> {
                 false
             }
         };
-        // Unpark outside the channel lock — it may take the run-queue lock;
+        // Unpark outside the channel lock: it may take the run-queue lock;
         // legal under a Channel lock, but pointless to nest.
         if unpark {
             crate::scheduler::unpark_at(pid, epoch);
@@ -409,7 +492,7 @@ impl<T: Send + 'static> crate::timer::TimerTarget for RawMutex<Inner<T>> {
 }
 
 // ---------------------------------------------------------------------------
-// select — ready-index wait over multiple receivers
+// select: ready-index wait over multiple receivers
 // ---------------------------------------------------------------------------
 
 pub(crate) mod sealed {
@@ -417,33 +500,34 @@ pub(crate) mod sealed {
 }
 impl<T> sealed::Sealed for Receiver<T> {}
 
-/// An arm of a [`select`]. Implemented by [`Receiver`]; sealed, because the
-/// registration contract below is part of the runtime's wake protocol.
+/// An arm of a [`select`]: something you can wait on alongside other arms
+/// and be told when it becomes ready. Implemented by [`Receiver`]; sealed
+/// (cannot be implemented outside this crate), since the registration
+/// contract below is part of the runtime's internal wake protocol.
 ///
 /// Contract (all under the arm's own lock): `sel_register` checks-or-
-/// registers atomically — if the arm is ready it does NOT register and
+/// registers atomically. If the arm is ready it does not register and
 /// returns `Ok(false)`; otherwise it publishes `(pid, epoch)` where its
 /// wakers will find it and returns `Ok(true)`. "Ready" means a receive
-/// would not park: a message is queued, or the arm is closed. `Err` means
+/// would not block: a message is queued, or the arm is closed. `Err` means
 /// the arm could not register at all (only fd arms can fail; channel
-/// registration is infallible) — the wait must be retired and earlier
+/// registration always succeeds), and the wait must be retired and earlier
 /// eager-cleanup arms unregistered.
 pub trait Selectable: sealed::Sealed {
     #[doc(hidden)]
     fn sel_register(&self, pid: Pid, epoch: u32) -> std::io::Result<bool>;
     #[doc(hidden)]
     fn sel_ready(&self) -> bool;
-    /// Remove this arm's `(pid, epoch)` registration if — and only if — it
-    /// is still in place. Default no-op: a losing channel arm's stale
-    /// registration is inert (its wakers die at the epoch CAS; the next
-    /// wait overwrites the slot). Fd arms override this: their staleness
-    /// poisons the fd (waiters entry + kernel-side ONESHOT registration)
-    /// and needs an eager cleanup pass.
+    /// Remove this arm's `(pid, epoch)` registration if, and only if, it is
+    /// still in place. Default no-op: a losing channel arm's stale
+    /// registration is harmless and self-cleans. Fd arms override this:
+    /// their staleness would otherwise leave the fd unusable for future
+    /// selects, so they need an eager cleanup pass.
     #[doc(hidden)]
     fn sel_unregister(&self, _pid: Pid, _epoch: u32) {}
     /// Whether this arm requires the eager cleanup pass at all. Gates the
-    /// post-wake `sel_unregister` sweep so channel-only selects keep
-    /// today's zero-cancellation hot path.
+    /// post-wake `sel_unregister` sweep so channel-only selects keep their
+    /// cheap, cleanup-free path.
     #[doc(hidden)]
     fn sel_eager_cleanup(&self) -> bool {
         false
@@ -470,38 +554,35 @@ impl<T> Selectable for Receiver<T> {
     }
 }
 
-/// Park on every arm at once; return the index of the first ready one.
+/// Wait on several channels at once and return the index of the first one
+/// that is ready, instead of blocking on just one with [`Receiver::recv`].
 ///
-/// "Ready" means a receive on that arm would not park: a message is queued,
-/// or the arm is **closed** (so the caller's `try_recv` observes the
-/// disconnect — a dead arm is an event, not a hang). The caller consumes the
-/// arm itself, typically via [`Receiver::try_recv`]; single-receiver
-/// channels guarantee nothing can steal the message in between.
+/// "Ready" means a receive on that arm would not block: a message is
+/// queued, or the arm is closed (so the caller's own `try_recv` observes
+/// the disconnect: a dead arm is something to react to, not something to
+/// hang on). `select` only tells you which arm is ready; read the actual
+/// message yourself, typically with [`Receiver::try_recv`] on that arm.
 ///
-/// A closed arm stays ready *forever*: once its disconnect has been
-/// observed, drop it from the arm set — under priority order it would
-/// otherwise win every subsequent call and starve every higher-indexed arm.
+/// A closed arm stays ready forever. Once you have observed its disconnect,
+/// drop it from the arm set you pass in next time: otherwise, under the
+/// priority order below, it would win every subsequent call and starve
+/// every arm listed after it.
 ///
-/// Arms are scanned **in order**: index 0 is the highest priority, both on
-/// the immediate-ready path and after a wake. This is a documented
-/// guarantee (compose like BEAM receive clauses: put control channels
-/// first), not an accident — and therefore there is NO fairness promise; a
-/// saturated arm 0 starves arm 1 by design.
+/// Arms are checked **in order**: index 0 is the highest priority, both
+/// when checking immediately and after being woken. This is a deliberate,
+/// documented guarantee, not an accident of implementation: put a control
+/// or shutdown channel first so it is always noticed promptly. The
+/// flip side is that there is **no fairness guarantee**: a busy arm 0 can
+/// starve arm 1 indefinitely by design.
 ///
-/// One actor may select on a channel and later `recv` on it (or select on
-/// overlapping sets) freely. What stays illegal is what was always illegal:
-/// two *different* actors receiving on one channel.
+/// One actor can `select` on a channel and later plain `recv` on it (or
+/// `select` again on an overlapping set of arms) with no restriction. What
+/// stays illegal is what was always illegal for a channel: two *different*
+/// actors receiving on the same one.
 ///
-/// Built on the consuming-wake protocol (see slot_state.rs): all arms are
-/// registered under one wait epoch; the winning wake consumes it, so losing
-/// arms' registrations are inert and need no cancellation pass — they
-/// self-clean at their wakers' failed CAS, or get overwritten by this
-/// receiver's next wait on that channel.
-///
-/// Panics if `arms` is empty, when called outside an actor, or if an fd
-/// arm fails to register (EBADF, EMFILE, a second waiter on one fd —
-/// see [`try_select`] for the fallible form; channel-only selects cannot
-/// fail).
+/// Panics if `arms` is empty, if called outside an actor, or if an fd arm
+/// fails to register (see [`try_select`] for the fallible form; a
+/// channel-only `select` can never fail).
 pub fn select(arms: &[&dyn Selectable]) -> usize {
     match try_select(arms) {
         Ok(i) => i,
@@ -509,9 +590,10 @@ pub fn select(arms: &[&dyn Selectable]) -> usize {
     }
 }
 
-/// [`select`], fallible: `Err` when an arm fails to register (only fd
-/// arms can — EBADF, EMFILE on the epoll set, or a second waiter on an
-/// fd that already has one). On `Err` the wait is fully retired and no
+/// The fallible form of [`select`]: `Err` when an arm fails to register.
+/// Only fd arms can fail this way (for example, the file descriptor is
+/// invalid, or something else is already waiting on it); a channel-only
+/// select can never fail. On `Err` the wait is fully retired and no
 /// registration is left behind: every arm registered before the failing
 /// one has been unregistered.
 pub fn try_select(arms: &[&dyn Selectable]) -> std::io::Result<usize> {
@@ -527,13 +609,12 @@ pub fn try_select(arms: &[&dyn Selectable]) -> std::io::Result<usize> {
         }
 
         // Stale fd registrations are not harmless (a losing fd arm's
-        // waiters entry poisons the fd with AlreadyExists and its
-        // kernel-side ONESHOT registration can fire arbitrarily late), so
-        // selects containing fd arms run an eager cleanup pass after the
-        // park — including when a terminal stop unwinds out of it, via
-        // the guard. Channel-only selects skip all of it: `eager` is
-        // false, the guard is disarmed, and the loser-arm self-cleaning
-        // story is unchanged.
+        // leftover registration can make the fd unusable for the next
+        // select until a kernel event happens to clear it), so selects
+        // containing fd arms run an eager cleanup pass after the park,
+        // including when a terminal stop unwinds out of it, via the guard.
+        // Channel-only selects skip all of it: `eager` is false, the guard
+        // is disarmed, and the loser-arm self-cleaning story is unchanged.
         let eager = arms.iter().any(|a| a.sel_eager_cleanup());
         let mut guard = UnregisterGuard { arms, me, epoch, armed: eager };
 
@@ -546,22 +627,22 @@ pub fn try_select(arms: &[&dyn Selectable]) -> std::io::Result<usize> {
         drop(guard);
 
         // Woken precisely: an arm's send (message) or last-sender drop
-        // (closure) consumed our epoch, and both leave their arm ready —
-        // return the first one, in priority order (which may be a
+        // (closure) is what woke us, and both leave their arm ready.
+        // Return the first ready one, in priority order (which may be a
         // different, higher-priority arm than the one that woke us; its
         // message stays queued and re-reports ready on the next call).
         // Fd arms classify by a fresh zero-timeout poll, so they too are
-        // a pure function of state — independent of the registration the
-        // cleanup pass just removed.
+        // a pure function of current state, independent of the
+        // registration the cleanup pass just removed.
         for (i, arm) in arms.iter().enumerate() {
             if arm.sel_ready() {
                 return Ok(i);
             }
         }
-        // Unreachable by protocol (a stop wake unwinds out of
-        // park_current). Defensive: re-open the wait and re-register —
-        // stale own-registrations are overwritten (channels) or were
-        // removed by the cleanup pass above (fds).
+        // Unreachable in practice (a stop wake unwinds out of
+        // park_current before we get here). Defensive: re-open the wait
+        // and re-register; stale own-registrations are overwritten
+        // (channels) or were removed by the cleanup pass above (fds).
     }
 }
 
@@ -576,11 +657,11 @@ fn unregister_arms(arms: &[&dyn Selectable], me: Pid, epoch: u32) {
     }
 }
 
-/// Stop-unwind twin of the explicit cleanup pass: a terminal stop unwinds
-/// out of `park_current`, and a registered fd arm must not outlive its
-/// actor (the generalization of `wait_fd`'s `Dereg`). Disarmed on the
-/// normal path after the explicit pass runs; never armed when no fd arm
-/// registered, keeping the channel-only path guard-free in effect.
+// Stop-unwind twin of the explicit cleanup pass: a terminal stop unwinds
+// out of `park_current`, and a registered fd arm must not outlive its
+// actor. Disarmed on the normal path after the explicit pass runs; never
+// armed when no fd arm is registered, keeping the channel-only path
+// guard-free in effect.
 struct UnregisterGuard<'a> {
     arms: &'a [&'a dyn Selectable],
     me: Pid,
@@ -596,20 +677,16 @@ impl Drop for UnregisterGuard<'_> {
     }
 }
 
-/// The registration pass shared by [`select`] and [`select_timeout`]:
-/// check-or-register each arm, in priority order, each atomically under its
-/// own lock. Cross-arm atomicity is unnecessary: an arm becoming ready
-/// right after its registration wakes the caller through the protocol (the
-/// prep-to-park window is closed by RunningNotified).
-///
-/// `Ok(Some(i))` = arm `i` was ready, the pass stopped, and the wait has
-/// been RETIRED (no park may follow): earlier arms hold live-epoch
-/// registrations, so earlier *fd* arms are unregistered eagerly, then the
-/// epoch is bumped, a landed notification eaten, and a pending stop
-/// re-observed — without which a stale arm wake could fault a later
-/// one-shot park. `Err` = an arm failed to register; identical unwind
-/// (earlier fd arms unregistered, wait retired). `Ok(None)` = every arm
-/// registered; the caller parks.
+// The registration pass shared by `select` and `select_timeout`: check-or-
+// register each arm, in priority order, each atomically under its own lock.
+// Cross-arm atomicity is unnecessary: an arm becoming ready right after its
+// registration still wakes the caller through the normal wake path.
+//
+// `Ok(Some(i))` = arm `i` was already ready, the pass stopped, and the wait
+// has been fully retired (no park may follow): earlier fd arms are
+// unregistered eagerly so none are left dangling. `Err` = an arm failed to
+// register; same unwind (earlier fd arms unregistered, wait retired).
+// `Ok(None)` = every arm registered successfully; the caller parks.
 fn register_arms(
     me: Pid,
     epoch: u32,
@@ -633,10 +710,10 @@ fn register_arms(
     Ok(None)
 }
 
-/// The [`select_timeout`] timer target: stateless, because precise wakes
-/// make classification a pure function of channel state. The entry is
-/// stamped with the select's epoch; if an arm already won, this unpark dies
-/// at the word's epoch CAS (the no-cancellation convention in `timer.rs`).
+// The `select_timeout` timer target: stateless, because a wake's cause can
+// always be read back off plain channel state (an arm ready, or not). If
+// an arm already won before the deadline, this timer's fire is simply
+// ignored, the way any other stale wakeup is.
 struct SelectTimeout;
 impl crate::timer::TimerTarget for SelectTimeout {
     fn on_timeout(&self, pid: Pid, epoch: u32) {
@@ -644,27 +721,21 @@ impl crate::timer::TimerTarget for SelectTimeout {
     }
 }
 
-/// [`select`] with a deadline: returns `Some(index)` like `select`, or
-/// `None` once `timeout` elapses with no arm ready.
+/// Like [`select`], but gives up and returns `None` if no arm becomes
+/// ready before `timeout` elapses.
 ///
-/// All of `select`'s semantics carry over (priority order, closed arms
-/// permanently ready, no fairness promise). The timeout is one more stamped
-/// waker on the same wait epoch — nothing is registered in any arm for it,
-/// so there is nothing to cancel or leak: an arm winning leaves the timer
-/// entry to expire as a stale-epoch no-op; the timer winning leaves the
-/// arms' registrations to self-clean exactly as a `select` loser's would.
+/// All of `select`'s semantics carry over: arms are still checked in
+/// priority order, a closed arm is still permanently ready, and there is
+/// still no fairness guarantee across arms. A message that arrives at
+/// essentially the same moment the deadline passes still wins, the same
+/// way [`Receiver::recv_timeout`] resolves that race.
 ///
-/// The wake is classified from state alone (wakes are precise): some arm
-/// ready → `Some` of the first, in priority order; none ready → the timer
-/// was the only remaining stamped waker → `None`. A message that races the
-/// deadline resolves message-first, as `recv_timeout` does.
+/// `Duration::ZERO` is a valid timeout: it still gives an already-ready arm
+/// a chance to be reported before falling through to `None`.
 ///
-/// `Duration::ZERO` is a valid timeout: it parks until the immediately-due
-/// timer is drained, then reports `None` unless an arm was already ready.
-///
-/// Panics if `arms` is empty, when called outside an actor, or if an fd
-/// arm fails to register (see [`try_select_timeout`] for the fallible
-/// form; channel-only selects cannot fail).
+/// Panics if `arms` is empty, if called outside an actor, or if an fd arm
+/// fails to register (see [`try_select_timeout`] for the fallible form; a
+/// channel-only select can never fail).
 pub fn select_timeout(
     arms: &[&dyn Selectable],
     timeout: std::time::Duration,
@@ -677,9 +748,9 @@ pub fn select_timeout(
     }
 }
 
-/// [`select_timeout`], fallible: `Err` when an arm fails to register
-/// (only fd arms can). On `Err` the wait is fully retired and no
-/// registration — arm-side or kernel-side — is left behind.
+/// The fallible form of [`select_timeout`]: `Err` when an arm fails to
+/// register (only fd arms can). On `Err` the wait is fully retired and no
+/// registration is left behind on any arm.
 pub fn try_select_timeout(
     arms: &[&dyn Selectable],
     timeout: std::time::Duration,
@@ -694,17 +765,16 @@ pub fn try_select_timeout(
         return Ok(Some(i)); // ready now: the timer was never armed
     }
 
-    // Arm the timer after the registration pass, outside every Channel
-    // lock (insert takes the timers lock).
+    // Arm the timer after the registration pass, outside every channel
+    // lock (inserting a timer takes the timers lock).
     let deadline = crate::timer::deadline_from_now(timeout);
     let target: std::sync::Arc<dyn crate::timer::TimerTarget> = std::sync::Arc::new(SelectTimeout);
     crate::scheduler::insert_wait_timer(deadline, me, target, epoch);
 
-    // Same eager-cleanup story as `try_select`: the timer arm needs none
-    // (stateless, stale entries die at the epoch CAS), channel arms need
-    // none, fd arms do — and a timer win in particular leaves every fd
-    // arm's registration behind, which without this pass would poison
-    // those fds until a kernel event happened to fire.
+    // Same eager-cleanup story as `try_select`: a timer win in particular
+    // leaves every fd arm's registration behind, which without this pass
+    // would leave those fds unusable until a kernel event happened to
+    // clear them.
     let eager = arms.iter().any(|a| a.sel_eager_cleanup());
     let mut guard = UnregisterGuard { arms, me, epoch, armed: eager };
 

src/introspect.rs

@@ -1,26 +1,85 @@
-//! RFC 016 — runtime introspection (Chunk 1: the read primitive).
+//! Inspect what is running right now: which actors exist, what state each one
+//! is in, and how they are related.
 //!
-//! A synchronous, internal read of the slab that returns *owned* data. This is
-//! the mechanism the whole RFC hangs off: tests, the future observer
-//! gen_server (Chunk 4), and a later control plane (RFC 003) are all consumers
-//! of [`snapshot`] / [`actor_info`], never of the runtime internals directly.
+//! This is the tool for questions like "is my server still alive", "how many
+//! actors are currently parked waiting on something", or "what does the spawn
+//! tree look like". It is meant for debugging, test assertions, a health check
+//! endpoint, or a monitoring dashboard: anywhere you want to look at the
+//! runtime from the outside without stopping it or coupling your code to its
+//! internals.
 //!
-//! ## Consistency (DECISION D2 — per-slot tearing, `ps` semantics)
+//! Three entry points, in order of scope:
 //!
-//! [`snapshot`] is point-in-time and mildly racy *across* actors: each slot's
-//! scheduling state is a lock-free word load, so an actor reported `Running`
-//! may already be `Parked`, and an actor can die mid-scan. This is the cheap,
-//! useful model (a coherent stop-the-world cut is expensive and rarely wanted).
-//! [`actor_info`] is coherent for the single actor it names.
+//! - [`snapshot`] returns every actor that currently exists, as a plain
+//!   owned `Vec`, so you can filter, count, or search it however you like.
+//! - [`actor_info`] returns a coherent view of exactly one actor, by pid.
+//!   Cheaper than filtering a whole snapshot down to one entry, and more
+//!   precise (see "Consistency" below).
+//! - [`tree`] returns the same actors as [`snapshot`], folded into a
+//!   parent/child forest that mirrors who spawned whom.
 //!
-//! ## Locking
+//! ```
+//! use smarm::{actor_info, channel, run, snapshot, spawn, ActorState};
 //!
-//! The lock order is **Leaf → Channel, at most one of each** (`raw_mutex.rs`);
-//! cold locks, the registry, and the free list are all Leaves, so we may never
-//! hold two at once. The read is therefore phased: first a single registry-leaf
-//! pass for names and mailbox depth (the per-channel length read is a Channel
-//! lock taken under that Leaf — legal), released before the slab scan takes any
-//! per-slot cold Leaf.
+//! run(|| {
+//!     let (ready_tx, ready_rx) = channel::<()>();
+//!     let (gate_tx, gate_rx) = channel::<()>();
+//!
+//!     let worker = spawn(move || {
+//!         ready_tx.send(()).unwrap();
+//!         gate_rx.recv().unwrap(); // blocks here until released
+//!     });
+//!     ready_rx.recv().unwrap();
+//!
+//!     // `snapshot` sees every actor, including this one and the worker.
+//!     let snap = snapshot();
+//!     assert!(snap.actors.len() >= 2);
+//!
+//!     // `actor_info` gives a coherent view of just the worker. It is
+//!     // blocked on the gate channel, so it must be Parked.
+//!     let pid = worker.pid();
+//!     let info = actor_info(pid).expect("worker is still alive");
+//!     assert_eq!(info.state, ActorState::Parked);
+//!
+//!     gate_tx.send(()).unwrap();
+//!     worker.join().unwrap();
+//!
+//!     // Once joined, the pid no longer names a live actor.
+//!     assert!(actor_info(pid).is_none());
+//! });
+//! ```
+//!
+//! ## Consistency
+//!
+//! [`snapshot`] is not a single atomic pause-the-world freeze: it walks every
+//! actor's state one after another, so it is a series of independent,
+//! cheap, lock-free reads rather than one coherent moment in time. Between
+//! reading actor A and actor B, either one can change state, and an actor can
+//! even finish and disappear mid-scan. In practice this is exactly what you
+//! want: a coherent stop-the-world snapshot would mean pausing every actor in
+//! the runtime just to look at it, which is expensive and rarely necessary
+//! for a dashboard, a test assertion, or a debugging session.
+//!
+//! [`actor_info`], in contrast, is coherent for the one actor it names: all of
+//! its fields describe the same instant for that actor, because a single
+//! actor's data cannot tear the way a scan across many actors can.
+//!
+//! ## Implementation notes
+//!
+//! These details matter if you are working on smarm itself; they are not part
+//! of the public contract.
+//!
+//! The read never stops the scheduler and never holds a lock across the whole
+//! scan. Each actor's scheduling state is a single lock-free word load
+//! (hence the possible tearing described above). Reading the rest of an
+//! actor's cold data (its supervisor, monitors, links, and so on) takes a
+//! brief per-actor lock, just long enough to copy those fields out; nothing
+//! is held across actors. Locking follows the crate-wide rule that at most
+//! one "leaf" lock (a per-actor lock, the registry lock, or the free list
+//! lock) is held at a time, with no leaf lock held while acquiring another.
+//! The read is phased accordingly: first one pass over the registry to
+//! collect every actor's registered names and mailbox depth, released before
+//! the per-actor scan begins.
 
 use crate::pid::Pid;
 use crate::registry::MailboxInfo;
@@ -31,15 +90,28 @@ use crate::slot_state::{
 };
 use std::collections::HashMap;
 
-/// Snapshot wire-format version (DECISION D1). [`RuntimeSnapshot`] is treated as
-/// a stable type from day one: it becomes the observer protocol (Chunk 4) and
-/// crosses a version boundary the moment a remote observer attaches (RFC 011),
-/// so the version travels with the data from the start.
+/// The format version carried by every [`RuntimeSnapshot`] and
+/// [`RuntimeTree`], as [`RuntimeSnapshot::format_version`] /
+/// [`RuntimeTree::format_version`]. If you serialize a snapshot (for example
+/// to send it somewhere else, or to compare snapshots taken with different
+/// versions of smarm) check this field: a change in its value means the shape
+/// of [`ActorInfo`] or its neighbors has changed and old and new snapshots
+/// should not be assumed compatible. If you only ever read a snapshot
+/// in-process in the same version of smarm that produced it, you can ignore
+/// this field.
 pub const SNAPSHOT_FORMAT_VERSION: u16 = 1;
 
-/// Fine-grained scheduling state, mapped from the packed slot word with no new
-/// storage. `RunningNotified` collapses into `Notified` — a wake landed while
-/// the actor was on-CPU and it will re-queue when it yields.
+/// What an actor is doing right now, from the scheduler's point of view.
+///
+/// - `Queued`: runnable, waiting for a scheduler thread to pick it up.
+/// - `Running`: currently executing on a scheduler thread.
+/// - `Notified`: was running and got woken up (for example, a message
+///   arrived) before it had a chance to yield or park; it will be re-queued
+///   as soon as it does.
+/// - `Parked`: blocked, waiting on something such as a channel receive, a
+///   mutex, a timer, or an IO event.
+/// - `Done`: has finished (returned or panicked) but its slot has not been
+///   reclaimed for reuse yet, so it is still visible to introspection.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ActorState {
     Queued,
@@ -49,8 +121,8 @@ pub enum ActorState {
     Done,
 }
 
-/// Classify a packed state word. `None` for a Vacant slot (skipped by the scan)
-/// — the only state that is not an actor.
+/// Classify a packed state word. `None` for a Vacant slot (skipped by the
+/// scan): a vacant slot holds no actor at all, live or done.
 fn classify(w: u64) -> Option<ActorState> {
     Some(match word_state(w) {
         ST_QUEUED => ActorState::Queued,
@@ -62,61 +134,76 @@ fn classify(w: u64) -> Option<ActorState> {
     })
 }
 
-/// Owned, point-in-time view of one actor — no borrows of runtime internals, so
-/// it is safe to hand to any consumer.
+/// An owned, self-contained view of one actor at (approximately) one moment.
+/// It borrows nothing from the runtime, so you can keep it, send it
+/// elsewhere, or print it long after the actor it describes has changed
+/// state or even exited.
 #[derive(Debug, Clone)]
 pub struct ActorInfo {
     pub pid: Pid,
-    /// Registered names, inverted from the registry (usually 0 or 1).
+    /// Names this actor is currently registered under (see the
+    /// [`registry`](crate::registry) module). Usually empty or one name;
+    /// an actor can have more if it registered several.
     pub names: Vec<&'static str>,
     pub state: ActorState,
-    /// Spawn-time parent edge (DECISION D9): `spawn_under` sets it to the
-    /// supervisor, plain `spawn` to the spawning actor — so it is parentage,
-    /// not necessarily a supervision relationship. `ROOT_PID` for the run's
-    /// root actor and for `Done` tombstones (whose `Actor` is already gone).
+    /// The actor that spawned this one: whoever called `spawn` or
+    /// `spawn_under` to create it. This is a parentage record, not
+    /// necessarily a supervision relationship: `spawn_under` records the
+    /// supervisor you asked for, while plain `spawn` records the spawning
+    /// actor itself, whether or not it supervises anything. It is the
+    /// runtime's root pid for the run's own root actor, and for a `Done`
+    /// actor whose bookkeeping has already been cleared.
     pub supervisor: Pid,
     pub trap_exit: bool,
     pub monitors: u32,
     pub links: u32,
     pub joiners: u32,
-    /// Queued messages summed over the actor's *published* channels (register /
-    /// install / spawn_addr / gen_server). 0 for an actor that holds only a
-    /// private `channel()` receiver — those are invisible to the registry.
+    /// Messages currently queued and not yet delivered, summed across every
+    /// channel this actor has published (via `register`, `install`,
+    /// `spawn_addr`, or starting a gen_server). This is 0 for an actor that
+    /// only holds a private, unpublished `channel()` receiver, since nothing
+    /// outside the actor can see that channel exists.
     pub mailbox_depth: u32,
-    /// Timeslice overruns tallied for this incarnation (RFC 016 Chunk 2): how
-    /// many times the actor was preempted for exceeding its slice. Resets on
-    /// restart (per-incarnation, D7).
+    /// How many times this actor has been preempted for running past its
+    /// scheduling timeslice. Counts only since the actor's current start (a
+    /// supervisor restart begins a fresh count).
     pub overruns: u64,
-    /// Messages this actor has received (dequeued) this incarnation (RFC 016
-    /// Chunk 2) — answers "is this actor a hotspot / draining slower than its
-    /// mailbox fills." Counts received, not sent (D4). Per-incarnation (D7).
+    /// How many messages this actor has received (taken off its inbox), since
+    /// its current start. Useful for spotting an actor whose mailbox is
+    /// filling up faster than it can drain it: compare this against
+    /// `mailbox_depth` over time.
     pub messages_received: u64,
-    /// Approximate on-CPU cycles this incarnation has consumed (RFC 016 Chunk 2)
-    /// — a reductions-like work metric for relative comparison. Always 0 unless
-    /// the `budget-accounting` feature is enabled (it costs an RDTSC per resume,
-    /// D6). Per-incarnation (D7).
+    /// Approximate CPU cycles this actor has spent running, since its current
+    /// start. A relative measure for comparing actors against each other, not
+    /// an absolute or wall-clock figure. Always 0 unless the crate's
+    /// `budget-accounting` feature is enabled, since measuring it costs a
+    /// timestamp read on every resume.
     pub budget_cycles: u64,
 }
 
-/// A whole-runtime snapshot. See the module docs for the D2 tearing model.
+/// A snapshot of every actor in the runtime at (approximately) one moment.
+/// See the module docs' "Consistency" section for what "approximately" means
+/// here.
 #[derive(Debug, Clone)]
 pub struct RuntimeSnapshot {
     pub format_version: u16,
     pub actors: Vec<ActorInfo>,
 }
 
-/// Snapshot every live (and `Done`-but-not-yet-reclaimed) actor on the slab.
-/// O(n) over the slot table, running with preemption disabled (like every
-/// runtime primitive) but holding no lock across the scan. Panics outside
-/// `Runtime::run()`; callable from actor code and the run thread.
+/// Every actor that currently exists: running, queued, parked, or finished
+/// but not yet cleaned up. Cheap and lock-free per actor; see the module
+/// docs for what "approximately one moment" means for the result as a whole.
+/// Panics if called outside [`run`](crate::run).
 pub fn snapshot() -> RuntimeSnapshot {
     with_runtime(|inner| {
-        // Phase A: one registry-leaf pass for names + mailbox depth, released
-        // before any cold leaf (no two Leaves at once).
+        // First pass: one registry lock to collect names + mailbox depth for
+        // every actor, released before touching any per-actor lock below.
         let mail = inner.registry.lock().introspect_map();
 
-        // Phase B: lock-free slab scan; per-slot cold leaf only to copy cold
-        // fields. Tearing across slots is intentional (D2).
+        // Second pass: walk the actor table. Each actor's scheduling state is
+        // a lock-free word load; only copying its other fields takes a brief
+        // per-actor lock. Tearing across actors is expected here (see the
+        // module docs' "Consistency" section).
         let mut actors = Vec::new();
         for (idx, slot) in inner.slots.iter().enumerate() {
             let idx = idx as u32;
@@ -128,8 +215,11 @@ pub fn snapshot() -> RuntimeSnapshot {
     })
 }
 
-/// Coherent view of a single actor, or `None` if the pid is stale, out of
-/// range, or names a Vacant slot.
+/// A coherent view of exactly one actor, or `None` if `pid` does not name a
+/// currently-live entry: it is stale (that actor has already exited and its
+/// slot was reused by another), out of range, or was never a real pid at
+/// all. Unlike [`snapshot`], every field of the result describes the same
+/// instant, since there is only one actor to read.
 pub fn actor_info(pid: Pid) -> Option<ActorInfo> {
     with_runtime(|inner| {
         let slot = inner.slot_at(pid)?;
@@ -141,11 +231,12 @@ pub fn actor_info(pid: Pid) -> Option<ActorInfo> {
     })
 }
 
-/// Build one `ActorInfo` for slot `idx`, or `None` if Vacant or
-/// racing-reclaimed. State is classified from a lock-free word load (the torn
-/// read); the cold lock then pins the generation (reclaim bumps it under that
-/// same lock) so the cold fields are coherent for this incarnation. `mail` is
-/// this slot's registry entry, if any.
+/// Build one `ActorInfo` for slot `idx`, or `None` if the slot is empty or
+/// was reclaimed while this read was in progress. The scheduling state comes
+/// from a lock-free word load (the source of the tearing described in the
+/// module docs); the per-actor lock then confirms the actor has not since
+/// exited and been replaced, so the rest of the fields are coherent for this
+/// exact actor. `mail` is this slot's registry entry, if any.
 fn read_slot(slot: &Slot, idx: u32, mail: Option<&MailboxInfo>) -> Option<ActorInfo> {
     let w = slot.state_word();
     let state = classify(w)?;
@@ -153,10 +244,11 @@ fn read_slot(slot: &Slot, idx: u32, mail: Option<&MailboxInfo>) -> Option<ActorI
     let pid = Pid::new(idx, gen);
 
     let cold = slot.cold.lock();
-    // If the generation moved between the lock-free load and acquiring the cold
-    // lock, the slot was reclaimed (and maybe reused) — drop it rather than mix
-    // one incarnation's state with another's cold data. (ps semantics: a racing
-    // actor may simply be missed mid-scan.)
+    // If the generation moved between the lock-free load and acquiring the
+    // per-actor lock, this actor exited (and the slot may already hold a new
+    // one). Drop it rather than mix one actor's state with another's data; a
+    // racing actor may simply be missed by this scan, which is expected (see
+    // the module docs' "Consistency" section).
     if word_gen(slot.state_word()) != gen {
         return None;
     }
@@ -172,7 +264,7 @@ fn read_slot(slot: &Slot, idx: u32, mail: Option<&MailboxInfo>) -> Option<ActorI
     let joiners = cold.waiters.len() as u32;
     drop(cold);
 
-    // Counters are hot-region atomics, read lock-free (RFC 016 Chunk 2).
+    // Counters are plain atomics, read lock-free.
     let overruns = slot.overruns();
     let messages_received = slot.messages_received();
     let budget_cycles = slot.budget_cycles();
@@ -202,39 +294,45 @@ fn read_slot(slot: &Slot, idx: u32, mail: Option<&MailboxInfo>) -> Option<ActorI
 }
 
 // ---------------------------------------------------------------------------
-// Chunk 3 — tree view (pure derivation over a Chunk-1 snapshot)
+// Tree view: a pure derivation over a snapshot
 // ---------------------------------------------------------------------------
 
-/// One node in the parentage forest. `children` are the actors whose recorded
-/// parent edge points at this node's pid.
+/// One node in the parentage forest returned by [`tree`]. `children` are the
+/// actors whose recorded parent (see [`ActorInfo::supervisor`]) points at
+/// this node's actor.
 #[derive(Debug, Clone)]
 pub struct TreeNode {
     pub info: ActorInfo,
-    /// The actor's recorded parent was absent from the snapshot (already
-    /// Done/Vacant, or itself a tombstone), so it was re-rooted under the forest
-    /// sentinel rather than dropped — the tree stays total (DECISION D8).
+    /// True if this actor's recorded parent was not found in the snapshot
+    /// (it had already exited, or was itself missing), so this node was
+    /// placed at the top of the forest instead of being dropped. This keeps
+    /// every actor in the snapshot visible somewhere in the tree, even one
+    /// whose parent is gone.
     pub orphaned: bool,
     pub children: Vec<TreeNode>,
 }
 
-/// The parentage forest. Roots are actors parented at `ROOT_PID` (genuine
-/// roots) plus re-rooted orphans. The edge is *spawned-by / parent*, not
-/// necessarily supervision (DECISION D9) — see [`ActorInfo::supervisor`].
+/// The parentage forest: every actor from a snapshot, arranged by who spawned
+/// whom. Roots are actors with no parent in the snapshot (including the
+/// run's own root actor) plus any orphaned actors (see [`TreeNode::orphaned`]).
+/// This mirrors spawn parentage, not necessarily a supervision tree; see
+/// [`ActorInfo::supervisor`].
 #[derive(Debug, Clone)]
 pub struct RuntimeTree {
     pub format_version: u16,
     pub roots: Vec<TreeNode>,
 }
 
-/// Take a live [`snapshot`] and fold it into the parentage forest.
+/// Take a fresh [`snapshot`] and fold it into the parentage forest.
 pub fn tree() -> RuntimeTree {
     tree_from(snapshot())
 }
 
-/// Fold an existing snapshot into a forest by grouping each actor under its
-/// parent pid — a single O(n) pass, no new reads. Exposed separately so a
-/// consumer that already holds a snapshot (or a synthetic one, in tests) can
-/// derive the tree without a second scan.
+/// Fold an existing snapshot into a parentage forest by grouping each actor
+/// under its parent, without taking a new snapshot. Useful if you already
+/// have one (for example, one built in a test, or one you took earlier and
+/// want to inspect again) and want the tree view of it without re-reading
+/// the runtime.
 pub fn tree_from(snap: RuntimeSnapshot) -> RuntimeTree {
     let RuntimeSnapshot { format_version, actors } = snap;
 
@@ -254,7 +352,7 @@ pub fn tree_from(snap: RuntimeSnapshot) -> RuntimeTree {
             children_of.entry(parent).or_default().push(i);
         } else {
             // Parent is the forest sentinel (genuine root) or absent from the
-            // snapshot (orphan, D8) — either way a root of the forest.
+            // snapshot (orphan): either way, a root of the forest.
             orphaned[i] = parent != ROOT_PID;
             roots.push(i);
         }

src/monitor.rs

@@ -1,49 +1,85 @@
-//! Process monitors.
+//! Find out when another actor dies, without it knowing or caring that you're
+//! watching.
 //!
-//! `monitor(target)` asks the runtime to deliver a single [`Down`] when
-//! `target` terminates, and hands back a [`Monitor`] — the [`Receiver`] to read
-//! it from, plus the identity (`id`, `target`) needed to take the registration
-//! back down with [`demonitor`]. A monitor is:
+//! Say one actor manages a pool of workers and needs to know when a worker
+//! exits, so it can replace it. The worker does not need to know it is being
+//! watched, and nothing about the worker's own behavior should change because
+//! someone is watching it. That is what [`monitor`] is for: call
+//! `monitor(target)` to get a [`Monitor`], and read exactly one [`Down`]
+//! message off `monitor.rx` whenever `target` terminates, however it
+//! terminates.
 //!
-//!   - **unidirectional** — the watcher learns of the target's death, but the
-//!     target learns nothing of the watcher, and the watcher is unaffected by
-//!     the death beyond the notification (contrast a *link*, which propagates
-//!     failure);
-//!   - **one-shot** — exactly one `Down` is ever sent for a given monitor.
-//!     The returned channel closes afterwards, so a second `recv()` yields
-//!     `Err(RecvError)`.
+//! ```
+//! use smarm::{monitor, run, spawn, DownReason};
 //!
-//! This generalizes the older single-`supervisor_channel` mechanism: a
-//! supervisor is just a hard-wired monitor that the parent installs at spawn
-//! time. Here any actor may monitor any pid, any number of times.
+//! run(|| {
+//!     let worker = spawn(|| {
+//!         // does some work, then returns
+//!     });
+//!     let pid = worker.pid();
 //!
-//! ## Reasons
+//!     let m = monitor(pid);
+//!     let _ = worker.join();
 //!
-//! [`DownReason`] is deliberately payload-free. A panicking actor's payload
-//! has a single owner and is delivered to whoever `join()`s the actor (as
-//! `JoinError`); a monitor only learns *that* it panicked, not the value.
-//! Monitoring a pid that is already gone (reclaimed, or never alive) yields
-//! [`DownReason::NoProc`] immediately, mirroring Erlang's `noproc`.
+//!     let down = m.rx.recv().expect("monitor channel closed before Down");
+//!     assert_eq!(down.pid, pid);
+//!     assert_eq!(down.reason, DownReason::Exit);
+//! });
+//! ```
 //!
-//! ## Demonitoring
+//! A monitor is one-directional and one-shot:
 //!
-//! Each `monitor()` registration is tagged with a process-unique [`MonitorId`].
-//! [`demonitor`] removes the registration named by a [`Monitor`] from its
-//! target's slot, returning `Some(id)` if a live registration was found or
-//! `None` if it had already fired (or the target is gone). Dropping the
-//! [`Monitor`] afterwards discards any `Down` that the target had *already*
-//! queued — the equivalent of Erlang's `demonitor(Ref, [flush])`.
+//! - **One-directional**: the watcher learns that the target died, but the
+//!   target is completely unaffected. It never learns it was being watched,
+//!   and its own behavior and lifetime do not change because of the monitor.
+//!   This is the opposite of a [`link`](mod@crate::link), which is bidirectional:
+//!   linking two actors means an abnormal death on either side can bring the
+//!   other down too. Reach for a monitor when you just want to *know*; reach
+//!   for a link when a peer's crash should actually stop you.
+//! - **One-shot**: you get exactly one [`Down`] per `monitor()` call, then the
+//!   channel closes. Calling `monitor` again on the same target (or a
+//!   different one) gives you an independent registration with its own
+//!   [`Monitor`] and its own one-shot channel; nothing stops you from
+//!   monitoring the same actor many times over; each call is watched and
+//!   fires on its own.
 //!
-//! ## Races
+//! ## Why a monitor never hands you the panic value
 //!
-//! Registration (below) and `finalize_actor` (in `runtime`) both run under the
-//! shared-state mutex, so a target that is still alive when its monitor is
-//! registered is guaranteed to deliver a real `Down`; there is no window in
-//! which the death slips between the liveness check and the registration.
-//! `demonitor` is protected by the generation half of the pid: if the target
-//! has died and its slot index been recycled, `slot_mut(target)` fails the
-//! generation check and `demonitor` is a clean no-op — it can never strip a
-//! *different* actor's monitor that happens to share the slot index.
+//! If the target panicked, [`Down`] tells you *that* it panicked
+//! ([`DownReason::Panic`]), but not the panic's payload. The payload has a
+//! single owner: it is handed to whichever caller `join()`s the actor's
+//! [`JoinHandle`](crate::JoinHandle), as a `JoinError`. A monitor only needs
+//! to know that something went wrong, not reproduce the exact value that
+//! caused it, so it gets the reason and nothing else.
+//!
+//! Monitoring a target that is already gone (it finished and was cleaned up,
+//! or the pid never pointed at a real actor) is not an error: you get a
+//! [`Down`] with [`DownReason::NoProc`] right away, instead of waiting
+//! forever for something that already happened.
+//!
+//! ## Stopping a monitor early
+//!
+//! [`demonitor`] cancels a monitor before it fires. If the registration was
+//! still live, it removes it and returns `Some` of the monitor's id: no
+//! `Down` will arrive on that channel from here on. If the target had already
+//! died and its `Down` already sent, there is nothing left to cancel and
+//! `demonitor` returns `None`; the `Down` you already have (or that is
+//! already sitting in the channel) is unaffected.
+//!
+//! If you want to cancel *and* make sure a `Down` that already arrived is
+//! discarded without reading it, just drop the [`Monitor`]: dropping it closes
+//! its receiver, and any queued `Down` is dropped along with it.
+//!
+//! ## Correctness notes for implementers
+//!
+//! A target that is still alive at the moment `monitor()` registers is
+//! guaranteed to eventually produce a real `Down`: registration and the
+//! target's own termination bookkeeping run under the same lock, so there is
+//! no window in which the target could die without the just-added
+//! registration seeing it. `demonitor` is similarly race-free against a target
+//! that has since died and had its slot reused by a new, unrelated actor: it
+//! is checked against the exact monitored incarnation, so it can never remove
+//! a different actor's registration by accident, it simply reports `None`.
 
 use crate::channel::{channel, Receiver, Sender};
 use crate::pid::Pid;
@@ -51,8 +87,8 @@ use crate::scheduler::with_runtime;
 
 /// Why a monitored actor went down.
 ///
-/// `Copy` because it carries no payload — see the module docs for why the
-/// panic payload is *not* included here.
+/// Carries no payload: see the module docs for why a monitor never receives
+/// the panic value itself.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum DownReason {
     /// The target returned normally.
@@ -76,21 +112,22 @@ pub struct Down {
     pub reason: DownReason,
 }
 
-/// A process-unique identifier for one `monitor()` registration.
+/// A unique identifier for one [`monitor`] registration.
 ///
-/// Opaque and `Copy`. Allocated from a monotonic counter in shared state, so
-/// it is never reused for the lifetime of the runtime — distinct `monitor()`
-/// calls on the same target get distinct ids, which is what lets [`demonitor`]
-/// tear down exactly one of several monitors on a target.
+/// Opaque and `Copy`. Never reused for the life of the runtime, so if you
+/// monitor the same target more than once, each call's id is distinct. This
+/// is what lets [`demonitor`] tear down exactly one of several monitors on
+/// the same target without disturbing the others.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct MonitorId(pub(crate) u64);
 
 /// A live monitor: the receiving end of the one-shot [`Down`] channel, plus the
 /// identity needed to [`demonitor`] it.
 ///
-/// Read the notification from [`Monitor::rx`]. Not `Clone` (the receiver is a
-/// single consumer). Dropping it closes the receiving end; if a `Down` was
-/// already queued it is discarded with the channel.
+/// Read the notification from [`Monitor::rx`]. Not `Clone`, since only one
+/// side is meant to consume it. Dropping a `Monitor` closes the receiving
+/// end; if a `Down` had already arrived but was never read, it is discarded
+/// along with it.
 pub struct Monitor {
     /// This registration's process-unique id.
     pub id: MonitorId,
@@ -110,10 +147,11 @@ pub fn monitor<A>(target: Pid<A>) -> Monitor {
     let target = target.erase();
     let (tx, rx) = channel::<Down>();
 
-    // Register under the target's cold lock. `tx.clone()` takes the channel's
-    // own lock — a Channel-class RawMutex, explicitly permitted *under* a Leaf
-    // (cold) lock by the lock order (see raw_mutex.rs). We must still not
-    // *send* under the lock, as `Sender::send` can unpark a parked receiver,
+    // Implementation note: registration happens under the target's cold
+    // lock. `tx.clone()` takes the channel's own lock, a Channel-class
+    // RawMutex, which is explicitly permitted under a Leaf (cold) lock by
+    // the lock order documented in raw_mutex.rs. We must still not *send*
+    // under the lock, since `Sender::send` can unpark a parked receiver,
     // and there's no reason to nest that.
     let (id, registered) = with_runtime(|inner| {
         let id = inner.alloc_monitor_id();
@@ -140,19 +178,21 @@ pub fn monitor<A>(target: Pid<A>) -> Monitor {
 }
 
 /// Cancel the monitor `m`. Returns `Some(id)` if a live registration was found
-/// on the target's slot and removed, or `None` if there was nothing to remove
-/// — the target already fired its `Down` (the registration is drained on
-/// finalize), was never alive (`NoProc`), or has been reclaimed.
+/// and removed, so no `Down` will arrive on `m.rx` from here on. Returns
+/// `None` if there was nothing left to remove: the target had already gone
+/// down and its `Down` was already sent (or is already sitting in the
+/// channel, unread).
 ///
-/// This stops any *future* `Down`. To also discard a `Down` the target may have
-/// *already* queued (the finalize-races-demonitor case), drop `m` afterwards;
-/// dropping the [`Monitor`] closes its receiver and the queued notice goes with
-/// it — the analogue of Erlang's `demonitor(Ref, [flush])`.
+/// This only stops a *future* `Down`. If you also want to discard a `Down`
+/// that already arrived (or is about to, in a race with this call), drop `m`
+/// instead of, or in addition to, calling this: dropping the [`Monitor`]
+/// closes its receiver and any queued notice is discarded with it.
 pub fn demonitor(m: &Monitor) -> Option<MonitorId> {
-    // Remove the registration under the target's cold lock, but move the
-    // `Sender` *out* and let it drop only after the lock is released:
-    // dropping the last sender runs `Sender::drop`, which may unpark a parked
-    // receiver — legal under a cold lock, but pointless to nest.
+    // Implementation note: the registration is removed under the target's
+    // cold lock, but the `Sender` is moved *out* and dropped only after the
+    // lock is released. Dropping the last sender runs `Sender::drop`, which
+    // may unpark a parked receiver; legal under a cold lock, but pointless
+    // to nest.
     let removed: Option<(MonitorId, Sender<Down>)> = with_runtime(|inner| {
         let slot = inner.slot_at(m.target)?;
         let mut cold = slot.cold.lock();

src/mutex.rs

@@ -1,12 +1,89 @@
-//! Actor-aware mutex with mandatory timeout.
+//! Shared mutable state across actors, when a channel is overkill.
 //!
-//! `Mutex<T>` parks the calling *green* thread on contention rather than
-//! blocking the OS thread. Every lock attempt is bounded by a timeout.
+//! smarm actors normally coordinate by sending messages, and for a piece of
+//! owned state the right tool is usually a `gen_server`: one actor holds the
+//! data and everyone else talks to it. Sometimes that is more machinery than
+//! you need, and plain shared, lockable state is simpler: [`Mutex<T>`] is
+//! that escape hatch. It behaves like `std::sync::Mutex<T>`, guarding a value
+//! of type `T` behind a guard that gives you `&mut T` while held, but it is
+//! built for smarm's actors rather than OS threads.
 //!
-//! Internals use `Arc<std::sync::Mutex<...>>` so the type is genuinely
-//! `Send + Sync` and can be shared across scheduler threads.
+//! The key difference from `std::sync::Mutex` is what happens on contention.
+//! [`Mutex::lock`] parks the calling actor (a cooperatively scheduled green
+//! thread) rather than blocking the underlying OS thread, so other actors on
+//! the same OS thread keep running while it waits. And every lock attempt is
+//! bounded by a timeout: an actor that hangs on to the lock forever (stuck in
+//! a bug, or just slow) would otherwise wedge every other actor waiting on
+//! it, so smarm makes the wait bounded by default instead of leaving it up
+//! to you to remember.
 //!
-//! Fairness: FIFO. Poisoning: none. Reentrance: deadlock (caller bug).
+//! ## A first lock
+//!
+//! ```
+//! use smarm::{run, spawn, Mutex};
+//!
+//! run(|| {
+//!     let counter = Mutex::new(0u32);
+//!
+//!     // Mutex::clone() is cheap and hands out another handle to the SAME
+//!     // underlying value, much like Arc::clone: every clone shares one lock
+//!     // and one value, so mutations through one are visible through all.
+//!     let a = counter.clone();
+//!     let b = counter.clone();
+//!
+//!     let h1 = spawn(move || {
+//!         let mut guard = a.lock().unwrap();
+//!         *guard += 1;
+//!     });
+//!     let h2 = spawn(move || {
+//!         let mut guard = b.lock().unwrap();
+//!         *guard += 1;
+//!     });
+//!     h1.join().unwrap();
+//!     h2.join().unwrap();
+//!
+//!     assert_eq!(*counter.lock().unwrap(), 2);
+//! });
+//! ```
+//!
+//! ## Choosing a timeout
+//!
+//! [`Mutex::lock`] waits up to [`DEFAULT_TIMEOUT`] (30 seconds) before giving
+//! up with [`LockTimeout`]. To use a different bound for one call, use
+//! [`Mutex::lock_timeout`] instead; to change the default for every future
+//! `lock()` call on this mutex (including through its clones), use
+//! [`Mutex::set_default_timeout`]. If you never want to wait at all, use
+//! [`Mutex::try_lock`], which returns immediately whether or not the lock was
+//! free.
+//!
+//! ## Fairness and panics
+//!
+//! Waiters are granted the lock in the order they started waiting (FIFO), so
+//! no actor can be starved by later arrivals repeatedly cutting in line.
+//!
+//! This mutex never poisons. `std::sync::Mutex` marks itself poisoned if a
+//! thread panics while holding the lock, because a partly mutated value might
+//! be left behind for the next lock holder to see. smarm's actors already
+//! rely on `Drop` running during unwinding to release the lock, so if a
+//! holder panics, [`MutexGuard::drop`] still runs and the next waiter is
+//! granted the lock normally. It is the same tradeoff `std::sync::Mutex`
+//! offers you if you choose to ignore poisoning: you may see a value left
+//! mid-update by the panicking actor, so a panic inside a critical section is
+//! still a bug worth fixing, just not one that also wedges every future lock
+//! attempt.
+//!
+//! Locking a mutex you already hold (on the same actor) does not queue
+//! behind yourself: it deadlocks, the same way relocking a non-reentrant
+//! `std::sync::Mutex` does. Don't call `lock` while already holding a guard
+//! from the same `Mutex`.
+//!
+//! ## Outside the runtime
+//!
+//! `Mutex<T>` also works when called from plain code that is not running as
+//! a smarm actor (for example, in a test's setup code before calling
+//! [`run`](crate::run)). There, an actor's cooperative park has no meaning,
+//! so a lock attempt instead blocks the calling OS thread directly until the
+//! mutex is free; there is no timeout on this path.
 
 use crate::pid::Pid;
 use crate::scheduler;
@@ -15,8 +92,14 @@ use std::collections::VecDeque;
 use std::sync::{Arc, Mutex as StdMutex};
 use std::time::Duration;
 
+/// How long [`Mutex::lock`] waits for the lock before giving up, unless
+/// overridden per-mutex with [`Mutex::set_default_timeout`] or per-call with
+/// [`Mutex::lock_timeout`].
 pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
 
+/// Returned by [`Mutex::lock`] / [`Mutex::lock_timeout`] when the timeout
+/// elapses before the lock became available. The lock attempt is abandoned;
+/// nothing was acquired, and the mutex's value is unaffected.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub struct LockTimeout;
 
@@ -70,7 +153,7 @@ impl TimerTarget for MutexCore {
             };
             // Remove from waiters only if still there with matching epoch.
             // If the lock was already granted (holder == Some(pid)), the
-            // timer fired after the grant — treat as no-op; the actor
+            // timer fired after the grant: treat as no-op; the actor
             // will see `is_holder == true` and return Ok.
             if st.holder == Some(pid) {
                 return;
@@ -100,6 +183,8 @@ pub struct Mutex<T> {
 }
 
 impl<T> Mutex<T> {
+    /// Wrap `value` in a new mutex, initially unlocked, with the default
+    /// lock timeout ([`DEFAULT_TIMEOUT`]).
     pub fn new(value: T) -> Self {
         Self {
             core: Arc::new(MutexCore::new(DEFAULT_TIMEOUT)),
@@ -107,6 +192,11 @@ impl<T> Mutex<T> {
         }
     }
 
+    /// Change how long future [`lock`](Self::lock) calls on this mutex wait
+    /// before giving up. Applies to every clone of this `Mutex` (they share
+    /// one underlying lock), and to `lock` calls already in progress that
+    /// have not yet started waiting. Does not affect [`lock_timeout`](Self::lock_timeout)
+    /// calls, which always use the timeout passed in.
     pub fn set_default_timeout(&self, timeout: Duration) {
         match self.core.state.lock() {
             Ok(mut st) => st.default_timeout = timeout,
@@ -114,6 +204,12 @@ impl<T> Mutex<T> {
         }
     }
 
+    /// Acquire the lock, waiting up to this mutex's default timeout
+    /// ([`DEFAULT_TIMEOUT`], or whatever [`set_default_timeout`](Self::set_default_timeout)
+    /// last set) if it is currently held elsewhere. Returns a [`MutexGuard`]
+    /// that releases the lock when dropped, or [`LockTimeout`] if the
+    /// deadline passes first. To use a one-off timeout instead of the
+    /// mutex's default, call [`lock_timeout`](Self::lock_timeout) directly.
     pub fn lock(&self) -> Result<MutexGuard<'_, T>, LockTimeout> {
         let timeout = match self.core.state.lock() {
             Ok(st) => st.default_timeout,
@@ -122,6 +218,10 @@ impl<T> Mutex<T> {
         self.lock_timeout(timeout)
     }
 
+    /// Acquire the lock, waiting up to `timeout` (ignoring this mutex's
+    /// default) if it is currently held elsewhere. Returns a [`MutexGuard`]
+    /// that releases the lock when dropped, or [`LockTimeout`] if `timeout`
+    /// elapses first with the lock still unavailable.
     pub fn lock_timeout(&self, timeout: Duration) -> Result<MutexGuard<'_, T>, LockTimeout> {
         // Outside the runtime (e.g. in tests, after run() returns) there is no
         // current actor PID.  Fall back to a blocking std::sync::Mutex acquire.
@@ -157,7 +257,7 @@ impl<T> Mutex<T> {
                 Ok(g) => g,
                 Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
             };
-            // begin_wait is lock-free — legal under the state lock; this
+            // begin_wait is lock-free (legal under the state lock); this
             // makes the epoch atomic with the registration's visibility to
             // grants and timeouts.
             let epoch = scheduler::begin_wait();
@@ -170,7 +270,7 @@ impl<T> Mutex<T> {
         scheduler::insert_wait_timer(deadline, me, target, epoch);
         scheduler::park_current();
 
-        // Resumed — precisely: only our grant or our timer can wake this
+        // Resumed, precisely: only our grant or our timer can wake this
         // wait (both epoch-stamped; a stop wake unwinds out of
         // park_current). The one-shot interpretation below is therefore
         // exhaustive. Are we the holder?
@@ -193,6 +293,9 @@ impl<T> Mutex<T> {
         }
     }
 
+    /// Acquire the lock only if it is immediately available: never parks and
+    /// never waits. Returns `Some` with a [`MutexGuard`] if the lock was
+    /// free, `None` if it is currently held elsewhere.
     pub fn try_lock(&self) -> Option<MutexGuard<'_, T>> {
         let me = crate::actor::current_pid()?;
         let mut st = match self.core.state.lock() {
@@ -234,6 +337,10 @@ impl<T> Mutex<T> {
 }
 
 impl<T> Clone for Mutex<T> {
+    /// Cheap: hands back another handle to the same underlying lock and
+    /// value, the way `Arc::clone` does. All clones of a `Mutex` share one
+    /// lock and one protected value; locking through any clone excludes
+    /// every other clone.
     fn clone(&self) -> Self {
         Self { core: self.core.clone(), value: self.value.clone() }
     }
@@ -247,6 +354,10 @@ unsafe impl<T: Send> Sync for Mutex<T> {}
 // Guard
 // ---------------------------------------------------------------------------
 
+/// Grants access to the value inside a [`Mutex`] while the lock is held.
+/// Dereferences to `&T` and `&mut T`. Dropping the guard releases the lock
+/// and, if another actor is waiting, wakes the next one in arrival order.
+/// Returned by [`Mutex::lock`], [`Mutex::lock_timeout`], and [`Mutex::try_lock`].
 pub struct MutexGuard<'a, T> {
     mutex: &'a Mutex<T>,
     value: Option<T>,

src/registry.rs

@@ -1,55 +1,108 @@
-//! Named mailbox registry — resolve a name (or pid) to a *messageable* actor.
+
+//! Give an actor a name so other actors can find it and message it.
 //!
-//! ## What changed (RFC 014)
+//! Without the registry, the only way to reach an actor is to already be
+//! holding its [`Pid`], usually because you spawned it yourself or someone
+//! passed it to you. That is fine for a worker you just created, but it does
+//! not work for a well-known service that arbitrary parts of your program
+//! need to find independently, like a logger, a config store, or a
+//! connection pool. The registry solves this: an actor claims a name once,
+//! and from then on any other actor can look that name up, or send to it
+//! directly, without ever having been handed a `Pid`.
 //!
-//! The old registry was a `name <-> pid` bimap: `whereis` handed back a `Pid`
-//! you could not send to, because a pid is just `(index, generation)` with no
-//! delivery endpoint. This rework makes resolution yield something messageable.
+//! ```
+//! use smarm::{channel, register, run, send, spawn, unregister, whereis, Name};
 //!
-//! Two facts shape the structure:
+//! const COUNTER: Name<u64> = Name::new("counter");
 //!
-//! 1. **A name resolves to a single actor.** Many actors under one label is
-//!    what *process groups* (`pg`) are for; the registry is one-name-one-actor
-//!    (several names *may* point at the same actor).
-//! 2. **Channels are typed**, so an actor has no single untyped mailbox. An
-//!    actor instead owns a *set* of typed channels — one [`Sender`] per message
-//!    type it accepts. So the registry maps name/pid to a [`Mailbox`]: a small
-//!    structure holding that actor's pid plus all of its typed channels, keyed
-//!    by message [`TypeId`].
+//! run(|| {
+//!     let (ready_tx, ready_rx) = channel::<()>();
+//!     let (tx, rx) = channel::<u64>();
 //!
-//! Resolution is therefore: `name -> pid` (single actor) `-> Mailbox -> the
-//! channel for message type M`. A `Name<Cmd>` and a `Name<Admin>` on the *same*
-//! actor select *different* channels purely by their type parameter, so
-//! capability separation (RFC 014 §4.7) needs no extra machinery.
+//!     let worker = spawn(move || {
+//!         // Claim the name for this actor's inbox. Any actor holding
+//!         // `COUNTER` can now reach this one by name.
+//!         register(COUNTER, tx).unwrap();
+//!         ready_tx.send(()).unwrap();
+//!         assert_eq!(rx.recv().unwrap(), 42);
+//!     });
 //!
-//! ## Type erasure is contained
+//!     ready_rx.recv().unwrap(); // wait for the worker to register
 //!
-//! Each stored channel is a `Box<dyn Any + Send>` that is concretely a
-//! `Sender<M>`, filed under `TypeId::of::<M>()`. A resolve for `M` looks up
-//! that exact `TypeId` and downcasts to `Sender<M>` — keyed by the very type we
-//! downcast to, so the downcast cannot fail on correct data; a failure is a
-//! smarm bug, asserted in debug. The phantom `M` on [`Name`] re-imposes the
-//! type at the call site, so callers never touch the erasure.
+//!     // Look the name up, or just send to it directly.
+//!     assert_eq!(whereis("counter"), Some(worker.pid()));
+//!     send(COUNTER, 42).unwrap();
 //!
-//! ## Cleanup is lazy (prune-on-contact)
+//!     worker.join().unwrap();
 //!
-//! As before, there is no `finalize` hook and no name field on the slot. Every
-//! operation that touches a binding checks the target pid's liveness via the
-//! generation-checked slot word; a binding to a dead actor behaves as absent
-//! and is pruned on contact (its [`Mailbox`] and every name pointing at it are
-//! dropped). The cost is a dead binding lingering until something looks at it;
-//! the payoff is zero coupling to the actor lifecycle.
+//!     // The name dies with the actor: nobody holds it anymore.
+//!     assert_eq!(whereis("counter"), None);
+//! });
+//! ```
 //!
-//! ## Locking
+//! ## Names carry a message type
 //!
-//! One `RawMutex` (Leaf class) in `RuntimeInner`, exactly like the old
-//! registry. The fold (name index *and* handles under the one lock) is what
-//! keeps a name-addressed `send` on a single Leaf — `raw_mutex` panics on a
-//! second Leaf acquired while one is held. The send path clones the `Sender`
-//! **under** the Leaf lock (a `Sender::clone` takes a Channel lock, permitted
-//! under a Leaf), then **releases** the Leaf and only *then* sends — a send can
-//! unpark a receiver, and wakeup-bearing work runs outside the Leaf. Order is
-//! **Leaf -> Channel**, as `pg`/`finalize`.
+//! A [`Name<M>`] is a plain string plus a type parameter `M`: the message
+//! type that name expects to receive. [`Name::new`] is `const`, so the usual
+//! pattern is a module-level constant like `COUNTER` above, shared by every
+//! caller. The type parameter means a name is only ever sent the kind of
+//! message it was declared for. If two different constants share the same
+//! string but have different message types, they still address two
+//! independent channels on the same actor: registering both just gives that
+//! actor two ways to be reached, one per message type. This is how you give
+//! one actor a "public" channel and a separate, differently-typed "admin"
+//! channel under related names, without inventing an enum to merge them.
+//!
+//! ## One actor per name, looked up fresh every time
+//!
+//! A name always points at exactly one actor at a time (contrast a *process
+//! group*, from the [`pg`](crate::pg) module, which is one name mapping to
+//! many actors). Unlike a plain [`Pid`], which names one specific actor
+//! forever and stops working the moment that actor dies, a name is
+//! re-resolved on every [`send`]: if the actor holding it dies and a new one
+//! registers under the same name, the next `send` reaches the new holder
+//! automatically. Use a name for a long-lived service whose exact identity
+//! you do not want to track by hand; use a `Pid` when you already have one
+//! and want to talk to that exact actor.
+//!
+//! ## Registration ends when the actor does
+//!
+//! There is no separate step to clean up a name when its actor exits: dying
+//! is enough. The next operation that touches a dead binding (a [`whereis`],
+//! a [`send`], or another actor's [`register`] of the same name) notices the
+//! actor is gone and clears the stale entry as a side effect, so the name
+//! becomes free again. [`unregister`] is only for a live actor voluntarily
+//! giving up a name it no longer wants; nothing has to call it on the way
+//! out.
+//!
+//! ## Implementation notes
+//!
+//! These details matter if you are working on smarm itself; they are not
+//! part of the public contract.
+//!
+//! Internally, each live actor that has published at least one channel owns
+//! a `Mailbox`: its pid plus a set of typed channels, keyed by the message
+//! type's `TypeId`. A stored channel is a `Box<dyn Any + Send>` that
+//! is concretely a `Sender<M>`; resolving for `M` looks up that exact
+//! `TypeId` and downcasts, so the downcast cannot fail on correct data (a
+//! failure would be a bug in the registry itself, checked in debug builds).
+//! Registering a name therefore means: find or create the actor's mailbox,
+//! insert the channel under its type, and point the name at the actor's pid.
+//!
+//! There is no callback when an actor exits. Every operation that touches a
+//! binding checks the target pid's liveness directly against the scheduler's
+//! slot table (which also tracks a generation counter, so a dead actor's
+//! reused slot index is never mistaken for the same actor). A binding to a
+//! dead actor is treated as absent and dropped right there. This keeps the
+//! registry decoupled from actor teardown, at the cost of a dead binding
+//! lingering until something happens to look at it.
+//!
+//! The whole registry (both the name index and the per-actor mailboxes) sits
+//! behind one lock, which is what lets a name-addressed [`send`] resolve and
+//! clone the target's sender in a single critical section. The sender is
+//! cloned while that lock is held, then the lock is released before the
+//! actual send, since delivering a message can wake a parked receiver and
+//! that wakeup work should not run while the registry is locked.
 
 use crate::channel::Sender;
 use crate::pid::{Addressable, Name, Pid};
@@ -80,28 +133,33 @@ impl std::fmt::Display for RegisterError {
 
 impl std::error::Error for RegisterError {}
 
-/// Why a name-addressed [`send`] did not deliver. Carries the message back so
-/// the caller never loses it (mirrors [`crate::channel::SendError`]).
+/// Why a send did not deliver. Every variant carries the undelivered message
+/// back, mirroring [`crate::channel::SendError`], so a failed send never
+/// silently drops what you tried to send.
 ///
-/// `Debug`/`Display` are hand-written so neither demands `M: Debug` — the
-/// payload is returned, not printed.
+/// `Debug` and `Display` are hand-written so neither requires `M: Debug`,
+/// since the payload is handed back to you, not printed.
 pub enum SendError<M> {
-    /// No live actor is currently registered under this name. Name-addressed
-    /// [`send`] only; the pid-addressed counterpart is [`SendError::Dead`].
+    /// No live actor is currently registered under this name. Returned only
+    /// by name-addressed [`send`]; the pid-addressed counterpart of "nothing
+    /// there" is [`SendError::Dead`].
     Unresolved(M),
-    /// The pid-addressed actor is no longer the live incarnation this pid names
-    /// — it has died, even if its slot now holds a *different* actor (a direct
-    /// `Pid<A>` send never redirects; contrast name-addressed [`send`]). Pid
-    /// paths ([`send_to`] / [`send_dyn`]) only.
+    /// The actor this pid identifies has died, even if its slot has since
+    /// been taken over by a different, live actor. A direct `Pid<A>` send
+    /// never redirects to that new occupant; contrast name-addressed
+    /// [`send`], which would reach it. Returned by the pid-addressed sends,
+    /// [`send_to`] and [`send_dyn`].
     Dead(M),
-    /// The actor is live but exposes no channel for this message type.
+    /// The actor is live but has not published a channel for this message
+    /// type.
     NoChannel(M),
-    /// The actor's channel for this message type is closed (its receiver is gone).
+    /// The actor's channel for this message type is closed (its receiver has
+    /// been dropped).
     Closed(M),
-    /// No live member to deliver to — a [`dispatch`](crate::dispatch) over an
-    /// empty (or all-dead) process group. Group-addressed dispatch only; the
-    /// name-addressed counterpart is [`SendError::Unresolved`]. The message is
-    /// handed back undelivered.
+    /// No live member was available to deliver to: returned by
+    /// [`dispatch`](crate::dispatch) when the target process group is empty
+    /// or every member in it has died. The name-addressed counterpart of
+    /// this case is [`SendError::Unresolved`].
     NoMember(M),
 }
 
@@ -150,9 +208,9 @@ impl<M> std::error::Error for SendError<M> {}
 
 /// A registry-stored channel, type-erased over its message type. The stored
 /// object must serve two readers: `clone_sender` (downcast back to the concrete
-/// `Sender<M>`) and the RFC 016 snapshot (queued length without knowing `M`).
-/// A bare `Box<dyn Any>` gives the first but not the second, so we erase behind
-/// this small trait instead.
+/// `Sender<M>`) and the runtime introspection snapshot (queued length without
+/// knowing `M`). A bare `Box<dyn Any>` gives the first but not the second, so
+/// we erase behind this small trait instead.
 trait ErasedSender: Send {
     fn as_any(&self) -> &dyn Any;
     fn queued_len(&self) -> usize;
@@ -169,7 +227,7 @@ impl<M: Send + 'static> ErasedSender for Sender<M> {
 
 /// One typed channel of an actor, type-erased. Concretely a `Sender<M>` filed
 /// under `TypeId::of::<M>()`; `msg_type` is `type_name::<M>()`, kept for
-/// observers (RFC 014 §4.5) and as the debug cross-check on the downcast.
+/// observability tooling and as the debug cross-check on the downcast.
 struct Channel {
     sender: Box<dyn ErasedSender>,
     msg_type: &'static str,
@@ -204,7 +262,7 @@ impl Mailbox {
     }
 }
 
-/// Per-actor registry view handed to RFC 016 introspection: registered names
+/// Per-actor registry view handed to runtime introspection: registered names
 /// and summed mailbox depth, tagged with the mailbox's `pid` so a stale
 /// incarnation can be filtered against the slab. Covers only *published*
 /// channels (`register` / `install` / `spawn_addr` / gen_server start); an
@@ -219,17 +277,18 @@ pub(crate) struct MailboxInfo {
 /// The directory. Invariant (held under the registry lock): every value in
 /// `by_name` is the full [`Pid`] (index *and* generation) of an actor that
 /// published a [`Mailbox`] into `by_index` at registration time. Stale entries
-/// (dead holders — including holders whose slot has since been re-tenanted by
-/// a different actor) violate nothing — they are pruned on contact, and the
+/// (dead holders, including holders whose slot has since been re-tenanted by
+/// a different actor) violate nothing: they are pruned on contact, and the
 /// generation makes "dead" decidable even after slot reuse.
 pub(crate) struct Registry {
     /// `pid.index() -> the actor's mailbox`. The handle store.
     by_index: HashMap<u32, Mailbox>,
     /// `name -> holder pid`. Several names may map to one actor. The full pid
     /// (not just the index) is load-bearing: an index alone cannot tell a dead
-    /// holder from the live actor now tenanting its recycled slot, which made
-    /// such a name read as live-held — unresolvable *and* unregisterable — and
-    /// would misdeliver to a same-typed tenant (soak20 signature 2).
+    /// holder from the live actor now tenanting its recycled slot. Comparing
+    /// only the index would make such a name read as live-held (unresolvable
+    /// and unregisterable at once) and could misdeliver to whatever new,
+    /// same-typed actor now sits in that slot.
     by_name: HashMap<&'static str, Pid>,
 }
 
@@ -238,10 +297,10 @@ impl Registry {
         Self { by_index: HashMap::new(), by_name: HashMap::new() }
     }
 
-    /// Drop a dead holder's artifacts: every name bound to it, and its mailbox
-    /// — but only while the mailbox is still *its own*. A recycled slot's
-    /// mailbox belongs to the live tenant (publish replaces it wholesale on
-    /// pid mismatch) and is left untouched.
+    /// Drop a dead holder's artifacts: every name bound to it, and its
+    /// mailbox, but only while the mailbox is still *its own*. A recycled
+    /// slot's mailbox belongs to the live tenant (publish replaces it
+    /// wholesale on pid mismatch) and is left untouched.
     fn prune_holder(&mut self, holder: Pid) {
         self.by_name.retain(|_, p| *p != holder);
         if self.by_index.get(&holder.index()).is_some_and(|mb| mb.pid == holder) {
@@ -249,17 +308,16 @@ impl Registry {
         }
     }
 
-    /// RFC 016 snapshot input: per-slot-index registry view — the actor's
-    /// registered names (inverted from `by_name`) and its mailbox depth (queued
-    /// messages summed across every published typed channel). Built in one pass
-    /// under the registry Leaf; the per-channel `queued_len` takes a Channel
-    /// lock, legal under the Leaf (Leaf → Channel). Carries each mailbox's full
-    /// `pid` so the caller can discard a stale incarnation's entry against the
-    /// slab's live generation. Names are matched to mailboxes by *full pid*, so
-    /// a stale name (dead holder) still annotates the corpse's own mailbox if
-    /// that survives, but never a recycled slot's new tenant; names that attach
-    /// to no mailbox are dropped — they violate no invariant and get pruned on
-    /// next contact.
+    /// Runtime introspection input: per-slot-index registry view, giving the
+    /// actor's registered names (inverted from `by_name`) and its mailbox
+    /// depth (queued messages summed across every published typed channel).
+    /// Carries each mailbox's full `pid` so the caller can discard a stale
+    /// incarnation's entry against the slab's live generation. Names are
+    /// matched to mailboxes by *full pid*, so a stale name (dead holder)
+    /// still annotates the corpse's own mailbox if that survives, but never a
+    /// recycled slot's new tenant; names that attach to no mailbox are
+    /// dropped, since that violates no invariant and they get pruned on next
+    /// contact.
     pub(crate) fn introspect_map(&self) -> HashMap<u32, MailboxInfo> {
         let mut names: HashMap<Pid, Vec<&'static str>> = HashMap::new();
         for (&name, &pid) in &self.by_name {
@@ -282,8 +340,9 @@ impl Registry {
 
     /// Single-actor form of [`introspect_map`](Self::introspect_map): the
     /// registry view for one slot index, or `None` if no mailbox is published
-    /// there. Used by `actor_info` so its cost stays proportional to the one
-    /// actor rather than locking every channel in the runtime.
+    /// there. Used by the runtime's per-actor introspection so its cost stays
+    /// proportional to the one actor rather than locking every channel in the
+    /// runtime.
     pub(crate) fn introspect_one(&self, idx: u32) -> Option<MailboxInfo> {
         let mb = self.by_index.get(&idx)?;
         let depth: usize = mb.channels.values().map(|c| c.sender.queued_len()).sum();
@@ -301,14 +360,18 @@ fn live(inner: &crate::runtime::RuntimeInner, pid: Pid) -> bool {
     inner.slot_at(pid).is_some_and(|s| s.is_live_for(pid))
 }
 
-/// Publish the current actor's `Sender<M>` under `name`, capturing the channel
-/// so the name becomes messageable. Idempotent for the same `(name, type)`;
-/// registering a *second* type under the same (or another) name on the same
-/// actor just adds another channel to the actor's mailbox.
+/// Give the current actor's channel a name, so other actors can find and
+/// message it by that name instead of needing its [`Pid`].
 ///
-/// Fails with [`RegisterError::NameTaken`] if the name is held by a *different*
-/// live actor (a binding to a dead actor is pruned and the name treated as
-/// free). Panics if called outside `Runtime::run()`.
+/// Calling this again with the same `(name, type)` from the same actor is
+/// harmless. Registering a *second* message type under the same (or a
+/// different) name from the same actor just adds another typed channel to
+/// that actor's mailbox; it does not replace the first.
+///
+/// Fails with [`RegisterError::NameTaken`] if the name is currently held by a
+/// *different* live actor. A name held by an actor that has since died is not
+/// considered taken: it is quietly reclaimed and handed to you. Panics if
+/// called outside [`run`](crate::run).
 pub fn register<M: Send + 'static>(name: Name<M>, tx: Sender<M>) -> Result<(), RegisterError> {
     register_with(self_pid(), name.as_str(), tx)
 }
@@ -316,8 +379,8 @@ pub fn register<M: Send + 'static>(name: Name<M>, tx: Sender<M>) -> Result<(), R
 /// Bind `name` to `pid`'s mailbox and publish `tx` under `M`'s [`TypeId`], for
 /// an explicit (already-live) actor rather than `self`. The shared core of
 /// [`register`] (which passes `self_pid()`) and the parent-side server-name
-/// bind in `gen_server` (which names a freshly spawned server before its body
-/// has run, so the name resolves the instant `start()` returns). Same collision
+/// bind in `gen_server`, which names a freshly spawned server before its body
+/// has run, so the name resolves the instant `start()` returns. Same collision
 /// rules and lock discipline as `register`.
 pub(crate) fn register_with<M: Send + 'static>(
     me: Pid,
@@ -337,8 +400,8 @@ pub(crate) fn register_with<M: Send + 'static>(
             } else {
                 // Dead holder: free the name (and its other stale artifacts).
                 // Liveness is judged against the *stored* pid, generation
-                // included — a recycled slot's live tenant no longer makes a
-                // dead name read as taken (soak20 signature 2).
+                // included, so a recycled slot's live tenant no longer makes a
+                // dead name read as taken.
                 reg.prune_holder(holder);
             }
         }
@@ -367,14 +430,14 @@ fn publish_channel<M: Send + 'static>(reg: &mut Registry, me: Pid, tx: Sender<M>
 
 /// Publish the current actor's `Sender<A::Msg>` into its mailbox **without**
 /// binding a name, and hand back the typed [`Pid<A>`] that addresses this
-/// actor directly. This is the opt-in, lazy install of RFC 014 §5: an actor
-/// that wants to be reachable by a direct, identity-bound [`Pid<A>`] (rather
-/// than only via a re-resolving [`Name`]) calls this once with its inbox
-/// sender, then hands the returned pid out.
+/// actor directly.
 ///
-/// Unlike [`register`] there is no name to collide on, and `self` is always a
-/// live actor inside `run()`, so this is infallible. Panics if called outside
-/// `Runtime::run()`.
+/// This is for an actor that wants to be reachable directly by its pid,
+/// rather than only through a re-resolving [`Name`]: call this once with your
+/// inbox sender, then hand the returned `Pid<A>` to whoever should be able to
+/// message you. Unlike [`register`] there is no name to collide on, and the
+/// current actor is always live while inside `run()`, so this cannot fail.
+/// Panics if called outside [`run`](crate::run).
 pub fn install<A: Addressable>(tx: Sender<A::Msg>) -> Pid<A> {
     let me = self_pid();
     with_runtime(|inner| {
@@ -390,11 +453,12 @@ pub fn install<A: Addressable>(tx: Sender<A::Msg>) -> Pid<A> {
 /// Publish `tx` into `pid`'s mailbox under `M`'s [`TypeId`], for an explicit
 /// (freshly minted, already-live) actor rather than `self`. The parent-side
 /// half of [`spawn_addr`](crate::spawn_addr): the spawner makes the inbox and
-/// publishes the sender here *before* handing back the `Pid<A>`, so an immediate
-/// `send_to` on the returned pid always resolves — the address is live the
-/// instant the caller holds it, with no dependence on the body having run yet.
+/// publishes the sender here *before* handing back the `Pid<A>`, so an
+/// immediate `send_to` on the returned pid always resolves. The address is
+/// live the instant the caller holds it, with no dependence on the spawned
+/// actor's body having run yet.
 ///
-/// Caller guarantees `pid` is the just-installed actor (Queued, this exact
+/// Caller guarantees `pid` is the just-installed actor (queued, this exact
 /// incarnation); `publish_channel` replaces any stale leftover at the slot.
 pub(crate) fn install_for<M: Send + 'static>(pid: Pid, tx: Sender<M>) {
     with_runtime(|inner| {
@@ -404,8 +468,9 @@ pub(crate) fn install_for<M: Send + 'static>(pid: Pid, tx: Sender<M>) {
     });
 }
 
-/// The single actor currently registered under `name`, or `None` if unbound or
-/// no longer live (the stale binding is pruned on the way out).
+/// Look up which actor currently holds `name`, if any. Returns `None` if the
+/// name is unbound, or if it was bound to an actor that has since died (the
+/// stale binding is cleared as a side effect of this call).
 pub fn whereis(name: &str) -> Option<Pid> {
     with_runtime(|inner| {
         let mut reg = inner.registry.lock();
@@ -421,34 +486,37 @@ pub fn whereis(name: &str) -> Option<Pid> {
     })
 }
 
-/// Resolve `name` to a *typed* [`Pid<A>`] — the identity-bound counterpart of
-/// [`whereis`] (RFC 014 §4.4). Recovers the compile-checked
-/// [`send_to`] path from a durable name: looks the name up,
-/// then re-types the erased pid as `Pid<A>` via the unchecked
-/// [`assert_type`](crate::pid::assert_type) primitive. A wrong `A` is not
-/// unsound — it degrades to [`SendError::NoChannel`] on the next send (routing
-/// is by message `TypeId`), never a misdelivery. `None` if unbound or dead.
+/// Like [`whereis`], but returns a *typed* [`Pid<A>`] instead of a bare
+/// [`Pid`], so a follow-up [`send_to`] is compile-checked instead of needing
+/// the untyped [`send_dyn`] escape hatch. `None` if the name is unbound or its
+/// holder has died.
 ///
-/// Panics if called outside `Runtime::run()`.
+/// The type `A` is not checked against what the name's holder actually
+/// published: if you pick the wrong `A`, this still succeeds, but the next
+/// send against the returned pid degrades to [`SendError::NoChannel`] rather
+/// than reaching the wrong actor or the wrong channel.
+///
+/// Panics if called outside [`run`](crate::run).
 pub fn lookup_as<A: Addressable>(name: &str) -> Option<Pid<A>> {
     whereis(name).map(crate::pid::assert_type::<A>)
 }
 
-/// Resolve `name` to its actor's pid and a cloned `Sender<M>`, under the Leaf
-/// lock (clone-under-lock, then release). The crate-internal building block for
-/// `gen_server`'s by-name addressing: a named server publishes its inbox as a
-/// `Sender<Envelope<G>>` (via [`register_with`]), and `whereis_server` / `call`
-/// / `cast` recover that exact typed sender here to rebuild a `GenServerRef<G>`.
-/// `None` if unbound, dead (pruned on the way out), or holding no `M` channel.
+/// Resolve `name` to its actor's pid and a cloned `Sender<M>`, all under one
+/// lock acquisition. The crate-internal building block for `gen_server`'s
+/// by-name addressing: a named server publishes its inbox as a
+/// `Sender<Envelope<G>>` (via [`register_with`]), and the server's `call` /
+/// `cast` / `whereis_server` recover that exact typed sender here to rebuild a
+/// `GenServerRef<G>`. `None` if unbound, dead (pruned on the way out), or
+/// holding no `M` channel.
 pub(crate) fn resolve_named_sender<M: Send + 'static>(name: &str) -> Option<(Pid, Sender<M>)> {
     with_runtime(|inner| {
         let mut reg = inner.registry.lock();
         let pid = *reg.by_name.get(name)?;
         if !live(inner, pid) {
             // Stored-pid liveness, generation included: a name whose holder
-            // died is pruned (heals) even if the slot has a new tenant —
-            // previously the tenant's mailbox made the name unresolvable
-            // *without* pruning, wedging it for the tenant's lifetime.
+            // died is pruned (heals) even if the slot has a new tenant.
+            // Otherwise the tenant's mailbox would make the name unresolvable
+            // without pruning, wedging it for the tenant's lifetime.
             reg.prune_holder(pid);
             return None;
         }
@@ -459,9 +527,10 @@ pub(crate) fn resolve_named_sender<M: Send + 'static>(name: &str) -> Option<(Pid
     })
 }
 
-/// Remove the binding for `name`, returning the actor it pointed at if still
-/// live. Only the *name* is freed; the actor's mailbox (and any other names for
-/// it) remain. A binding to a dead actor is reported as `None`.
+/// Give up a name. Returns the actor it pointed at, if that actor was still
+/// live. Only the *name* is freed; the actor's mailbox (and any other names
+/// bound to it) are unaffected. A binding to an already-dead actor reports
+/// `None`, since there was nothing live to release.
 pub fn unregister(name: &str) -> Option<Pid> {
     with_runtime(|inner| {
         let mut reg = inner.registry.lock();
@@ -470,18 +539,21 @@ pub fn unregister(name: &str) -> Option<Pid> {
     })
 }
 
-/// Resolve `name` to its actor's `Sender<M>` and deliver `msg`. The whole point
-/// of the rework: a name you can *send* to.
+/// Look `name` up and deliver `msg` to whichever actor currently holds it.
+/// This is the point of naming an actor: a name you can send a message to
+/// directly, without a separate lookup step.
 ///
-/// Errors (message returned in every case): [`SendError::Unresolved`] if no
-/// live actor holds the name, [`SendError::NoChannel`] if that actor has no
-/// channel for `M`, [`SendError::Closed`] if its `M` channel's receiver is
-/// gone. Panics if called outside `Runtime::run()`.
+/// On failure the message comes back to you, wrapped in the [`SendError`]
+/// variant that explains why: [`SendError::Unresolved`] if no live actor
+/// currently holds the name, [`SendError::NoChannel`] if the actor that holds
+/// it never published a channel for `M`, or [`SendError::Closed`] if it
+/// published one but has since dropped the receiving end. Panics if called
+/// outside [`run`](crate::run).
 pub fn send<M: Send + 'static>(name: Name<M>, msg: M) -> Result<(), SendError<M>> {
     let key = name.as_str();
     with_runtime(|inner| {
-        // Resolve + clone the sender under the Leaf lock, then drop the lock
-        // before sending (a send can unpark a receiver).
+        // Resolve + clone the sender under the registry lock, then drop the
+        // lock before sending (a send can unpark a receiver).
         let tx = {
             let mut reg = inner.registry.lock();
             let pid = match reg.by_name.get(key) {
@@ -489,11 +561,9 @@ pub fn send<M: Send + 'static>(name: Name<M>, msg: M) -> Result<(), SendError<M>
                 None => return Err(SendError::Unresolved(msg)),
             };
             if !live(inner, pid) {
-                // Stored-pid liveness (generation included). Previously this
-                // checked the slot's *current* mailbox pid, so a recycled
-                // slot's live tenant passed — and a same-typed tenant would
-                // have received the message (misdelivery), a differently
-                // typed one a misleading NoChannel.
+                // Stored-pid liveness (generation included), so a recycled
+                // slot's new live tenant is never mistaken for the name's
+                // original (now-dead) holder.
                 reg.prune_holder(pid);
                 return Err(SendError::Unresolved(msg));
             }
@@ -508,18 +578,19 @@ pub fn send<M: Send + 'static>(name: Name<M>, msg: M) -> Result<(), SendError<M>
 
 /// Resolve a *raw* pid to its mailbox and deliver `msg` on the channel for `M`,
 /// with **no redirect**. The stored mailbox must be this exact incarnation
-/// (generation included) and still live; otherwise the actor this pid named is
-/// gone and the result is [`SendError::Dead`] — even when the slot now holds a
-/// different, live actor (which we leave untouched). Shared by [`send_to`]
-/// (typed, `M = A::Msg`, channel guaranteed on an installed actor) and
-/// [`send_dyn`] (explicit `M`, where `NoChannel` is a real outcome).
+/// (generation included) and still live; otherwise the actor this pid named
+/// is gone and the result is [`SendError::Dead`], even when the slot now
+/// holds a different, live actor (which is left untouched). Shared by
+/// [`send_to`] (typed, `M = A::Msg`, channel guaranteed on an installed
+/// actor) and [`send_dyn`] (explicit `M`, where `NoChannel` is a real
+/// outcome).
 fn send_to_pid<M: Send + 'static>(
     inner: &crate::runtime::RuntimeInner,
     pid: Pid,
     msg: M,
 ) -> Result<(), SendError<M>> {
-    // Resolve + clone the sender under the Leaf lock, then drop the lock before
-    // sending (a send can unpark a receiver) — Leaf -> Channel, as name `send`.
+    // Resolve + clone the sender under the registry lock, then drop the lock
+    // before sending (a send can unpark a receiver), same order as `send`.
     let tx = {
         let mut reg = inner.registry.lock();
         match reg.by_index.get(&pid.index()).map(|m| m.pid) {
@@ -543,32 +614,36 @@ fn send_to_pid<M: Send + 'static>(
     tx.send(msg).map_err(|crate::channel::SendError(m)| SendError::Closed(m))
 }
 
-/// Deliver `msg` to the exact actor named by `pid` — RFC 014 §4.2's direct,
-/// identity-bound addressing mode. Unlike name-addressed [`send`] there is **no
-/// redirect**: if that incarnation has died the message comes back as
-/// [`SendError::Dead`], even if its slot now holds a different actor.
+/// Deliver `msg` directly to the exact actor identified by `pid`. Unlike
+/// name-addressed [`send`], there is **no redirect**: if that specific actor
+/// has died, the message comes back as [`SendError::Dead`], even if its slot
+/// has since been taken over by a different, live actor. Use this when you
+/// already hold a `Pid<A>` and want to talk to that one actor specifically;
+/// use [`send`] with a [`Name`] when you want whichever actor currently holds
+/// a name.
 ///
 /// The message type is the actor's `A::Msg`, so on a live actor that has
-/// installed its inbox (via [`install`] or [`register`]) the channel is always
-/// present; [`SendError::NoChannel`] therefore means the actor is live but
-/// never published a `Pid<A>`-reachable inbox. Panics if called outside
-/// `Runtime::run()`.
+/// installed its inbox (via [`install`] or [`register`]) the channel is
+/// always present; [`SendError::NoChannel`] therefore means the actor is live
+/// but never published a `Pid<A>`-reachable inbox. Panics if called outside
+/// [`run`](crate::run).
 pub fn send_to<A: Addressable>(pid: Pid<A>, msg: A::Msg) -> Result<(), SendError<A::Msg>> {
     with_runtime(|inner| send_to_pid::<A::Msg>(inner, pid.erase(), msg))
 }
 
-/// The explicit bare-pid escape hatch (RFC 014 §4.6): deliver `msg` of type `M`
-/// to `pid` when all you hold is an untyped [`Pid`] — a pid off a [`Down`], or
-/// out of a future `members()` — so the typed [`send_to`] is unavailable.
+/// The escape hatch for sending to a bare, untyped [`Pid`] when the typed
+/// [`send_to`] is unavailable, for example a pid recovered from a [`Down`]
+/// notification or a group's `members()` list, where you no longer know the
+/// actor's message type at compile time.
 ///
-/// This is the one send whose message type can genuinely be wrong: the actor
-/// may be live yet expose no channel for `M`, returning [`SendError::NoChannel`]
-/// (on the typed paths that downcast collapses to a `debug_assert`). It is
-/// named and documented as the fallible fallback so the typed `Pid<A>` /
-/// `Name<M>` paths stay the obvious default and an agentic caller reaches for a
-/// present primitive instead of inventing a workaround. Liveness is identical
-/// to [`send_to`]: identity-bound, no redirect, [`SendError::Dead`] once the
-/// addressed incarnation is gone. Panics if called outside `Runtime::run()`.
+/// Because the message type is not checked at compile time here, this is the
+/// one send that can genuinely be live-but-wrong: the actor may be alive yet
+/// expose no channel for `M`, in which case you get [`SendError::NoChannel`]
+/// back instead of a misdelivery. Liveness and redirect behavior are
+/// otherwise identical to [`send_to`]: identity-bound, no redirect,
+/// [`SendError::Dead`] once the addressed incarnation is gone. Prefer
+/// `send_to` with a typed `Pid<A>` whenever you have one; reach for this only
+/// when you don't. Panics if called outside [`run`](crate::run).
 ///
 /// [`Down`]: crate::Down
 pub fn send_dyn<M: Send + 'static>(pid: Pid, msg: M) -> Result<(), SendError<M>> {

src/scheduler.rs

@@ -1,11 +1,69 @@
-//! Scheduler public API — thin façade over the multi-scheduler runtime.
+//! Start actors and control them: `run`, `spawn`, `sleep`, timers, and IO waits.
 //!
-//! All heavy lifting lives in `runtime.rs`. This module exposes the same
-//! surface that the rest of the codebase (channel, mutex, io, timer, actor)
-//! calls into, plus the public API re-exported from `lib.rs`.
+//! ## What is an actor?
 //!
-//! The single-threaded `run()` entry point is kept as a convenience wrapper
-//! around `runtime::init(Config::exact(1)).run(f)`.
+//! An actor in smarm is a *green thread*: a lightweight, cooperatively
+//! scheduled unit of execution with its own stack, running alongside
+//! thousands of others on a handful of OS threads. You give it a closure;
+//! smarm gives it a [`Pid`] and a [`JoinHandle`]. Actors talk to each other by
+//! sending messages over [`channel`](mod@crate::channel)s, not by sharing memory,
+//! so most of the concurrency bugs that come from shared mutable state simply
+//! don't arise.
+//!
+//! Everything in smarm (channels, [`Mutex`](crate::Mutex), timers, IO waits,
+//! `gen_server`) needs to run on top of a scheduler. [`run`] starts one and
+//! blocks the calling OS thread until the actor you give it finishes; from
+//! inside that actor (or any actor it spawns), call [`spawn`] to start more.
+//!
+//! ```
+//! use smarm::{run, spawn};
+//!
+//! run(|| {
+//!     let handle = spawn(|| {
+//!         println!("hello from another actor");
+//!     });
+//!     handle.join().unwrap();
+//! });
+//! ```
+//!
+//! ## Waiting for an actor: `JoinHandle`
+//!
+//! [`spawn`] returns a [`JoinHandle`], your only handle on the actor's
+//! outcome. Call [`JoinHandle::join`] to block the calling actor until the
+//! spawned one finishes:
+//!
+//! - if it returned normally, `join` returns `Ok(())`;
+//! - if it panicked, `join` returns `Err(`[`JoinError`]`)` carrying the panic
+//!   payload, so a crash in one actor never silently vanishes and never
+//!   crashes the process; the caller decides what to do with it (log it,
+//!   propagate it, ignore it).
+//!
+//! If you don't need the result, drop the `JoinHandle` (or never bind it):
+//! the actor keeps running independently. To watch an actor without
+//! blocking, or to react to failures across a whole tree of actors, see
+//! [`monitor`](mod@crate::monitor), [`link`](mod@crate::link), and
+//! [`supervisor`](crate::supervisor) instead.
+//!
+//! ## Sleeping, timeouts, and IO
+//!
+//! [`sleep`] parks only the calling actor, not the OS thread underneath it,
+//! so thousands of sleeping actors cost nothing but the timer entry.
+//! [`send_after`] and [`send_after_named`] schedule a message to be delivered
+//! later (Erlang-style `send_after`), and [`cancel_timer`] can call one off
+//! before it fires.
+//!
+//! For blocking or file-descriptor-based IO, see [`block_on_io`],
+//! [`wait_readable`], and [`wait_writable`]: they park the calling actor and
+//! resume it when the work completes or the fd is ready, again without
+//! blocking an OS thread.
+//!
+//! ## Stopping an actor from the outside
+//!
+//! [`request_stop`] asks an actor to cooperatively unwind: it's the
+//! mechanism `gen_server` shutdown, timeouts, and supervisor restarts are
+//! built on. It's best-effort: an actor that never yields, allocates, or
+//! blocks (a tight loop with nothing else in it) has no opportunity to
+//! notice the request.
 
 use crate::actor::current_pid;
 use crate::channel::Sender;
@@ -20,21 +78,14 @@ use std::sync::Arc;
 // with_runtime / try_with_runtime
 // ---------------------------------------------------------------------------
 
-/// Borrow the current runtime. Panics if called outside `Runtime::run()`.
-///
-/// The whole span runs with preemption disabled. Two reasons, both load-
-/// bearing:
-///
-/// - The `RUNTIME` thread-local borrow is live across `f`. A preemption-
-///   driven context switch inside `f` can resume the actor on a DIFFERENT OS
-///   thread; the borrow guard would then increment this thread's RefCell but
-///   decrement the other's — a count underflow that leaves that thread's
-///   RefCell permanently "mutably borrowed". Holding a thread-local guard
-///   across a potential switch point is the one unforgivable sin of green
-///   threads; disabling preemption makes "no switch inside `f`" structural
-///   instead of an accident of which bodies happen to allocate.
-/// - `f` is runtime bookkeeping. Suspending an actor halfway through it (or
-///   unwinding via the stop sentinel, which shares the gate) is never wanted.
+// Borrow the current runtime. Panics if called outside `Runtime::run()`.
+//
+// Preemption is disabled for the whole span. `f` holds a thread-local borrow
+// of `RUNTIME`; if a preemption-driven context switch moved the actor to a
+// different OS thread in the middle of `f`, the borrow guard would be
+// released on the wrong thread's copy of the thread-local, corrupting its
+// borrow count. `f` is also always runtime bookkeeping that should run to
+// completion without the actor being suspended or unwound partway through.
 pub(crate) fn with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> R {
     let prev = crate::preempt::PREEMPTION_ENABLED.with(|c| c.replace(false));
     let result = RUNTIME.with(|r| {
@@ -49,9 +100,9 @@ pub(crate) fn with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> R {
     result
 }
 
-/// Borrow the runtime if present; returns `None` otherwise.
-/// Used on cleanup paths (channel Drop during teardown).
-/// Same preemption gate as [`with_runtime`]; same reasons.
+// Borrow the runtime if present, otherwise `None`. Used on cleanup paths
+// (e.g. a channel's Drop impl during teardown) that may run after the
+// runtime has already gone away. Same preemption gate as `with_runtime`.
 pub(crate) fn try_with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> Option<R> {
     let prev = crate::preempt::PREEMPTION_ENABLED.with(|c| c.replace(false));
     let result = RUNTIME.with(|r| r.borrow().as_ref().map(f));
@@ -63,19 +114,49 @@ pub(crate) fn try_with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> Op
 // JoinHandle / JoinError
 // ---------------------------------------------------------------------------
 
+/// The spawned actor panicked. Returned by [`JoinHandle::join`]; `payload`
+/// is exactly what the panic carried (the value passed to `panic!`, or
+/// whatever a library panicked with), the same payload you'd get from
+/// [`std::thread::JoinHandle::join`]. Downcast it if you need to inspect it:
+///
+/// ```
+/// use smarm::{run, spawn};
+///
+/// run(|| {
+///     let h = spawn(|| panic!("boom"));
+///     let err = h.join().unwrap_err();
+///     let msg = err.payload.downcast_ref::<&str>().copied().unwrap_or("?");
+///     assert_eq!(msg, "boom");
+/// });
+/// ```
 #[derive(Debug)]
 pub struct JoinError {
     pub payload: Box<dyn std::any::Any + Send>,
 }
 
+/// A handle to a spawned actor, returned by [`spawn`], [`spawn_under`], and
+/// friends. Use [`join`](Self::join) to wait for the actor to finish and
+/// collect its outcome, or [`pid`](Self::pid) to get its identity for use
+/// with [`request_stop`], [`monitor`](crate::monitor::monitor), or
+/// [`link`](crate::link::link).
+///
+/// If you never call `join` (or drop the handle instead), the actor is not
+/// affected: it keeps running and its resources are still reclaimed when it
+/// finishes. `join` is how you find out *what happened*, not a requirement
+/// for the actor to make progress or clean up.
 pub struct JoinHandle {
     pid: Pid,
     consumed: bool,
 }
 
 impl JoinHandle {
+    /// The identity of the actor this handle refers to.
     pub fn pid(&self) -> Pid { self.pid }
 
+    /// Block the calling actor until the spawned actor finishes, then
+    /// report how it finished: `Ok(())` if it returned normally or stopped
+    /// cooperatively via [`request_stop`], `Err(`[`JoinError`]`)` if it
+    /// panicked.
     pub fn join(mut self) -> Result<(), JoinError> {
         use crate::actor::Outcome;
 
@@ -177,6 +258,19 @@ impl Drop for JoinHandle {
 // spawn / spawn_under / self_pid
 // ---------------------------------------------------------------------------
 
+/// Start a new actor running `f`, and return a [`JoinHandle`] for it.
+///
+/// The new actor runs concurrently with its caller and with every other
+/// actor in the runtime; smarm schedules it cooperatively across the
+/// available OS threads. `spawn` can be called from inside `run`'s closure,
+/// or from inside any actor (spawning a child from a child works the same
+/// way); it cannot be called before `run` has started or after it returns.
+///
+/// The returned [`JoinHandle`] is how you learn how the actor finished. If
+/// you don't need that, it's fine to drop it: the actor still runs to
+/// completion either way.
+///
+/// Panics if called outside `Runtime::run()`.
 pub fn spawn(f: impl FnOnce() + Send + 'static) -> JoinHandle {
     let parent = current_pid().unwrap_or_else(|| {
         // Outside an actor but inside run(): the initial spawn. with_runtime
@@ -186,6 +280,11 @@ pub fn spawn(f: impl FnOnce() + Send + 'static) -> JoinHandle {
     spawn_under(parent, f)
 }
 
+/// Like [`spawn`], but explicitly attaches the new actor to `supervisor`
+/// instead of the calling actor. Ordinary code should reach for [`spawn`];
+/// this exists for supervision trees (see [`supervisor`](crate::supervisor))
+/// and other cases that need to place a child under a specific ancestor
+/// rather than its true caller.
 pub fn spawn_under<A>(supervisor: Pid<A>, f: impl FnOnce() + Send + 'static) -> JoinHandle {
     let supervisor = supervisor.erase();
     // Stack + closure boxing happen before ANY runtime lock is taken: no
@@ -208,19 +307,20 @@ pub fn spawn_under<A>(supervisor: Pid<A>, f: impl FnOnce() + Send + 'static) ->
     JoinHandle { pid, consumed: false }
 }
 
-/// Spawn a typed, single-message actor and hand back its identity-bound
-/// [`Pid<A>`] (RFC 014's typed-path producer). The runtime makes the actor's
-/// inbox, hands the body its [`Receiver<A::Msg>`], installs the sender, and
-/// returns the parent a `Pid<A>`.
+/// Spawn an actor that other actors can message directly by its [`Pid<A>`],
+/// rather than only by holding on to a channel `Sender` you passed it
+/// yourself.
 ///
-/// The inbox is published from the parent side **before** the pid is returned
-/// (see [`registry::install_for`](crate::registry::install_for)), so the address
-/// is live the instant the caller holds it: an immediate
-/// [`send_to`](crate::send_to) always resolves, never racing the body's first
-/// instruction. The actor is detached — its lifetime is governed by its own
-/// logic (an explicit stop message, or returning), like
-/// [`GenServerBuilder::start`](crate::GenServerBuilder::start) — so the backing join
-/// handle is dropped. Spawns under the current actor (via [`spawn`]).
+/// `body` receives the [`Receiver<A::Msg>`](crate::channel::Receiver) smarm
+/// creates for it; `spawn_addr` publishes the matching `Sender` and hands
+/// back the actor's typed address. That address is usable the instant you
+/// hold it: an immediate [`send_to`](crate::send_to) on the returned pid
+/// always finds the inbox, even if `body` hasn't started running yet.
+///
+/// The spawned actor is detached (there is no [`JoinHandle`] to join): its
+/// lifetime is up to its own logic, for example running until it receives a
+/// stop message, or until the actor decides to return. This mirrors how
+/// [`GenServerBuilder::start`](crate::GenServerBuilder::start) works.
 ///
 /// Panics if called outside `Runtime::run()`.
 pub fn spawn_addr<A: crate::pid::Addressable>(
@@ -237,6 +337,11 @@ pub fn spawn_addr<A: crate::pid::Addressable>(
 
 use crate::context::init_actor_stack;
 
+/// The identity of the actor currently running. Use it to hand your own
+/// address to another actor (for a reply, a monitor, or a link).
+///
+/// Panics if called outside an actor (for example, from the closure passed
+/// to [`run`] itself, before any [`spawn`]).
 pub fn self_pid() -> Pid {
     match current_pid() {
         Some(pid) => pid,
@@ -248,6 +353,12 @@ pub fn self_pid() -> Pid {
 // yield_now / park_current / unpark
 // ---------------------------------------------------------------------------
 
+/// Voluntarily give up the CPU so another runnable actor gets a turn, then
+/// resume as soon as the scheduler gets back around to you. Use this in a
+/// long-running, allocation-free loop that you want to stay cooperative with
+/// the rest of the runtime (see also the [`check!`](crate::check) macro,
+/// which does the same thing conditionally, only when your timeslice has
+/// actually run out).
 pub fn yield_now() {
     runtime::set_yield_intent(YieldIntent::Yield);
     unsafe { crate::context::switch_to_scheduler() };
@@ -255,48 +366,44 @@ pub fn yield_now() {
     crate::preempt::check_cancelled();
 }
 
+// Suspend the current actor until something wakes it (a message arrives, a
+// timer fires, a lock is granted, and so on). This is the low-level parking
+// primitive that every blocking smarm operation (channel recv, sleep,
+// Mutex::lock, IO waits, JoinHandle::join) is built on; application code
+// should reach for one of those rather than calling this directly.
+//
+// Checks for a pending cooperative-stop request both before parking (a stop
+// requested while merely queued to run would otherwise have no future wake
+// to catch it) and after resuming (so a stop that arrived while parked is
+// noticed as soon as we wake, and unwinds from here exactly like any other
+// blocking call would).
 pub fn park_current() {
-    // Entry-side observation point: a stop flagged while we were QUEUED is
-    // otherwise lost — the stop's wildcard unpark no-ops on a Queued actor
-    // (the pending run "is" the wake), so if our first action on resume is
-    // this park, no wake is ever coming and the wake-side check below is
-    // unreachable. Checking here closes that hole; a flag that lands after
-    // this check is covered by the existing protocol (the stop's unpark
-    // finds Running / the prep-to-park window, sets Notified, and the
-    // park-return re-queues us into the wake-side check). Unwinding from
-    // here is the same unwind path as the wake side: leftover wait
-    // registrations are stale-epoch / dead-generation and self-clean at
-    // their wakers' failed CAS.
     crate::preempt::check_cancelled();
     runtime::set_yield_intent(YieldIntent::Park);
     unsafe { crate::context::switch_to_scheduler() };
-    // Observation point on the wakeup side of every blocking primitive
-    // (recv/sleep/mutex/io/join). Past the prep-to-park window, so this never
-    // races a wakeup: a stop unparks us, we resume here, and unwind out of
-    // whatever blocking call parked us — running Drop along the way.
     crate::preempt::check_cancelled();
 }
 
+// Wake `pid` unconditionally, regardless of what it's currently waiting for.
+// Reserved for terminal wakes (`request_stop`); anything waking an actor from
+// a specific registered wait (a channel send, a mutex grant, a timer, an IO
+// completion) must use `unpark_at` instead, so a stale wakeup can never be
+// mistaken for the one the actor is actually waiting on.
 pub fn unpark(pid: Pid) {
-    // The whole protocol lives on the slot's packed word (gen + epoch +
-    // state in one CAS) — see slot_state.rs. No runtime lock unless we
-    // enqueue. WILDCARD form: reserved for terminal wakes (request_stop);
-    // every registration-based waker must use `unpark_at`.
     let _ = try_with_runtime(|inner| inner.unpark(pid));
 }
 
-/// Epoch-matched unpark: wake `pid` only if its current wait is still the
-/// one this waker registered for. The form every registration-based waker
-/// (channel senders, mutex grants, wait-timers, io completions, joiner
-/// wakes) must use — see slot_state.rs for the consuming-wake rules.
+// Wake `pid` only if its current wait is still the one this waker
+// registered for (an "epoch-matched" unpark). Every registration-based
+// waker (channel senders, mutex grants, wait-timers, IO completions, joiner
+// wakes) must use this rather than the unconditional `unpark`.
 pub(crate) fn unpark_at(pid: Pid, epoch: u32) {
     let _ = try_with_runtime(|inner| inner.unpark_at(pid, epoch));
 }
 
-/// Open a new wait for the CURRENT actor: bump its park-epoch and return
-/// it. Call once per wait, before registering `(pid, epoch)` with any
-/// waker. Lock-free (one CAS on the own slot word), so it is legal under
-/// any lock, including a Channel-class lock.
+// Open a new wait for the current actor and return its wait identity
+// ("epoch"). Call once per wait, before registering with any waker. Lock-free,
+// so it's legal to call while already holding another internal lock.
 pub(crate) fn begin_wait() -> u32 {
     let me = match current_pid() {
         Some(pid) => pid,
@@ -305,48 +412,47 @@ pub(crate) fn begin_wait() -> u32 {
     with_runtime(|inner| inner.begin_wait(me))
 }
 
-/// Close the current actor's wait WITHOUT parking on it. For the no-park
-/// exit of multi-registration waits (`select` finding an arm ready at
-/// registration time): bumps the epoch so in-flight wakes die at their CAS,
-/// eats a notification that already landed, then observes a pending stop —
-/// in that order. After this, leftover registrations are stale-epoch and
-/// self-clean at their wakers' failed CAS; nothing can fault the actor's
-/// next one-shot park.
+// Close the current actor's wait without parking on it: the no-park exit
+// used when a multi-arm `select` finds an arm already ready at registration
+// time. Leftover registrations from the other arms are left to self-clean
+// when their wakers try to use them.
 pub(crate) fn retire_wait() {
     let me = match current_pid() {
         Some(pid) => pid,
         None => panic!("retire_wait() called outside an actor"),
     };
     with_runtime(|inner| inner.retire_wait(me));
-    // A request_stop that fired before the clear had its notification
-    // eaten, but it set the stop flag first — observe it here and unwind.
-    // One that fires after re-notifies a Running word as usual.
     crate::preempt::check_cancelled();
 }
 
-/// Request cooperative cancellation of `pid`.
+/// Ask `pid` to stop cooperatively.
 ///
-/// Sets the actor's stop flag and wakes it so it observes the flag promptly:
-/// a parked target is re-queued; a running target is marked notified, so its
-/// next park returns immediately to an observation point. The actor realises
-/// the stop as a controlled unwind at its next observation point
-/// (`check!()`/allocation, or the wakeup side of a blocking park),
-/// terminating with `Outcome::Stopped`.
+/// This sets a flag on the target actor and wakes it so it notices promptly;
+/// the actor itself decides when it's safe to actually unwind, at its next
+/// natural checkpoint (a blocking call returning, a `check!()`, or an
+/// allocation). Once it does, it terminates as if it panicked, except that
+/// [`JoinHandle::join`] reports it as a normal, non-error exit: cooperative
+/// stop is a controlled shutdown, not a failure.
 ///
-/// This is best-effort and cooperative: an actor that never reaches an
-/// observation point — a tight loop with no `check!()`, no allocation, and no
-/// blocking op — cannot be stopped, exactly as it cannot be preempted. A no-op
-/// if `pid` is already gone.
+/// This is exactly the mechanism `gen_server` shutdown, supervisor restarts,
+/// and structured teardown are built from: reach for [`GenServerRef::shutdown`](crate::GenServerRef::shutdown)
+/// or a [`supervisor`](crate::supervisor) instead of calling this directly
+/// where those apply.
+///
+/// Because it's cooperative, an actor stuck in a tight loop with no
+/// blocking call, no [`check!`](crate::check), and no allocation cannot be
+/// stopped, for the same reason it cannot be preempted. Calling this on an
+/// actor that has already finished is a harmless no-op.
 pub fn request_stop<A>(pid: Pid<A>) {
     let pid = pid.erase();
     let _ = try_with_runtime(|inner| request_stop_inner(inner, pid));
 }
 
-/// The core of [`request_stop`], taking the runtime directly so it can be
-/// driven from inside the runtime (e.g. the root-exit sweep in
-/// `finalize_actor`) without re-borrowing the thread-local. Sets the stop flag
-/// under the target's cold lock (generation re-verified there; a mismatch or a
-/// slot with no live actor is a no-op) and wakes it.
+// The core of `request_stop`, taking the runtime directly so it can also be
+// driven from inside the runtime itself (the root-exit sweep) without
+// re-borrowing the thread-local. Sets the stop flag under the target's lock
+// (a generation mismatch, or no live actor there, makes it a no-op) and
+// wakes the target.
 pub(crate) fn request_stop_inner(inner: &RuntimeInner, pid: Pid) {
     if let Some(slot) = inner.slot_at(pid) {
         {
@@ -367,6 +473,10 @@ pub(crate) fn request_stop_inner(inner: &RuntimeInner, pid: Pid) {
 // NoPreempt
 // ---------------------------------------------------------------------------
 
+/// A guard that disables preemption for its lifetime, restoring the
+/// previous setting on drop. Internal-use: application code has no need to
+/// disable preemption directly. See [`check!`](crate::check) for the
+/// user-facing side of preemption.
 pub struct NoPreempt(bool);
 
 impl NoPreempt {
@@ -386,6 +496,21 @@ impl Drop for NoPreempt {
 // sleep / insert_wait_timer
 // ---------------------------------------------------------------------------
 
+/// Suspend the calling actor for `duration`. Unlike
+/// [`std::thread::sleep`], this parks only the actor, not the underlying OS
+/// thread, so every other actor (including others sharing the same OS
+/// thread) keeps running normally while this one waits.
+///
+/// ```
+/// use smarm::{run, sleep};
+/// use std::time::Duration;
+///
+/// run(|| {
+///     sleep(Duration::from_millis(1));
+/// });
+/// ```
+///
+/// Panics if called outside an actor.
 pub fn sleep(duration: std::time::Duration) {
     let me = match current_pid() {
         Some(pid) => pid,
@@ -403,11 +528,11 @@ pub fn sleep(duration: std::time::Duration) {
     park_current();
 }
 
-/// Like [`sleep`], but wall-anchored: under causal profiling (feature
-/// `smarm-causal`) the deadline is honoured in wall time instead of chasing
-/// injected virtual delay. Identical to [`sleep`] without the feature. For
-/// measurement machinery whose durations define wall time (the causal
-/// controller's windows, TSC calibration) — workload code wants [`sleep`].
+/// Like [`sleep`], but the deadline is always measured in real (wall-clock)
+/// time. Ordinary code should use [`sleep`]; this variant exists for smarm's
+/// own profiling and measurement tooling, which can otherwise stretch or
+/// compress simulated time. Without that tooling active, `sleep_wall` and
+/// `sleep` behave identically.
 pub fn sleep_wall(duration: std::time::Duration) {
     let me = match current_pid() {
         Some(pid) => pid,
@@ -425,6 +550,11 @@ pub fn sleep_wall(duration: std::time::Duration) {
     park_current();
 }
 
+// Building block for bounded waits elsewhere in the crate (Mutex::lock_timeout,
+// Receiver::recv_timeout, select_timeout): arm a timer that, on expiry, asks
+// `target` whether this particular wait is still pending and should be woken
+// with a timeout. Not part of the public API; application code wants
+// `sleep`, `send_after`, or one of the `*_timeout` methods instead.
 pub fn insert_wait_timer(
     deadline: std::time::Instant,
     pid: Pid,
@@ -444,20 +574,22 @@ pub fn insert_wait_timer(
 }
 
 // ---------------------------------------------------------------------------
-// send_after / cancel_timer — message-delivery timers (Erlang send_after).
-//
-// Arm a timer that delivers `msg` to an address after `after`, returning a
-// `TimerId`. The destination is resolved *on fire*, not at arm time: a
-// `Pid<A>` that has since died yields `SendError::Dead`, a `Name<M>` resolves
-// to whoever currently holds it (so a restarted server is reached). Either way
-// a failed resolve / closed inbox is dropped, matching `erlang:send_after`.
-// `cancel_timer` prevents an as-yet-unfired delivery; it returns whether the
-// timer was still armed.
+// send_after / cancel_timer: message-delivery timers, in the same spirit as
+// Erlang's `erlang:send_after/3`. Each schedules `msg` for delivery after a
+// delay and returns a TimerId; `cancel_timer` can call one off before it
+// fires. The destination is resolved when the timer actually fires, not when
+// it's armed, so a `Name`-addressed timer always reaches whoever currently
+// holds that name, even if the original holder has since restarted. If the
+// destination is gone by fire time, the message is silently dropped, exactly
+// as a live send to a dead address would be.
 // ---------------------------------------------------------------------------
 
-/// Deliver `msg` to the exact actor named by `dest` (identity-bound, no
-/// redirect — see [`send_to`](crate::registry::send_to)) after `after`.
-/// Returns a [`TimerId`](crate::timer::TimerId) for [`cancel_timer`].
+/// Deliver `msg` to the exact actor identified by `dest` after `after` has
+/// elapsed. Unlike [`send_after_named`], this targets one specific actor: if
+/// that actor is gone by the time the timer fires, the message is dropped
+/// (it is never redirected to a different actor, even one that inherited the
+/// same name). Returns a [`TimerId`](crate::timer::TimerId) you can pass to
+/// [`cancel_timer`] to call it off early.
 pub fn send_after<A: crate::pid::Addressable>(
     after: std::time::Duration,
     dest: Pid<A>,
@@ -475,9 +607,11 @@ pub fn send_after<A: crate::pid::Addressable>(
     })
 }
 
-/// Deliver `msg` to whichever actor holds the name `dest` at fire time
-/// (re-resolving [`send`](crate::registry::send) semantics) after `after`.
-/// Returns a [`TimerId`](crate::timer::TimerId) for [`cancel_timer`].
+/// Deliver `msg` to whichever actor holds the name `dest` when the timer
+/// fires, not necessarily whoever holds it now: if the named actor restarts
+/// (for example under a supervisor) and re-registers before the deadline,
+/// the message reaches the new instance. Returns a
+/// [`TimerId`](crate::timer::TimerId) you can pass to [`cancel_timer`].
 pub fn send_after_named<M: Send + 'static>(
     after: std::time::Duration,
     dest: Name<M>,
@@ -497,13 +631,12 @@ pub fn send_after_named<M: Send + 'static>(
     })
 }
 
-/// Wall-anchored [`send_after`] (RFC 007): under causal profiling the timer
-/// opts out of the virtual-time shift and fires at its raw deadline instead
-/// of dilating with injected delay — the user-facing opt-out whose substrate
-/// [`sleep_wall`] landed. Use it for deadlines that reflect the outside
-/// world (protocol timeouts, wall-clock schedules) rather than workload
-/// pacing. Without the `smarm-causal` feature it is identical to
-/// [`send_after`]. Cancellation via [`cancel_timer`] is unchanged.
+/// Like [`send_after`], but the deadline is always measured in real
+/// (wall-clock) time rather than being subject to smarm's own profiling and
+/// measurement tooling. Use this for deadlines that need to reflect the
+/// outside world (a protocol timeout, a wall-clock schedule) rather than
+/// simulated workload pacing. Without that tooling active, it behaves
+/// identically to [`send_after`].
 pub fn send_after_wall<A: crate::pid::Addressable>(
     after: std::time::Duration,
     dest: Pid<A>,
@@ -521,8 +654,8 @@ pub fn send_after_wall<A: crate::pid::Addressable>(
     })
 }
 
-/// Wall-anchored [`send_after_named`] (RFC 007): re-resolving name delivery,
-/// raw-deadline anchor — see [`send_after_wall`] for the semantics.
+/// Wall-clock-anchored [`send_after_named`]: re-resolving name delivery,
+/// with the same real-time deadline guarantee as [`send_after_wall`].
 pub fn send_after_named_wall<M: Send + 'static>(
     after: std::time::Duration,
     dest: Name<M>,
@@ -542,17 +675,12 @@ pub fn send_after_named_wall<M: Send + 'static>(
     })
 }
 
-/// Deliver `msg` onto a channel the caller owns after `after`, rather than to a
-/// registry address. The sibling of [`send_after`] used by the gen_server timer
-/// layer (RFC 015 §5): arming a server timer must land the fire on the loop's
-/// own `Sys` channel — giving it the loop's arm position — not in the inbox.
-///
-/// Same substrate as [`send_after`]: a `Reason::Send` entry, the same `armed`
-/// set, the same [`TimerId`](crate::timer::TimerId) for [`cancel_timer`]. Only
-/// the fire thunk differs — `tx.send(msg)` instead of a registry resolve — so a
-/// send onto a channel whose receiver is gone is dropped, exactly as a failed
-/// address resolve is (Erlang `send_after` semantics). `pid` is informational
-/// (who armed it); delivery lives entirely in the thunk.
+// Deliver `msg` onto a channel the caller already holds, after a delay,
+// rather than resolving a registry address at fire time. Used internally by
+// gen_server's timer support, which needs the fire to land on the server
+// loop's own dedicated channel instead of its public inbox. Otherwise
+// identical to `send_after`: same cancellation via `cancel_timer`, and a
+// send to a channel whose receiver is gone is silently dropped.
 pub(crate) fn send_after_to<T: Send + 'static>(
     after: std::time::Duration,
     tx: Sender<T>,
@@ -571,9 +699,9 @@ pub(crate) fn send_after_to<T: Send + 'static>(
     })
 }
 
-/// Cancel a timer armed by [`send_after`] / [`send_after_named`]. Returns
-/// `true` if it was still pending (delivery now prevented), `false` if it had
-/// already fired or been cancelled.
+/// Call off a timer armed by [`send_after`] or [`send_after_named`] before
+/// it fires. Returns `true` if the timer was still pending and delivery is
+/// now prevented, `false` if it had already fired or was already cancelled.
 pub fn cancel_timer(id: crate::timer::TimerId) -> bool {
     with_runtime(|inner| {
         match inner.timers.lock() {
@@ -587,6 +715,22 @@ pub fn cancel_timer(id: crate::timer::TimerId) -> bool {
 // block_on_io / wait_readable / wait_writable / read / write
 // ---------------------------------------------------------------------------
 
+/// Run a blocking closure (blocking file IO, a synchronous library call,
+/// anything that isn't itself actor-aware) on a dedicated worker thread,
+/// while the calling actor parks and every other actor keeps making
+/// progress. When `f` completes, the calling actor resumes with its result.
+///
+/// Reach for this whenever you need to call into something that would
+/// otherwise block the underlying OS thread outright: a blocking C library,
+/// a synchronous filesystem call, DNS resolution via the system resolver,
+/// and so on. For plain readiness-based network IO on a file descriptor,
+/// [`wait_readable`] / [`wait_writable`] are cheaper since they don't need a
+/// dedicated thread.
+///
+/// If `f` panics, that panic is carried over and re-raised in the calling
+/// actor, exactly as if the call had been made inline.
+///
+/// Panics if called outside an actor.
 pub fn block_on_io<F, T>(f: F) -> T
 where
     F: FnOnce() -> T + Send + 'static,
@@ -639,10 +783,19 @@ where
     }
 }
 
+/// Park the calling actor until `fd` becomes readable. Other actors keep
+/// running while you wait; when the kernel reports the fd ready, the actor
+/// resumes and you perform the actual `read(2)` yourself (see [`read`] for
+/// a convenience wrapper that does both steps).
+///
+/// Only one actor may wait on a given fd for a given direction at a time.
+/// Panics if called outside an actor.
 pub fn wait_readable(fd: std::os::fd::RawFd) -> std::io::Result<()> {
     wait_fd(fd, true, false)
 }
 
+/// Park the calling actor until `fd` becomes writable. See [`wait_readable`]
+/// for the read-side counterpart; the same notes apply.
 pub fn wait_writable(fd: std::os::fd::RawFd) -> std::io::Result<()> {
     wait_fd(fd, false, true)
 }
@@ -666,12 +819,12 @@ fn wait_fd(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::R
     })?;
 
     // If a terminal stop unwinds us out of the park below, the registration
-    // must not outlive us: a stale `waiters` entry fails every future
-    // `wait_*` on this fd with AlreadyExists, and the kernel-side ADD leaks
-    // until the fd happens to be reused. Clean up iff the entry is still
-    // ours — a `FdReady` racing the stop may have consumed it already (it
-    // removes + DELs under the io lock), after which the fd may even carry
-    // ANOTHER actor's fresh registration; in that case touch nothing.
+    // must not outlive us: a stale registration would fail every future
+    // `wait_*` on this fd, and the kernel-side registration would leak until
+    // the fd happens to be reused. Clean up only if the entry is still
+    // ours; a wakeup racing the stop may have already consumed it, possibly
+    // leaving a different actor's fresh registration in its place, which
+    // must not be disturbed.
     struct Dereg {
         fd: std::os::fd::RawFd,
         me: Pid,
@@ -695,24 +848,28 @@ fn wait_fd(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::R
     }
     let guard = Dereg { fd, me, epoch };
     park_current();
-    // Normal wake: the FdReady path removed the entry and DEL'd the fd
-    // before the unpark, so the guard's check would be a guaranteed no-op —
-    // skip the io lock on the hot path. (Dereg owns nothing; forget leaks
-    // no resource.)
+    // Normal wake: the ready-fd path already removed the entry and
+    // deregistered from epoll before waking us, so the guard's check on drop
+    // is a guaranteed no-op. Skip it on this hot path (Dereg owns no
+    // resource itself, so forgetting it leaks nothing).
     std::mem::forget(guard);
     Ok(())
 }
 
 // ---------------------------------------------------------------------------
-// FdArm — fd readiness as a select arm (RFC 008)
+// FdArm: fd readiness as a select arm
 // ---------------------------------------------------------------------------
 
-/// An fd-readiness arm for [`crate::select`] / [`crate::select_timeout`]:
-/// ready when the fd is readable (resp. writable), composable with channel
-/// receivers on one wait epoch. Phase-1 rules apply: one waiter per fd at a
-/// time, one direction per arm (duplex on a single fd needs `dup`; epoll
-/// registrations key on the open file description, so dup'd fds register
-/// independently).
+/// A file-descriptor readiness condition usable as an arm of
+/// [`select`](crate::select) / [`select_timeout`](crate::select_timeout),
+/// so you can wait on "this fd is readable" alongside ordinary channel
+/// receivers in the same call. Build one with [`FdArm::readable`] or
+/// [`FdArm::writable`].
+///
+/// Only one actor may wait on a given fd for a given direction at a time. A
+/// single fd open in both directions needs two `FdArm`s (or `dup` the fd) if
+/// you want to wait on both; you cannot wait on read and write readiness
+/// with one arm.
 pub struct FdArm {
     fd: std::os::fd::RawFd,
     readable: bool,
@@ -720,10 +877,12 @@ pub struct FdArm {
 }
 
 impl FdArm {
+    /// An arm that becomes ready when `fd` is readable.
     pub fn readable(fd: std::os::fd::RawFd) -> Self {
         FdArm { fd, readable: true, writable: false }
     }
 
+    /// An arm that becomes ready when `fd` is writable.
     pub fn writable(fd: std::os::fd::RawFd) -> Self {
         FdArm { fd, readable: false, writable: true }
     }
@@ -732,14 +891,12 @@ impl FdArm {
 impl crate::channel::sealed::Sealed for FdArm {}
 
 impl crate::channel::Selectable for FdArm {
-    /// Ready-now check is a zero-timeout `poll(2)`; if the requested events
-    /// are pending the wait is retired without registering (`Ok(false)`,
-    /// the channel-arm contract). Otherwise register with the io thread —
-    /// every failure surfaces as `Err` (EBADF including a closed-fd
-    /// POLLNVAL, EMFILE on the epoll set, AlreadyExists for a second
-    /// waiter on the fd): the fallible-out, nothing-left-behind rule, in
-    /// deviation from RFC 008's permanently-ready lean, which would spin a
-    /// consumer whose fd is healthy but unregistrable (EMFILE).
+    // Ready-now check is a zero-timeout poll(2); if the requested events are
+    // already pending, the wait is retired without registering. Otherwise
+    // register with the IO thread. Any registration failure (a closed fd,
+    // too many fds registered, a second waiter already on this fd) is
+    // surfaced as an error rather than silently treated as "always ready",
+    // so a caller never spins on an fd that genuinely can't be registered.
     fn sel_register(&self, pid: Pid, epoch: u32) -> std::io::Result<bool> {
         if poll_events(self.fd, self.readable, self.writable)? {
             return Ok(false);
@@ -759,20 +916,19 @@ impl crate::channel::Selectable for FdArm {
         Ok(true)
     }
 
-    /// Classification is the same zero-timeout poll: a pure function of fd
-    /// state, independent of the registration the cleanup pass removed. An
-    /// error here (EBADF: fd closed mid-wait) reports READY — the
-    /// consumer's read/write surfaces the errno; a dead arm is an event,
-    /// not a hang.
+    // Same zero-timeout poll used for classification: a pure function of
+    // fd state. An error here (fd closed mid-wait) is reported as ready
+    // rather than pending forever: the caller's own read/write then
+    // surfaces the real error, so a dead fd is an observable event, not a
+    // silent hang.
     fn sel_ready(&self) -> bool {
         poll_events(self.fd, self.readable, self.writable).unwrap_or(true)
     }
 
-    /// `wait_fd`'s `Dereg` compare, verbatim: remove the waiters entry and
-    /// kernel-side registration iff the entry is still `(pid, epoch)`-ours.
-    /// A `FdReady` racing the wake may have consumed it (it removes + DELs
-    /// under the io lock), after which the fd may even carry ANOTHER
-    /// actor's fresh registration; in that case touch nothing.
+    // Mirrors wait_fd's cleanup guard: remove the registration only if it's
+    // still ours. A wakeup racing this cleanup may have already consumed
+    // it, possibly leaving a different actor's fresh registration on the
+    // same fd, which must not be touched.
     fn sel_unregister(&self, pid: Pid, epoch: u32) {
         with_runtime(|inner| {
             let mut io = match inner.io.lock() {
@@ -793,9 +949,9 @@ impl crate::channel::Selectable for FdArm {
     }
 }
 
-/// Zero-timeout `poll(2)`: are any of the requested events (or ERR/HUP,
-/// which make the consumer's read/write fail loudly rather than park
-/// forever) pending on `fd`? POLLNVAL maps to `Err(EBADF)`.
+// Zero-timeout poll(2): are any of the requested events (or an error/hangup
+// condition, so the caller's read/write fails loudly instead of parking
+// forever) pending on `fd` right now?
 fn poll_events(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::Result<bool> {
     let mut events: libc::c_short = 0;
     if readable {
@@ -824,8 +980,9 @@ fn poll_events(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::i
     }
 }
 
-/// Wait until `fd` is readable or `timeout` elapses: `Ok(true)` = ready,
-/// `Ok(false)` = timed out. A one-arm [`crate::try_select_timeout`].
+/// Like [`wait_readable`], but gives up after `timeout` instead of waiting
+/// indefinitely: `Ok(true)` means the fd became ready, `Ok(false)` means the
+/// timeout elapsed first.
 pub fn wait_readable_timeout(
     fd: std::os::fd::RawFd,
     timeout: std::time::Duration,
@@ -834,8 +991,9 @@ pub fn wait_readable_timeout(
     Ok(crate::channel::try_select_timeout(&[&arm], timeout)?.is_some())
 }
 
-/// Wait until `fd` is writable or `timeout` elapses: `Ok(true)` = ready,
-/// `Ok(false)` = timed out.
+/// Like [`wait_writable`], but gives up after `timeout` instead of waiting
+/// indefinitely: `Ok(true)` means the fd became ready, `Ok(false)` means the
+/// timeout elapsed first.
 pub fn wait_writable_timeout(
     fd: std::os::fd::RawFd,
     timeout: std::time::Duration,
@@ -844,12 +1002,18 @@ pub fn wait_writable_timeout(
     Ok(crate::channel::try_select_timeout(&[&arm], timeout)?.is_some())
 }
 
+/// Convenience wrapper: park until `fd` is readable, then perform the
+/// `read(2)` into `buf`. Equivalent to calling [`wait_readable`] yourself
+/// followed by a raw read, provided as a shorthand for the common case.
 pub fn read(fd: std::os::fd::RawFd, buf: &mut [u8]) -> std::io::Result<usize> {
     wait_readable(fd)?;
     let n = unsafe { libc::read(fd, buf.as_mut_ptr() as *mut _, buf.len()) };
     if n < 0 { Err(std::io::Error::last_os_error()) } else { Ok(n as usize) }
 }
 
+/// Convenience wrapper: park until `fd` is writable, then perform the
+/// `write(2)` of `buf`. Equivalent to calling [`wait_writable`] yourself
+/// followed by a raw write, provided as a shorthand for the common case.
 pub fn write(fd: std::os::fd::RawFd, buf: &[u8]) -> std::io::Result<usize> {
     wait_writable(fd)?;
     let n = unsafe { libc::write(fd, buf.as_ptr() as *const _, buf.len()) };
@@ -857,7 +1021,7 @@ pub fn write(fd: std::os::fd::RawFd, buf: &[u8]) -> std::io::Result<usize> {
 }
 
 // ---------------------------------------------------------------------------
-// register_supervisor_channel
+// register_supervisor_channel: internal wiring used by supervisor.rs
 // ---------------------------------------------------------------------------
 
 pub fn register_supervisor_channel(pid: Pid, sender: Sender<Signal>) {
@@ -874,11 +1038,21 @@ pub fn register_supervisor_channel(pid: Pid, sender: Sender<Signal>) {
 }
 
 // ---------------------------------------------------------------------------
-// Legacy run() — convenience wrapper
+// run(): the single-threaded convenience entry point
 // ---------------------------------------------------------------------------
 
-/// Single-threaded runtime entry point (backwards-compatible wrapper).
-/// Equivalent to `runtime::init(Config::exact(1)).run(f)`.
+/// Start the smarm runtime on a single OS thread, run `f` as the first
+/// (root) actor, and block until every actor it transitively spawned has
+/// finished.
+///
+/// This is the simplest way to get started, and is all you need for most
+/// programs: `f` typically calls [`spawn`] to create more actors and waits
+/// on their [`JoinHandle`]s. If you want smarm to schedule actors across
+/// multiple OS threads instead, use
+/// [`crate::runtime::init`] with a
+/// [`Config`](crate::runtime::Config) that requests more than one scheduler
+/// thread, then call [`Runtime::run`](crate::runtime::Runtime::run) on it;
+/// `run` here is exactly that, pinned to one thread.
 pub fn run<F: FnOnce() + Send + 'static>(f: F) {
     crate::runtime::init(crate::runtime::Config::exact(1)).run(f);
 }