From 3ec918617cb1161a37947e470d6b3eb9689f8777 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:36:55 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m1/explicit-state/rule.md Quest-Claim: 5305e38ce8518963 From 69a740b09fb0387be08fe63e8e35cd39285648bb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:37:38 -0800 Subject: [PATCH 2/2] review: flag implicit lifecycle state REVIEW.md gains a State check (one enum per lifecycle, terminal after the fallible work, one lock per value) and AGENTS.md one line pointing at it. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 1 + REVIEW.md | 11 +++++++++++ quest/m1/explicit-state/README.md | 5 ++--- quest/m1/explicit-state/rule.md | 31 ------------------------------- 4 files changed, 14 insertions(+), 34 deletions(-) delete mode 100644 quest/m1/explicit-state/rule.md diff --git a/AGENTS.md b/AGENTS.md index 7cf56fea2e1..efd48bea846 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ Trust this checkout's source over published API references, which may describe a - Impair networks with bufferbloat, queuing until packets drop, instead of random loss. - Anything that fans out gets a benchmark swept over both axes. +- Model a lifecycle as one enum or union whose variants carry their data, mark it terminal only after the work that can fail, and guard each value with one lock (see State in `REVIEW.md`). # Public API diff --git a/REVIEW.md b/REVIEW.md index 5673fe1078d..248edb5340c 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -27,6 +27,17 @@ Assume a better approach exists until you have tried to find one: An approach finding names the alternative and why it holds up better long-term. "Rework or abandon this PR" is a valid finding when the case is strong. +# State + +Lifecycles (a session, a subscription, a producer, a codec drain) are where bugs hide as combinations no phase allows. +Flag new or changed code that breaks one of these, and point at the shape to copy: + +- **One enum per lifecycle**: phases are one enum or union whose variants carry their data, like `PresentState` in `rs/moq-net/src/lite/session.rs` and `State` in `js/net/src/ietf/join.ts`. Flag a flag, `Option`, or error kept beside an enum; a terminal state stored in two places; per-phase data reached through `.expect()` or call order; and a one-shot handle in an `Option` taken before validation, so "answered" and "failed to answer" look alike. +- **Terminal after the work**: a transition to finished, closed, or answered happens after the work that can fail, or records the failure as its terminal state. A consuming method like `finish(self)` in `rs/moq-rtmp/src/server.rs` leaves nothing to use after. Flag "done" set before a fallible flush or write. +- **One lock per value**: a value is never guarded by two locks or split across atomics. Use one lock, or one atomic holding the whole state, like `CompletionState` in `rs/moq-gst/src/sink/session.rs`. + +The fix makes the bad combination unrepresentable; a check that rejects it is not one. + # Tests Unit tests mock time instead of depending on the real clock: a test that sleeps to let work settle, waits out a timeout to prove nothing happened, or asserts that an operation finished within a real-time budget passes on a quiet machine and flakes under load. diff --git a/quest/m1/explicit-state/README.md b/quest/m1/explicit-state/README.md index 2850e41ae87..58b23f68f27 100644 --- a/quest/m1/explicit-state/README.md +++ b/quest/m1/explicit-state/README.md @@ -45,8 +45,8 @@ Decided 2026-11-07 (maintainer): chosen: m3 after the cut, or small fixes in m1 with the redesigns in m3. This replaces the earlier split from the same session (user-visible fixes in m1, internal ones in m3). -- ✅ Guard against new instances in both REVIEW.md and AGENTS.md (see - [Review and agent rule](/quest/m1/explicit-state/rule.md)). Not chosen: +- ✅ Guard against new instances in both REVIEW.md and AGENTS.md (done: + REVIEW.md's State check and its AGENTS.md line). Not chosen: REVIEW.md only, or no rule change. - ✅ `quic::driver::Endpoint::rebind` becomes crate-private, since only tests call it (see [Transport close](/quest/m1/explicit-state/transport-close.md)). @@ -68,7 +68,6 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md). ## Required -- [Review and agent rule](/quest/m1/explicit-state/rule.md) - REVIEW.md and AGENTS.md ask for one enum per lifecycle, terminal transitions after fallible work, and one lock per value - [moq-boy pause state](/quest/m1/explicit-state/boy-pause.md) - a new viewer always wakes a paused emulator - [Transport close](/quest/m1/explicit-state/transport-close.md) - connection status ends with its error, and every Rust QUIC backend agrees when a connection is closed - [Video codec drains](/quest/m1/explicit-state/video-drain.md) - a hardware codec whose drain fails is ready for input again or terminally failed, never left stuck diff --git a/quest/m1/explicit-state/rule.md b/quest/m1/explicit-state/rule.md deleted file mode 100644 index 2385d618dd9..00000000000 --- a/quest/m1/explicit-state/rule.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Review and agent rule - -## Goal - -Reviews and authoring agents catch the four implicit-state shapes the -[epic](/quest/m1/explicit-state/README.md) lists before they land. REVIEW.md -has a check, and AGENTS.md has one line, saying: - -- a lifecycle is one enum or union whose variants carry their data; -- a terminal transition happens after the work that can fail, or records - the failure; -- one value is never guarded by two locks or split across atomics. - -## Plan - -Decided 2026-11-07 (maintainer): ✅ both REVIEW.md and AGENTS.md. Not -chosen: REVIEW.md only, or no rule change. This is the prompt that the -repository's rule on changing agent instructions requires. - -Follow `quest context`'s Prompting section: keep the AGENTS.md line short, -since it loads into every session, and put the detail and examples in -REVIEW.md. Point at the patterns already in the tree as the shape to copy: - -- `PresentState` in `rs/moq-net/src/lite/session.rs` -- `Join.State` in `js/net/src/ietf/join.ts` -- `CompletionState` in `rs/moq-gst/src/sink/session.rs` -- the consuming `finish(self)` in `rs/moq-rtmp/src/server.rs` - -Check the official guidance the Prompting section links before editing. - -This child lands first so the other children's reviews apply the check.