---
name: brain-resume-test-rig
description: How to write deterministic (non-flaky) spt-daemon brain/broker resume tests in the in-proc rig — the fire-and-forget subscribe barrier + viewer-count seam
metadata:
  type: project
---

Deterministic-barrier pattern for spt-daemon brain/broker resume tests (in-proc rig:
`Broker::bind` + `Arc::clone` + serve thread; helpers `init_home`/`unique_name`/`spawn_flood`
in `crates/spt-daemon/tests/brain_resume_conn_deadlock.rs`).

**Why:** timing-based negative-space guards here are flaky. The round-3 flood-starvation
guard (`nondraining_subscriber_starves_under_flood_regression_guard`) went stale after the
r4 Option-C fix bounded every physical-conn write (BrokerConn watchdog retires a blocked
write at `brain_write_deadline()`), so a non-draining subscriber no longer starves the
heartbeat to ~0 — it failed REAL on kitsubito Linux CI ("worst completed 10"). doyle ruled
2026-07-10 (docs/UPDATE-WEDGE-R4-STALE-GUARD-RULING.md) to replace it with a deterministic
structural guard. Prefer structural/zero-window proofs over best-of-K timing bars.

**How to apply — two load-bearing facts (verify they still hold before relying on them):**
1. `Brain::subscribe_with` / `resume_sessions` is FIRE-AND-FORGET — it writes KIND_SUBSCRIBE
   and does NOT await KIND_SUBSCRIBED. So the viewer is NOT registered when `resume_sessions`
   returns (its internal `sessions()` round-trip runs BEFORE the subscribes are sent). A bare
   "assert viewer count" immediately after races and reads 0.
2. To force a happens-before: issue ONE more same-conn round-trip (`brain.sessions()` /
   `net_status()`). The broker dispatches a conn's frames strictly IN ORDER and `add_viewer`
   inserts synchronously as it dispatches each KIND_SUBSCRIBE, so all subscribes are applied
   before that reply. The reply-read loop (`_ => continue`) also DRAINS interleaved replay
   frames, so no viewer writer blocks/evicts — no deadlock, no r4 retirement race at small N.

Seam for observing broker-side viewer state: `Broker::test_session_viewer_count(id) ->
Option<usize>` (pub `#[doc(hidden)]`, added 2026-07-10, same locking idiom as
`test_seed_wedged_local_controller`). Pair a "cursor-only resume => 0 viewers" positive
assertion with a "second brain resume_sessions => >=1 viewer" seam-sensitivity arm so the
zero-proof can't pass vacuously against an always-0 seam. See
`daemon_resume_leaves_zero_brain_subscribers`.