smarm/TODO_HANDOFF.md

urus / smarm handoff — updated 2026-08-19 (session 3)

TL;DR for the next session

smarm is done for now (5 unpushed commits on local master, see below). Next = urus v0.3 endpoint refactor. You should NOT need to read smarm scheduler internals; the contract you build on is fully described here and in smarm_full/examples/graceful_shutdown.rs (read that file first — it is the exact shape urus's tree will take) plus smarm_full/tests/root_exit.rs.

The smarm contract urus builds on (all on local master, verified by tests)

• request_stop(pid) = kill (cooperative hard stop). request_shutdown(pid) = polite: trapping target gets ExitSignal{reason: Shutdown}, non-trapping is stopped outright. RuntimeHandle::{request_stop,request_shutdown} do the same from any OS thread (signal handler); grab rt.handle() before rt.run.
• Supervisor traps; request_shutdown(sup) = ordered reverse-start shutdown, per-child ChildSpec::shutdown(Shutdown::{Timeout(d)|Infinity|BrutalKill}) (default Timeout(5s)); sup then returns normally. request_stop(sup) hard-stops children too (no orphans).
• gen_server: ctx.trap_exit() in init; handle_shutdown() -> Exit|Continue; handle_exit(sig); ctx.stop_handle().stop() = normal self-exit; terminate() may block only on the graceful path (Exit / stop / inbox close). GenServerRef::shutdown() is graceful and waits.
• gen_statem: same in event clothes — cx.trap_exit() in initial enter, shutdown rows (default stop), exit sig rows, cx.stop() / stop tail, optional terminate { } block. GenStatemRef::shutdown().
• Root exit = program done: when the root actor returns, the runtime request_shutdowns every forest root (live actor whose parent is the run or dead). Supervisors cascade; trapping actors may drain (timers keep working) and end the run when they stop; non-trapping are stopped; no forcing sweep (join what must finish). The old "wait until nothing runnable then kill all" deferral is gone.
• Gotcha for urus: a gen_server's lifetime is governed by its refs — drop the last GenServerRef and the inbox closes → clean exit even mid-drain. The endpoint must be pinned (named, or its ref held by the supervisor wrapper) or it will terminate the moment the root drops its ref.
• Known gap (ROADMAP open item): a gen_server can't be a direct ChildSpec child; use the trapping wrapper pattern in examples/graceful_shutdown.rs:: drainer_child (starts under(self_pid()), forwards shutdown, waits). Doing an inline GenServerBuilder::run() first may be worth a short smarm detour — decide with Markk.

smarm commits this session (local master, NOT pushed, NOT tagged)

250f312 root-exit = graceful shutdown of forest roots (tests/root_exit.rs) 6ceb138 gen_statem shutdown parity (tests/gen_statem_shutdown.rs) 849a424 docs + examples/graceful_shutdown.rs + README "Stopping actors" On top of 1002777 (cross-thread wake) and 9c8f59c (graceful shutdown). Cargo.toml still 0.6.1. Release cut (push, tag — v0.7 is justified by the API surface — version bump) is Markk's. Full suite, doc tests, examples, cargo fmt, cargo clippy --lib all clean. (clippy --tests has pre-existing unwrap lints in tests/fd_select.rs, untouched.)

Decisions taken this session (Markk)

• Root exit means "program done" (Go/tokio/OTP), not "wait for pending work"; the previously agreed "sleep(50ms) must finish" test was dropped as encoding the wrong contract (a timer-wheel gate would re-wedge periodic-timer daemons).
• No behaviour-preserving deferral, no forcing second sweep.
• Examples/docs done in the same session; urus next session.

---

Previous handoff (still accurate where not superseded above)

Next-session goal

Phase 1 is done and committed; Phase 2 is next:

1. smarm v0.6.2 — cross-thread wake root fix. DONE, committed on master as 1002777. Not yet tagged, not yet version-bumped (Cargo.toml still reads 0.6.1), and not yet pushed to origin — it exists only in the delivered snapshot zip and the local sandbox clone. Cutting the release (push + tag v0.6.2 + bump 0.6.1→0.6.2) is Markk's step.
2. urus v0.3 — endpoint refactor. Working against smarm = { path = "../smarm_full" } with git update-index --skip-worktree Cargo.toml (Markk approved); release commit swaps back to the tag once Markk cuts it. Phase 2 plan below is STALE where it says drain-in-terminate; the endpoint is a trapping GenServer: handle_shutdown → Continue, enter Draining, StopHandle::stop() when the conn set empties.

Decisions below are locked unless marked (confirm).

Reconstruction (the sandbox resets between sessions)

A fresh sandbox has an empty home and no Rust toolchain. To restore:

• Install rustup/cargo. smarm reformats under rustc 1.97.1; urus rust-version is 1.95. Use 1.97.1.
• urus: git clone https://git.kalsbeek.dev/Markk116/urus — origin is registered and public-read. master 8bdec97 = the v0.2.x line. (Zips in outputs are stale; prefer the remote now.)
• smarm: git clone https://git.kalsbeek.dev/Markk116/smarm. Latest tag v0.6.1 (ca1c983). The cross-thread wake fix is committed as 1002777 on top of the post-v0.6.1 README commit 8f2d513 (= origin/master). It is NOT on origin yet — a fresh clone won't have it until Markk pushes. Restore it from the snapshot zip if working before the push. v0.6.2 is not yet tagged.
• urus pins smarm by git tag in Cargo.toml (currently v0.6.0). A trivial first commit bumps it to v0.6.1 (also picks up try_spawn + monitor terminal-outcome fixes).

Why (context — the finding that drives the plan)

urus's shutdown machinery (the AtomicBool listener flag + the SHUTDOWN_POLL loop in serve.rs) is scaffolding around two smarm properties. Their statuses differ, which is the whole point:

• Issue A — lossy stop vs a QUEUED actor: ALREADY FIXED in smarm. Commit 7bab4d2 added an entry-side check_cancelled() in park_current. A request_stop against a listener parked in wait_readable_timeout now unwinds cleanly (it parks via try_select_timeout → park_current). urus's flag + its stale "smarm's lossy stop-while-QUEUED window" comment can be deleted.
• Issue B — foreign-thread wake is a no-op: FIXED in 1002777 (was present through v0.6.1). The gap: unpark/unpark_at/request_stop all route through try_with_runtime, which reads a thread-local that is None on any non-scheduler thread, so no cross-thread wake worked — a signal handler / OS thread could not wake or stop a parked actor, which is why serve.rs polls the shutdown signal instead of parking on it. Now closed (see Phase 1 below): urus's SHUTDOWN_POLL loop can be deleted and its Handle::shutdown can park on a handle-driven stop.

Phase 1 — smarm cross-thread wake (root fix) — DONE (1002777)

Shipped as one commit generalizing RFC 018 (a producer reaches the runtime through a Weak it holds) from the IO backend to channel senders and a new handle:

• Runtime::handle() -> RuntimeHandle (Send + Sync), holding a Weak<RuntimeInner>. Grab it before rt.run and hand it to the signal thread.
• RuntimeHandle::request_stop<A>(Pid<A>) — upgrades the Weak and calls request_stop_inner on the inner; no-op if the runtime is gone. This is the signal-handler-drives-shutdown path; it cascades the ordered stop down the tree exactly like an in-runtime request_stop.
• Send-wake: the receiver captures scheduler::runtime_weak() into its parked_receiver tuple at park time (not at channel creation — the resolved sub-decision; a parked receiver is a live actor so the Weak is provably upgradable, and it scopes the capture to when a wake is possible). send() and last-sender drop wake via scheduler::unpark_at_via(pid, epoch, &weak): thread-local path when on a scheduler thread (preempt-gated, slot-eligible), captured Weak otherwise. In-runtime timer wakes (recv/select) were left on scheduler::unpark_at.

API scope decision (signed off): RuntimeHandle exposes request_stop only. No public unpark/unpark_at on the handle — send-wake needs no user-facing handle, and "unpark off-runtime" is covered because request_stop drives unpark on the upgraded inner. No is_alive(). Both are one-line additions if a consumer appears.

No RFC written — pattern was already established (RFC 018), agreed not needed.

Tests: tests/cross_thread_wake.rs (foreign-thread send wakes a parked receiver; foreign-thread request_stop wakes+stops a parked actor; a lingering handle never blocks all-done and degrades to a no-op once the runtime drops). Full suite green; cargo fmt + cargo clippy --lib clean.

Remaining release step (Markk): push master, tag v0.6.2, bump Cargo.toml 0.6.1→0.6.2. Left paired with the tag as the release cut, not done in 1002777.

Phase 1b — smarm graceful shutdown (OTP lift) — DONE (9c8f59c, on top of 1002777)

Decided this session (Markk): B — fix at the smarm level rather than a two-stop split in urus. No RFC (Markk: "just implement it"). Shipped, tested, committed on the local master, not pushed, not tagged. It should ship as the same release as 1002777 (v0.6.2, or v0.7 given the API surface — Markk's call).

• request_shutdown(pid) / RuntimeHandle::request_shutdown = exit(Pid, shutdown); request_stop = exit(Pid, kill). Trapping target gets ExitSignal{reason: DownReason::Shutdown}; non-trapping is stopped outright.
• ChildSpec::shutdown(Shutdown::{BrutalKill, Timeout(d), Infinity}), default 5s. Supervisor traps exits; request_shutdown(sup) = ordered top-down shutdown, returns normally. Also fixed: request_stop(sup) used to ORPHAN children (probe-verified; the handoff's "cascade" claim was wrong) — Live drop guard now hard-stops them.
• gen_server: ctx.trap_exit(), handle_shutdown() -> ShutdownAction::{Exit, Continue}, handle_exit(ExitSignal), ctx.stop_handle().stop() = normal self-exit ({stop, normal}; previously impossible — only abnormal Stopped). GenServerRef::shutdown() is graceful now.
• Root finding that forced this: gen_server terminate() runs from a Drop guard, mid-unwind on the stop path; any park in it = double panic = abort. So "drain-in-terminate()" (the old Phase 2 plan) was never viable.

Next-session smarm work DONE this session (see TL;DR)

1. Root-exit sweep: make Pop::RootDrain also require an empty timer wheel (and it already requires nothing runnable; io_out is only checked for AllDone — check whether it should gate RootDrain too). TDD: an actor in sleep(50ms) when the root returns must finish, not be swept. Then a Reservoir-style test that a truly parked-forever daemon still gets swept.
2. gen_statem parity: ctx.trap_exit(), handle_shutdown -> ShutdownAction, handle_exit, stop handle. Mirror gen_server; mechanical.
3. Examples review: examples/*.rs predate all of this. Rework where they show shutdown/teardown to use request_shutdown, Shutdown policies, and StopHandle; named_genserver.rs first (uses shutdown). Also docs/smarm - Deep Dive.html says terminate() must be non-blocking — now only true on the unwind paths; and README could use a "Stopping actors" paragraph (request_stop = kill, request_shutdown = shutdown, Shutdown policy).

Open smarm items found on the way (noted, not scheduled)

• (root-exit sweep and gen_statem parity moved up to the scheduled list.)
• Sweep in the supervisor Live drop guard is request_stop (kill propagates as kill); OTP would deliver a trappable killed. Chosen for boundedness.

Phase 2 — urus v0.3: endpoint refactor (after v0.6.2 is tagged)

Target = the spec's original shape (urus-spec.md §2.1/§6: listener_sup under the user's root supervisor). Deviation to unwind: serve owning rt.run.

• App owns the runtime: smarm::init(cfg).run(|| root_sup.run()), root e.g. RestForOne[ app actors…, urus::endpoint(config, pipeline) ]. This is what kills the Arc<OnceLock> idiom for the right reason (app state born in-runtime as a supervised, ordered child).
• urus::endpoint = one GenServer child owning the registry + an internal listener sub-supervisor + drain-in-terminate(). Listeners stay internal, not app-visible peers.
• Shutdown = request_stop the root supervisor (or via the runtime handle from a signal thread) → cascades down → endpoint.terminate() runs the drain (drain_timeout, force-stop sweep).
• DELETE: the AtomicBool listener flag (A fixed) and the SHUTDOWN_POLL loop
  • its apologetic comment (B fixed → park, don't poll).
• Nuance: request_stop → Signal::Stopped is abnormal → Transient restarts. Stop-without-restart = stop the supervisor, not the children.
• (confirm) Keep serve/serve_with/serve_with_shutdown as thin wrappers that build the one-child tree internally, so the simple case stays one line.
• (confirm) Keep Handle/ShutdownSignal? Now that cross-thread wake works, Handle::shutdown can map to handle-driven request_stop on the endpoint.
• Breaking → cut urus v0.3; bump the smarm pin to v0.6.2 here.

Working norms

• Every bash call: export PATH=$HOME/.cargo/bin:$PATH (once the toolchain's in).
• TDD: failing test first, then implement; keep suites green.
• Hammer ritual for ANY connection-lifecycle change (the urus #2 shutdown work qualifies): 35× subset (shutdown timeout reaped slowloris streaming chunked sse stalled ws_ channels session) + 3× full + 1× trace. scripts/hammer.sh does NOT pass feature flags — loop manually with --features phoenix. Subset filter must NOT use --test integration (session tests live in lib).
• Example smoke tests: hold the server's stdin open (mkfifo + sleep > fifo) or the Enter-to-shutdown thread fires on EOF instantly.
• Background procs are reaped BETWEEN bash calls; pkill -f matches your own shell.
• Artefact store (specs): curl -H "Authorization: Bearer sk-llmingest-2e45d80c63db24c6781e761eb2a9a58e83d9f48ef77a42185bad311d07c80e68" https://artefacts.kalsbeek.dev/artifacts/<name> — urus-spec.md, urus-bench-spec.md, rfc_008-implementation-notes.md, …
• smarm feature flags: smarm-trace, smarm-causal (urus re-exports both).

Local cross-repo testing — KEEP OUT OF COMMITS

To test urus #2 against un-tagged smarm 0.6.2, point urus's Cargo.toml smarm dep at a local path (smarm = { path = "../smarm" }) instead of the git tag.

• Must NOT land in commits. Guard: git update-index --skip-worktree Cargo.toml after editing (undo with --no-skip-worktree), or stash before committing.
• The committed Cargo.toml stays pinned to the git tag; restore the tag (bumped to v0.6.2) for the release commit.