diff --git a/REVIEW.md b/REVIEW.md index c5d4c778b0e..64b654e4fd6 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -42,7 +42,8 @@ The fix makes the bad combination unrepresentable; a check that rejects it is no Flag a unit test that waits on the real clock, in any language, even when the timer goes through `kio::clock` or `@moq/clock`, whose timers still wait in real time until the test installs a paused, simulated, or `Manual` clock. The fix is a mocked clock or an awaited event, never a shorter or longer real wait or a looser budget, and the same fix lands in every language's sibling test. -The exception is a test that drives real sockets, devices, or processes, which may wait on the real clock and opts out with `host_time()` or `hostTime()`; that opt-out belongs nowhere else. +The exception is a test that drives real sockets, devices, or processes, which may wait on the real clock and opts out with `host_time()` or `hostTime()`. +The opt-out belongs nowhere else, except in a transport adapter where it binds a real socket, such as moq-tokio's QUIC `wrap_udp_socket` and moq-webrtc's ICE `Socket::new`. The runtime guards fail Rust and bun tests only when a timer fires on the host clock, so they miss Go and Python tests, elapsed-time assertions, and any wait that bypasses those clocks; and Rust's `host_time()` lasts for the whole process, so it hides other tests' waits outside nextest's one-test-per-process runs. # Models diff --git a/doc/bin/relay/auth.md b/doc/bin/relay/auth.md index 80022a41215..fc0a7c5fe8d 100644 --- a/doc/bin/relay/auth.md +++ b/doc/bin/relay/auth.md @@ -253,7 +253,8 @@ averages over a second, with one second of the rate as a burst. Older relays refuse a capped role rather than drop the cap. Only QUIC and WebTransport on the tokio or io\_uring listener enforce caps. -WebSocket and HTTP `/fetch` and `/announced` refuse a capped grant, +Every other transport refuses a capped grant (WebSocket, `tls://` and +plaintext qmux over TCP, Unix sockets, and HTTP `/fetch` and `/announced`), whether it arrives at connect, in band, or at revalidation. When in-band tokens add grants to one session, each direction takes the highest cap among them, and a grant giving that direction paths without a cap lifts it. A cap changed at diff --git a/quest/m0/ci/README.md b/quest/m0/ci/README.md index 93ef3873ad4..501e54ab46e 100644 --- a/quest/m0/ci/README.md +++ b/quest/m0/ci/README.md @@ -178,7 +178,12 @@ the spike measured that ~11% cheaper than crane cold and modeled it 49% cheaper over a week of `main`. Those builds run on free GitHub-hosted runners today, but many of these jobs are planned to move to self-hosted runners, where the saving lands on our own hosts. The generated file, and the release profile -restated in `nix/crates.nix`, are accepted for that caching. +restated in `nix/crates.nix`, are accepted for that caching. Measured +2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): the +Cache job's Runtime step took a median 13.1 min over 32 crane builds and +11.9 min over 21 crate2nix builds, so the wall-time saving waits on that move, +which no quest plans yet; per-PR cost is small (`just rs cargo-nix --check` +takes about 3 s, and `nix/Cargo.nix` changed in 2 of the next 57 commits). Decided 2026-10-25 (maintainer), from a profile of moq-net: monomorphized generics dominate its build (53% of the library's CPU), and its test target diff --git a/quest/m0/nightly/bench-timeouts.md b/quest/m0/nightly/bench-timeouts.md new file mode 100644 index 00000000000..d84a0ba8a66 --- /dev/null +++ b/quest/m0/nightly/bench-timeouts.md @@ -0,0 +1,24 @@ +# [S] Nightly's benchmark jobs finish within their hour + +## Goal + +Nightly's "Rust bench targets" and "JS benchmarks" jobs finish inside their +timeout and publish their series again, and the Nightly triage counts a +cancelled job as a failure, so a job that times out every night is owned. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +"Rust bench targets" was cancelled 10 of the 14 nights before 2026-11-14 +(every night since 11-09), and "JS benchmarks" 11 of 14 (every night since +11-04); in run 43601796176 the Rust job was still compiling the paired base +in `/tmp/moq-bench-base.*` when `timeout-minutes: 60` +(`.github/workflows/nightly.yml`) cancelled it. A cancelled job is not a +failed one, so the failure-based triage never named either; about 2 +job-hours a night produce nothing. Find why the paired base builds cold +though the previous Nightly built that same commit +([moq-dev/moq#8763](https://github.com/moq-dev/moq/pull/8763) notes cache +units that were "not looked up"), fix that at the cause, and only then split +or trim the jobs if they still overrun. Never raise the timeout to fit. + +Public API: none. Wire: none. diff --git a/quest/m0/nightly/gate-cost-perf.md b/quest/m0/nightly/gate-cost-perf.md index be8046d50d7..59d9a5f35a2 100644 --- a/quest/m0/nightly/gate-cost-perf.md +++ b/quest/m0/nightly/gate-cost-perf.md @@ -1,9 +1,10 @@ -# [XS] Gate cost can count instructions on the merge-queue runners +# [S] Gate cost can count instructions on the merge-queue runners ## Goal -Nightly's `Gate cost` job (`just gh gate-cost`) counts user-space instructions -with perf on the `nixos` merge-queue runners and passes. +The `Gate cost` job (`just gh gate-cost`), part of Nightly today, counts +user-space instructions with perf on the `nixos` merge-queue runners and +passes, and runs on a schedule of its own at the merge queue's quietest hour. ## Plan @@ -33,6 +34,15 @@ Check with `perf stat -e instructions:u true` as the runner user inside a queue container, then the next scheduled Nightly's Gate cost job; never dispatch Nightly. +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +once perf counts, gate cost runs for hours (timeout 330 min) on a `moq-queue` +runner, and scheduled Nightlies start 5 to 9 h late, around 15:00 UTC when +the queue takes 47 to 90 entries an hour, which adds noise to its own series +and slows the queue. Decided 2026-11-14 (maintainer, pick on +[moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ gate cost +moves to its own schedule at the queue's quietest hour (rejected: keep it in +Nightly and trust only its instruction counts). + ## Waiting - Maintainer: merge the dotfiles PR and rebuild `nixos`, which restarts the CI runner containers; an agent does not deploy host config. Check with the `perf stat` command above. diff --git a/quest/m0/test-flakes-2/listing-yield.md b/quest/m0/test-flakes-2/listing-yield.md new file mode 100644 index 00000000000..d4f7c9a4dbc --- /dev/null +++ b/quest/m0/test-flakes-2/listing-yield.md @@ -0,0 +1,19 @@ +# [S] A peer's listing churn yields to the host's tasks, unquarantined + +## Goal + +`js/net`'s "a flood of a peer's listing churn yields to the host's tasks" +(`js/net/src/lite/tracks.test.ts`) runs again and passes under a loaded +`just check`, fixed at its cause on a mocked clock or an awaited event, never +with a looser budget. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md)'s +first pass: [moq-dev/moq#8355](https://github.com/moq-dev/moq/pull/8355) +skipped it after it timed out at 5 s in 2 of 30 full `js/net` runs under 48 +CPU burners, while that PR fixed a different test, so no quest owned the +quarantine. Reproduce under the same load first, then decide whether the +budget loop or the test's wait is at fault, following this epic's rules. + +Public API: none. Wire: none. diff --git a/quest/m0/test-flakes-2/mux-consumer-clock.md b/quest/m0/test-flakes-2/mux-consumer-clock.md new file mode 100644 index 00000000000..92b8f8a5138 --- /dev/null +++ b/quest/m0/test-flakes-2/mux-consumer-clock.md @@ -0,0 +1,21 @@ +# [S] moq-mux's container consumer tests run on the simulated clock + +## Goal + +The tests in `rs/moq-mux/src/container/consumer.rs` that depend on time run +under `#[kio::test]`'s simulated clock instead of `#[tokio::test]` on the real +one, and `gap_in_group_sequence_recovery` stops flaking in the merge queue. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +queue run 43557751216 failed `gap_in_group_sequence_recovery` ("Expected >= 4 +frames, got 2", 0.386 s) on a quest-only PR the day after this epic's three +loaded runs passed. It is a plain `#[tokio::test]` with a 100 ms max delay, +like most of the file's 115 tests, about 40 of which set a millisecond +`with_max`. `KIO_DENY_HOST_TIMERS` catches timers fired on the host clock, not +reads of it, which is the gap REVIEW.md's Tests section names. Convert the +time-dependent tests, as `rs/AGENTS.md` asks; tests with no timing stay as +they are. + +Public API: none. Wire: none. diff --git a/quest/m1/binding-delay-tests.md b/quest/m1/binding-delay-tests.md new file mode 100644 index 00000000000..682361c4f32 --- /dev/null +++ b/quest/m1/binding-delay-tests.md @@ -0,0 +1,34 @@ +# [XS] Binding playout-delay tests stop racing the native wall clock + +## Goal + +The Go, Swift, Kotlin, and Dart "audio consumer reports its playout delay" +tests no longer hang when the host stalls between the writes and the first +read, matching the Python and Rust fixes +([moq-dev/moq#8050](https://github.com/moq-dev/moq/pull/8050), +[moq-dev/moq#8566](https://github.com/moq-dev/moq/pull/8566)). + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +A fixed consumer with `max` zero skips a group by the native wall clock, so a +read that starts more than the 80 ms warmup after group 1 arrives waits out its +timeout (#8566 reproduced it with a 200 ms stall). Still latent in +`go/wrapper/moq_test.go` (`Delay{Min: 80ms}`, zero Max), Swift's +`SmokeTests.swift` (`max: 0`), and Dart's `moq_test.dart` (`max` defaults to +zero); Kotlin's +[moq-dev/moq#8475](https://github.com/moq-dev/moq/pull/8475) kept `max = 0` +and added a writer that loops until a read lands, which is a retry around the +cause. Pass `max: None` (or the language's unset value) to both consumers, and +delete Kotlin's writer loop. + +As a rule for new tests, assert native timing and decoding once, +in moq-ffi's Rust tests, and limit wrapper tests to the code each wrapper +owns (record mapping, cancellation, async adapters, lifetimes). Six copies of +this test took three separate fixes over a week, and three copies were still +unfixed. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) fix all four copies, and from now on native timing and decoding are asserted once, in moq-ffi's Rust tests, while wrapper tests cover only the code each wrapper owns; this quest writes that rule into `rs/moq-ffi/AGENTS.md` (rejected: (b) delete the four copies now). + +Public API: none. Wire: none. + diff --git a/quest/m1/bitrate-cap-sim.md b/quest/m1/bitrate-cap-sim.md new file mode 100644 index 00000000000..de838be82c1 --- /dev/null +++ b/quest/m1/bitrate-cap-sim.md @@ -0,0 +1,20 @@ +# [S] Relay bitrate cap tests run on the QUIC simulator + +## Goal + +The tokio half of `rs/moq-relay/tests/integration/bitrate_caps.rs` runs on +`quic::driver::sim` and asserts the capped transfer's time within a window in +simulated time, so a regression that throttles far below the cap fails, and +the tests stop waiting on the real clock. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +The tests assert only `elapsed >= 700ms` and poll every 10 ms on real time, +because [moq-dev/moq#7535](https://github.com/moq-dev/moq/pull/7535) chose +real sockets while no QUIC simulator existed; one landed in +[moq-dev/moq#8709](https://github.com/moq-dev/moq/pull/8709) +(`rs/moq-relay/tests/integration/quic_sim.rs`). The io_uring half stays on +real sockets. + +Public API: none. Wire: none. diff --git a/quest/m1/failover-fetch-residuals.md b/quest/m1/failover-fetch-residuals.md new file mode 100644 index 00000000000..f705325ec80 --- /dev/null +++ b/quest/m1/failover-fetch-residuals.md @@ -0,0 +1,29 @@ +# [M] A fetch survives the track ending on a relay chain + +## Goal + +On a relay chain, a fetch already in flight when the publisher ends the track +still delivers the rest of its group, and a fetch asked of a copy that has +completed goes on the wire instead of waiting out the subscriber's budget. +Both `residual_*` tests in `rs/moq-net/tests/integration/failover_chain.rs` +flip to assert delivery, and `EndedRelay.cfg`'s open finding is gone. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +the tests pin two bugs `verify/failover/FailoverChain.tla` rules out, and no +quest or PR owns them. + +- `residual_ending_the_track_fails_a_fetch_in_flight` (`NoSkipWhileHeld`): + E's fetch of group 0 is in flight through B when the track ends; B's copy, + asked from group 1, completes, which cancels B's fetch from P, so E's read + fails though P still writes the rest. +- `residual_a_fetch_from_a_completed_copy_never_leaves_the_relay` + (`Settles`): reading group 0 on after E's track ended asks B's completed + copy, and that fetch never goes on the wire, a hang bounded only by the + subscriber's budget. + +Replay `EndedRelay.cfg` on the real stack, fix at the cause, and run +`/verify-failover` and `/verify-resume` on the head. + +Public API: none. Wire: none. diff --git a/quest/m1/first-dial-refusal.md b/quest/m1/first-dial-refusal.md new file mode 100644 index 00000000000..66aefa1721e --- /dev/null +++ b/quest/m1/first-dial-refusal.md @@ -0,0 +1,38 @@ +# [S] A first session refused at SETUP fails fast + +## Goal + +A client whose first session is refused right after ALPN (a rejected token on +moq-lite 03 or later, which has no server SETUP to wait for) reports the +refusal and stops, as a first dial that reaches no relay does, instead of +redialing forever. Rust and JS behave the same, and the docs promise only +what the code does. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`Reconnect` (`rs/moq-net/src/reconnect.rs`) sets `established` as soon as the +transport connects, and `walk_failed` fails fast only while `!established`, +though its comment says that catches "a refused credential". A relay's +`MalformedAuthToken` close then reaches `closed()`, which backs off and redials +forever under `Backoff::timeout: None`. +[moq-dev/moq#8694](https://github.com/moq-dev/moq/pull/8694) hit exactly this +(one refusal a second in the relay log) and changed the interop test rather +than the client. `doc/bin/gstreamer.md` ("only reports `failed` on an answer +redialing can't change, such as a rejected token") and the comments in +`rs/moq-gst/src/sink/session.rs` are false since +[moq-dev/moq#8618](https://github.com/moq-dev/moq/pull/8618). + +Mark a session established only once it clears +`Backoff::healthy`, which `Retry::settle` already computes, so no error kind +is read; mirror it in `js/net`'s `#establishedHref`; update `Handover.tla` +through `/verify-reconnect`; fix the gst docs and comments and +`.claude/skills/verify-reconnect/SKILL.md`'s stale refusal exception. +#8618 settled that a refusal of a session that was live retries; this changes +only a first session that never became healthy. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) a session is established only once it clears `Backoff::healthy` (rejected: (b) keep retrying and correct only the docs). + +Public API: none. Wire: none. Behavior: a client whose first session is +refused before it is healthy ends with that error. + diff --git a/quest/m1/flight-priority.md b/quest/m1/flight-priority.md new file mode 100644 index 00000000000..4757f6feda5 --- /dev/null +++ b/quest/m1/flight-priority.md @@ -0,0 +1,16 @@ +# [XS] A flight asks upstream with its riders' priority + +## Goal + +A flight's upstream fill (`track::board` in `rs/moq-net/src/model/track.rs`) +asks with the priority and delay of the reader that boarded it, as every other +fill does, so a late joiner's replay is not ranked below all live traffic on a +congested upstream link. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +`board` hardcodes `fill::Asking { priority: 0, max_delay: None }`. Pass the +rider's `Preferences` in, and add a test that the fill carries them. + +Public API: none. Wire: none. diff --git a/quest/m1/gate-gh-scope.md b/quest/m1/gate-gh-scope.md new file mode 100644 index 00000000000..2dc9cb826f7 --- /dev/null +++ b/quest/m1/gate-gh-scope.md @@ -0,0 +1,28 @@ +# [XS] The merge gate runs repository tooling tests only when tooling changes + +## Goal + +A diff that touches no repository tooling stops paying for the `gh` module's +tests in the merge queue, while Nightly's full `gate` job still runs them +every night. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`sh/dispatch.sh` registers `module gh ''`, an empty pattern that matches every +diff, in `lane=bun` after the JS checks. In queue run 43634181288 (a +`flake.lock` bump) that lane was the whole 497 s run, with `test gh` at 224 s; +in 43622947541 the bun lane (409 s, `test gh` 220 s) outlasted the Rust lane. +Its wall time is about twice its CPU time, and it failed none of 34 queue +failures sampled from 11-12 to 11-14. Three files take 65 s of its 115 s +locally (`dispatch-query.test.py`, `nightly.test.py`, `rs/select.test.py`). + +Give `module gh` a path pattern covering what its tests +read (`sh/`, `bench/`, `.github/`, justfiles, `test/smoke/`, the Go publish +scripts) and keep the actionlint and zizmor lints on workflow changes; run +the three slow files in parallel if the lane still leads. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) scope the module to tooling paths, with Nightly's `gate` as the backstop (rejected: (b) keep it on every diff and only parallelize). + +Public API: none. Wire: none. + diff --git a/quest/m1/js-fill-timeout.md b/quest/m1/js-fill-timeout.md new file mode 100644 index 00000000000..d3dd4ca5ffc --- /dev/null +++ b/quest/m1/js-fill-timeout.md @@ -0,0 +1,21 @@ +# [XS] JavaScript ignores FILL_TIMEOUT as Rust does + +## Goal + +A JS publisher accepts any FILL_TIMEOUT a moq-transport subscriber sends, up to +the varint maximum, and ignores it as the Rust publisher does, instead of +refusing the subscription with `malformed(FILL_PARAMETERS)`. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +`js/net/src/ietf/filter.ts` and `parameters.ts` decode it with `toNumber`, +which throws above 2^53, while Rust skips it and keeps only whether it was +present (`rs/moq-net/src/ietf/fetch.rs`). Nothing in JS reads `fillTimeout` +since [moq-dev/moq#8445](https://github.com/moq-dev/moq/pull/8445) removed +JS FETCH serving, so keep presence only, delete the numeric field and its +encode path, and flip `js/net/src/integers.test.ts`'s refusal. Also fix +`fetch.rs`'s comment saying the request "is refused", which contradicts +`doc/concept/standard.md` ("accept and ignore"). + +Public API: none. Wire: none (the JS side stops refusing a valid value). diff --git a/quest/m1/js-pool-reach.md b/quest/m1/js-pool-reach.md new file mode 100644 index 00000000000..0ff732addb4 --- /dev/null +++ b/quest/m1/js-pool-reach.md @@ -0,0 +1,33 @@ +# [S] The JavaScript byte pool carries only what a JS caller can reach + +## Goal + +`js/net`'s per-broadcast byte pool keeps idle expiry, drop-run expiry, and the +per-group frame tail cap, and carries byte eviction only if a JS consumer sets +a capacity. Code that no production path reaches leaves the bundle. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +The pool's capacity defaults to infinity (`js/net/src/cache.ts`), every pool +is built without one (`broadcast.ts`, `track.ts`), and `resize` has no +non-test caller, so `Pool.accrue` always returns `undefined` and `#payDebt`, +reader debt, group `#shed`, and the debt calls in `track.ts` run only in +tests. [moq-dev/moq#8177](https://github.com/moq-dev/moq/pull/8177) said so +("byte eviction runs only for a pool given one. Today only tests do that"), +yet [moq-dev/moq#8294](https://github.com/moq-dev/moq/pull/8294), +[moq-dev/moq#8440](https://github.com/moq-dev/moq/pull/8440), and +[moq-dev/moq#8673](https://github.com/moq-dev/moq/pull/8673) kept building +on it. Rust differs: the relay sets a capacity. Expiry alone already bounds +the drop set (#8294). + +This revisits the pool quest's decision to port it "with no new setting" +(deleted by #8177), with the evidence that two weeks on nothing reaches the +path. + +Delete byte debt, shed, reader debt, and run billing from JS, +keeping the expiries; restore them from git with a consumer. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) delete the unreachable eviction (rejected: (b) expose `capacity`; (c) keep it for parity). + +Public API: none. Wire: none. diff --git a/quest/m3/mp4-repair-lock.md b/quest/m1/mp4-repair-lock.md similarity index 100% rename from quest/m3/mp4-repair-lock.md rename to quest/m1/mp4-repair-lock.md diff --git a/quest/m1/socket-endpoint-end.md b/quest/m1/socket-endpoint-end.md new file mode 100644 index 00000000000..e000d0080ba --- /dev/null +++ b/quest/m1/socket-endpoint-end.md @@ -0,0 +1,23 @@ +# [S] A socket endpoint's every ending runs its cleanup + +## Goal + +`moq_net::socket::Endpoint` models its lifecycle as one state whose ended +variant carries its error, and every ending, including the route broadcast +closing, goes through `close()`, so track streams already handed out end with +it as they do in JS. `is_endpoint` reaches moq-ffi, every binding, and the +socket guide. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +In `rs/moq-net/src/model/socket.rs`, `Handler::None` means both "not made +yet" and "ended", with `end: Option` stored beside it, and `poll_end` +returns `Closed` when a route broadcast closes without recording it or running +`close()`: when the origin shuts down, streams already handed out stay open +until the application drops the `Endpoint`. Shape it as REVIEW.md's State +section asks (`Open { .. } | Closed(Error)`). +[moq-dev/moq#8468](https://github.com/moq-dev/moq/pull/8468)'s +`socket::is_endpoint` exists only in Rust and JS. + +Public API: moq-ffi and every binding gain `is_endpoint`. Wire: none. diff --git a/quest/m1/tla-nightly-cache.md b/quest/m1/tla-nightly-cache.md new file mode 100644 index 00000000000..34bac8a4f02 --- /dev/null +++ b/quest/m1/tla-nightly-cache.md @@ -0,0 +1,24 @@ +# [XS] Nightly re-checks a TLA+ config only when its inputs change + +## Goal + +Nightly runs each exhaustive or fixed-seed TLA+ config only when its spec, +config, or TLC version changed since its last pass, and keeps running the +unseeded simulation configs every night. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`sh/tla.sh` reads only the spec, the config, and TLC, and 26 of the 30 configs +are exhaustive or pin `-seed 1`, so they give the same result on unchanged +inputs. On 2026-11-14 the TLA+ legs were Nightly's three longest jobs (102, +98, and 74 min) and the route leg set its end; over 14 nights their only +failures were CI configuration, such as a deleted config, never a broken +model. Key a cache of passing results on a hash of spec, config, and TLC +version (`actions/cache` works), and run every config whenever the key +misses. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) cache passing results by input hash (rejected: (b) every config every night). + +Public API: none. Wire: none. + diff --git a/quest/m1/ts-late-pmt.md b/quest/m1/ts-late-pmt.md new file mode 100644 index 00000000000..c273c76650d --- /dev/null +++ b/quest/m1/ts-late-pmt.md @@ -0,0 +1,25 @@ +# [S] A late PMT ends only its own program + +## Goal + +Under `--program all`, a program the PAT lists whose PMT does not arrive is +reported as TR 101 290 `PMT_error_2` in the import's health, and every other +program keeps publishing; the late program publishes once its PMT arrives. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`Programs` (`rs/moq-mux/src/container/ts/programs.rs`, from +[moq-dev/moq#6252](https://github.com/moq-dev/moq/pull/6252)) returns +`Err(self.late())` once any listed program waits more than 0.5 s of program +clock, so an MPTS whose PAT keeps listing a service after its encoder dies, or +announces one before its PMT starts, ends every program's broadcast. The +guide documents that ("A listed program whose PMT does not arrive within +0.5 s of program clock ends the import"), but its Loss section says feed +health "is logged and reported without changing what publishes". Treat the +late program's PIDs as unclaimed and update `doc/bin/ts.md`. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) report and continue (rejected: (b) keep ending the import and reword the Loss section). + +Public API: none. Wire: none. + diff --git a/quest/m1/ts-mux-rate-hold.md b/quest/m1/ts-mux-rate-hold.md new file mode 100644 index 00000000000..084af98b3c3 --- /dev/null +++ b/quest/m1/ts-mux-rate-hold.md @@ -0,0 +1,31 @@ +# [S] Only a padded TS export waits for the mux rate + +## Goal + +No TS import withholds its catalog to measure a mux rate. The catalog goes out +with the first media and gains `muxRate` as an update once a PCR window +measures it; a padded (CBR) export that has no `--mux-rate` waits for that +update instead. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Since [moq-dev/moq#5287](https://github.com/moq-dev/moq/pull/5287), every +import whose catalog carries the `mpegts` section holds it for a full 2 s PCR +window, CBR or VBR alike (asserted by a test in +`rs/moq-mux/src/container/ts/import.rs`), though only a padded export reads +the rate. Every new SRT connection and every `ffmpeg -f mpegts | moq import +ts` pays it, and ffmpeg's default VBR output never yields a rate. A +contributor measured the hold as about 2 s of the 2.8 s lost per restart +([moq-dev/moq#7102](https://github.com/moq-dev/moq/issues/7102)). The hold is +not on `release`, so moving it breaks nothing shipped. Padded export drew a +line of fixes ([moq-dev/moq#7967](https://github.com/moq-dev/moq/pull/7967), +[moq-dev/moq#8449](https://github.com/moq-dev/moq/pull/8449)). + +Then only an export joining in the first window pays. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) the padded export waits up to one window for the rate (rejected: (b) pad only to an explicit `--mux-rate`; (c) keep the import's hold). + +Public API: none. Wire: the catalog's `muxRate` may arrive in a later catalog +update than the first. + diff --git a/quest/m1/ts-open-gop-trim.md b/quest/m1/ts-open-gop-trim.md new file mode 100644 index 00000000000..70f835aa7aa --- /dev/null +++ b/quest/m1/ts-open-gop-trim.md @@ -0,0 +1,21 @@ +# [XS] TS export stops trimming MPEG-2 open-GOP leading pictures + +## Goal + +The TS export forwards MPEG-2 video as whole PES without parsing picture +headers, unless a consumer that needs leading B-pictures trimmed is named. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +[moq-dev/moq#7365](https://github.com/moq-dev/moq/pull/7365) added +`Mpeg2Picture` to `rs/moq-mux/src/container/ts/export.rs`, a picture-header +parser that runs on every MPEG-2 video frame, plus 153 test lines. Its own +quest called it "Low priority: decoders usually skip these B-pictures", and no +consumer asked for it. Delete the parser, its call, and its tests; HEVC RASL +trimming, which the guide's evidence table also names, stays. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ delete it (rejected: name a consumer). + +Public API: none. Wire: none. + diff --git a/quest/m1/ts-republish.md b/quest/m1/ts-republish.md new file mode 100644 index 00000000000..2bb189033ea --- /dev/null +++ b/quest/m1/ts-republish.md @@ -0,0 +1,34 @@ +# [S] One TS republish, owned by moq-mux + +## Goal + +`moq import srt` and `moq import ts` republish a stepped single-program TS +source through one moq-mux implementation: the new instance keeps the +measured mux rate, stays hidden until its catalog is out, and the step reaches +the caller as a typed value rather than an error it downcasts. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Three places mint TS instances: `container::ts::Programs` in moq-mux, the +CLI's `Republish` (`rs/moq-cli/src/publish.rs`), and moq-srt's `Instance` +(`rs/moq-srt/src/ts.rs`). [moq-dev/moq#7293](https://github.com/moq-dev/moq/pull/7293) +and [moq-dev/moq#7780](https://github.com/moq-dev/moq/pull/7780) fixed only +the CLI copy, so moq-srt's `Instance::publish` builds a default catalog on a +default, visible route, and `Import::new` re-arms the 2 s mux-rate hold on +every step. The guide (`doc/bin/ts.md`, Programs and changes) says a +republished stream "keeps the measured mux rate", which is false for SRT, +the path a live contributor uses. Both callers also find the step by +`err.downcast::()`, which AGENTS.md's "never match on errors" +forbids. + +- Move the CLI's `Republish` into `container::ts` as the single-program + sibling of `Programs`, returning the step as a variant of what decode + returns, and have both callers use it. +- Fix `doc/bin/ts.md`'s claim that SRT carries "the same import and export": + SRT has no passthrough. +- [Multi-program restart](/quest/m3/ts-multi-program-restart.md) then reuses + this instead of a fourth copy. + +Public API: moq-mux gains the republishing import; the `ts::Restart` error +goes if nothing else returns it. Wire: none. diff --git a/quest/m2/auth-listen-public.md b/quest/m2/auth-listen-public.md new file mode 100644 index 00000000000..c674ba5f7a8 --- /dev/null +++ b/quest/m2/auth-listen-public.md @@ -0,0 +1,22 @@ +# [XS] moq auth serve exposes a listener by its secret, not an allow flag + +## Goal + +`moq auth serve` accepts a non-loopback `--listen` address whenever +`--listen-secret` is set, and `--listen-public` is gone. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`rs/moq-cli/src/auth.rs` already refuses `--listen-public` without +`--listen-secret` and a non-loopback address without `--listen-public`; its +other use is the mesh guard, which +[moq-dev/moq#8756](https://github.com/moq-dev/moq/pull/8756) removes. After +that the flag carries nothing the address and the secret do not, and AGENTS.md +says not to add `allow-*` opt-out flags. Start once #8756 merges: delete the +flag and its setting, refuse a non-loopback address without a secret, update +`doc/bin/relay/auth.md`, and add a `MIGRATE.md` note, since `release` ships the +flag. + +Public API: removes `moq auth serve --listen-public` and its config key. +Wire: none. diff --git a/quest/m2/auth-retry-codes.md b/quest/m2/auth-retry-codes.md new file mode 100644 index 00000000000..87831ebecdd --- /dev/null +++ b/quest/m2/auth-retry-codes.md @@ -0,0 +1,29 @@ +# [S] AUTH_ERROR says which refusals a presenter retries + +## Goal + +Whether a presenter presents a refused token again follows a rule the lite-07 +draft writes down, driven by the AUTH_ERROR code it received, and Rust and JS +apply it from the decoded code rather than by classifying a local error. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Rust's `transient` and `verdict` (`rs/moq-net/src/auth.rs`, and +`lite/session.rs`'s `protocol_error`) and JS's `js/net/src/auth_session.ts` +retry a refused token only when the refusal maps to `Internal`, +`TooManyRequests`, or `Timeout`. The draft's AUTH_ERROR section says nothing +about retrying, so a third-party acceptor, or an embedder calling +`Request::reject`, whose auth backend is down and which answers UNAUTHORIZED +stops the client for good, while INTERNAL would have retried; only moq-relay +knows to answer `Internal`. lite-07 freezes this behavior at the cut. +[moq-dev/moq#8618](https://github.com/moq-dev/moq/pull/8618) removed the same +pattern from the reconnect loop for AGENTS.md's "never match on errors". + +It changes no behavior and makes the contract visible to +other implementations. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) write today's three codes (the session error codes Rust's `Internal`, `TooManyRequests`, and `Timeout` encode) into the draft as "not decided, present again after backoff", and have Rust and JS pass the decoded code to the retry decision (rejected: (b) every refusal final; (c) retry every refusal). + +Public API: none. Wire: lite-07-wip's AUTH_ERROR gains a retry rule. + diff --git a/quest/m2/congestion-candidates.md b/quest/m2/congestion-candidates.md new file mode 100644 index 00000000000..c1120fd933d --- /dev/null +++ b/quest/m2/congestion-candidates.md @@ -0,0 +1,65 @@ +# [S] The congestion selector ships BBR, and new algorithms join it additively + +## Goal + +The cut ships one public congestion-control selector that applications, the +relay's config, the CLI, and every binding use, with BBR (v3) selectable and +the default. Algorithms still under test (GCC, SCReAMv2, and BBR3's delay +bound) are not reachable from any published crate's public API, and each can +join the selector later without a breaking change. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +GCC (`rs/moq-congestion/src/gcc/`, about 16.3k vendored lines), SCReAMv2 +(`scream.rs`), and BBR3's delay bound (`bbr3::Config::delay_bound`) from +[moq-dev/moq#7546](https://github.com/moq-dev/moq/pull/7546), +[moq-dev/moq#7547](https://github.com/moq-dev/moq/pull/7547), and +[moq-dev/moq#7544](https://github.com/moq-dev/moq/pull/7544) are public in +moq-congestion 0.1.0, which has never been published, yet no session can +select them, and nothing outside tests turns on the receive timestamps GCC +needs. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)), +in the maintainer's words: "Add a way to select them? We need BBR for sure, +while GCC and Scream can wait for more testing I guess. So long as new +algorithms are additive." ✅ A public selector ships BBR; GCC and SCReAM are +not selectable in the cut and stay out of the published surface until tested +(rejected: delete them now and restore them for the bake-off; ship them +behind an unstable feature; publish them as they are). + +Choices made with that pick, for review: + +- The selector already exists, so extend it rather than add a second one: + `moq_tokio::quic::CongestionControl` (`#[non_exhaustive]`, with `Loss` + for CUBIC, `Delay` for BBR v3 and the default, and `None`), the relay and + CLI's `congestion_control` key, and moq-ffi's `MoqCongestionControl` in + every binding. `quic::Controller` stays the escape hatch for an + application's own controller. Its spellings ship on `release` (`delay` and + `loss` in relay configs), so keep them rather than break every deployed + config, and name each new variant after its algorithm (`gcc`, `scream`). + The docs say plainly that `delay` is BBR v3. A generated enum that a + language switches over exhaustively (Swift, Kotlin, Dart) makes a new + variant a break for its users, so give `MoqCongestionControl` a shape each + binding can grow without one before the cut. +- The delay bound is a BBR option, not a variant of its own: it bounds BBR3's + inflight from the forward-delay trend inside BBR's own state machine, so a + separate variant would duplicate BBR's settings under a second name, while a + field on a non-exhaustive `bbr3::Config` is additive. Until it is tested, + its setter is not public; it graduates as that option, or as BBR's default + if the bake-off shows it wins. +- Keep GCC and SCReAM in the tree but off the published API. Recommended: + move them into a workspace-only crate (`publish = false`) that the + bake-off's sim and integration tests use as a path dev-dependency, which + `cargo publish` drops; the vendor-sync quests follow the code. +- JS has nothing to select: browsers choose WebTransport's congestion + control, and `js/net` already asks for `low-latency`. + +[Realtime QUIC](/quest/m4/quic-realtime.md) is the bake-off that tests the +candidates and adds each winner to the selector as a variant (or the delay +bound as a BBR option). + +Public API: removes `moq_congestion::gcc`, `moq_congestion::scream`, and +`bbr3::Config::delay_bound` from the public API, none of them yet +published; `CongestionControl` and `MoqCongestionControl` are unchanged. +Wire: none. diff --git a/quest/m2/fetch-start-byte.md b/quest/m2/fetch-start-byte.md new file mode 100644 index 00000000000..31c695b9863 --- /dev/null +++ b/quest/m2/fetch-start-byte.md @@ -0,0 +1,30 @@ +# [S] lite-07 freezes without FETCH Start Byte + +## Goal + +lite-07's FETCH carries no Start Byte: a failover mid-frame refetches the +frame and skips what was read, as before +[moq-dev/moq#8699](https://github.com/moq-dev/moq/pull/8699), and the draft, +Rust, and JS match. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Frames are capped at `MAX_CACHE_BYTES`, 32 MiB (`rs/moq-net/src/model/group.rs`). +Whole-frame reads move `read_idx` only once a frame completes, so they ask +byte 0 anyway; only chunk readers gain: a relay forwarding a frame, and the +TCP pump of [moq-dev/moq#8741](https://github.com/moq-dev/moq/pull/8741), +whose own measurements found 64 KiB frames fastest. The saving is at most one +frame's prefix, on one hop, per failover. The cost is a `Lead` type in the group code, +66 start-byte sites across `rs/moq-net` and `js/net`, and a field frozen in +lite-07. No quest names a consumer of frames over 32 MiB. + +Restore refetch-and-skip, and require a named consumer of +large frames before [byte holes](/quest/m3/unbounded-groups/byte-holes.md) +starts. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) back Start Byte out of lite-07 and restore refetch-and-skip (rejected: (b) keep it). + +Public API: (a) removes the start-byte surface #8699 added. Wire: lite-07-wip +FETCH loses Start Byte. + diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index f10cc5eb5ef..6415e73d60f 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -157,6 +157,12 @@ would need a breaking release had it landed right after the cut: - [Routes and announces](/quest/m2/cluster-routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the native hop list gone (only the temporary lite-06 compatibility chain remains) - [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire +- [Warm routes on the wire](/quest/m2/warm-routes-wire.md) - removes WARM_* and SUBSCRIBE's `Warm` byte from lite-07 +- [ROUTE's RTT](/quest/m2/route-rtt.md) - removes ROUTE's informational RTT +- [FETCH Start Byte](/quest/m2/fetch-start-byte.md) - removes FETCH's byte offset into a half-read frame +- [Yield on relay links](/quest/m2/yield-relay-links.md) - narrows YIELDED from `ietf` sessions to tracks carrying moq-transport records +- [Subscriber Min Age](/quest/m2/subscriber-min-age.md) - removes SUBSCRIBE's minimum age, which nothing reads +- [AUTH_ERROR retries](/quest/m2/auth-retry-codes.md) - writes down which refusal codes a presenter retries - [A moq-lite subscriber always learns which group it abandoned](/quest/m2/group-drops-wire.md) - may add SUBSCRIBE_DROP for a stopped group; leaves this list if it takes the no-wire path ## Related diff --git a/quest/m2/nix-cluster-mode.md b/quest/m2/nix-cluster-mode.md new file mode 100644 index 00000000000..4da90f3632f --- /dev/null +++ b/quest/m2/nix-cluster-mode.md @@ -0,0 +1,24 @@ +# [XS] The NixOS relay module drops its dead cluster.mode + +## Goal + +`services.moq-relay` has no `cluster.mode` option, and its missing-credential +warning fires for any relay that dials a cluster peer (`cluster.rootUrl` set) +without a certificate or token. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Since [moq-dev/moq#8301](https://github.com/moq-dev/moq/pull/8301), +`cluster.mode` in `nix/modules/moq-relay.nix` is read only by an assertion and +a warning; dialing follows `rootUrl` alone. A root that dials other roots with +no `certFile` or `tokenFile` dials anonymously, is refused with +`unauthorized`, and retries forever with no warning, and `mode = "none"` with +`rootUrl` set still dials. Remove the option, key the warning on `rootUrl`, +drop the leaf assertion, update the plan in +[relay peers test](/quest/m5/nix-relay-peers-test.md), which checks that +assertion, and note it in `rs/moq-relay/MIGRATE.md`, since `release` ships the +option. + +Public API: removes the NixOS option `services.moq-relay.cluster.mode`. +Wire: none. diff --git a/quest/m2/route-rtt.md b/quest/m2/route-rtt.md new file mode 100644 index 00000000000..d9e0807bcc0 --- /dev/null +++ b/quest/m2/route-rtt.md @@ -0,0 +1,31 @@ +# [S] ROUTE drops its informational RTT + +## Goal + +lite-07's ROUTE_START and ROUTE_UPDATE carry no RTT, and `RouteInfo::rtt` is +gone from Rust, JS, and the bindings, with the `js/net` sampler that fed it. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +[moq-dev/moq#8458](https://github.com/moq-dev/moq/pull/8458) and +[moq-dev/moq#8553](https://github.com/moq-dev/moq/pull/8553) carry a summed +RTT because, per the deleted route-latency quest, a lite-07 route "cannot name +its path, so a sum is all the wire can carry". Since +[moq-dev/moq#8487](https://github.com/moq-dev/moq/pull/8487) every route +carries its hops. In `path::Router::rtt` (`rs/moq-net/src/route/path.rs`), one +link's RTT change past max(5 ms, 25%) recomputes every identity heard through +that neighbour and sends one ROUTE_UPDATE per publisher on every downstream +stream, repeating at each relay down; nothing ranks or selects by it, the +sizing covered chain length for one origin only (AGENTS.md asks for a sweep +over both axes), the "a node may withhold it" requirement never shipped, and +its in-repo consumer, link quality, moved downstream +([moq-dev/moq#8756](https://github.com/moq-dev/moq/pull/8756)). `js/net` +polls `getStats()` every second while a route exists, and nothing in JS reads +`RouteInfo.rtt`. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) drop the field and `RouteInfo::rtt` in Rust, JS, and the bindings, and the `js/net` `getStats()` sampler that fills it (rejected: (b) keep it after a sweep; (c) per-session link RTT summed along the path). + +Public API: (a) removes `RouteInfo::rtt` in Rust, JS, and the bindings. +Wire: lite-07-wip ROUTE_START/ROUTE_UPDATE lose the field. + diff --git a/quest/m2/sign-retire.md b/quest/m2/sign-retire.md new file mode 100644 index 00000000000..e4a05a60335 --- /dev/null +++ b/quest/m2/sign-retire.md @@ -0,0 +1,38 @@ +# [S] Per-frame signing leaves moq before the cut + +## Goal + +The cut publishes no per-frame signing (moq-sign-00): the signing wrappers, +their JS twin, the draft, and its vectors leave moq, the endpoint key the +cluster route key uses stays, and the docs say what moq-crypto publishes. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +The signing line ([moq-dev/moq#7092](https://github.com/moq-dev/moq/pull/7092), +[moq-dev/moq#7870](https://github.com/moq-dev/moq/pull/7870), +[moq-dev/moq#7702](https://github.com/moq-dev/moq/pull/7702)) was built for +the mesh, where content would be signed by default. The mesh moved downstream +([moq-dev/moq#8756](https://github.com/moq-dev/moq/pull/8756)). No crate uses +`moq_crypto::sign`'s broadcast, track, or group wrappers; the only Rust use of +`sign` is `SecretKey` for `--cluster-route-key` (`rs/moq-relay/src/cluster.rs`), +and nothing outside `js/crypto` imports `@moq/crypto`'s signing. +`draft-lcurley-moq-sign` was never submitted to the datatracker, and +`release` has no sign code. Yet moq-crypto is a required dependency of the +published moq-quic, moq-tokio, and moq-auth, with default features +`["sign", "e2ee"]`, so the cut would publish about 1.5k lines of Rust signing +API, and `doc/lib/rs/index.md` wrongly calls moq-crypto "Workspace-only". + +e2ee stays: its draft (rev 00) and `moq-e2ee` are already published. + +Delete `rs/moq-crypto/src/sign/` except `SecretKey` and +`PublicKey` (kept behind a feature that does not pull in `moq-net`), its +bench, `js/crypto`'s sign wrappers, and `drafts/draft-lcurley-moq-sign.md` with +`moq-sign-00.{json,ts}`; correct `doc/lib/rs/index.md`, `doc/lib/js/index.md`, +and `doc/concept/standard.md` to say e2ee is published and experimental. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) delete per-frame signing and keep the endpoint key (rejected: (b) hand it downstream; (c) publish it at the cut). + +Public API: (a) removes moq-crypto's and @moq/crypto's signing wrappers, +neither yet published. Wire: (a) withdraws the unpublished moq-sign-00 draft. + diff --git a/quest/m2/subscriber-min-age.md b/quest/m2/subscriber-min-age.md new file mode 100644 index 00000000000..0c8e61c22b4 --- /dev/null +++ b/quest/m2/subscriber-min-age.md @@ -0,0 +1,24 @@ +# [S] lite-07 drops Subscriber Min Age + +## Goal + +SUBSCRIBE and SUBSCRIBE_UPDATE carry no `Subscriber Min Age`, relays stop +aggregating and forwarding it, and `Delay::min` stays a local setting. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`Delay::min` (`rs/moq-net/src/model/subscription.rs`) is "the `Subscriber Min +Age` on the moq-lite-07 wire", and its own doc says "A publisher may use it, +such as to start a cold join that far back; nothing reads it there yet". It +is still encoded in Rust and JS, aggregated across subscribers in a +`BTreeMap` in `demand.rs`, and forwarded upstream by every relay. + +A field frozen with no reader costs every relay an +aggregate and a forward, and a later wire version can add it with its reader. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) drop the wire field and its aggregate; `Delay::min` stays a local setting (rejected: (b) plan the publisher's cold-join reader). + +Public API: none if `Delay::min` stays local. Wire: lite-07-wip SUBSCRIBE and +SUBSCRIBE_UPDATE lose the field. + diff --git a/quest/m2/sync-segments.md b/quest/m2/sync-segments.md new file mode 100644 index 00000000000..bbb5ea4a80c --- /dev/null +++ b/quest/m2/sync-segments.md @@ -0,0 +1,29 @@ +# [M] moq_mux::sync resets at a segment transition, as JS does + +## Goal + +`moq_mux::sync` handles a declared end and its replacement media with one +rule that Rust and JS share, and its state follows REVIEW.md's State rules: +one enum per lifecycle, one lock per value. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +Segment transitions in `rs/moq-mux/src/sync.rs` keep parallel `members`, +`resumed`, and `plans` arrays in `Pending`, and one track's segment state sits +behind two locks. +[moq-dev/moq#8589](https://github.com/moq-dev/moq/pull/8589) and +[moq-dev/moq#8513](https://github.com/moq-dev/moq/pull/8513) patched it, and +#8589 says JS needs no mirror because `js/watch/src/sync.ts` has no segment +transitions, so Rust runs a third model the deleted mux-sync quest said not +to invent. + +Coordinate with +[moq-dev/moq#8749](https://github.com/moq-dev/moq/pull/8749), which changes +the same clock. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) delete the transitions and reset the way JS does (rejected: (b) one enum per role, ported to JS). + +Public API: possibly `moq_mux::sync`'s transition surface, unpublished. +Wire: none. + diff --git a/quest/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md index 02e7786c968..42581d0d5ad 100644 --- a/quest/m2/time-addressing/lite07.md +++ b/quest/m2/time-addressing/lite07.md @@ -62,6 +62,27 @@ Lite-07 FETCH is single-group only ([moq-dev/moq#8616](https://github.com/moq-de which rewrites the same lite-07 draft sections (`Range`, Positions, SUBSCRIBE anchors). +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +reopening stale (OLD) drops is overbuilt for what it serves. Every +SUBSCRIBE_UPDATE reopens every OLD drop, and a relay settles a received stale +drop only for readers within budget and range; it took 27 recorded decisions +in [moq-dev/moq#7670](https://github.com/moq-dev/moq/pull/7670), then +[moq-dev/moq#8546](https://github.com/moq-dev/moq/pull/8546), +[moq-dev/moq#8551](https://github.com/moq-dev/moq/pull/8551), and +[moq-dev/moq#8584](https://github.com/moq-dev/moq/pull/8584), and still has +an open model finding (`StreamWins.cfg`, owned by +[finished across updates](/quest/m3/lite-finished-across-updates.md)). The +case it serves is a relay reader whose budget widens after the upstream +dropped a group as OLD. Since this quest rewrites SUBSCRIBE_DROP, +SUBSCRIBE_UPDATE, and SUBSCRIBE_SKIP anyway, it can make OLD final on its +subscription: the widening reader asks with a SUBSCRIBE of its own, as the +draft already requires for delivered or finally dropped groups, and the +`Update` numbers, re-offers, reopen rules, and their model configs go, while +YIELDED continuations keep their hold. Also check whether GROUP's +previous-start link makes SUBSCRIBE_SKIP redundant. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) OLD drops are final on their subscription: this rewrite deletes `Update`, the reopen and re-offer paths, and their model configs (rejected: (b) keep reopening and finish [finished across updates](/quest/m3/lite-finished-across-updates.md)). + Public API: none beyond [the model](/quest/m2/time-addressing/model.md). Wire: lite-07-wip GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, SUBSCRIBE_STARTED, SUBSCRIBE_FINISH, SUBSCRIBE_SKIP, and diff --git a/quest/m2/warm-routes-wire.md b/quest/m2/warm-routes-wire.md new file mode 100644 index 00000000000..a51eb2d422d --- /dev/null +++ b/quest/m2/warm-routes-wire.md @@ -0,0 +1,47 @@ +# [S] lite-07 freezes without warm routes + +## Goal + +lite-07 freezes without WARM_START, WARM_UPDATE, WARM_END, and SUBSCRIBE's +`Warm` byte: the draft, `rs/moq-net`, and `js/net` drop them, and the merge +gate stops running `sweep_cache_routing`, which runs nightly until a +production implementation brings the warm wire back in a later wip version. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md) +on [moq-dev/moq#8732](https://github.com/moq-dev/moq/pull/8732). + +- The rule lives only in test code (`rs/moq-net/src/route/tests/cache.rs`, + `offer_from` and `decide`); production reads the warm messages and ignores + them. The sweep's `steady()` and `fixed_point()` check relays against the + same functions they run, so it is a consistency check, not an independent + oracle, and it checks none of the Goal's efficiency properties: a rule that + never offered a copy would pass it. +- `sweep_cache_routing` was the slowest route test, 36 s in a debug run, on + every moq-net PR, for code that never ships; the long sweep already runs + nightly from `test/route-sweep.sh`. +- No sweep compares copies or relays crossed against plain path routing, + which already shares one copy along each publisher's tree; the only gain + shown is LAN siblings with their own uplinks + (`lan_relays_share_uplink_copies`). Pull cycles form in 3.3% of churn steps + and about 9 in 10 of those leave a reader unfed (#8732), a stall plain + routing cannot have. +- The warm wire changed on 2026-11-12, 11-13, and 11-14, while the + implementation ([select](/quest/m3/cache-routing/select.md), XL) lands + after the cut. Item 7 of the [epic](/quest/m3/cache-routing/README.md) + moved the proof into m2 for a downstream fleet plan, and on 2026-11-14 the + mesh work moved downstream + ([moq-dev/moq#8756](https://github.com/moq-dev/moq/pull/8756)); item 11's + choice of lite-07 had neither as evidence. + +Before select is planned, measure copies and relays +crossed against plain path routing on an edge/core topology; if the only win +is LAN siblings, (d). Whatever is picked, move `sweep_cache_routing` out of +the gate into the nightly sweep until a production rule exists. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (b) strip WARM_START, WARM_UPDATE, WARM_END, and SUBSCRIBE's `Warm` byte from lite-07, and re-add them in the then-current wip version with the implementation, after measuring copies and relays crossed against plain path routing; `sweep_cache_routing` leaves the merge gate for the nightly sweep (rejected: (a) keep the wire as it is; (c) keep the messages and drop the byte; (d) move the epic downstream). + +Public API: none. Wire: lite-07-wip loses or keeps the warm messages and the +`Warm` byte. + diff --git a/quest/m2/warmup-one-decoder.md b/quest/m2/warmup-one-decoder.md new file mode 100644 index 00000000000..8d1aad14389 --- /dev/null +++ b/quest/m2/warmup-one-decoder.md @@ -0,0 +1,51 @@ +# [M] Warmup video plays through one decoder + +## Goal + +A video rendition with a `warmup` plays through one decoder that joins one +group earlier through the container consumer's existing warmup reach, as +audio does, in `@moq/watch`, `moq_video::decode`, and `moq play`; the +max-delay lane and its selector are gone, and the docs describe what ships. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +[moq-dev/moq#7555](https://github.com/moq-dev/moq/pull/7555), +[moq-dev/moq#5842](https://github.com/moq-dev/moq/pull/5842), and +[moq-dev/moq#7376](https://github.com/moq-dev/moq/pull/7376) added about +2,800 lines, none on `release`. + +- No producer in the stack sets a video `warmup`: the only writers are Opus + importers and encoders. The [intra-refresh](/quest/m4/intra-refresh/README.md) + import that would set one moved to m4 on 2026-11-12, for want of a consumer. +- Once `warmup` is nonzero, the max-delay lane never stops + (`js/watch/src/video/decoder.ts`; `rs/moq-video/src/decode/select.rs` says + both lanes race in steady state), so a viewer decodes twice for the whole + session to improve the moments after a join or skip. +- [Dual decoder](/quest/m4/intra-refresh/dual-decoder.md) says Firefox and + Safari are unverified and HEVC refresh fails in Chromium, while + `doc/lib/js/watch.md` presents the feature as working. +- The Rust and JS selection policies differ (Rust holds a sticky source, + JS picks per picture), though the JS docs say Rust does the same. +- `js/hang`'s container consumer and `moq_mux::container::Playout` already + decode from the group start and present at start plus `warmup`; video opts + out of passing it. + +The two-decoder design was the maintainer's decision on 2026-10-14; the new +evidence is the 2026-11-12 move to m4 and the absence of any producer. + +Pass `warmup` to the container consumer for video, delete +`Rendition`'s selector and the max-delay lanes in JS, `decode/select.rs` and +`moq play`'s dual path in Rust, keep `insertRecoveryPoint` only if Chromium +needs it for one decoder, trim `doc/lib/js/watch.md`, and rescope the m4 +dual-decoder quest to deciding whether a second decoder pays for itself, with +catch-up measurements. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) one decoder through the container consumer's warmup reach, revisiting two in m4 with measurements (rejected: (b) keep it as Chromium-only and experimental; (c) keep it as is). + +Public API: (a) removes the dual-decoder selection from `@moq/watch` and +`moq_video::decode`, unpublished. Wire: none. + +## Related + +- [Transcoder warmup](/quest/m4/intra-refresh/consumer-warmup.md) - its Goal assumes the players' two decoders; reword it if (a) is picked diff --git a/quest/m2/yield-relay-links.md b/quest/m2/yield-relay-links.md new file mode 100644 index 00000000000..99131656d1b --- /dev/null +++ b/quest/m2/yield-relay-links.md @@ -0,0 +1,24 @@ +# [S] A plain group yields on a relay link + +## Goal + +A lite-07 group whose stream is reset to make room pauses (YIELDED) on a +relay-to-relay session too, unless that track carries moq-transport object +records, so a relay short of stream credit stops losing preempted groups for +every viewer behind it. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`GroupServe::yields` (`rs/moq-net/src/lite/publisher.rs`) is +`version.has_yield() && !ctx.ietf`, and `ietf` is per session. moq-relay +offers the `ietf` extension on both its listen and connect sides +(`rs/moq-relay/src/config.rs`), so every relay-to-relay session negotiates it +and no group yields there: a preempted group is reset with TooFarBehind and +lost. Decide per track instead, the way Start Byte refuses only tracks that +carry a MoqTransport Version; narrow the lite draft's YIELDED rule to match, +mirror it in `js/net` if it has the same check, add a test, and run +`/verify-subscribe`. + +Public API: none. Wire: lite-07-wip's YIELDED rule narrows from sessions with +the `ietf` extension to tracks that carry moq-transport object records. diff --git a/quest/m3/audio-playout-library.md b/quest/m3/audio-playout-library.md new file mode 100644 index 00000000000..1040430cc56 --- /dev/null +++ b/quest/m3/audio-playout-library.md @@ -0,0 +1,39 @@ +# [L] Native audio playout is a library + +## Goal + +`moq play` and any other native player place received audio on the shared +clock through one `moq-audio` type, so every rule of the +[audio playout](/quest/m2/audio-playout/README.md) epic reaches each native +player without a copy. `rs/moq-cli/src/play/media.rs` keeps only CLI wiring. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +`play_audio` in `rs/moq-cli/src/play/media.rs` (a 2,865-line file with 70 +first-parent commits since the last release) carries everything a native +player needs for the epic's rule: anchoring the sink to the shared clock, +resumes across declared ends, declared silence and comfort noise, hole fills, +sink resets, and the 50 ms floor. Its loop keeps nine loose booleans +(`playing`, `ended`, `deferred`, `sequential`, `silent`, `declare`, +`utterance`, `trimming`, `fresh`) instead of one enum, and it matches on +`moq_audio::Error::Decode`, which AGENTS.md forbids. moq-dev/studio's +`moq-scene` keeps a second copy that has already drifted: a 2 s ceiling where +`moq play` uses `moq_mux::container::DELAY_MAX` (10 s), trimming instead of +the lag rule, and no declared-silence or stretch handling. + +- Extract the placement into `moq-audio` behind its `playback` feature, + writing to a `playback::Sink`, with a `bus::Positioned` output for a mixer. +- Model its lifecycle as one enum, and have the decoder report an + undecodable packet as a `Read` variant instead of an error the caller + classifies. +- Move `media.rs`'s audio tests with the code; then bump studio so + `moq-scene` adopts the type and deletes its copy. + +It waits so the epic's remaining children land first and this +breaks nothing in the cut. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (b) m3, after the audio playout epic merges (rejected: (a) an m2 child; (c) leave placement in the binary). + +Public API: `moq-audio` gains the placement type. Wire: none. + diff --git a/quest/m3/cache-routing/select.md b/quest/m3/cache-routing/select.md index e45103b0cb9..0700156904c 100644 --- a/quest/m3/cache-routing/select.md +++ b/quest/m3/cache-routing/select.md @@ -13,13 +13,17 @@ and how many moves warm routes caused. ## Plan - Implement the rule the [epic](/quest/m3/cache-routing/README.md)'s item 14 - records ([moq-dev/moq#8732](https://github.com/moq-dev/moq/pull/8732)) and - pass the fixtures and sweep in `rs/moq-net/src/route/tests/cache.rs`: the - warm messages lite-07 carries, which `rs/moq-net/src/lite/` reads and - ignores today, and SUBSCRIBE's `Warm` byte, which it and `js/net` send as 0 - (follow the route) and ignore when read, warm state derived - from each front's demand, and the choice of what to pull. The long sweep - already runs nightly from `test/route-sweep.sh`. + records ([moq-dev/moq#8732](https://github.com/moq-dev/moq/pull/8732)) by + moving `decide` and `offer_from` out of `rs/moq-net/src/route/tests/cache.rs` + into production code that the fixtures and sweep then drive, the way `Sim` + drives `path::Router`: today they test the rule against itself and pass + without touching the session. Add a check of the Goal's efficiency to + `steady()`, copies held against a cold-routing baseline, since a rule that + never offered a copy passes the sweep now. The rule covers the + warm messages and SUBSCRIBE's `Warm` byte (which return to the wire with + it, below), warm state derived from each front's demand, and the choice of + what to pull. The long sweep already runs nightly from + `test/route-sweep.sh`. - Extend today's selection rather than adding a second selector. `route_order` in `rs/moq-net/src/model/origin.rs` already hashes equal routes per path, and a front already moves to a better route of its own @@ -28,10 +32,9 @@ and how many moves warm routes caused. only to a copy of its own instance. - Bound the warm state a peer can make a relay hold by design, as announcements are bounded. -- Each pull states whom it serves, where Rust says unknown today: alone for - a local reader or a client session, which forwards nothing. `js/net` - already says alone and skips the warm types as unknown, so it needs - nothing. +- Each pull sets SUBSCRIBE's `Warm` byte, which #8732 put in place of the + `Serves` field; `js/net`, which forwards nothing, sends 0 (follow the + route) and skips the warm types as unknown. - Export upstream copies held, warm routes sent and received, and moves by cause through the relay's existing metrics. - `rs/moq-net/AGENTS.md` says a relay behaves the same warm or cold. That @@ -39,11 +42,19 @@ and how many moves warm routes caused. request goes to. If the rule's wording contradicts warm routes, bring a rewording to the maintainer. -Public API: report any relay configuration added for warm routes. Wire: a -change the implementation needs updates the draft's Warm Routes section in -the same PR, in lite-07 while it is unpublished and in the next version -after. +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): +✅ lite-07 freezes without the warm wire +([warm routes on the wire](/quest/m2/warm-routes-wire.md)), so this quest +re-adds WARM_START, WARM_UPDATE, WARM_END, and SUBSCRIBE's `Warm` byte in the +then-current wip version, and first measures copies and relays crossed +against plain path routing. + +Public API: report any relay configuration added for warm routes. Wire: the +warm messages and the `Warm` byte return in the then-current wip version, +with the draft's Warm Routes section. ## Related -- [Routes and announces](/quest/m2/cluster-routes/README.md) - the route layer driving lite-07 sessions since [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023), whose feasibility distances eligibility reads +- [Routes and announces](/quest/m2/cluster-routes/README.md) - the route layer driving lite-07 sessions since [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023); its switch to path routes deletes the feasibility distances this rule once read +- [Warm routes on the wire](/quest/m2/warm-routes-wire.md) - may strip the warm wire from lite-07 or move this epic downstream before this starts +- [Transient cycles](/quest/m3/cache-routing/transient-cycles.md) - lowers the churn-time pull cycles the rule allows diff --git a/quest/m3/cache-routing/transient-cycles.md b/quest/m3/cache-routing/transient-cycles.md new file mode 100644 index 00000000000..d165450bed5 --- /dev/null +++ b/quest/m3/cache-routing/transient-cycles.md @@ -0,0 +1,41 @@ +# [M] Fewer pull cycles while warm routes churn + +## Goal + +The cache-aware rule's transient pull cycles during churn happen less often +than the 3.3% of churn steps [moq-dev/moq#8732](https://github.com/moq-dev/moq/pull/8732) +measured, or clear faster than its 142 deliveries, without slowing a join the +maintainer has not agreed to slow, and the sweep reports the rate so a change +that raises it shows. + +## Plan + +Decided 2026-11-14 (maintainer, /quest-complete on #8732): ✅ merge, and plan +a quest to lower the rate (rejected: accept the rate as is, hold the PR, +delete). Planned 2026-11-14 by the +[feature review](/quest/m3/release/feature-review.md), which found the pick +had no quest yet. + +What #8732 measured: about 9 in 10 cycle steps leave some reader unfed until +the crossing message lands; #8615's earlier sweep saw 0.39% and 53 +deliveries; at seed 3, dropping per-link priorities (2.8 to 3.0%) or letting +carriers exclude the neighbours they serve (2.9 to 3.1%) explained neither the +gap. Start by finding which of the sweep's churn or the per-neighbour offers +causes it, then propose fixes with their join-latency cost. + +A second baseline to account for: [moq-dev/moq#8734](https://github.com/moq-dev/moq/pull/8734) +(the path rule for a flapping publisher) re-pinned +`route::tests::cache::a_ring_of_stale_offers_settles_on_the_link_left`'s cap +on cycle steps from 40 to 204 across 20 seeds, 4 to 22 per seed, each cycle +cleared within 20 deliveries; the rule it replaced gave 2 per seed, each +cleared within 2. Explain that rise along with #8732's rate, and measure any +fix against both the sweep and this fixture. + +If [warm routes on the wire](/quest/m2/warm-routes-wire.md) moves the epic +downstream, this moves with it. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ a fix adds no join latency; one that only clears cycles faster comes first (rejected: a carrier waiting for a crossing message before it joins). + +Public API: none. Wire: none expected; a rule change that needs one updates +the draft's Warm Routes section. + diff --git a/quest/m3/fmp4-declared-clock.md b/quest/m3/fmp4-declared-clock.md index 01da2890d9f..879b47de66d 100644 --- a/quest/m3/fmp4-declared-clock.md +++ b/quest/m3/fmp4-declared-clock.md @@ -14,4 +14,14 @@ Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-a - A rendition that declares no depth keeps today's inference, including #7491's rule. - Keep #7491's tests (`tfdt` never steps back across sub-GOP fragments, ffprobe reads every fragment) and add a variable-rate B-frame case with a stall longer than the cadence, whose decode times follow the presentation slots across the stall. `DeclaredClock` derives DTS from PTS and depth alone, so a gap that only the encoder's own decode times would show is out of reach and not a goal. +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +the exporters break exact timestamp ties four ways. fMP4 gives a frame the +cadence ([moq-dev/moq#8470](https://github.com/moq-dev/moq/pull/8470)), +`DecodeClock` nudges the DTS, FLV bumps it, and `DeclaredClock` refuses an +exact repeat, so an MP4 with one repeated timestamp exports to fMP4 but fails +to FLV. [moq-dev/moq#8716](https://github.com/moq-dev/moq/pull/8716) retimed +the demo's source, so no test exercises an exact repeat any more. Since this +quest makes `DeclaredClock` the one decode-time rule, settle one tie rule with +it and add an exact-repeat case to each exporter's tests. + Public API: none. Wire: none. diff --git a/quest/m3/one-port/rtc-feed.md b/quest/m3/one-port/rtc-feed.md index 4cf24bf8699..ed8a765f039 100644 --- a/quest/m3/one-port/rtc-feed.md +++ b/quest/m3/one-port/rtc-feed.md @@ -38,6 +38,14 @@ pub enum Socket { ``` Build on moq-webrtc's ICE module (split out in #5702) rather than beside it. + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +the one-port demux already hands WebRTC its share of the port as +`moq_tokio::quic::demux::WebRtc` (`rs/moq-tokio/src/quic/demux.rs`), with +`poll_recv`, `poll_send`, and a `pin` that releases on drop, reached through +`Relay::webrtc()`; only tests call either today. Consume that handle instead +of the sketch's `mpsc` channels and new send trait, which `rs/AGENTS.md`'s +rule against `tokio::sync` in libraries rules out. moq-webrtc's `ice::Socket { udp, locals, inbound }` already separates the advertised host candidates (`locals`, from `ice_candidates`) from the bound address and takes routed datagrams on its `Inbound` queue, and the server mux diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index d826f0b24b7..8c7594c4df1 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -53,6 +53,32 @@ this comparison only after both web-transport publishers are frozen the last; if a freeze lands later, repeat it. This review still runs after m2 lands, over what changed since. +The [feature review](/quest/m3/release/feature-review.md)'s first pass +(2026-11-14) found exports whose consumer never came or whose premise was +later removed; judge each here. Recommended: drop each unless a consumer turns +up. + +- moq-ffi's `MoqTrackProducer::largest` and `MoqBroadcastConsumer::closed`, + added for browser parity ([moq-dev/moq#7304](https://github.com/moq-dev/moq/pull/7304)) + just before WASM support was removed + ([moq-dev/moq#7475](https://github.com/moq-dev/moq/pull/7475)); only + wrappers and tests call them. +- The byte-stream rung of `MoqMediaProducer`'s simulcast ladder + ([moq-dev/moq#7699](https://github.com/moq-dev/moq/pull/7699)), raised by + an automated reviewer; nothing passes a stream producer as `lower`, and it + changed `lower`'s type in every binding. Recommended: keep, since reverting + is another break. +- `moq_mux` container consumer's `set_wait`, a third delay knob beside + `Delay { min, max }`; native audio sets it to the `min` it already passes. +- `moq_transcode`'s `active::Rendition::applied()` and + `moq_video::encode::Applied`, with no caller outside their crates. +- moq-sock's ICMP error queue, `qmux::Config::fixed_receive_window` (used only + by the unconsumed p2p module), moq-webrtc's `p2p` feature, and moq-relay's + `stun` feature, none of which a shipped build uses. +- `moq_tokio`'s `TcpTls::new` under `cfg(all(feature = "tcp", not(feature = + "_certs")))`, a cfg that can never hold (`tcp` enables `_certs`) and whose + arity no longer matches its caller: delete it. + ## Required - [Breaking release readiness](/quest/m2/README.md) - the release's code is final before it is reviewed diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 77d647e0853..e2cbda2b87d 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -33,7 +33,11 @@ compatibility, draft, package, and all-language interop checks, and verify publication outcomes. Separate artifact install proofs and package-specific tags follow this cut. This planning PR cuts and publishes nothing. After publication, check Release remeasure and its pin-update PR, as -RELEASE.md describes. The pipeline re-measures changed planned-break pins +RELEASE.md describes. Also check that the first release-plz PR after the cut +gets the regenerated `nix/Cargo.nix` commit +([moq-dev/moq#8684](https://github.com/moq-dev/moq/pull/8684)) and passes +Check: that step has never run (found by the +[feature review](/quest/m3/release/feature-review.md), 2026-11-14). The pipeline re-measures changed planned-break pins and requests landing through the main merge queue. This cut carries stats epochs, so it drops diff --git a/quest/m3/release/feature-review.md b/quest/m3/release/feature-review.md index 4d121fae2e5..36a2c2159df 100644 --- a/quest/m3/release/feature-review.md +++ b/quest/m3/release/feature-review.md @@ -1,4 +1,4 @@ -# [L] Feature review before the cut +# [M] Feature review before the cut ## Goal @@ -8,33 +8,75 @@ complexity, holds its stated contract, is tested and documented, and should ship as is. Each line that needs work has a follow-up quest that lands before the cut, or a recorded decision to ship it as is. +What remains is the delta pass: the work that landed after the first pass's +base (`ce616b52c`, 2026-11-14), m2's included, and the lines the first pass +covered only lightly. + ## Plan Recurs once per API or wire cut (decided 2026-10-19; per breaking cut 2026-11-09). The [release cut](/quest/m3/release/cut.md) re-creates this quest when the maintainer names the next API or wire cut, so the PR finishing this run adds no successor. -Record what this run learned (inventory method, findings, what to check first) -in the cut's PR notes or a follow-up quest, so the next run starts from it. +Record what this run learned in the cut's PR notes or a follow-up quest, so +the next run starts from it. Only `/quest-delete` ends the recurrence. Decided 2026-11-12 (maintainer, /quest-audit before the cut): ✅ this run starts now, on what has landed, with a delta pass after m2 (rejected: one pass after m2 lands, which puts every finding behind the routes chain instead of -beside it). The first pass's PR rewrites this quest to the delta pass: what -m2 landed since, with [m2](/quest/m2/README.md) under `Required`. The cut -waits for the delta pass. Inventory the work lines from the -epics and quests deleted since the last release and from `git log` by area. -Judge each one adversarially (AGENTS.md) and challenge its premise, not only -its execution: is the feature worth supporting at all, and would a simpler -mechanism the stack already has deliver most of it? Then look for simpler -designs, code that can be deleted, tests that cost more than they catch, and -claims without evidence. -File follow-ups through `/quest-plan` into m1 or m2, or ask the maintainer to -ship as is. - -The first run must cover the MPEG-TS work (decided 2026-10-19 instead of a -separate TS audit): everything since the 2026-10-11 TS audit, judged against -the contracts in the [MPEG-TS guide](/doc/bin/ts.md). -Question each TS capability's premise the way the move to distinct importer -epochs dropped active-active publishers. +beside it). The cut waits for the delta pass. Judge each line adversarially +(AGENTS.md) and challenge its premise, not only its execution: is the feature +worth supporting at all, and would a simpler mechanism the stack already has +deliver most of it? Then look for simpler designs, code that can be deleted, +tests that cost more than they catch, and claims without evidence. File +follow-ups into m1 or m2, or ask the maintainer to ship as is. + +The first pass ([moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764), +2026-11-14) covered `d0b086e71` (the `release` merge base, 2026-10-09) to +`ce616b52c`: 3,652 commits, 588 of them `feat`. Its follow-ups and the lines +it would ship as is are listed in that PR. It covered the MPEG-TS work the +first run owed (decided 2026-10-19): the guide's evidence holds (every unit +test `doc/bin/ts.md` cites exists, `ts.yml` runs every harness flag it cites, +and the TS Nightly was green for its last eight runs), and its contract +breaks became m1 quests. Decided 2026-11-14 (maintainer, pick on #8764): ✅ +every line the first pass would ship as is ships as is, and its follow-ups +carry the maintainer's picks; the VR catalog fields stay, since a VR demo +([moq-dev/moq#6373](https://github.com/moq-dev/moq/pull/6373)) reads them. + +The delta pass: + +- Inventory `git log --first-parent ce616b52c..origin/main` by area, and the + quests deleted in that range, the same way. It includes + [moq-dev/moq#8741](https://github.com/moq-dev/moq/pull/8741) (byte streams + and the TCP pump) and [moq-dev/moq#8721](https://github.com/moq-dev/moq/pull/8721) + (`@moq/obs`), open at the first pass. +- Give a full pass to what the first pass read lightly: the RTMP, RTSP, and + SRT gateway lifecycles, CLI flag changes, JSON snapshot budgets and + broadcast-clock timestamps, the codec submission/receive split + ([moq-dev/moq#8372](https://github.com/moq-dev/moq/pull/8372)) and its drain + lifecycle, and moqsink's restart and completion lifecycle (three fixes and + two quarantines in the window). +- Confirm each first-pass decision landed as picked. + +What the first pass learned: + +- One read-only reviewer per cluster (routing and relay, Rust delivery, + js/net, transport, auth and crypto, native media, formats and TS, browser + media, bindings, CI and tests) covers a window this size; a reviewer that + splits its own cluster into sub-reviewers can stall waiting on them. +- Reviewers' counts and premises need checking before they become quests: + two claims fell on a re-read (a type said to have about 60 references had + 6; a quest said to be obsolete still had its premise in the code). +- Check first next time: exports and wire fields whose doc comment says + "nothing reads" or "MAY ignore"; settings that default to infinity with no + non-test setter; code copied between Rust crates or between Rust and JS + (TS republish, io_uring and tokio WebTransport, reconnect state, sibling + binding tests), where fixes land in one copy only; quarantined tests with no + owning quest; features whose consumer quest later moved to m4 or m5 or + downstream; and whether a "proof" checks code that ships or only a model of + it. + +## Required + +- [m2](/quest/m2/README.md) - the delta pass reviews what m2 lands, so the cut's code is final first diff --git a/quest/m3/route-trace-validation.md b/quest/m3/route-trace-validation.md index e4d12ed9fab..a18518fcb96 100644 --- a/quest/m3/route-trace-validation.md +++ b/quest/m3/route-trace-validation.md @@ -1,50 +1,47 @@ -# [L] Route sweeps are checked against the TLA+ model +# [M] The exhaustive route search replaces RouteHandoff.tla ## Goal -Every run of the route layer's random sweeps (`sweep_handoff`, -`sweep_scoped_handoff`) is also a behaviour of `RouteHandoff.tla`: a code -change the model does not allow fails the sweep, without anyone remembering to -resync the model. +One exhaustive check guards the lite-07 route rule, and it runs the compiled +code: the search over every delivery order on `path::Router` also checks +`Seen`, `StaleIsChased`, and `NoStaleReturn`, and `RouteHandoff.tla`, its +configs, and the route trace validation this quest first planned are gone, +with every skill, quest, and doc that pointed at the model pointing at the +search instead. ## Plan -Moved from m1 to m3 2026-11-13 (maintainer, /quest-plan): it waits on m2 -work, and no quest requires one in a later milestone, since a blocker ranks -by its own milestone. ✅ m3 (rejected: m2, where the cut would wait on it; -pulling the m2 blocker into m1). It ranks right after m2, when it can start. - -Decided 2026-11-10 (maintainer, /quest-plan), as the strongest guard against -the route model drifting from the code ([moq-dev/moq#8447](https://github.com/moq-dev/moq/pull/8447)). - -Decided 2026-11-10 (maintainer, a later /quest-plan the same day): - -- ✅ m1 (rejected: staying in m4; superseded 2026-11-13: m3, above). The mesh configs beside it, the - inductive invariant (dropped 2026-11-13: no checker can step the model), and the - cache-aware routing proof all build on - `RouteHandoff.tla`, so drift there costs the most. -- ✅ The other three models get trace validation too, each its own m4 quest - behind this one (rejected: "route only for now; judge the other models - after", decided earlier the same day). So the recorder's trace format and - the recipe that hands a trace to TLC are built here for - [resume](/quest/m4/resume-trace-validation.md), - [reconnect](/quest/m4/reconnect-trace-validation.md), and - [subscribe](/quest/m4/subscribe-trace-validation.md) to reuse. - -This is TLA+ trace validation (Cirstea, Kuppe, Loillier, Merz, 2024, used on -CCF and etcd's raft): `route::tests::Sim` records each step as the model -action it corresponds to, with the variables the model keeps, and TLC checks -that the recorded trace is a behaviour of the spec. Where the model covers -less than the sweeps do, the sweeps either restrict to what it models or the -model grows to cover them; pick whichever costs less and say which. - -Decided 2026-11-12 (maintainer, /quest-plan on the quests still written for -Babel): the traces come from the path router -([routes epic](/quest/m2/cluster-routes/README.md) Plan item 27). -Once the model has the path rule, a trace of Babel's router is no behaviour -of it, so this waits for the router too. - -Run it on the sweeps' existing seeds in CI only if it stays fast; otherwise in -Nightly with the sweeps' fresh seeds. +Decided 2026-11-10 (maintainer, /quest-plan): trace validation as the +strongest guard against the route model drifting from the code +([moq-dev/moq#8447](https://github.com/moq-dev/moq/pull/8447)), with resume, +reconnect, and subscribe each getting their own in m4. Moved to m3 on +2026-11-13 (maintainer, /quest-plan), since it waits on m2 work. + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +the exhaustive route search +([moq-dev/moq#8729](https://github.com/moq-dev/moq/pull/8729), merged +2026-11-14) searches every delivery order on the compiled `path::Router`, +faster than TLC on the same bounds (0.44 s against 2 s on the triangle) and on +meshes TLC cannot reach. `RouteHandoff.tla` now mostly duplicates it: only +`Seen`, `StaleIsChased`, and `NoStaleReturn` stay outside it, and a search +over the compiled code cannot drift from it, which was this quest's whole +purpose for route. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): +✅ keep the search and delete `RouteHandoff.tla` once #8729 lands (rejected: +keep the model and drop the search; keep both); #8729 has landed, so this is +ready. This replaces route trace +validation. + +- Fold the three rules into the search as properties it checks, and show + each one fails on a mutation that breaks it before deleting the model. +- Delete `rs/moq-net/verify/route/` and retarget or delete the + `verify-route` skill and its Coverage table, REVIEW.md's Models pointers, + and the quests that tell a PR to run `/verify-route`. +- The trace format and TLC recipe this quest was to build for the other + models now come from the first of their m4 quests: + [resume](/quest/m4/resume-trace-validation.md) builds them, and + [reconnect](/quest/m4/reconnect-trace-validation.md) and + [subscribe](/quest/m4/subscribe-trace-validation.md) reuse them. Public API: none. Wire: none. diff --git a/quest/m4/connect-policy-state.md b/quest/m4/connect-policy-state.md new file mode 100644 index 00000000000..f9e5ddaf65e --- /dev/null +++ b/quest/m4/connect-policy-state.md @@ -0,0 +1,33 @@ +# [M] The connect policy's state lives in one place, in both languages + +## Goal + +The client connect policy's lifecycle is stored once per language: +`moq_tokio::Connection` reads a snapshot of `moq_net::Reconnect`'s state +rather than rebuilding it from the action stream, and `js/net`'s `Reload` +runs a port of the same policy object, with the same inputs and actions, so a +Rust fix is a one-to-one diff in JS and one fixture table checks both. + +## Plan + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). +The lifecycle is kept three times: `Reconnect` (`rs/moq-net/src/reconnect.rs`), +moq-tokio's `Lifecycle::Live { migrating, predecessor }` +(`rs/moq-tokio/src/connection.rs`), and about ten private fields in +`js/net/src/connection/reload.ts`, which no model checks. About 22 reconnect +and GOAWAY fixes landed since the last release, and +[moq-dev/moq#8595](https://github.com/moq-dev/moq/pull/8595), +[moq-dev/moq#8597](https://github.com/moq-dev/moq/pull/8597), and +[moq-dev/moq#8737](https://github.com/moq-dev/moq/pull/8737) each had to be +hand-ported to `reload.ts`; REVIEW.md reads a line of fixes like that as a +design problem. moq-tokio's `Retired` then `Offline` double write briefly +publishes an aborted session. + +It makes JS the same shape the +[trace validation](/quest/m4/reconnect-trace-validation.md) checks, so that +quest can cover both languages. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) port the policy object to JS and snapshot it in moq-tokio (rejected: (b) wait for rs2ts; (c) JS traces only). + +Public API: none. Wire: none. + diff --git a/quest/m4/intra-refresh/dual-decoder.md b/quest/m4/intra-refresh/dual-decoder.md index cc3f53530a6..84c29d1153a 100644 --- a/quest/m4/intra-refresh/dual-decoder.md +++ b/quest/m4/intra-refresh/dual-decoder.md @@ -34,5 +34,6 @@ What remains is checking the other engines. ## Related +- [Warmup with one decoder](/quest/m2/warmup-one-decoder.md) - may replace the players' two decoders with one before the cut, leaving this to decide whether a second pays for itself - [H.264 import](/quest/m4/intra-refresh/h264-import.md) - publishes the real `warmup` for an end-to-end x264 check - [Consumer warmup](/quest/m4/intra-refresh/consumer-warmup.md) - the transcoder decodes history so it never encodes stripes diff --git a/quest/m4/quic-realtime.md b/quest/m4/quic-realtime.md index 9f74a4e56c3..f3e7b10f528 100644 --- a/quest/m4/quic-realtime.md +++ b/quest/m4/quic-realtime.md @@ -172,3 +172,13 @@ through `bandwidth_estimate` → `estimated_send_rate` → `set_bitrate`. the upstream encoder, so a GStreamer pipeline at a fixed bitrate still queues when capacity drops; [its own quest](/quest/m4/moqsink-feedback.md) owns that feedback. The bake-off and shipping `Realtime` do not wait on it. + +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +the candidates would publish unselectable with moq-congestion's first +release. Decided 2026-11-14 (maintainer, pick on +[moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ the cut ships +BBR through the existing selector and keeps GCC, SCReAM, and the BBR3 delay +bound off the published API ([congestion selector](/quest/m2/congestion-candidates.md)). +This bake-off tests them, and each winner joins `CongestionControl` as a +variant named after its algorithm, or, for the delay bound, a `bbr3::Config` +option; losers stay out of the published API. diff --git a/quest/m4/reconnect-trace-validation.md b/quest/m4/reconnect-trace-validation.md index 787bdc7596c..46faaeddb88 100644 --- a/quest/m4/reconnect-trace-validation.md +++ b/quest/m4/reconnect-trace-validation.md @@ -12,10 +12,10 @@ remembering to resync the model. Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about moq-net): every TLA+ model gets trace validation, not route alone. Milestone -m4, behind route's. +m4, behind resume's. - Reuse the trace format and the TLC recipe - [route trace validation](/quest/m3/route-trace-validation.md) builds, with + [resume trace validation](/quest/m4/resume-trace-validation.md) builds, with the `verify-reconnect` skill's Coverage table as the mapping from code to model actions. - `reconnect/tests.rs` holds fixtures, not a sweep. Add a seeded one on the @@ -32,4 +32,4 @@ Public API: none. Wire: none. ## Required -- [Route sweeps are checked against the TLA+ model](/quest/m3/route-trace-validation.md) - the trace format and TLC recipe this reuses +- [Resume sweeps are checked against the TLA+ model](/quest/m4/resume-trace-validation.md) - builds the trace format and TLC recipe this reuses diff --git a/quest/m4/relay-io-uring-package.md b/quest/m4/relay-io-uring-package.md index 11b966bfea7..df290890ba1 100644 --- a/quest/m4/relay-io-uring-package.md +++ b/quest/m4/relay-io-uring-package.md @@ -43,6 +43,14 @@ relay path to serve through moq-net's policy, so packaging never publishes the hand-copied lifecycle path; that landed in [moq-dev/moq#8082](https://github.com/moq-dev/moq/pull/8082). +Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md): +`rs/moq-uring` is about 12,000 lines with 140 commits since the last release, +no PR measured a throughput win, and its WebTransport layer is a copy of +moq-tokio's that 25 commits in the window edited twice. Decided 2026-11-14 +(maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): +✅ continue toward parity as decided, with no benchmark gate (rejected: freeze +new io_uring features until a quiet-host benchmark shows a gain). + Public API: none. Wire: none. ## Required diff --git a/quest/m4/resume-trace-validation.md b/quest/m4/resume-trace-validation.md index d0199cc2def..fb854733727 100644 --- a/quest/m4/resume-trace-validation.md +++ b/quest/m4/resume-trace-validation.md @@ -11,10 +11,14 @@ anyone remembering to resync the model. Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about moq-net): every TLA+ model gets trace validation, not route alone, so none -can keep passing on code that has moved on. Milestone m4, behind route's. - -- Reuse the trace format and the TLC recipe - [route trace validation](/quest/m3/route-trace-validation.md) builds. The +can keep passing on code that has moved on. Milestone m4. + +- Build the trace format and the TLC recipe that + [reconnect](/quest/m4/reconnect-trace-validation.md) and + [subscribe](/quest/m4/subscribe-trace-validation.md) reuse: route's trace + validation, which was to build them, gave way to the + [exhaustive route search](/quest/m3/route-trace-validation.md) (decided + 2026-11-14, maintainer, on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)). The sweep records each step as the model action it corresponds to (the `verify-resume` skill's Coverage table is the mapping) with the variables the model keeps, and TLC checks the trace is a behaviour of the spec. @@ -30,9 +34,6 @@ can keep passing on code that has moved on. Milestone m4, behind route's. Public API: none. Wire: none. -## Required - -- [Route sweeps are checked against the TLA+ model](/quest/m3/route-trace-validation.md) - the trace format and TLC recipe this reuses ## Related diff --git a/quest/m4/subscribe-trace-validation.md b/quest/m4/subscribe-trace-validation.md index fbbbf2abfa2..adde86d7eb9 100644 --- a/quest/m4/subscribe-trace-validation.md +++ b/quest/m4/subscribe-trace-validation.md @@ -12,10 +12,10 @@ remembering to resync the model. Decided 2026-11-10 (maintainer, /quest-plan on what could be proved about moq-net): every TLA+ model gets trace validation, not route alone. Milestone -m4, behind route's. +m4, behind resume's. - Reuse the trace format and the TLC recipe - [route trace validation](/quest/m3/route-trace-validation.md) builds, with + [resume trace validation](/quest/m4/resume-trace-validation.md) builds, with the `verify-subscribe` skill's Coverage table as the mapping from code to model actions. - The model's steps are spread over `lite/publisher.rs` (`TrackRun`, @@ -34,7 +34,7 @@ Public API: none. Wire: none. ## Required -- [Route sweeps are checked against the TLA+ model](/quest/m3/route-trace-validation.md) - the trace format and TLC recipe this reuses +- [Resume sweeps are checked against the TLA+ model](/quest/m4/resume-trace-validation.md) - builds the trace format and TLC recipe this reuses ## Related