Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 2 additions & 3 deletions quest/m1/explicit-state/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)).
Expand All @@ -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
Expand Down
31 changes: 0 additions & 31 deletions quest/m1/explicit-state/rule.md

This file was deleted.