From bcfb12cc085adf64cf3beef36522b78ee4e19a55 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 15:16:20 -0700 Subject: [PATCH 01/17] quest: plan the probe chain move, evicted-group staleness, and #5878/#6059 follow-ups Co-Authored-By: Claude Opus 5.5 --- quest/m1/claim-answer-epochs.md | 7 +- quest/m1/drop-set.md | 1 + quest/m1/evicted-group-stale.md | 50 +++++++++++ quest/m1/ietf-setup-validity.md | 45 ++++++++++ quest/m1/listen-admission-test.md | 27 ++++++ quest/m1/lite07-finalize.md | 5 ++ quest/m1/lite07-padding.md | 26 ++++++ .../probe/target.md => m1/probe-target.md} | 17 ++-- quest/m1/recovery-verdicts.md | 37 +++++++++ quest/m1/replica-resume.md | 34 ++++++++ .../probe => m1}/simulcast-rung-disable.md | 41 +++++---- quest/m1/sink-restart-follow.md | 39 +++++++-- quest/m1/track-priority-scope.md | 17 +++- quest/m2/group-failed.md | 34 ++++++++ quest/m2/mux-vr-fields.md | 40 +++++++++ quest/m2/obs-multitrack.md | 4 +- quest/m2/probe/README.md | 33 ++++++-- quest/m2/probe/padding.md | 83 +++++++++---------- quest/m2/probe/players.md | 4 +- quest/m2/probe/rung-disable-js.md | 38 +++++++++ quest/m2/probe/viewer-upswitch.md | 15 ++-- quest/m2/quic-bbr-natural-drain.md | 2 +- quest/m2/quic-deadline.md | 2 +- quest/m3/README.md | 1 + quest/m3/watch-webxr.md | 33 ++++++++ 25 files changed, 534 insertions(+), 101 deletions(-) create mode 100644 quest/m1/evicted-group-stale.md create mode 100644 quest/m1/ietf-setup-validity.md create mode 100644 quest/m1/listen-admission-test.md create mode 100644 quest/m1/lite07-padding.md rename quest/{m2/probe/target.md => m1/probe-target.md} (89%) create mode 100644 quest/m1/recovery-verdicts.md create mode 100644 quest/m1/replica-resume.md rename quest/{m2/probe => m1}/simulcast-rung-disable.md (68%) create mode 100644 quest/m2/group-failed.md create mode 100644 quest/m2/mux-vr-fields.md create mode 100644 quest/m2/probe/rung-disable-js.md create mode 100644 quest/m3/watch-webxr.md diff --git a/quest/m1/claim-answer-epochs.md b/quest/m1/claim-answer-epochs.md index 955cc00bf00..9208464eb8b 100644 --- a/quest/m1/claim-answer-epochs.md +++ b/quest/m1/claim-answer-epochs.md @@ -87,8 +87,10 @@ group, and sibling paths keep their readers. On the wires without an epoch that rests on our relays retiring a copy on End then Start, as `tests/integration/restart.rs` shows; arbitrary older caching relays are out of scope, as in [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md), since base IETF object identity -survives a withdrawal. A same-epoch lagging replica still resumes, checked on -lite-07 only, the one wire here that carries the epoch. JS mirrors the tests. +survives a withdrawal. A same-epoch lagging replica still resumes on the wires +here that carry the epoch, lite-07 and moq-transport 22 (since +[#5932](https://github.com/moq-dev/moq/pull/5932)), as +[replica resume](/quest/m1/replica-resume.md) checks. JS mirrors the tests. `just test interop --all`. Public API: breaking. A claim request is answered through `prepare` and @@ -104,6 +106,7 @@ the broader C API still waits for the generated replacement. ## Related +- [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes on lite-07 and moq-transport - [Announcement takeover](/quest/m1/announce-takeover.md) - its claim-to-route operation is `Request::prepare` then `publish`; TAKEOVER then removes the cold-start reset - [MoQ Epoch](/drafts/draft-lcurley-moq-epoch.md) - carries the answer epoch over moq-transport, so same-epoch resume and replacement can be told apart there - [#5057](https://github.com/moq-dev/moq/pull/5057) - the relay-side check this replaces diff --git a/quest/m1/drop-set.md b/quest/m1/drop-set.md index a8263306a1a..57eaa333190 100644 --- a/quest/m1/drop-set.md +++ b/quest/m1/drop-set.md @@ -220,5 +220,6 @@ unchanged. ## Related - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - settles what the same message's Error Code means on lite-07 +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - the sibling for groups a reader already holds after the cache evicts them - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - fills the cache miss an evicted run leaves - [JS unbounded groups](/quest/m2/unbounded-groups/js.md) - the JS byte bound for groups and the runs between them; not required, since JS runs never outgrow the JS cache diff --git a/quest/m1/evicted-group-stale.md b/quest/m1/evicted-group-stale.md new file mode 100644 index 00000000000..0fa8f8dee59 --- /dev/null +++ b/quest/m1/evicted-group-stale.md @@ -0,0 +1,50 @@ +# [S] An evicted group is judged stale by its successor + +## Goal + +A group already handed to a reader stays judgeable after the cache evicts +it: once its successor's arrival plus the reader's budget has passed, the +group is stale, the same verdict `hooks.staleAt` already gives a resumed +copy's group by sequence alone. A serve loop that waits on such a group (a +group stream whose FIN never completes) is then reset as `Old`, whatever the +budget. + +Today the verdict needs the group to still be cached. Rust `GroupExpiry` +(`rs/moq-net/src/model/track.rs`) requires the sequence in the cache lookup, +and JS `#isStale` (`js/net/src/track.ts`) requires the group in the +timeline. Both caches evict an idle group after their window (Rust +`cache::DEFAULT_EXPIRY`, JS `CACHE_WINDOW`, both 30 s), so under a budget of +about 30 s or more a stalled group is never convicted. Since +[#6059](https://github.com/moq-dev/moq/pull/6059) the same stalled stream +also holds the IETF PUBLISH_DONE, which waits on a finished group's FIN +under the budget. + +## Plan + +Found in #6059's follow-ups and decided with the maintainer on 2026-10-20 as +a sibling of [Drop set](/quest/m1/drop-set.md): that quest judges missing +groups, this one judges groups a reader already holds. + +- Judge by the successor, as `#staleAt` does for a sequence the track does + not hold. The verdict needs the successor's arrival (and its reach, for the + media-time arm), not the evicted group itself. +- Find out what the cache-membership checks guard before dropping them, such + as a different copy now occupying the sequence, and keep that guard. +- Settle what the verdict reads once the successor is evicted too. It must + never convict early: any later group arrived no earlier than the successor, + and the newest group is never stale. +- Check `FetchExpiry` beside `GroupExpiry`, which has the same cache-lookup + condition. + +Regression tests on mock time, Rust and JS, each failing without the fix, +with a budget of at least the cache window: a handed-out group whose stream +never completes is evicted, then reset as `Old` once its successor's arrival +plus the budget passes, and on IETF the PUBLISH_DONE then goes out. The +newest group is still never convicted. + +Public API: none. Wire: none. + +## Related + +- [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget +- [#6059](https://github.com/moq-dev/moq/pull/6059) - bounds a stalled group stream's FIN wait by the age budget, which this extends past eviction diff --git a/quest/m1/ietf-setup-validity.md b/quest/m1/ietf-setup-validity.md new file mode 100644 index 00000000000..d9ac4e85e22 --- /dev/null +++ b/quest/m1/ietf-setup-validity.md @@ -0,0 +1,45 @@ +# [XS] Every IETF setup wait runs under request validity + +## Goal + +Every wait while the IETF subscriber sets up a request ends as soon as the +request stops being valid (its route retired, or its grant revoked, narrowed, +or expired), with the same local refusal and peer cancellation that the +SUBSCRIBE's request-ID and SUBSCRIBE_OK waits give since +[#6061](https://github.com/moq-dev/moq/pull/6061). In +`rs/moq-net/src/ietf/subscriber.rs` that covers: + +- `Stream::open` for SUBSCRIBE, TRACK_STATUS, the cache-miss group FETCH, + and the joining FETCH on draft 17+; +- the request-ID wait for a fetch-only TRACK_STATUS; +- the cache-miss group FETCH's request-ID and response waits, whose response + wait still uses a `retired` flag. + +Today each is bounded only by QUIC stream credit or the ten-second +request-ID give-up. + +## Plan + +Decided with the maintainer on 2026-10-20, from #6061's follow-ups: + +- Reuse #6061's poll-native shape: poll the gate and `validity` beside + `Control::poll_credit(waiter, &mut Deadline)` or the response read inside + one wait, rather than racing the whole setup future. An allocated ID is + still sent on drafts 14-16, since the peer grants MAX_REQUEST_ID credit + back only for requests it receives; the response wait then cancels it. +- Refuse the request locally before awaiting the peer's acknowledgement of + the cancellation, as #6061 does. +- If [Rust request credit](/quest/m1/rs-request-credit.md) lands first, + `Stream::open` no longer waits for stream credit, and only the request-ID + and response waits remain here. + +Regression tests on sim time, one per wait, each failing on main by timing +out: a revocation and a route retirement during the wait refuse the request +promptly, on drafts 14 and 16 and on 17+ where the wait differs. + +Public API: none. Wire: none. + +## Related + +- [#6061](https://github.com/moq-dev/moq/pull/6061) - brings the SUBSCRIBE's own request-ID and SUBSCRIBE_OK waits under the grant +- [Rust request credit](/quest/m1/rs-request-credit.md) - a request without stream credit fails at once instead of waiting in `Stream::open` diff --git a/quest/m1/listen-admission-test.md b/quest/m1/listen-admission-test.md new file mode 100644 index 00000000000..7c883e047fb --- /dev/null +++ b/quest/m1/listen-admission-test.md @@ -0,0 +1,27 @@ +# [XS] Test that `moq --listen` bounds admission + +## Goal + +An in-process test proves that `moq --listen` bounds auth admission by +`listen.timeout`: an admission that never answers closes at the deadline, one +answered just inside it is admitted, and `"0"` waits. Today +`rs/moq-cli/tests/listen.rs` drives the binary with `--auth-public`, where +admission never waits, so nothing covers `serve_client` +(`rs/moq-cli/src/main.rs`) running admission under the handshake deadline. + +## Plan + +Decided with the maintainer on 2026-10-20, from the follow-ups of +[#5765](https://github.com/moq-dev/moq/pull/5765), which implements the +deadline. + +- Drive `serve_client` in process on controlled time, with an auth decider + that can stall, rather than the binary on wall time. If it cannot be driven + that way, open the smallest seam that lets it. +- Match the relay's `auth_lifetime` cases so the two listeners stay alike. + +Public API: none. Wire: none. + +## Required + +- [Handshake deadline covers admission](/quest/m1/handshake-admission-deadline.md) - the bound this tests diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 2c0e9fed356..c62a457ada9 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -68,6 +68,10 @@ On 2026-10-19 TRACKS, a per-broadcast track listing, replaced SUBSCRIBE_ALL and kept that slot. The `Time(pts)` range end rides in Subscribe ranges, already Required. +Decided 2026-10-20: the padding stream type joins Required, so the m2 +browser [padding probes](/quest/m2/probe/padding.md) can use lite-07 without +a new version. + Rust's lite-07 varints already carry the full 64 bits the draft specifies, so no codec work waits on the cut. @@ -91,6 +95,7 @@ is published; older versions are unchanged. - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS](/quest/m1/archive/tracks.md) - lite-07 carries the request listing a broadcast's tracks as they appear - [Ingress-version provenance](/quest/m1/ietf-extension/lite.md) - the `ietf` extension carries a track's ingress version once instead of a code per block +- [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves the padding stream type the browser probes with ## Related diff --git a/quest/m1/lite07-padding.md b/quest/m1/lite07-padding.md new file mode 100644 index 00000000000..4acbbb337b0 --- /dev/null +++ b/quest/m1/lite07-padding.md @@ -0,0 +1,26 @@ +# [XS] lite-07 reserves a padding stream + +## Goal + +lite-07 defines a unidirectional padding stream type that a receiver reads +and discards, in `rs/moq-net`, `js/net`, and `drafts/draft-lcurley-moq-lite.md`, +so the browser's [padding probes](/quest/m2/probe/padding.md) can send it +once lite-07 is published. This quest adds no sender. + +## Plan + +Decided with the maintainer on 2026-10-20: the padding sender stays in m2, +but its stream type joins lite-07 now, since lite-07's wire freezes at the +[cut](/quest/m1/lite07-finalize.md). + +- Match moq-transport's PADDING, which moq-net already discards + (`rs/moq-net/src/ietf/session.rs`). +- A padding stream is untrusted input: discard bytes as they arrive and + return their credit, so it holds nothing beyond the stream itself. +- Peers on lite-06 and older keep resetting an unknown stream without + closing the session. + +Tests: Rust and JS receivers discard a padding stream and the session stays +up, across languages; `just drafts check` passes. + +Public API: none. Wire: lite-07 (unpublished) gains the padding stream type. diff --git a/quest/m2/probe/target.md b/quest/m1/probe-target.md similarity index 89% rename from quest/m2/probe/target.md rename to quest/m1/probe-target.md index 452531ff4de..517e66a4199 100644 --- a/quest/m2/probe/target.md +++ b/quest/m1/probe-target.md @@ -18,13 +18,18 @@ against their own share instead of the whole downlink. ## Plan -Decided with the maintainer on 2026-10-17 (see the -[epic](/quest/m2/probe/README.md)): +Decided with the maintainer on 2026-10-20: this moved to m1 with +[native probing](/quest/m1/probe-native.md) and the native +[rung disable](/quest/m1/simulcast-rung-disable.md), so a native publisher's +stopped rendition can resume in the next breaking release. The rest of the +[epic](/quest/m2/probe/README.md) stays in m2. + +Decided with the maintainer on 2026-10-17 (see the epic): - **Publisher side: reuse the reservation.** The local send target is the sum of the `max` ceilings of every live `Reservation` on the connection's `bandwidth::Allocator`, including a disabled rung's and an undemanded - track's, because [rung disable](/quest/m2/probe/simulcast-rung-disable.md) + track's, because [rung disable](/quest/m1/simulcast-rung-disable.md) needs recovery that doesn't depend on demand: viewers deselect a disabled rung, so its demand goes away. Dropping a reservation removes it from the sum. No new publisher handle, and publishers need no catalog reader. @@ -63,9 +68,9 @@ Decided with the maintainer on 2026-10-17 (see the override the session's target or disable probing. - **The sender seam.** Define the hook a transport implements to probe up to a rate, and advertise `Increase` in SETUP only when the session has a sender - behind it. [Native](/quest/m2/probe/native.md) implements it in moq-quic, - and [padding](/quest/m2/probe/padding.md) is the fallback for transports - that don't. This quest only needs a test sender. + behind it. [Native](/quest/m1/probe-native.md) implements it in moq-quic, + and [padding](/quest/m2/probe/padding.md) in the browser. This quest only + needs a test sender. Notes for the implementer: diff --git a/quest/m1/recovery-verdicts.md b/quest/m1/recovery-verdicts.md new file mode 100644 index 00000000000..f604c751c84 --- /dev/null +++ b/quest/m1/recovery-verdicts.md @@ -0,0 +1,37 @@ +# [S] Group recovery refetches only on errors a new copy can fix + +## Goal + +A resumed group's recovery asks a route for a new copy only when the failure +was about delivery (the route or session went away, the stream was reset by a +peer that is leaving), never when it was about the group itself and would +repeat on every copy. Such a failure ends the group with its error once, +instead of looping on refetches. Rust and JS agree. + +## Plan + +From the follow-ups of [#5878](https://github.com/moq-dev/moq/pull/5878), +decided with the maintainer on 2026-10-20. Rust `Recover::wants` +(`rs/moq-net/src/model/resume.rs`) and JS `verdict` (`js/net/src/resume.ts`) +treat only `Old`, `Evicted`, and an application code as verdicts; every other +error is read as no verdict and refetched. An error that repeats on every copy +therefore loops. #5878's eviction reports `Evicted`, a verdict, so it no +longer triggers this, but other errors still can. + +- Classify by error, with one list mirrored in Rust and JS. Keep the existing + rule that an error from a copy whose route failed is never a verdict. +- A content error from one route may not repeat on another. Settle whether + such an error may move to a different route once; it never asks the same + route again. +- A hostile route can answer every refetch with bad data. Bound that by the + classification itself, not by a retry count. + +Regression tests on mock time, Rust and JS: a group whose every copy fails +with the same content error ends once with that error, and a route-loss +failure still recovers the group on the next route. + +Public API: none. Wire: none. + +## Related + +- [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - how long a replaced copy stays to back a handed-out group diff --git a/quest/m1/replica-resume.md b/quest/m1/replica-resume.md new file mode 100644 index 00000000000..e115c67fa4a --- /dev/null +++ b/quest/m1/replica-resume.md @@ -0,0 +1,34 @@ +# [S] A lagging same-epoch replica resumes on every epoch wire + +## Goal + +One publisher announced through two relays under its epoch, one of them +lagging: when the route a subscriber reads dies mid-group, the subscriber +resumes on the other route and sees every frame exactly once, in order. This +holds on lite-07 and on moq-transport with the MoQ Epoch extension (draft +17+), since epochs ride moq-transport as of +[#5932](https://github.com/moq-dev/moq/pull/5932). + +## Plan + +Decided with the maintainer on 2026-10-20. Today +`lite_resumes_after_a_lagging_route_dies` +(`rs/moq-net/tests/integration/route_change.rs`) covers the lagging case on +lite-07 only, and the route-flap tests cover moq-transport 22 without a lag. + +- Run the lagging scenario on moq-transport 17 and 22 as well. Lite carries + the resume point upstream; find what moq-transport carries instead, and fix + a duplicate or gap it shows at its cause rather than weakening the + assertion. +- A shared epoch here means true replicas of one publisher's bytes, never two + independent publishers. +- Mirror the case in `js/net` if its resume tests can drive a lagging route. + +Mocked time, wired into CI with the other integration tests. + +Public API: none. Wire: none. + +## Related + +- [Claim answer epochs](/quest/m1/claim-answer-epochs.md) - rechecks this contract after changing how a claim answers +- [Resume through an outage](/quest/m1/resume-outage.md) - the same-epoch resume after an unclosed route dies diff --git a/quest/m2/probe/simulcast-rung-disable.md b/quest/m1/simulcast-rung-disable.md similarity index 68% rename from quest/m2/probe/simulcast-rung-disable.md rename to quest/m1/simulcast-rung-disable.md index c723ab1496e..59f00f945f1 100644 --- a/quest/m2/probe/simulcast-rung-disable.md +++ b/quest/m1/simulcast-rung-disable.md @@ -1,4 +1,4 @@ -# [L] Publishers disable simulcast rungs the grant cannot fund +# [L] Native publishers disable simulcast rungs the grant cannot fund ## Goal @@ -6,22 +6,26 @@ A publisher encoding several video renditions of one source stops encoding its top renditions when its bandwidth grant cannot fund them, advertising each as `enabled: false` in the catalog, and re-enables them with hysteresis once the grant recovers. The lower renditions keep their share instead of -every rung degrading together. Covers the JS publisher (`js/publish`), the -Rust and FFI publishers (the `rs/moq-video` producer under the `rs/moq-mux` -rate policy), and the OBS plugin. `@moq/watch`, `moq play`, `moqsrc`, WHEP, -HLS and DASH export, and the moq-mux exports already skip disabled renditions -and follow one that flips; moq-ffi and moq-c refuse to subscribe one and leave -the fallback pick to the application. +every rung degrading together. Covers the Rust and FFI publishers (the +`rs/moq-video` producer under the `rs/moq-mux` rate policy) and the OBS +plugin; the JS publisher is +[JS rung disable](/quest/m2/probe/rung-disable-js.md). `@moq/watch`, +`moq play`, `moqsrc`, WHEP, HLS and DASH export, and the moq-mux exports +already skip disabled renditions and follow one that flips; moq-ffi and moq-c +refuse to subscribe one and leave the fallback pick to the application. ## Plan Today each video encoder reserves its configured ceiling and follows its own -grant down (`js/publish/src/video/encoder.ts`, -`rs/moq-video/src/encode/producer.rs`), so a congested uplink squeezes every -rendition at once and a top rung starved of most of its share keeps -encoding. JS also takes a manual `enabled` input that already publishes -`enabled: false` and stops encoding; this quest drives that state from the -grant. +grant down (`rs/moq-video/src/encode/producer.rs`), so a congested uplink +squeezes every rendition at once and a top rung starved of most of its share +keeps encoding. + +Decided with the maintainer on 2026-10-20: the native publishers moved to m1 +and require the [session target](/quest/m1/probe-target.md) and +[native probing](/quest/m1/probe-native.md), not padding, which is +browser-only. The JS publisher split into its own m2 quest, since it probes +with padding. - One rule, one home. Put the disable and re-enable decision in `moq_mux::rate` beside `Control`, so audio @@ -30,7 +34,7 @@ grant. it. Start from the ladder's band boundary (`disable = (max + 2 * lower) / 3`, see the [ladder questline](/quest/m3/ladder/README.md)) unless measurement argues - otherwise. JS mirrors the same rule and constants. + otherwise. The JS quest mirrors the same rule and constants. - Catalog state follows what the encoder applied, not what the policy asked. Never rewrite the advertised maximum bitrate or remove the rendition. - Recovery must not depend on demand. Once viewers deselect a disabled rung @@ -52,19 +56,20 @@ grant. Tests with mocked time: a shrinking grant disables the top rung first and keeps the lower ones at their share; a recovering grant re-enables it only past the hysteresis and after its viewers left; a jittering grant near the -boundary does not flap the catalog. Prove one shaped-uplink run in the -browser and one through moq-ffi. +boundary does not flap the catalog. Prove one shaped-uplink run through +moq-ffi. Public API: the shared rule in `moq_mux::rate` and whatever knobs the publishers expose for it. Wire: none; `enabled` already exists. ## Required -- [Session probe target](/quest/m2/probe/target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited -- [Padding probes](/quest/m2/probe/padding.md) - the sender a browser publisher probes with, and any transport without native probing +- [Session probe target](/quest/m1/probe-target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited +- [Native probing](/quest/m1/probe-native.md) - the sender that raises the estimate so a disabled rung can resume ## Related +- [JS rung disable](/quest/m2/probe/rung-disable-js.md) - the same rule in `js/publish`, probing with padding - [Ladder controller](/quest/m3/ladder/controller.md) - the same rung disable for generated transcode ladders - [OBS multitrack](/quest/m2/obs-multitrack.md) - OBS's native multitrack encoders as the renditions this disables - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - the viewer side of moving between renditions as capacity changes diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index a0e7a48a2c6..ae3dd712e55 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -1,16 +1,37 @@ -# [M] Server and push sinks handle a broadcast's restarts +# [L] moq-cli and moq-gst readers follow a broadcast's restarts ## Goal -Every moq-cli sink that resolves a broadcast and keeps serving it handles an -epochless `Restart` on purpose: it follows the new publisher instance where -its output can mark the break. A route change alone is never fatal: a sink -that cannot follow stays on the old instance while its publisher serves it, -and fails once that route dies, since its subscriptions then end with an -error. +Every moq-cli and moq-gst reader that resolves a broadcast and keeps reading +it follows publisher instances through moq-net's announced request +([moq-net follows announced instances](/quest/m1/net-announced-follow.md)), +the Rust counterpart of moq-ffi's `announced_broadcast`, instead of a +hand-rolled `origin.follow` loop. Each handles an epochless +`Restart` on purpose: it follows the new instance where its output can mark +the break. A route change alone is never fatal: a reader that cannot follow +stays on the old instance while its publisher serves it, and fails once that +route dies, since its subscriptions then end with an error. ## Plan +Decided with the maintainer on 2026-10-20: widened from the server and push +sinks to every moq-cli and moq-gst reader. Following a catalog's references +to other broadcasts stays with +[catalog references](/quest/m0/broadcast-epoch/catalog-references.md). + +Readers with their own follow loop today move onto the announced request: + +- moqsrc: `follow_path` in `rs/moq-gst/src/source/imp.rs` drains + `origin.follow` and re-requests on each start, holding its pads across + instances. +- `moq play`: `play` in `rs/moq-cli/src/play/media.rs` does the same and + resets its presentation per instance. +- The TS stitching follower (`rs/moq-mux/src/container/ts/follower.rs`), if + the announced request fits how it marks a break. + +Readers that resolve once (`subscribe`, `fetch`) either follow the same way +or say in the PR why they stay on one instance. + The stdout exports already do this: TS follows with `--stitch`, and the other formats ride the old instance until its route dies and its tracks error. Audit and fix the rest the same way: @@ -30,8 +51,8 @@ and fix the rest the same way: Share one helper (a `moq_mux` `Source::follow`-style API per [catalog references](/quest/m0/broadcast-epoch/catalog-references.md)) -rather than one rule per sink. Each fix lands with a test that replaces the -publisher while the sink runs. +rather than one rule per reader. Each fix lands with a test that replaces the +publisher while the reader runs. Public API: possibly a shared follow helper in `moq-mux`. Wire: none. diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 9fb29bb5ccc..61f337dc37d 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -85,6 +85,19 @@ Direction to settle in the draft first, then the code: gives moq-net's `poll::Session::send_group(priority)` a domain, so land that in the same trait break and implementers break once. +Receive ranks, folded in from +[#5878](https://github.com/moq-dev/moq/pull/5878)'s follow-ups by the +maintainer on 2026-10-20. When the receive window is stuck, #5878 evicts the +lowest subscription priority first across every broadcast on the session, +then the group its subscription would deliver last, and sets a stream's rank +once, when its header decodes: + +- With fairness on, rank received groups within their broadcast's domain + first, as sends are, so one broadcast's priorities never evict another's + partial groups. +- Re-rank a receive stream when its subscription's priority or group order + changes, instead of keeping the rank from its header. + Signed priority, decided with the maintainer: - moq-lite carries `p + 128` (flip the top bit). The mapping is one-to-one @@ -115,7 +128,9 @@ Signed priority, decided with the maintainer: Prove scoping with the existing lite publisher tests extended to two broadcasts on one session with fairness on: neither starves, a downstream 255 does not change the upstream order, and with fairness off the strict order is -unchanged. The io_uring workers apply the same setting. Move +unchanged. On the receive side, with fairness on, a high priority in one +broadcast never makes a stuck window evict another broadcast's partial groups +first, and a priority or order update moves an already-ranked stream. The io_uring workers apply the same setting. Move `doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md` (IETF 128 maps to 127) to the new range and mapping. diff --git a/quest/m2/group-failed.md b/quest/m2/group-failed.md new file mode 100644 index 00000000000..4f2307b607d --- /dev/null +++ b/quest/m2/group-failed.md @@ -0,0 +1,34 @@ +# [M] Publishers learn which groups failed to deliver + +## Goal + +A publisher can observe a group it produced whose delivery a subscriber's +stream gave up on (reset as `Old`, evicted, or the stream failed), with one +shape in Rust `moq-net` and in both `js/net` publishers, lite and IETF. + +## Plan + +Decided with the maintainer on 2026-10-20, from +[#6059](https://github.com/moq-dev/moq/pull/6059), which dropped JS +`Track.Producer.failed` because Rust had no counterpart and it covered only +the lite publisher. + +- Name the consumer first, such as an encoder that forces a keyframe or a + stats counter, and let it decide what the notification carries. If none + exists by the time this starts, propose deleting the quest. +- Return a handle or an event stream, not a callback. +- A relay fans a track out to many subscribers, and a hostile subscriber can + fail streams on purpose. Coalesce per group so N subscribers failing one + group cost one event, and benchmark the path swept over subscribers and + groups. +- Carry it through moq-ffi and the bindings only once a binding consumer + asks. + +Tests on mock time, Rust and JS: a group reset as `Old`, an evicted group, and +a failed stream each surface once, on lite and IETF. + +Public API: new, mirrored across Rust and JS. Wire: none. + +## Related + +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - more stalled groups reset as `Old`, which this would surface diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md new file mode 100644 index 00000000000..d05308c8350 --- /dev/null +++ b/quest/m2/mux-vr-fields.md @@ -0,0 +1,40 @@ +# [S] moq-mux importers fill the VR catalog fields + +## Goal + +The `moq-mux` importers fill the hang catalog's spatial fields from +[#5543](https://github.com/moq-dev/moq/pull/5543): a video rendition's +`projection` and `stereo` from MP4 `st3d`/`sv3d` (Spherical Video V2) and +Matroska `Projection`/`StereoMode`, and an audio rendition's +`layout: "ambisonic"` from Opus channel mapping family 2. Media without these +boxes or elements imports as today. + +## Plan + +Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once +#5543 lands. + +- The fields are live state like `color` (#5543), so fill them the way the + importers fill color (`rs/moq-mux/src/codec/color.rs`) and update them when + the source's config changes. +- Derive `fov` from the equirectangular bounds. A projection the catalog has + no kind for (cubemap, mesh) leaves the field absent: a flat picture is a + worse result, not a wrong one. Malformed input, such as family 2 with a + channel count that is not a square of at least 4, is refused. +- `mp4-atom` 0.16.2 has no `st3d` or `sv3d` atom; add them in + kixelated/mp4-atom. `webm-iterable` already names the Matroska elements. +- An fMP4 Opus track needs the `dOps` mapping table that + [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) adds, so ambisonic + fMP4 follows it; Matroska and raw Opus do not wait. +- Exporters writing the fields back are out of scope. + +Tests: a fixture per source (MP4 360 and VR180, Matroska stereo, Opus +first-order ambisonics) imports with the expected fields, and a malformed one +is refused. + +Public API: none beyond the catalog fields #5543 adds. Wire: none. + +## Related + +- [WebXR playback](/quest/m3/watch-webxr.md) - `` renders these fields +- [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) - the `dOps` mapping table an ambisonic fMP4 track needs diff --git a/quest/m2/obs-multitrack.md b/quest/m2/obs-multitrack.md index bc11950f249..80ae07948ba 100644 --- a/quest/m2/obs-multitrack.md +++ b/quest/m2/obs-multitrack.md @@ -7,7 +7,7 @@ simulcast renditions of one broadcast, one rendition per track, each with its own size and bitrate in the catalog. A user configures them the way OBS multitrack video is configured, including over obs-websocket. Disabling the top renditions as the bandwidth grant falls is -[simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md)'s work, not +[simulcast rung disable](/quest/m1/simulcast-rung-disable.md)'s work, not this quest's. ## Plan @@ -34,6 +34,6 @@ at least two video tracks watched in ``. ## Related -- [Simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md) - the grant-driven rung disable these renditions follow +- [Simulcast rung disable](/quest/m1/simulcast-rung-disable.md) - the grant-driven rung disable these renditions follow - [MoQ in obs-studio](/quest/m2/obs-studio/README.md) - the native output this configuration carries into - [OBS native codecs](/quest/m2/obs-moq-video/README.md) - the encoders behind each track when MoQ encoders are chosen diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 78471c82442..5ddd669e7da 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -28,7 +28,7 @@ publisher-local padding handle: - **One session target.** The session probes to the larger of its local target and the peer's PROBE target. PROBE `Increase` is the wire signal; retransmission or padding is the mechanism. The - [target](/quest/m2/probe/target.md) quest owns it. + [target](/quest/m1/probe-target.md) quest owns it. - **Viewers are in scope.** The viewer up-switch joined the epic, since a viewer's target is the same session target sent the other way. - **moq-net stays catalog-agnostic, and each hop is independent.** A relay @@ -39,11 +39,25 @@ publisher-local padding handle: - **Automatic, opt-out.** Our publishers (through their reservations) and players set targets by default, so probing works without an application knowing about it. -- **Native first, padding as the fallback.** Where moq-quic sends, it +- **Native retransmits, the browser pads.** Where moq-quic sends, it retransmits in-flight data during BBR3's ProbeBW_UP phase - ([native](/quest/m2/probe/native.md)). Where the stack can't (browsers over - WebTransport, other QUIC backends), a lowest-priority padding stream on an - ALR probe schedule does ([padding](/quest/m2/probe/padding.md)). + ([native](/quest/m1/probe-native.md)). A browser over WebTransport can't + reach its controller, so a lowest-priority padding stream on an ALR probe + schedule does ([padding](/quest/m2/probe/padding.md)). + +Decided with the maintainer on 2026-10-20: + +- The [target](/quest/m1/probe-target.md), [native](/quest/m1/probe-native.md), + and the native publishers' [rung disable](/quest/m1/simulcast-rung-disable.md) + moved to m1, so Rust, FFI, and OBS publishers recover a stopped rendition in + the next breaking release. Their rung disable needs the target and native + probing, not padding. +- Padding is browser-only (WebTransport in `js/net`): moq-quic is the only + Rust transport, so no native session needs it. lite-07 reserves its stream + type before the cut ([lite-07 padding](/quest/m1/lite07-padding.md)), and + the sender stays here. +- The JS publisher's rung disable split into its own quest here, since it + probes with padding. This README's own work, once the children land: @@ -59,11 +73,12 @@ This README's own work, once the children land: ## Required -- [Session probe target](/quest/m2/probe/target.md) - a session probes up to its reservations or the peer's PROBE target, sends its viewer handles as its own PROBE target, and advertises `Increase` where a sender exists -- [Native probing](/quest/m2/probe/native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender still validates headroom up to the target -- [Padding probes](/quest/m2/probe/padding.md) - a lowest-priority padding stream probes on an ALR schedule where the stack can't retransmit, in browsers and on other QUIC backends +- [Session probe target](/quest/m1/probe-target.md) - a session probes up to its reservations or the peer's PROBE target, sends its viewer handles as its own PROBE target, and advertises `Increase` where a sender exists +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender still validates headroom up to the target +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis +- [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule +- [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding - [Players set viewer targets](/quest/m2/probe/players.md) - players hold a viewer handle per watched broadcast at its highest enabled rendition's bitrate -- [Simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md) - JS, Rust/FFI, and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up ## Related diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index def47818650..a992e5fd357 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -1,63 +1,60 @@ -# [L] Padding probes where the stack can't retransmit +# [L] Padding probes from the browser ## Goal -Where a session's transport has no native probe (a browser over WebTransport -through `js/net`, a moq-net session on another QUIC backend), the session -probes up to its target with a padding stream at the lowest send priority. On -an ALR schedule, while app-limited below the target, it sends a short probe -cluster at about twice the estimate, capped at the target, about every five -seconds, with a follow-up probe when one validates. When the path has room -the estimate rises; when it doesn't, padding stays within its overhead and -media frame-delay budgets. Such sessions then advertise PROBE `Increase`. +A browser session (`js/net` over WebTransport) can't reach its congestion +controller, so it probes up to its target with a padding stream at the lowest +send priority. On an ALR schedule, while app-limited below the target, it +sends a short probe cluster at about twice the estimate, capped at the target, +about every five seconds, with a follow-up probe when one validates. When the +path has room the estimate rises; when it doesn't, padding stays within its +overhead and media frame-delay budgets. Such sessions then advertise PROBE +`Increase`. ## Plan Decided with the maintainer on 2026-10-17 (see the [epic](/quest/m2/probe/README.md)): -- **Padding is the fallback, not the first choice.** A browser can't reach - its congestion controller, and other backends lack - [native probing](/quest/m2/probe/native.md), so padding is ordinary stream - data that any controller counts and paces. It implements the - [target](/quest/m2/probe/target.md) quest's sender hook wherever the - transport doesn't. +- **Padding is the browser's sender.** Native sessions retransmit in-flight + data instead ([native probing](/quest/m1/probe-native.md)). Padding is + ordinary stream data that any controller counts and paces, and it + implements the [target](/quest/m1/probe-target.md) quest's sender hook in + `js/net`. Decided 2026-10-20: browser-only. moq-quic is the only Rust + transport, so no native session needs it. - **WebRTC's schedule.** Model it on GoogCC's `ProbeController` ALR probing. Rejected: [#5863](https://github.com/moq-dev/moq/pull/5863)'s exponential backoff to 60 s, which leaves a rendition waiting up to a minute after the path opens. A cluster that finds congestion (a falling estimate) ends early. -- **Wire: a moq-lite padding stream** (kept from #5863's analysis). Add a - unidirectional stream type the receiver reads and discards, matching - moq-transport's PADDING, which moq-net already discards - (`rs/moq-net/src/ietf/session.rs`). A moq-lite peer that predates it resets - the unknown stream without closing the session, so the probe just ends. - On moq-transport, send PADDING only from draft-18 on: drafts 14 to 17 close - the session on an unknown stream type (`UniType::classify`), so refuse to - pad there and keep `Report`. Update `drafts/draft-lcurley-moq-lite.md` and - `drafts/draft-lcurley-moq-probe.md` in this PR and run `just drafts check`. +- **Wire.** lite-07 reserves the padding stream type + ([lite-07 padding](/quest/m1/lite07-padding.md)), matching moq-transport's + PADDING. A moq-lite peer that predates it resets the unknown stream without + closing the session, so the probe just ends. On moq-transport, send PADDING + only from draft-18 on: drafts 14 to 17 close the session on an unknown + stream type (`UniType::classify`), so refuse to pad there and keep + `Report`. Update `drafts/draft-lcurley-moq-probe.md` if the sender changes + what it says, and run `just drafts check`. - A browser sender can't see whether it is app-limited; settle how to judge it from what it sends against the estimate. -Tests, with mocked time: - -- The schedule, Rust and JS: nothing while media meets the target or the - sender isn't app-limited; a cluster about every five seconds at twice the - estimate, capped at the target; a follow-up after one that validates; an - early end when the estimate falls. -- moq-net under its simulated transport: padding goes out at the lowest - priority; lite and IETF draft-18 receivers discard it; an old lite peer - resets it and the session stays up; drafts 14 to 17 pad nothing. -- `js/net`: the padding writer over a fake WebTransport under `@moq/clock`'s - `Manual`. -- moq-quic's seeded simulation with a stepped bottleneck and native probing - off: with padding the estimate rises past the media, without it it stays - frozen. On a path held below the target, report media frame delay and - deadline misses against budgets set before tuning: lowest priority can't - preempt padding already in flight or queued at the bottleneck, so a frame - ready just after a cluster can still wait behind it. Wire it into CI at - least nightly. +Tests, on `@moq/clock`'s `Manual`: + +- The schedule: nothing while media meets the target or the sender isn't + app-limited; a cluster about every five seconds at twice the estimate, + capped at the target; a follow-up after one that validates; an early end + when the estimate falls. +- The padding writer over a fake WebTransport: padding goes out at the lowest + priority on lite-07 and IETF draft-18, an old lite peer resets it and the + session stays up, and drafts 14 to 17 pad nothing. +- In Chrome through a shaped link: with padding the estimate rises past the + media, without it it stays frozen. On a path held below the target, report + media frame delay and deadline misses against budgets set before tuning: + lowest priority can't preempt padding already in flight or queued at the + bottleneck, so a frame ready just after a cluster can still wait behind it. + Wire it into CI at least nightly, sharing the epic's shaped-uplink setup. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the target this probes to and the sender hook it implements +- [Session probe target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [lite-07 padding](/quest/m1/lite07-padding.md) - the stream type the padding is sent on diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index 191a6fbdcc7..222672a38ac 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -16,7 +16,7 @@ Decided with the maintainer on 2026-10-17 (see the already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. -- The handle comes from the [target](/quest/m2/probe/target.md) quest; this +- The handle comes from the [target](/quest/m1/probe-target.md) quest; this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. @@ -31,4 +31,4 @@ and yields to an application override. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the per-broadcast viewer handle +- [Session probe target](/quest/m1/probe-target.md) - the per-broadcast viewer handle diff --git a/quest/m2/probe/rung-disable-js.md b/quest/m2/probe/rung-disable-js.md new file mode 100644 index 00000000000..aa1b393c584 --- /dev/null +++ b/quest/m2/probe/rung-disable-js.md @@ -0,0 +1,38 @@ +# [M] The browser publisher disables simulcast rungs the grant cannot fund + +## Goal + +`@moq/publish` (`js/publish`) stops encoding its top video renditions when its +bandwidth grant cannot fund them, advertising each as `enabled: false`, and +re-enables them with hysteresis once padding probes raise the estimate. The +lower renditions keep their share instead of every rung degrading together. + +## Plan + +Split from [native rung disable](/quest/m1/simulcast-rung-disable.md) by the +maintainer on 2026-10-20: the native publishers moved to m1 on native +probing, while a browser can only probe with +[padding](/quest/m2/probe/padding.md), which stays in m2. + +- Mirror the native quest's rule and constants from `moq_mux::rate`, rather + than tuning a JS-only one. Its decisions hold here too: catalog state + follows what the encoder applied, recovery does not depend on demand, and a + disabled rung keeps its reservation at its ceiling so the session keeps + probing for it. +- Today each encoder reserves its ceiling and follows its own grant down + (`js/publish/src/video/encoder.ts`). The manual `enabled` input already + publishes `enabled: false` and stops encoding; this drives that state from + the grant and settles how the two inputs combine. + +Tests on `@moq/clock`'s `Manual`: a shrinking grant disables the top rung +first and keeps the lower ones at their share; a recovering grant re-enables +it only past the hysteresis and after its viewers left; a jittering grant near +the boundary does not flap the catalog. The epic's shaped-uplink browser test +proves recovery end to end. + +Public API: whatever knob `@moq/publish` exposes for the rule. Wire: none. + +## Required + +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - the shared rule and constants this mirrors +- [Padding probes](/quest/m2/probe/padding.md) - the browser's sender, which raises the estimate so a disabled rung can resume diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md index 1713d5ac940..80c0da14cd5 100644 --- a/quest/m2/probe/viewer-upswitch.md +++ b/quest/m2/probe/viewer-upswitch.md @@ -19,15 +19,16 @@ estimate. Decided with the maintainer on 2026-10-17: this joined the [probe epic](/quest/m2/probe/README.md). [Players](/quest/m2/probe/players.md) -set the viewer target, the [session](/quest/m2/probe/target.md) sends it as +set the viewer target, the [session](/quest/m1/probe-target.md) sends it as its PROBE target, and the relay's sender probes the downlink up to it; this quest makes selection act on the estimate that rises. The relay runs -moq-quic, so it requires [native probing](/quest/m2/probe/native.md); if that -ends in a measured no-go, require [padding](/quest/m2/probe/padding.md) -instead rather than leaving this blocked. +moq-quic, so it requires [native probing](/quest/m1/probe-native.md). If that +ends in a measured no-go, take this back to the maintainer rather than +leaving it blocked: [padding](/quest/m2/probe/padding.md) is browser-only +since 2026-10-20, so the relay has no other sender. Selection reads its broadcast's viewer grant from the -[target](/quest/m2/probe/target.md) quest, not the connection's whole +[target](/quest/m1/probe-target.md) quest, not the connection's whole `estimatedRecvRate`, so several watchers on one pooled connection don't each select against the full downlink (decided with the maintainer on 2026-10-19). @@ -38,8 +39,8 @@ and audio, or selection stops discounting a probed estimate. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the viewer handle the session sends as its PROBE target -- [Native probing](/quest/m2/probe/native.md) - the relay validates headroom above the media it sends +- [Session probe target](/quest/m1/probe-target.md) - the viewer handle the session sends as its PROBE target +- [Native probing](/quest/m1/probe-native.md) - the relay validates headroom above the media it sends - [Players set viewer targets](/quest/m2/probe/players.md) - `@moq/watch` asks for its highest enabled rendition ## Closes diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index 134c89dc161..cf2a7826da6 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -108,4 +108,4 @@ separately; it does not adopt any of them in advance. ## Related - [TS validation](/test/ts/README.md) - shaped paths, whole-group shedding, and measured baselines -- [Native probing](/quest/m2/probe/native.md) - preserving an estimate and discovering spare capacity are separate problems +- [Native probing](/quest/m1/probe-native.md) - preserving an estimate and discovering spare capacity are separate problems diff --git a/quest/m2/quic-deadline.md b/quest/m2/quic-deadline.md index 9bae16af5ee..515b0959cd0 100644 --- a/quest/m2/quic-deadline.md +++ b/quest/m2/quic-deadline.md @@ -60,6 +60,6 @@ Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. - [QUIC receive-timestamps spike](/quest/m2/quic-realtime/receive-ts.md) - measures whether receive-time differences improve an explicit delay estimator over half-RTT - [ACK hook](/quest/m2/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic` -- [Native probing](/quest/m2/probe/native.md) - retransmits in-flight data +- [Native probing](/quest/m1/probe-native.md) - retransmits in-flight data to probe, and must not resend what a deadline has expired - [noq#813](https://github.com/n0-computer/noq/issues/813) - the per-stream deadline proposal to n0 diff --git a/quest/m3/README.md b/quest/m3/README.md index 00e5db6741f..b97158d639d 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -63,6 +63,7 @@ m4's upstream waits in here and moved m2 work with no consumer. - [MSFTS convergence](/quest/m3/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where they differ, once an MSFTS implementer engages - [#2279](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [CEA-608/708](/quest/m3/captions-cea.md) - captions carried inside video SEI become a real text rendition at import +- [WebXR playback](/quest/m3/watch-webxr.md) - `` renders equirectangular and stereo renditions through WebXR layers on a headset - [Paced replay](/quest/m3/archive-paced-replay.md) - an archive consumer pushes stored groups to live subscribers on one shared clock, so any live player plays it - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder reads its viewers' feedback and adapts its bitrate diff --git a/quest/m3/watch-webxr.md b/quest/m3/watch-webxr.md new file mode 100644 index 00000000000..137cf8dd344 --- /dev/null +++ b/quest/m3/watch-webxr.md @@ -0,0 +1,33 @@ +# [M] `` renders spatial video through WebXR layers + +## Goal + +On a headset browser with WebXR layers, `` presents a rendition +whose catalog says `projection: equirectangular` in an immersive session +through an `XREquirectLayer`: the horizontal span comes from `fov`, and the +layer layout from `stereo` (`left-right`, `top-bottom`, or mono). A flat +rendition, and a browser without WebXR layers, play as today. + +## Plan + +Decided with the maintainer on 2026-10-20, from the follow-ups of +[#5543](https://github.com/moq-dev/moq/pull/5543), which adds the fields. +Start once #5543 lands. + +- `XRMediaBinding` layers take an `HTMLVideoElement`, which `` + does not use (it decodes with WebCodecs), so an `XRWebGLBinding` layer fed + each decoded frame is the likely path. Check whether a WebGPU XR binding is + usable yet. +- Entering an immersive session needs a user gesture, so the UI offers it + only when the browser supports layers and the rendition is spatial. +- Ambisonic audio playback is out of scope; propose it as a follow-up. + +Tests: a mocked XR session checks the layer each catalog produces and is wired +into CI; a manual run on a headset browser proves playback. + +Public API: possibly a `` attribute to enter or disable immersive +playback. Wire: none. + +## Related + +- [moq-mux importers fill the VR fields](/quest/m2/mux-vr-fields.md) - native sources that carry these fields From 9731713bce34c46a75b205b45e9f6c2e5fab9b0f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 15:55:09 -0700 Subject: [PATCH 02/17] quest: move native probing and the failover drift flake, list the new quests Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 6 +++++ .../redundant-failover-drift.md | 4 +++- quest/m1/README.md | 19 +++++++++++++-- quest/m1/audit-test-cost.md | 2 +- quest/m1/listen-admission-test.md | 2 +- .../probe/native.md => m1/probe-native.md} | 24 ++++++++++++------- quest/m1/quic/README.md | 2 +- quest/m1/resume-outage.md | 2 +- quest/m1/test-flakes-2/README.md | 8 +++---- quest/m2/README.md | 4 +++- quest/m3/watch-webxr.md | 2 +- 11 files changed, 54 insertions(+), 21 deletions(-) rename quest/{m1/test-flakes-2 => m0}/redundant-failover-drift.md (90%) rename quest/{m2/probe/native.md => m1/probe-native.md} (79%) diff --git a/quest/m0/README.md b/quest/m0/README.md index a2e2ed681b9..1f2e5829d30 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -75,6 +75,11 @@ the runner moved here from Watch (maintainer, 2026-10-13). The other red jobs have fixes on `main`: macOS tests (#5335), drill-sensitivity (#5338), loom (#5389) and Windows tests (#5339). +Flakes (2026-10-20, maintainer): the redundant failover drift moved here from +the m1 [load round](/quest/m1/test-flakes-2/README.md). It fails loaded +`just check` runs, the local gate every merge waits on, and may hide a TS +export bug. + Hygiene (decided 2026-10-19): the audits sit at the end of this list. Each recurs once per major release: its PR adds the next run to the following milestone, gated from m2 onward on the [release cut](/quest/m2/release/cut.md). @@ -87,6 +92,7 @@ Each lands its fixes in its own PR and plans only what needs a decision. - [qmux release backport](/quest/m0/qmux-credit-backport.md) - adopt the 0.5 fix independently of the next breaking cut - [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in the merge queue as one `just ci` pass, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last +- [Redundant failover drift](/quest/m0/redundant-failover-drift.md) - a stitching TS export switches back to the surviving importer behind bufferbloat instead of failing on a stalled clock - [Release builds link](/quest/m0/release-link.md) - the Linux zigbuild release binaries and moq-gst packages link again after the 2026-10-11 nixpkgs bump, so the next release cut can publish - [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on #412 to publish the patched 0.6.x that main adopts - [qmux credit](/quest/m0/qmux-credit.md) - main adopts qmux 0.6 credit and close fixes; the 0.5 backport is independent diff --git a/quest/m1/test-flakes-2/redundant-failover-drift.md b/quest/m0/redundant-failover-drift.md similarity index 90% rename from quest/m1/test-flakes-2/redundant-failover-drift.md rename to quest/m0/redundant-failover-drift.md index 4701cd08ee6..060a2967303 100644 --- a/quest/m1/test-flakes-2/redundant-failover-drift.md +++ b/quest/m0/redundant-failover-drift.md @@ -11,7 +11,9 @@ slowest test in the queue suite (37 s, past nextest's 30 s SLOW mark). ## Plan Found by the 2026-10-19 test cost audit, with the exporter's stderr captured -on a failing run. After the test kills the newest importer, the exporter +on a failing run. Moved from the m1 +[load round](/quest/m1/test-flakes-2/README.md) to m0 on 2026-10-20 +(maintainer), since it fails loaded `just check` runs. After the test kills the newest importer, the exporter fails instead of switching back to the survivor: > export failed with the broadcast still up, so not lingering ... the diff --git a/quest/m1/README.md b/quest/m1/README.md index c22ba8665ba..e00629e9367 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -45,6 +45,12 @@ Added 2026-10-16: refresh, ranked after moq-transport passthrough, whose dynamic-groups path it promotes. It is a breaking `Demand` change, so it lands before the cut. +Added 2026-10-20 (maintainer): the probe target, native probing, and the +native rung disable moved up from the [m2 probe epic](/quest/m2/probe/README.md), +so Rust, FFI, and OBS publishers recover a stopped rendition in this release; +padding and the browser's rung disable stay in m2, with only padding's +lite-07 stream type here. + ## Required - [Epoch correctness](/quest/m0/broadcast-epoch/README.md) - publisher identity, duplicate suppression, and catalog pinning gate the breaking cut @@ -52,17 +58,19 @@ lands before the cut. - [qmux credit](/quest/m0/qmux-credit.md) - dropped/stopped streams return credit and close is delivered - [moq-net follows announced instances](/quest/m1/net-announced-follow.md) - the Rust equivalent of JS `request(path, { announced: true })`, replacing the follow loops in moq-ffi and moq-c -- [Sink restart follow](/quest/m1/sink-restart-follow.md) - moq-cli's server and push sinks follow an epochless `Restart` where their output can mark it, and fail loud otherwise +- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - every moq-cli and moq-gst reader, moqsrc and `moq play` included, follows instances through moq-net's announced request and an epochless `Restart` where its output can mark it, and fails loud otherwise - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [Controlled time](/quest/m1/time/README.md) - every crate and package reads time through moq-clock or @moq/clock, with regression tests for the changed contracts - [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding +- [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves a padding stream type that receivers read and discard, for the browser's padding probes - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - object IDs, properties, end status, datagram objects, and unknown track properties survive moq-transport -> moq-relay (and a relay cluster) -> moq-transport; moxygen's moq-test sections 1-7 pass nightly, except cases that use a subgroup other than 0 - [Refresh](/quest/m1/refresh/README.md) - a join asks for a fresh group once the current group's deltas exceed a publisher-advertised byte ratio, at every hop; replaces `Demand::used`/`unused` and moq-json's `delta_ratio` - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure - [Claim answer epochs](/quest/m1/claim-answer-epochs.md) - a claim answers each output by publishing it at its exact path under its own epoch, so a restarted output never reaches a returning reader as the old one's cache +- [IETF setup waits under validity](/quest/m1/ietf-setup-validity.md) - every IETF subscriber setup wait ends once its request's route retires or its grant is revoked - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - a dropped or cut group ends its reader with an error, never a clean end, across cache reclaim, cap changes, and recovery - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause @@ -84,11 +92,15 @@ lands before the cut. - [Redundant ingest guide](/quest/m1/redundant-ingest-guide.md) - a setup page on redundant ingest over multiple routes, for any publisher - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [moq-ffi reports why a first dial fails](/quest/m1/ffi-first-dial-failure.md) - OBS names the reason while the first dial retries, as moq-c already can -- [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants +- [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, sent and received, and a shared cluster session is fair across tenants +- [Session probe target](/quest/m1/probe-target.md) - a session probes up to its reservations or the peer's PROBE target and advertises `Increase` where a sender exists +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender validates headroom up to the target +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund and resume them once probing raises the estimate - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain - [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence, and the media fixture's cold-start audio-tone flake is fixed at its cause - [Handshake deadline covers admission](/quest/m1/handshake-admission-deadline.md) - `listen.timeout` bounds a connection through auth admission on both listeners, replacing the hardcoded admission timeout +- [moq --listen admission test](/quest/m1/listen-admission-test.md) - an in-process test proves `moq --listen` bounds admission by `listen.timeout` - [Restart reset](/quest/m1/stateless-reset-key.md) - a relay restarted with the same `listen.reset_key` stateless-resets its predecessor's connections, so clients reconnect within an RTT instead of the idle timeout - [Drain cleanup](/quest/m1/drain-cleanup.md) - sessions force-closed at the drain deadline record their lease end and bytes before the relay or CLI exits, while unfinished handshakes stay bounded - [GOAWAY coverage](/quest/m1/goaway-coverage.md) - every IETF request stream handles GOAWAY, a closed control stream is a violation, and the draft-18 cutoff is honored @@ -100,10 +112,13 @@ lands before the cut. - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end - [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - a replaced route copy stays while a group below its bound is in flight or it backs a handed-out group late, and no longer than the reader's budget - [Resume through an outage](/quest/m1/resume-outage.md) - a same-epoch resume after an unclosed route dies delivers the backlog its max age still holds, pinned by a regression test +- [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes with every frame once, on lite-07 and on moq-transport - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence +- [Recovery verdicts](/quest/m1/recovery-verdicts.md) - group recovery refetches only on errors a new copy can fix, so a repeating error ends the group instead of looping - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops - [WebGPU on Safari](/quest/m1/webgpu-safari.md) - the WebGPU renderer is verified on Safari 26 for macOS and iOS - [HLS export drains after End](/quest/m1/hls-export-end-drain.md) - a cleanly ended broadcast still exports its retained segments diff --git a/quest/m1/audit-test-cost.md b/quest/m1/audit-test-cost.md index b4a5f697e0b..dab311ce97a 100644 --- a/quest/m1/audit-test-cost.md +++ b/quest/m1/audit-test-cost.md @@ -32,7 +32,7 @@ the stats session graph's recursive Send proof (send-depth and fuzz), bench/ffi-gen's stale wasm-bindgen lock, moq-uring's fixed 1 ms calibration slack, the Nightly JS benchmark stall, the CI selection test's feature count, and the stats producer benchmark lint. It planned -[redundant failover drift](/quest/m1/test-flakes-2/redundant-failover-drift.md) +[redundant failover drift](/quest/m0/redundant-failover-drift.md) and [macOS QUIC connects](/quest/m1/test-flakes-2/macos-quic-connect.md). Baselines from queue run diff --git a/quest/m1/listen-admission-test.md b/quest/m1/listen-admission-test.md index 7c883e047fb..a05b7be4265 100644 --- a/quest/m1/listen-admission-test.md +++ b/quest/m1/listen-admission-test.md @@ -1,4 +1,4 @@ -# [XS] Test that `moq --listen` bounds admission +# [XS] Test that moq --listen bounds admission ## Goal diff --git a/quest/m2/probe/native.md b/quest/m1/probe-native.md similarity index 79% rename from quest/m2/probe/native.md rename to quest/m1/probe-native.md index 0634a731d14..71fd117dafc 100644 --- a/quest/m2/probe/native.md +++ b/quest/m1/probe-native.md @@ -12,6 +12,11 @@ measured no-go is a valid outcome. ## Plan +Decided with the maintainer on 2026-10-20: this moved to m1 with the +[target](/quest/m1/probe-target.md), since the native +[rung disable](/quest/m1/simulcast-rung-disable.md) requires it to resume a +stopped rendition. + Decided with the maintainer on 2026-10-17 (see the [epic](/quest/m2/probe/README.md)), replacing the old plan's "measure which mechanism wins first" step: @@ -31,10 +36,12 @@ mechanism wins first" step: distinct; preserving an old estimate does not discover capacity. - Evaluate the IMMEDIATE_ACK extension so ACK delay doesn't obscure a short sample. -- Implement the [target](/quest/m2/probe/target.md) quest's sender hook in +- Implement the [target](/quest/m1/probe-target.md) quest's sender hook in moq-quic's recovery and pacing layer and the moq-tokio and moq-uring - adapters. A controller with no ProbeBW_UP phase can't, so its sessions - fall back to [padding](/quest/m2/probe/padding.md). + adapters. A controller with no ProbeBW_UP phase (such as the + [realtime controller](/quest/m2/quic-realtime/README.md)) can't, so its + sessions keep `Report`: [padding](/quest/m2/probe/padding.md) is + browser-only. Acceptance, in moq-quic's seeded simulation (`rs/moq-quic/src/tests/`, extending `Bottleneck` to step its rate) and wired into CI at least nightly: @@ -51,14 +58,15 @@ upward adaptation, downward reaction, estimate age, frame deadlines, queue delay, unique goodput, and redundant bytes, against a no-probing baseline. A successful small burst is not proof of full path capacity. -On a no-go, keep the baseline, record why, and leave padding as moq-quic's -sender; the [viewer up-switch](/quest/m2/probe/viewer-upswitch.md) then -requires padding instead of this. Padding can't reach moq-transport drafts 14 -to 17, so sessions on those drafts would keep `Report`. +On a no-go, keep the baseline, record why, and native sessions keep `Report`. +Padding is browser-only, so the native +[rung disable](/quest/m1/simulcast-rung-disable.md) and the +[viewer up-switch](/quest/m2/probe/viewer-upswitch.md) then go back to the +maintainer instead of falling back to it. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the target this probes to and the sender hook it implements +- [Session probe target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements ## Related diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index e465c2b06a4..6b033cbdd96 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -69,7 +69,7 @@ cache limits remain separate; bitrate pacing composes with this memory cap. - [Scope track priority](/quest/m1/track-priority-scope.md) - the per-broadcast fairness policy on cluster sessions -- [Native probing](/quest/m2/probe/native.md) - moq-quic retransmits in-flight data during ProbeBW_UP to probe up to a session's target +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during ProbeBW_UP to probe up to a session's target - [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in `moq-quic`, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m3/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive from the idle timeout](/quest/m2/quic-keep-alive.md) - the keep-alive interval defaults to a fraction of the negotiated idle timeout; an explicit `quic.keep_alive` overrides diff --git a/quest/m1/resume-outage.md b/quest/m1/resume-outage.md index e63430d778e..5d2e8e6c713 100644 --- a/quest/m1/resume-outage.md +++ b/quest/m1/resume-outage.md @@ -65,4 +65,4 @@ Decided with the maintainer, 2026-10-20: - [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - which replaced copies stay while groups below them are in flight - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - the same max-age bound on a warm relay -- [Redundant failover drift](/quest/m1/test-flakes-2/redundant-failover-drift.md) - the same idle-timeout outage hitting the TS jitter clock +- [Redundant failover drift](/quest/m0/redundant-failover-drift.md) - the same idle-timeout outage hitting the TS jitter clock diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md index bcf8a0dad5c..199b760b61c 100644 --- a/quest/m1/test-flakes-2/README.md +++ b/quest/m1/test-flakes-2/README.md @@ -32,15 +32,15 @@ times on a loaded machine, as the first round did. moq-tokio's known exception, tracked by [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md). Added 2026-10-19 (maintainer): three more, the redial pair first since CI -hit it. The same day's test cost audit added the macOS QUIC connects, and the -redundant failover drift first: it may hide a TS export bug and failed two of -three loaded `just check` runs. +hit it. The same day's test cost audit added the macOS QUIC connects and the +[redundant failover drift](/quest/m0/redundant-failover-drift.md), which moved +to m0 on 2026-10-20 (maintainer): it may hide a TS export bug and fails loaded +`just check` runs. Public API: none. Wire: none. ## Required -- [Redundant failover drift](/quest/m1/test-flakes-2/redundant-failover-drift.md) - a stitching TS export switches back to the surviving importer behind bufferbloat instead of failing on a stalled clock - [macOS QUIC connects](/quest/m1/test-flakes-2/macos-quic-connect.md) - moq-tokio's loopback QUIC tests stop timing out on the macOS Platform job ## Related diff --git a/quest/m2/README.md b/quest/m2/README.md index 0ac917c264e..ff80dea5cbb 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -53,7 +53,8 @@ ranked just below deterministic TS legs, which it requires. - [GPU CI](/quest/m2/gpu-ci.md) - NVIDIA tests run nightly on real hardware, and `just rs nvidia` runs them locally instead of skipping - [Vendor-free CARLA bridge](/quest/m2/carla-bridge.md) - the CARLA demo's GPU bridge lets moq-video pick the encoder, and its stand-in test runs on AMD as well as NVIDIA - [V4L2 virtual camera](/quest/m2/v4l2-virtual-camera.md) - V4L2 capture runs nightly against the `vivid` virtual driver instead of only on a developer's camera -- [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches +- [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; the browser pads where native sessions retransmit +- [Failed groups reach the publisher](/quest/m2/group-failed.md) - Rust and both JS publishers surface a group whose delivery a subscriber's stream gave up on, with one shape - [A finished PROBE stops reporting](/quest/m2/probe-end-stale.md) - the Rust receive estimate reads unknown once its PROBE stream ends - [Wire stats](/quest/m2/wire-stats/README.md) - `Presence` counts each root's transport bytes on the wire, `wire_tx` and `wire_rx`, from QUIC, WebSocket, and embedder gateway sources - [Media stats](/quest/m2/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and one model turns both into a health verdict and a preflight report @@ -97,6 +98,7 @@ ranked just below deterministic TS legs, which it requires. - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end - [fMP4 edit lists](/quest/m2/fmp4-edit-lists.md) - the fMP4 importer applies edit lists to frame timestamps - [MKV import refuses out-of-range values](/quest/m2/mkv-dimension-overflow.md) - the Matroska importer errors on a dimension, channel count, or sample rate that would truncate +- [Importers fill the VR fields](/quest/m2/mux-vr-fields.md) - MP4, Matroska, and Opus imports set the catalog's projection, stereo, and ambisonic layout - [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback - [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback diff --git a/quest/m3/watch-webxr.md b/quest/m3/watch-webxr.md index 137cf8dd344..80f4b82a6d1 100644 --- a/quest/m3/watch-webxr.md +++ b/quest/m3/watch-webxr.md @@ -1,4 +1,4 @@ -# [M] `` renders spatial video through WebXR layers +# [M] The watch element renders spatial video through WebXR layers ## Goal From 82b4452909e2a6362754616c021605d7d3dab032 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:02:14 -0700 Subject: [PATCH 03/17] quest: bound what a peer's probe target costs by native's overhead budget Co-Authored-By: Claude Opus 5.5 --- quest/m1/probe-native.md | 5 +++-- quest/m1/probe-target.md | 7 +++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/quest/m1/probe-native.md b/quest/m1/probe-native.md index 71fd117dafc..20620f29504 100644 --- a/quest/m1/probe-native.md +++ b/quest/m1/probe-native.md @@ -47,8 +47,9 @@ Acceptance, in moq-quic's seeded simulation (`rs/moq-quic/src/tests/`, extending `Bottleneck` to step its rate) and wired into CI at least nightly: an illustrative 2 Mbit/s source seeking 4 Mbit/s while the path steps 3 to 12 to 3 Mbit/s, on identical media traces and wire budgets. Cover keyframes, idle -restart, stale high estimates, receiver credit limits, compressed ACKs, and -competing CUBIC and BBR flows. Add a congested arm below the media bitrate +restart, stale high estimates, receiver credit limits, compressed ACKs, +competing CUBIC and BBR flows, and a peer target far above the path, whose +redundant bytes stay within the overhead budget. Add a congested arm below the media bitrate behind a deep but finite queue for impairment acceptance and performance. Verify actual overflow drops, adding competing loss-based traffic if BBR alone will not fill it. Sweep queue depth separately. Random or scripted burst loss may diff --git a/quest/m1/probe-target.md b/quest/m1/probe-target.md index 517e66a4199..18d04736fab 100644 --- a/quest/m1/probe-target.md +++ b/quest/m1/probe-target.md @@ -61,8 +61,11 @@ Decided with the maintainer on 2026-10-17 (see the epic): no per-track wire field. moq-net reads no catalog. A peer's target is untrusted, but it only sets how high to probe: each probe scales the current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under - congestion control, so a huge target costs no more than one just above the - estimate. Clamp it to the session's rate cap where one exists + congestion control. Repeated cycles can still walk the estimate up to the + path's capacity, so a huge target costs the redundant bytes of probing that + far, held to the overhead budget [native](/quest/m1/probe-native.md) sets + before tuning; a peer that subscribes to more media can already cost the + sender that much. Clamp it to the session's rate cap where one exists ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. - **Automatic, opt-out.** Targets are on by default; an application can override the session's target or disable probing. From 3820f95b7a7db1f0664ffe7e2e547005137eb443 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:12:09 -0700 Subject: [PATCH 04/17] quest: refuse spatial input the catalog cannot describe Co-Authored-By: Claude Opus 5.5 --- quest/m2/mux-vr-fields.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md index d05308c8350..a639e269691 100644 --- a/quest/m2/mux-vr-fields.md +++ b/quest/m2/mux-vr-fields.md @@ -17,10 +17,12 @@ Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once - The fields are live state like `color` (#5543), so fill them the way the importers fill color (`rs/moq-mux/src/codec/color.rs`) and update them when the source's config changes. -- Derive `fov` from the equirectangular bounds. A projection the catalog has - no kind for (cubemap, mesh) leaves the field absent: a flat picture is a - worse result, not a wrong one. Malformed input, such as family 2 with a - channel count that is not a square of at least 4, is refused. +- Derive `fov` from the equirectangular bounds. +- Refuse what the catalog cannot describe, since an absent field claims flat + video or plain channels: a cubemap or mesh projection, and an Opus family 2 + stream outside a square channel count of at least 4 (zeroth order, or one + carrying RFC 8486's non-diegetic stereo pair). Input RFC 8486 itself + forbids is malformed and refused the same way. - `mp4-atom` 0.16.2 has no `st3d` or `sv3d` atom; add them in kixelated/mp4-atom. `webm-iterable` already names the Matroska elements. - An fMP4 Opus track needs the `dOps` mapping table that @@ -29,8 +31,8 @@ Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once - Exporters writing the fields back are out of scope. Tests: a fixture per source (MP4 360 and VR180, Matroska stereo, Opus -first-order ambisonics) imports with the expected fields, and a malformed one -is refused. +first-order ambisonics) imports with the expected fields, and a cubemap, an +ambisonic stream with non-diegetic stereo, and a malformed one are refused. Public API: none beyond the catalog fields #5543 adds. Wire: none. From 98f943555ff83af866c27c1710bc900cfd379582 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:21:50 -0700 Subject: [PATCH 05/17] quest: widen a mid-group compressed subscription at the subscriber Co-Authored-By: Claude Opus 5.5 --- quest/m1/compress/README.md | 1 + quest/m1/compress/app-range-widen.md | 35 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 quest/m1/compress/app-range-widen.md diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 21433416164..94c119c4297 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -81,6 +81,7 @@ This README owns the end-to-end proof and the guide once every child lands: ## Required - [Core](/quest/m1/compress/core.md) - Rust moq-net compresses opted-in tracks, carries them on lite-07, and serves a shared inflated copy to everything else +- [Mid-group subscriptions widen](/quest/m1/compress/app-range-widen.md) - an application range starting mid-group on a compressed track widens to frame 0 at the subscriber instead of failing with `Lagged` - [IETF extension](/quest/m1/compress/ietf.md) - moq-transport draft-16+ peers that negotiate the extension exchange compressed tracks - [JavaScript](/quest/m1/compress/js.md) - js/net publishes and consumes compressed tracks on lite-07 - [Migrate](/quest/m1/compress/migrate.md) - catalogs, stats, and timelines publish one compressed track; moq-flate, @moq/flate, and every `.z` name are gone diff --git a/quest/m1/compress/app-range-widen.md b/quest/m1/compress/app-range-widen.md new file mode 100644 index 00000000000..dd9dc712750 --- /dev/null +++ b/quest/m1/compress/app-range-widen.md @@ -0,0 +1,35 @@ +# [S] A mid-group subscription to a compressed track widens to frame 0 + +## Goal + +An application subscription whose range starts mid-group on a compressed +track succeeds: the subscriber's requesting model widens the request to frame +0 of that group before it leaves, and the reader gets the frames it asked for. +Today it fails with `Lagged`. The server never widens and keeps serving +exactly what is asked. + +## Plan + +Decided with the maintainer on 2026-10-20, from +[#5928](https://github.com/moq-dev/moq/pull/5928)'s Decision 6, which the +[epic](/quest/m1/compress/README.md)'s Ranges rule records: the subscriber +widens, never the server. + +- Route-change resume already widens to frame 0. This covers ranges an + application supplies, through the same requesting-model path rather than a + second rule. +- Widen only when the subscriber lacks the group's prefix; one that holds + frames 0..N-1 still asks from N. +- The reader still starts at the frame it asked for: the widened prefix only + feeds the inflater. + +Regression test on mock time, in Rust: a mid-group application subscribe on a +compressed track returns the requested frames instead of `Lagged`, and the +wire request starts at frame 0. Mirror it in `js/net` if +[JavaScript](/quest/m1/compress/js.md) has landed compressed tracks by then. + +Public API: none. Wire: none. + +## Required + +- [Core](/quest/m1/compress/core.md) - the compressed tracks and requesting model this fixes From 2bc6afe46d031ecf82e1b1b5e365e95d46156e3a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:32:53 -0700 Subject: [PATCH 06/17] quest: address review on spatial refusals, rung floors, and test coverage Co-Authored-By: Claude Opus 5.5 --- quest/m1/ietf-setup-validity.md | 5 +++-- quest/m1/listen-admission-test.md | 9 ++++++--- quest/m1/probe-native.md | 3 ++- quest/m1/recovery-verdicts.md | 16 +++++++++------- quest/m1/simulcast-rung-disable.md | 8 ++++++-- quest/m1/sink-restart-follow.md | 4 ++-- quest/m2/group-failed.md | 7 ++++--- quest/m2/mux-vr-fields.md | 18 +++++++++++------- quest/m2/probe/padding.md | 5 +++++ quest/m2/probe/rung-disable-js.md | 2 +- quest/m3/watch-webxr.md | 6 ++++-- 11 files changed, 53 insertions(+), 30 deletions(-) diff --git a/quest/m1/ietf-setup-validity.md b/quest/m1/ietf-setup-validity.md index d9ac4e85e22..1eecd054e89 100644 --- a/quest/m1/ietf-setup-validity.md +++ b/quest/m1/ietf-setup-validity.md @@ -34,8 +34,9 @@ Decided with the maintainer on 2026-10-20, from #6061's follow-ups: and response waits remain here. Regression tests on sim time, one per wait, each failing on main by timing -out: a revocation and a route retirement during the wait refuse the request -promptly, on drafts 14 and 16 and on 17+ where the wait differs. +out: a revoked, narrowed, and expired grant and a route retirement during +the wait each refuse the request promptly, on drafts 14 and 16 and on 17+ +where the wait differs. Public API: none. Wire: none. diff --git a/quest/m1/listen-admission-test.md b/quest/m1/listen-admission-test.md index a05b7be4265..b130a11d4de 100644 --- a/quest/m1/listen-admission-test.md +++ b/quest/m1/listen-admission-test.md @@ -15,9 +15,12 @@ Decided with the maintainer on 2026-10-20, from the follow-ups of [#5765](https://github.com/moq-dev/moq/pull/5765), which implements the deadline. -- Drive `serve_client` in process on controlled time, with an auth decider - that can stall, rather than the binary on wall time. If it cannot be driven - that way, open the smallest seam that lets it. +- Drive `moq --listen`'s listener in process on controlled time, through the + path that runs admission under the handshake deadline (#5765's + `Request::within`), with an auth decider that can stall, rather than the + binary on wall time. Calling `serve_client` alone would leave the deadline + out. If the listener cannot be driven that way, open the smallest seam that + lets it. - Match the relay's `auth_lifetime` cases so the two listeners stay alike. Public API: none. Wire: none. diff --git a/quest/m1/probe-native.md b/quest/m1/probe-native.md index 20620f29504..ac204ec5eef 100644 --- a/quest/m1/probe-native.md +++ b/quest/m1/probe-native.md @@ -41,7 +41,8 @@ mechanism wins first" step: adapters. A controller with no ProbeBW_UP phase (such as the [realtime controller](/quest/m2/quic-realtime/README.md)) can't, so its sessions keep `Report`: [padding](/quest/m2/probe/padding.md) is - browser-only. + browser-only. Nor can a session with no media in flight; the native rung + disable keeps its lowest rung encoding for that reason. Acceptance, in moq-quic's seeded simulation (`rs/moq-quic/src/tests/`, extending `Bottleneck` to step its rate) and wired into CI at least nightly: diff --git a/quest/m1/recovery-verdicts.md b/quest/m1/recovery-verdicts.md index f604c751c84..d28e5646d67 100644 --- a/quest/m1/recovery-verdicts.md +++ b/quest/m1/recovery-verdicts.md @@ -13,13 +13,14 @@ instead of looping on refetches. Rust and JS agree. From the follow-ups of [#5878](https://github.com/moq-dev/moq/pull/5878), decided with the maintainer on 2026-10-20. Rust `Recover::wants` (`rs/moq-net/src/model/resume.rs`) and JS `verdict` (`js/net/src/resume.ts`) -treat only `Old`, `Evicted`, and an application code as verdicts; every other -error is read as no verdict and refetched. An error that repeats on every copy -therefore loops. #5878's eviction reports `Evicted`, a verdict, so it no +treat `Old`, `Evicted`, and an application code as verdicts, and JS also +`TooFarBehind`, which Rust does not; every other error is read as no verdict +and refetched. An error that repeats on every copy therefore loops. #5878's eviction reports `Evicted`, a verdict, so it no longer triggers this, but other errors still can. -- Classify by error, with one list mirrored in Rust and JS. Keep the existing - rule that an error from a copy whose route failed is never a verdict. +- Classify by error, with one list mirrored in Rust and JS, settling + `TooFarBehind` on both sides. Keep the existing rule that an error from a + copy whose route failed is never a verdict. - A content error from one route may not repeat on another. Settle whether such an error may move to a different route once; it never asks the same route again. @@ -27,8 +28,9 @@ longer triggers this, but other errors still can. classification itself, not by a retry count. Regression tests on mock time, Rust and JS: a group whose every copy fails -with the same content error ends once with that error, and a route-loss -failure still recovers the group on the next route. +with the same content error ends once with that error, a route-loss failure +still recovers the group on the next route, and both languages classify every +listed error alike. Public API: none. Wire: none. diff --git a/quest/m1/simulcast-rung-disable.md b/quest/m1/simulcast-rung-disable.md index 59f00f945f1..4e1246a4bef 100644 --- a/quest/m1/simulcast-rung-disable.md +++ b/quest/m1/simulcast-rung-disable.md @@ -45,6 +45,9 @@ with padding. reservation at its ceiling. The session's probe target sums every live reservation, so it keeps probing for the stopped rung and the estimate can rise to fund it. No padding handle or burst schedule is driven from `Rung`. +- The lowest rendition never disables. Native probing retransmits in-flight + data, so a session with every rung stopped has nothing to probe with once + its last packets are acknowledged, and could never re-enable a rung. - Assign descending track priority down the renditions so the allocator fills lower rungs first; [Scope track priority](/quest/m1/track-priority-scope.md) settles how that number also orders sends. @@ -56,8 +59,9 @@ with padding. Tests with mocked time: a shrinking grant disables the top rung first and keeps the lower ones at their share; a recovering grant re-enables it only past the hysteresis and after its viewers left; a jittering grant near the -boundary does not flap the catalog. Prove one shaped-uplink run through -moq-ffi. +boundary does not flap the catalog; a grant below every boundary keeps the +lowest rung encoding. Prove one shaped-uplink run through moq-ffi, including +a path that reopens after the grant fell below the lowest rung. Public API: the shared rule in `moq_mux::rate` and whatever knobs the publishers expose for it. Wire: none; `enabled` already exists. diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index ae3dd712e55..50a49f00333 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -29,8 +29,8 @@ Readers with their own follow loop today move onto the announced request: - The TS stitching follower (`rs/moq-mux/src/container/ts/follower.rs`), if the announced request fits how it marks a break. -Readers that resolve once (`subscribe`, `fetch`) either follow the same way -or say in the PR why they stay on one instance. +`subscribe` reads until its track ends, so it follows like the rest. Only a +finite read such as `fetch` stays on the one instance it resolved. The stdout exports already do this: TS follows with `--stitch`, and the other formats ride the old instance until its route dies and its tracks error. Audit diff --git a/quest/m2/group-failed.md b/quest/m2/group-failed.md index 4f2307b607d..682a85c44a1 100644 --- a/quest/m2/group-failed.md +++ b/quest/m2/group-failed.md @@ -18,9 +18,10 @@ the lite publisher. exists by the time this starts, propose deleting the quest. - Return a handle or an event stream, not a callback. - A relay fans a track out to many subscribers, and a hostile subscriber can - fail streams on purpose. Coalesce per group so N subscribers failing one - group cost one event, and benchmark the path swept over subscribers and - groups. + fail streams on purpose. Coalesce per group, keyed by the publisher's track + and the group's sequence (the track belongs to one broadcast instance), so + N subscribers or retries failing one group cost one event, and benchmark + the path swept over subscribers and groups. - Carry it through moq-ffi and the bindings only once a binding consumer asks. diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md index a639e269691..a46f22c9da3 100644 --- a/quest/m2/mux-vr-fields.md +++ b/quest/m2/mux-vr-fields.md @@ -19,10 +19,13 @@ Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once the source's config changes. - Derive `fov` from the equirectangular bounds. - Refuse what the catalog cannot describe, since an absent field claims flat - video or plain channels: a cubemap or mesh projection, and an Opus family 2 - stream outside a square channel count of at least 4 (zeroth order, or one - carrying RFC 8486's non-diegetic stereo pair). Input RFC 8486 itself - forbids is malformed and refused the same way. + video or plain channels: a cubemap or mesh projection, so Google's + mesh-based VR180 is refused until the catalog has a mesh kind. For Opus + family 2, RFC 8486 allows `(1 + n)^2 + 2j` channels with `j` 0 or 1; only + `j = 0` with `n` of at least 1 (4, 9, 16, ... channels) maps to + `ambisonic`, and zeroth order or a non-diegetic stereo pair (1, 3, 6, 11, + ... channels) is refused. A count RFC 8486 forbids is malformed and refused + the same way. - `mp4-atom` 0.16.2 has no `st3d` or `sv3d` atom; add them in kixelated/mp4-atom. `webm-iterable` already names the Matroska elements. - An fMP4 Opus track needs the `dOps` mapping table that @@ -30,9 +33,10 @@ Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once fMP4 follows it; Matroska and raw Opus do not wait. - Exporters writing the fields back are out of scope. -Tests: a fixture per source (MP4 360 and VR180, Matroska stereo, Opus -first-order ambisonics) imports with the expected fields, and a cubemap, an -ambisonic stream with non-diegetic stereo, and a malformed one are refused. +Tests: a fixture per source (MP4 360, a 180-degree equirectangular MP4 with +`equi` bounds, Matroska stereo, Opus first-order ambisonics) imports with the +expected fields, and a cubemap, a mesh VR180, an ambisonic stream with +non-diegetic stereo, and a malformed one are refused. Public API: none beyond the catalog fields #5543 adds. Wire: none. diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index a992e5fd357..b8e2bd4002f 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -37,6 +37,9 @@ Decided with the maintainer on 2026-10-17 (see the what it says, and run `just drafts check`. - A browser sender can't see whether it is app-limited; settle how to judge it from what it sends against the estimate. +- Settle how the schedule stays within its overhead budget: how padding's + share of sent bytes is counted over time, and what a cluster does once it + would exceed the budget. Tests, on `@moq/clock`'s `Manual`: @@ -52,6 +55,8 @@ Tests, on `@moq/clock`'s `Manual`: media frame delay and deadline misses against budgets set before tuning: lowest priority can't preempt padding already in flight or queued at the bottleneck, so a frame ready just after a cluster can still wait behind it. + Assert that repeated clusters on a path with no room stay within the + overhead budget. Wire it into CI at least nightly, sharing the epic's shaped-uplink setup. ## Required diff --git a/quest/m2/probe/rung-disable-js.md b/quest/m2/probe/rung-disable-js.md index aa1b393c584..09de623431f 100644 --- a/quest/m2/probe/rung-disable-js.md +++ b/quest/m2/probe/rung-disable-js.md @@ -18,7 +18,7 @@ probing, while a browser can only probe with than tuning a JS-only one. Its decisions hold here too: catalog state follows what the encoder applied, recovery does not depend on demand, and a disabled rung keeps its reservation at its ceiling so the session keeps - probing for it. + probing for it. The lowest rendition never disables either. - Today each encoder reserves its ceiling and follows its own grant down (`js/publish/src/video/encoder.ts`). The manual `enabled` input already publishes `enabled: false` and stops encoding; this drives that state from diff --git a/quest/m3/watch-webxr.md b/quest/m3/watch-webxr.md index 80f4b82a6d1..644062b0a9f 100644 --- a/quest/m3/watch-webxr.md +++ b/quest/m3/watch-webxr.md @@ -5,7 +5,8 @@ On a headset browser with WebXR layers, `` presents a rendition whose catalog says `projection: equirectangular` in an immersive session through an `XREquirectLayer`: the horizontal span comes from `fov`, and the -layer layout from `stereo` (`left-right`, `top-bottom`, or mono). A flat +layer layout from `stereo`, mapping `left-right` to `stereo-left-right`, +`top-bottom` to `stereo-top-bottom`, and `mono` or absent to `mono`. A flat rendition, and a browser without WebXR layers, play as today. ## Plan @@ -22,7 +23,8 @@ Start once #5543 lands. only when the browser supports layers and the rendition is spatial. - Ambisonic audio playback is out of scope; propose it as a follow-up. -Tests: a mocked XR session checks the layer each catalog produces and is wired +Tests: a mocked XR session checks the layer each catalog produces, all three +layouts included, and is wired into CI; a manual run on a headset browser proves playback. Public API: possibly a `` attribute to enter or disable immersive From 9f38bae7c52abbab0555571cbdf6deb1264ea2a0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:59:01 -0700 Subject: [PATCH 07/17] quest: gate quic-qmux on the moq-gst close hangs and require it from close-tail-drain Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/close-tail-drain.md | 4 ++++ quest/m1/quic-qmux.md | 12 +++++++++++- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/quest/m1/README.md b/quest/m1/README.md index a7f549cf601..0d20e66def9 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -63,7 +63,7 @@ lite-07 stream type here. - [Controlled time](/quest/m1/time/README.md) - every crate and package reads time through moq-clock or @moq/clock, with regression tests for the changed contracts - [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding - [TS qmux in the monorepo](/quest/m1/ts-qmux.md) - `@moq/qmux` moves into `js/` and `js/net` stops depending on moq-dev/web-transport -- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - qmux runs in-tree over `moq-quic`'s stream state machine, returning credit for every byte and delivering its close frame +- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - qmux runs in-tree over `moq-quic`'s stream state machine, returning credit for every byte, delivering its close frame, and ending an unfinished read after its buffered data once the session closes - [Drop moq-native's noq feature](/quest/m1/native-noq-feature.md) - the empty default `noq` feature is removed - [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves a padding stream type that receivers read and discard, for the browser's padding probes - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it diff --git a/quest/m1/close-tail-drain.md b/quest/m1/close-tail-drain.md index d9762cfa8e0..7ecc669748b 100644 --- a/quest/m1/close-tail-drain.md +++ b/quest/m1/close-tail-drain.md @@ -76,6 +76,10 @@ moq-tokio's `quic::web` path) for the same ordering. Public API: none. Wire: none. +## Required + +- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - an unfinished qmux read ends after its buffered data once the session closes, which the drain relies on over qmux + ## Related - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - groups cut short by a session close diff --git a/quest/m1/quic-qmux.md b/quest/m1/quic-qmux.md index a8a9616c837..abfc4991d3f 100644 --- a/quest/m1/quic-qmux.md +++ b/quest/m1/quic-qmux.md @@ -70,7 +70,17 @@ are no longer pursued): a session returns connection-level credit for every byte receives, whether the app reads it, drops the stream unread, or it arrives after STOP_SENDING, so a long-lived session never stalls on MAX_DATA; and `close()` delivers its APPLICATION_CLOSE frame before the transport drops, whenever the transport stays writable -within the close bound. Test both. If +within the close bound. Test both. + +Also decided 2026-10-20 (maintainer): an unfinished read ends once the session +closes, after its buffered data, so a reader drains what already arrived and +then sees the close instead of hanging. The moq-gst tests +`a_closed_publisher_session_resumes_on_the_next_start` and +`a_moqsink_restart_keeps_pads_when_caps_arrive_at_different_times` +(`rs/moq-gst/src/source/imp.rs`) hang today with the qmux 0.6.3 teardown; +both pass on the in-tree qmux before this lands. + +If [Rust request credit](/quest/m1/rs-request-credit.md) landed first, the session also implements its non-waiting open, so a request without stream credit fails at once on qmux too. Preserve rejection of From 0823b196711d6ffa6b1dbf4ae94423e3accdb1ce Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:50:06 -0700 Subject: [PATCH 08/17] quest: split viewer targets from the m1 send target Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/probe-native.md | 7 +- quest/m1/probe-target.md | 119 ++++++++++------------------- quest/m1/simulcast-rung-disable.md | 2 +- quest/m2/probe/README.md | 10 ++- quest/m2/probe/padding.md | 7 +- quest/m2/probe/players.md | 4 +- quest/m2/probe/viewer-target.md | 87 +++++++++++++++++++++ quest/m2/probe/viewer-upswitch.md | 6 +- 9 files changed, 149 insertions(+), 95 deletions(-) create mode 100644 quest/m2/probe/viewer-target.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 0d20e66def9..8ff83ec928c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -95,7 +95,7 @@ lite-07 stream type here. - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [moq-ffi reports why a first dial fails](/quest/m1/ffi-first-dial-failure.md) - OBS names the reason while the first dial retries, as moq-c already can - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, sent and received, and a shared cluster session is fair across tenants -- [Session probe target](/quest/m1/probe-target.md) - a session probes up to its reservations or the peer's PROBE target and advertises `Increase` where a sender exists +- [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has - [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender validates headroom up to the target - [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund and resume them once probing raises the estimate - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain diff --git a/quest/m1/probe-native.md b/quest/m1/probe-native.md index e097f25d96d..eacfec12096 100644 --- a/quest/m1/probe-native.md +++ b/quest/m1/probe-native.md @@ -7,8 +7,9 @@ retransmits in-flight STREAM data (sent, unacknowledged, and not yet expired) to fill BBR3's ProbeBW_UP phase, so that phase's sample isn't app-limited and the estimate rises when the path has room. Media frames keep their deadlines, redundant bytes stay within budget, and unique goodput is counted once. -Sessions on moq-tokio and moq-uring then advertise PROBE `Increase`. A -measured no-go is a valid outcome. +Sessions on moq-tokio and moq-uring then have a sender, so +[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE +`Increase` for them. A measured no-go is a valid outcome. ## Plan @@ -68,7 +69,7 @@ maintainer instead of falling back to it. ## Required -- [Session probe target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [Session send target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements ## Related diff --git a/quest/m1/probe-target.md b/quest/m1/probe-target.md index 18d04736fab..3eb6991417d 100644 --- a/quest/m1/probe-target.md +++ b/quest/m1/probe-target.md @@ -1,79 +1,46 @@ -# [L] Session probe target +# [M] Session send target ## Goal -A moq-net session and a `js/net` connection each keep one target per -direction, so several broadcasts on one connection add up without the -application coordinating them. The send target is the larger of what the -session wants to send (the sum of its publisher reservations) and the peer's -PROBE target; the session hands it to whichever sender its transport has and -advertises PROBE `Increase` where one exists. The receive target is the sum of -its viewer handles, sent to the peer as its PROBE target. The two never mix: a -session that publishes and watches doesn't probe its uplink for what it -watches. Without a sender, behavior is today's: `Report`, and nothing probes. - -Each viewer handle also reads a grant: its share of the session's receive -estimate, so several broadcasts watched over one connection each select -against their own share instead of the whole downlink. +A moq-net session and a `js/net` connection each keep one send target: the +sum of its publisher reservations, so several broadcasts on one connection add +up without the application coordinating them. The session hands it to +whichever sender its transport has, which probes up to it. Without a sender, +behavior is today's: nothing probes. This is what the native +[rung disable](/quest/m1/simulcast-rung-disable.md) needs to resume a stopped +rendition; targets a peer asks for are the m2 +[viewer targets](/quest/m2/probe/viewer-target.md) quest. ## Plan Decided with the maintainer on 2026-10-20: this moved to m1 with -[native probing](/quest/m1/probe-native.md) and the native -[rung disable](/quest/m1/simulcast-rung-disable.md), so a native publisher's -stopped rendition can resume in the next breaking release. The rest of the -[epic](/quest/m2/probe/README.md) stays in m2. - -Decided with the maintainer on 2026-10-17 (see the epic): - -- **Publisher side: reuse the reservation.** The local send target is the sum - of the `max` ceilings of every live `Reservation` on the connection's - `bandwidth::Allocator`, including a disabled rung's and an undemanded - track's, because [rung disable](/quest/m1/simulcast-rung-disable.md) +[native probing](/quest/m1/probe-native.md) and the native rung disable, so a +native publisher's stopped rendition can resume in the next breaking release. +Later that day the maintainer split it: m1 keeps only the send target native +rung recovery needs, and viewer handles, viewer grants, the peer's PROBE +target, and advertising `Increase` moved back to m2 as +[viewer targets](/quest/m2/probe/viewer-target.md), whose consumers (players +and the viewer up-switch) are there. + +Decided with the maintainer on 2026-10-17 (see the +[epic](/quest/m2/probe/README.md)): + +- **Reuse the reservation.** The send target is the sum of the `max` ceilings + of every live `Reservation` on the connection's `bandwidth::Allocator`, + including a disabled rung's and an undemanded track's, because rung disable needs recovery that doesn't depend on demand: viewers deselect a disabled rung, so its demand goes away. Dropping a reservation removes it from the sum. No new publisher handle, and publishers need no catalog reader. Rejected: summing only demanded reservations, and an opt-in flag per reservation. -- **Viewer side: a handle per broadcast.** The subscriber session hands out a - reservation-like handle carrying a `max`, one per watched broadcast; the - session sums the live handles and sends the sum as its PROBE target. - Updating or dropping a handle changes the sum. Rejected: one target the - application sums, which pushes the multi-broadcast case onto every app. - [Players](/quest/m2/probe/players.md) hold these handles. -- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer - handle carries a grant the way a publisher `Reservation` does, splitting the - receive estimate across live handles max-min fair by `max`, the split the - send `Allocator` applies within one priority tier - (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even - cut takes all of it and leaves the rest to the others. Today every - `` on a pooled connection selects against 0.8x the whole - `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each - watcher measuring its own subscription's rate, which stays app-limited and - can't see headroom, and dividing the estimate by the watcher count, which - ignores each handle's `max`. - Handles carry no priority: subscription priorities are per track and fixed - by kind, so no per-broadcast priority exists to divide by. Add one when a - player needs to favor one broadcast over another. -- **Peer target.** A sending session probes to the larger of its own target - and the peer's PROBE target. Each hop is independent: a relay never forwards - a viewer's target upstream, and the PROBE target stays per connection, with - no per-track wire field. moq-net reads no catalog. A peer's target is - untrusted, but it only sets how high to probe: each probe scales the - current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under - congestion control. Repeated cycles can still walk the estimate up to the - path's capacity, so a huge target costs the redundant bytes of probing that - far, held to the overhead budget [native](/quest/m1/probe-native.md) sets - before tuning; a peer that subscribes to more media can already cost the - sender that much. Clamp it to the session's rate cap where one exists - ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. -- **Automatic, opt-out.** Targets are on by default; an application can - override the session's target or disable probing. -- **The sender seam.** Define the hook a transport implements to probe up to a - rate, and advertise `Increase` in SETUP only when the session has a sender - behind it. [Native](/quest/m1/probe-native.md) implements it in moq-quic, - and [padding](/quest/m2/probe/padding.md) in the browser. This quest only - needs a test sender. +- **Automatic, opt-out.** The target is on by default; an application can + override it or disable probing. +- **The sender seam.** Define the hook a transport implements to probe up to + a rate. [Native](/quest/m1/probe-native.md) implements it in moq-quic, and + [padding](/quest/m2/probe/padding.md) in the browser. This quest only needs + a test sender. Probing to a local target is invisible on the wire, so SETUP + keeps advertising `Report`; `Increase` promises to probe to the peer's + target, which viewer targets adds. Notes for the implementer: @@ -82,22 +49,14 @@ Notes for the implementer: `send_bandwidth()` themselves (`rs/moq-cli`, `rs/moq-c`, `rs/moq-ffi`), so the session can't see their reservations. Settle who owns the Rust allocator, and keep it across reconnects the way the estimate is. -- Rust sessions request PROBE today only while an owned `recv_bandwidth()` - consumer is held (`doc/concept/standard.md`); the viewer handle may subsume - that. -- Wire: none. PROBE already carries a target and SETUP the `Increase` level - (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). - Report the public API in the PR, mirrored across Rust and JS, and carry it - through moq-ffi and the bindings per the cross-package sync table. +- Wire: none. Report the public API in the PR, mirrored across Rust and JS, + and carry it through moq-ffi and the bindings per the cross-package sync + table. Tests with mocked time, Rust and JS: the send target follows reservations -being added, updated, and dropped, demanded or not; viewer handles sum into -the PROBE target sent to the peer; the session probes to the larger of its -reservations and the peer's target; a session that publishes and watches -keeps the two directions apart; viewer grants split the receive estimate -max-min fair by `max` and never sum above it; `Increase` is advertised only with a sender; -opting out sends no target and probes nothing. +being added, updated, and dropped, demanded or not; the session hands it to +its sender; opting out probes nothing; SETUP still advertises `Report`. -The sums fan out over reservations and viewer handles, so add a benchmark -sweeping both counts independently, wired into the benchmark CI, so an update -that rescans every handle shows up as a slope. +The sum fans out over reservations, so add a benchmark sweeping their count, +wired into the benchmark CI, so an update that rescans every reservation +shows up as a slope. diff --git a/quest/m1/simulcast-rung-disable.md b/quest/m1/simulcast-rung-disable.md index 4e1246a4bef..15e7db771ee 100644 --- a/quest/m1/simulcast-rung-disable.md +++ b/quest/m1/simulcast-rung-disable.md @@ -68,7 +68,7 @@ publishers expose for it. Wire: none; `enabled` already exists. ## Required -- [Session probe target](/quest/m1/probe-target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited +- [Session send target](/quest/m1/probe-target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited - [Native probing](/quest/m1/probe-native.md) - the sender that raises the estimate so a disabled rung can resume ## Related diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 5ddd669e7da..d513c207bc3 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -28,7 +28,8 @@ publisher-local padding handle: - **One session target.** The session probes to the larger of its local target and the peer's PROBE target. PROBE `Increase` is the wire signal; retransmission or padding is the mechanism. The - [target](/quest/m1/probe-target.md) quest owns it. + [send target](/quest/m1/probe-target.md) owns the local half and + [viewer targets](/quest/m2/probe/viewer-target.md) the peer's. - **Viewers are in scope.** The viewer up-switch joined the epic, since a viewer's target is the same session target sent the other way. - **moq-net stays catalog-agnostic, and each hop is independent.** A relay @@ -58,6 +59,10 @@ Decided with the maintainer on 2026-10-20: the sender stays here. - The JS publisher's rung disable split into its own quest here, since it probes with padding. +- The target then split: m1 keeps the [send target](/quest/m1/probe-target.md) + native rung recovery needs, and viewer handles, viewer grants, the peer's + PROBE target, and `Increase` came back here as + [viewer targets](/quest/m2/probe/viewer-target.md), beside their consumers. This README's own work, once the children land: @@ -73,11 +78,12 @@ This README's own work, once the children land: ## Required -- [Session probe target](/quest/m1/probe-target.md) - a session probes up to its reservations or the peer's PROBE target, sends its viewer handles as its own PROBE target, and advertises `Increase` where a sender exists +- [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has - [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender still validates headroom up to the target - [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis - [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule - [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding +- [Viewer targets](/quest/m2/probe/viewer-target.md) - a session sends its viewer handles as its PROBE target, probes to the peer's, splits the receive estimate into viewer grants, and advertises `Increase` where a sender exists - [Players set viewer targets](/quest/m2/probe/players.md) - players hold a viewer handle per watched broadcast at its highest enabled rendition's bitrate - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index b8e2bd4002f..75a3c548c45 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -8,8 +8,9 @@ send priority. On an ALR schedule, while app-limited below the target, it sends a short probe cluster at about twice the estimate, capped at the target, about every five seconds, with a follow-up probe when one validates. When the path has room the estimate rises; when it doesn't, padding stays within its -overhead and media frame-delay budgets. Such sessions then advertise PROBE -`Increase`. +overhead and media frame-delay budgets. Such sessions then have a sender, so +[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE +`Increase` for them. ## Plan @@ -61,5 +62,5 @@ Tests, on `@moq/clock`'s `Manual`: ## Required -- [Session probe target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [Session send target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements - [lite-07 padding](/quest/m1/lite07-padding.md) - the stream type the padding is sent on diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index 222672a38ac..eadf39e9eef 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -16,7 +16,7 @@ Decided with the maintainer on 2026-10-17 (see the already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. -- The handle comes from the [target](/quest/m1/probe-target.md) quest; this +- The handle comes from the [viewer targets](/quest/m2/probe/viewer-target.md) quest; this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. @@ -31,4 +31,4 @@ and yields to an application override. ## Required -- [Session probe target](/quest/m1/probe-target.md) - the per-broadcast viewer handle +- [Viewer targets](/quest/m2/probe/viewer-target.md) - the per-broadcast viewer handle diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md new file mode 100644 index 00000000000..0044edcdc38 --- /dev/null +++ b/quest/m2/probe/viewer-target.md @@ -0,0 +1,87 @@ +# [M] Viewer probe targets and grants + +## Goal + +A moq-net session and a `js/net` connection each keep a receive target: the +sum of their viewer handles, sent to the peer as the PROBE target. A sending +session probes to the larger of its own [send target](/quest/m1/probe-target.md) +and the peer's PROBE target, and advertises PROBE `Increase` where it has a +sender. The two directions never mix: a session that publishes and watches +doesn't probe its uplink for what it watches. + +Each viewer handle also reads a grant: its share of the session's receive +estimate, so several broadcasts watched over one connection each select +against their own share instead of the whole downlink. + +## Plan + +Split from the [send target](/quest/m1/probe-target.md) by the maintainer on +2026-10-20: m1 native rung recovery needs only the send target, while these +handles' consumers ([players](/quest/m2/probe/players.md) and the +[viewer up-switch](/quest/m2/probe/viewer-upswitch.md)) are in m2. + +Decided with the maintainer on 2026-10-17 (see the +[epic](/quest/m2/probe/README.md)): + +- **A viewer handle per broadcast.** The subscriber session hands out a + reservation-like handle carrying a `max`, one per watched broadcast; the + session sums the live handles and sends the sum as its PROBE target. + Updating or dropping a handle changes the sum. Rejected: one target the + application sums, which pushes the multi-broadcast case onto every app. + Players hold these handles. +- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer + handle carries a grant the way a publisher `Reservation` does, splitting the + receive estimate across live handles max-min fair by `max`, the split the + send `Allocator` applies within one priority tier + (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even + cut takes all of it and leaves the rest to the others. Today every + `` on a pooled connection selects against 0.8x the whole + `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each + watcher measuring its own subscription's rate, which stays app-limited and + can't see headroom, and dividing the estimate by the watcher count, which + ignores each handle's `max`. + Handles carry no priority: subscription priorities are per track and fixed + by kind, so no per-broadcast priority exists to divide by. Add one when a + player needs to favor one broadcast over another. +- **Peer target.** A sending session probes to the larger of its own target + and the peer's PROBE target. Each hop is independent: a relay never forwards + a viewer's target upstream, and the PROBE target stays per connection, with + no per-track wire field. moq-net reads no catalog. A peer's target is + untrusted, but it only sets how high to probe: each probe scales the + current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under + congestion control. Repeated cycles can still walk the estimate up to the + path's capacity, so a huge target costs the redundant bytes of probing that + far, held to the overhead budget [native](/quest/m1/probe-native.md) sets + before tuning; a peer that subscribes to more media can already cost the + sender that much. Clamp it to the session's rate cap where one exists + ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. +- **`Increase` only with a sender.** SETUP advertises `Increase` only when + the session has a sender behind the seam the send target defines: native + probing on moq-quic, padding in the browser. +- **Automatic, opt-out.** Targets are on by default; an application can + override them or disable probing. + +Notes for the implementer: + +- Rust sessions request PROBE today only while an owned `recv_bandwidth()` + consumer is held (`doc/concept/standard.md`); the viewer handle may subsume + that. +- Wire: none. PROBE already carries a target and SETUP the `Increase` level + (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). + Report the public API in the PR, mirrored across Rust and JS, and carry it + through moq-ffi and the bindings per the cross-package sync table. + +Tests with mocked time, Rust and JS: viewer handles sum into the PROBE target +sent to the peer; the session probes to the larger of its reservations and +the peer's target; a session that publishes and watches keeps the two +directions apart; viewer grants split the receive estimate max-min fair by +`max` and never sum above it; `Increase` is advertised only with a sender; +opting out sends no target. + +The sum fans out over viewer handles, so add a benchmark sweeping their count, +wired into the benchmark CI, so an update that rescans every handle shows up +as a slope. + +## Required + +- [Session send target](/quest/m1/probe-target.md) - the sender seam and the local target the peer's is compared against diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md index 80c0da14cd5..7471d2f5656 100644 --- a/quest/m2/probe/viewer-upswitch.md +++ b/quest/m2/probe/viewer-upswitch.md @@ -19,7 +19,7 @@ estimate. Decided with the maintainer on 2026-10-17: this joined the [probe epic](/quest/m2/probe/README.md). [Players](/quest/m2/probe/players.md) -set the viewer target, the [session](/quest/m1/probe-target.md) sends it as +set the viewer target, the [session](/quest/m2/probe/viewer-target.md) sends it as its PROBE target, and the relay's sender probes the downlink up to it; this quest makes selection act on the estimate that rises. The relay runs moq-quic, so it requires [native probing](/quest/m1/probe-native.md). If that @@ -28,7 +28,7 @@ leaving it blocked: [padding](/quest/m2/probe/padding.md) is browser-only since 2026-10-20, so the relay has no other sender. Selection reads its broadcast's viewer grant from the -[target](/quest/m1/probe-target.md) quest, not the connection's whole +[viewer targets](/quest/m2/probe/viewer-target.md) quest, not the connection's whole `estimatedRecvRate`, so several watchers on one pooled connection don't each select against the full downlink (decided with the maintainer on 2026-10-19). @@ -39,7 +39,7 @@ and audio, or selection stops discounting a probed estimate. ## Required -- [Session probe target](/quest/m1/probe-target.md) - the viewer handle the session sends as its PROBE target +- [Viewer targets](/quest/m2/probe/viewer-target.md) - the viewer handle the session sends as its PROBE target, and the relay probing up to it - [Native probing](/quest/m1/probe-native.md) - the relay validates headroom above the media it sends - [Players set viewer targets](/quest/m2/probe/players.md) - `@moq/watch` asks for its highest enabled rendition From 50c99f84d0e7157d66bee832cefa48d2f1730902 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 20:12:48 -0700 Subject: [PATCH 09/17] quest: address the #6102 merge review on padding versions, probe expiry, and failed-group bounds Co-Authored-By: Claude Opus 5.5 --- quest/m1/probe-native.md | 10 +++++++++- quest/m2/group-failed.md | 9 ++++++++- quest/m2/probe/padding.md | 17 +++++++++-------- quest/m2/probe/viewer-target.md | 7 +++++-- quest/m2/quic-deadline.md | 4 +++- 5 files changed, 34 insertions(+), 13 deletions(-) diff --git a/quest/m1/probe-native.md b/quest/m1/probe-native.md index eacfec12096..853e966d9ab 100644 --- a/quest/m1/probe-native.md +++ b/quest/m1/probe-native.md @@ -35,6 +35,13 @@ mechanism wins first" step: replace capacity with the encoder rate because the source plateaus. Keep current goodput, historical capacity and its age, and the desired rate distinct; preserving an old estimate does not discover capacity. +- **Expired means reset.** Both moq-net publishers reset a stale group's + stream as `Old`, even after its FIN while bytes await acknowledgment + (`poll_expired_while_pending`), and moq-quic never resends a reset stream's + bytes, so probing never sends past a group's expiry. Rejected: requiring + [per-stream deadlines](/quest/m2/quic-deadline.md) first. They predict + whether bytes can still arrive before the deadline, which tightens loss + recovery too, but expiry itself already reaches moq-quic as a reset. - Evaluate the IMMEDIATE_ACK extension so ACK delay doesn't obscure a short sample. - Implement the [target](/quest/m1/probe-target.md) quest's sender hook in @@ -50,7 +57,8 @@ extending `Bottleneck` to step its rate) and wired into CI at least nightly: an illustrative 2 Mbit/s source seeking 4 Mbit/s while the path steps 3 to 12 to 3 Mbit/s, on identical media traces and wire budgets. Cover keyframes, idle restart, stale high estimates, receiver credit limits, compressed ACKs, -competing CUBIC and BBR flows, and a peer target far above the path, whose +competing CUBIC and BBR flows, a group that expires mid-probe (no probe +bytes for its stream after the reset), and a peer target far above the path, whose redundant bytes stay within the overhead budget. Add a congested arm below the media bitrate behind a deep but finite queue for impairment acceptance and performance. Verify actual overflow drops, adding competing loss-based traffic if BBR diff --git a/quest/m2/group-failed.md b/quest/m2/group-failed.md index 682a85c44a1..7e0d1fa52a7 100644 --- a/quest/m2/group-failed.md +++ b/quest/m2/group-failed.md @@ -22,11 +22,18 @@ the lite publisher. and the group's sequence (the track belongs to one broadcast instance), so N subscribers or retries failing one group cost one event, and benchmark the path swept over subscribers and groups. +- Coalescing per group still leaves one notification per distinct sequence, + so a subscriber that fails every live group while the consumer is slow or + absent would grow an event queue. Keep what a track retains bounded + whatever the notification carries: coalesced latest state (such as the + newest failed sequence and a count since the last read), not a queue. - Carry it through moq-ffi and the bindings only once a binding consumer asks. Tests on mock time, Rust and JS: a group reset as `Old`, an evicted group, and -a failed stream each surface once, on lite and IETF. +a failed stream each surface once, on lite and IETF, and a long run of +distinct failed groups with no consumer reading keeps the track's retained +state constant. Public API: new, mirrored across Rust and JS. Wire: none. diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index 75a3c548c45..2725c501f1a 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -8,7 +8,8 @@ send priority. On an ALR schedule, while app-limited below the target, it sends a short probe cluster at about twice the estimate, capped at the target, about every five seconds, with a follow-up probe when one validates. When the path has room the estimate rises; when it doesn't, padding stays within its -overhead and media frame-delay budgets. Such sessions then have a sender, so +overhead and media frame-delay budgets. Such sessions on lite-07 or IETF +draft-18 and later then have a sender, so [viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE `Increase` for them. @@ -30,11 +31,11 @@ Decided with the maintainer on 2026-10-17 (see the early. - **Wire.** lite-07 reserves the padding stream type ([lite-07 padding](/quest/m1/lite07-padding.md)), matching moq-transport's - PADDING. A moq-lite peer that predates it resets the unknown stream without - closing the session, so the probe just ends. On moq-transport, send PADDING - only from draft-18 on: drafts 14 to 17 close the session on an unknown - stream type (`UniType::classify`), so refuse to pad there and keep - `Report`. Update `drafts/draft-lcurley-moq-probe.md` if the sender changes + PADDING. Pad only on lite-07 and, on moq-transport, from draft-18 on. On + lite-05 and lite-06 the peer resets every padding stream, so the estimate + can never rise, and drafts 14 to 17 close the session on an unknown stream + type (`UniType::classify`). Those sessions have no sender: refuse to pad + and keep `Report`. Update `drafts/draft-lcurley-moq-probe.md` if the sender changes what it says, and run `just drafts check`. - A browser sender can't see whether it is app-limited; settle how to judge it from what it sends against the estimate. @@ -49,8 +50,8 @@ Tests, on `@moq/clock`'s `Manual`: capped at the target; a follow-up after one that validates; an early end when the estimate falls. - The padding writer over a fake WebTransport: padding goes out at the lowest - priority on lite-07 and IETF draft-18, an old lite peer resets it and the - session stays up, and drafts 14 to 17 pad nothing. + priority on lite-07 and IETF draft-18, while lite-05, lite-06, and drafts + 14 to 17 pad nothing and negotiate `Report`. - In Chrome through a shaped link: with padding the estimate rises past the media, without it it stays frozen. On a path held below the target, report media frame delay and deadline misses against budgets set before tuning: diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md index 0044edcdc38..10310c121d1 100644 --- a/quest/m2/probe/viewer-target.md +++ b/quest/m2/probe/viewer-target.md @@ -57,7 +57,9 @@ Decided with the maintainer on 2026-10-17 (see the ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. - **`Increase` only with a sender.** SETUP advertises `Increase` only when the session has a sender behind the seam the send target defines: native - probing on moq-quic, padding in the browser. + probing on moq-quic, padding in the browser. A browser session on a version + [padding](/quest/m2/probe/padding.md) refuses (lite-05, lite-06, IETF + drafts 14 to 17) has none, so it keeps `Report`. - **Automatic, opt-out.** Targets are on by default; an application can override them or disable probing. @@ -75,7 +77,8 @@ Tests with mocked time, Rust and JS: viewer handles sum into the PROBE target sent to the peer; the session probes to the larger of its reservations and the peer's target; a session that publishes and watches keeps the two directions apart; viewer grants split the receive estimate max-min fair by -`max` and never sum above it; `Increase` is advertised only with a sender; +`max` and never sum above it; `Increase` is advertised only with a sender, and never by a browser session +on a version padding refuses; opting out sends no target. The sum fans out over viewer handles, so add a benchmark sweeping their count, diff --git a/quest/m2/quic-deadline.md b/quest/m2/quic-deadline.md index fa3bd9f5ec7..6473519d4b2 100644 --- a/quest/m2/quic-deadline.md +++ b/quest/m2/quic-deadline.md @@ -53,7 +53,9 @@ retransmitted past their deadline (must be zero), spurious resets under reordering, and probe overhead versus the default PTO. A proactive probe that raises loss or latency under any profile stays off by default. -Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. +Decided in the 2026-09-30 audit: moved to m2. No m1 quest needs it: +[native probing](/quest/m1/probe-native.md) learns of expiry from the stream +reset moq-net already sends. ## Related From e0076b1503ad4c03904cb5e8ccae3e327d3f73da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 07:20:48 -0700 Subject: [PATCH 10/17] quest: drop links to quests #6141 and #5849 completed Co-Authored-By: Claude Opus 5.5 --- quest/m1/recovery-verdicts.md | 4 ---- quest/m1/ts-reliability/stream-routes.md | 3 ++- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/quest/m1/recovery-verdicts.md b/quest/m1/recovery-verdicts.md index d28e5646d67..de9d77e6fbe 100644 --- a/quest/m1/recovery-verdicts.md +++ b/quest/m1/recovery-verdicts.md @@ -33,7 +33,3 @@ still recovers the group on the next route, and both languages classify every listed error alike. Public API: none. Wire: none. - -## Related - -- [Resumed in-flight groups](/quest/m1/resume-in-flight.md) - how long a replaced copy stays to back a handed-out group diff --git a/quest/m1/ts-reliability/stream-routes.md b/quest/m1/ts-reliability/stream-routes.md index 4cf46c13c08..7c1eaff51bd 100644 --- a/quest/m1/ts-reliability/stream-routes.md +++ b/quest/m1/ts-reliability/stream-routes.md @@ -87,7 +87,8 @@ dropped-PID owner (`Programs` under `--program all`) with every cumulative counter intact, since counters never go backward. `track` and `class` follow the current owner, empty and `Data` while dropped, and two rows never coexist under one key. Coordinate the serialized shape with -[TS health counters](/quest/m2/ts-health-stats.md). +the TS health counters [#5849](https://github.com/moq-dev/moq/pull/5849) +landed. Rust: `rs/moq-mux` TS import (and export for MPEG-2 video `pesPacket` packetization). JS: none. Draft From 3202814e6086afe9ba667d41a293d73b18e85720 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 07:35:46 -0700 Subject: [PATCH 11/17] quest: address review on the JS send target, VR pose refusals, and receive-window fairness Co-Authored-By: Claude Opus 5.5 --- quest/m1/probe-target.md | 31 +++++++++++++++++-------------- quest/m1/track-priority-scope.md | 10 +++++++++- quest/m2/mux-vr-fields.md | 16 +++++++++++----- quest/m2/probe/README.md | 2 ++ quest/m2/probe/padding.md | 10 ++++++++++ quest/m2/probe/viewer-target.md | 3 ++- quest/m3/watch-webxr.md | 3 +-- 7 files changed, 52 insertions(+), 23 deletions(-) diff --git a/quest/m1/probe-target.md b/quest/m1/probe-target.md index 3eb6991417d..f2670686c20 100644 --- a/quest/m1/probe-target.md +++ b/quest/m1/probe-target.md @@ -2,14 +2,15 @@ ## Goal -A moq-net session and a `js/net` connection each keep one send target: the -sum of its publisher reservations, so several broadcasts on one connection add -up without the application coordinating them. The session hands it to +A moq-net session keeps one send target: the sum of its publisher +reservations, so several broadcasts on one connection add up without the +application coordinating them. The session hands it to whichever sender its transport has, which probes up to it. Without a sender, behavior is today's: nothing probes. This is what the native [rung disable](/quest/m1/simulcast-rung-disable.md) needs to resume a stopped rendition; targets a peer asks for are the m2 -[viewer targets](/quest/m2/probe/viewer-target.md) quest. +[viewer targets](/quest/m2/probe/viewer-target.md) quest. The `js/net` +mirror lands with its only sender, [padding](/quest/m2/probe/padding.md). ## Plan @@ -20,7 +21,10 @@ Later that day the maintainer split it: m1 keeps only the send target native rung recovery needs, and viewer handles, viewer grants, the peer's PROBE target, and advertising `Increase` moved back to m2 as [viewer targets](/quest/m2/probe/viewer-target.md), whose consumers (players -and the viewer up-switch) are there. +and the viewer up-switch) are there. Review of +[#6102](https://github.com/moq-dev/moq/pull/6102) then moved the `js/net` +send target to padding, since without a sender it would be API with no +behavior until m2. Decided with the maintainer on 2026-10-17 (see the [epic](/quest/m2/probe/README.md)): @@ -44,16 +48,15 @@ Decided with the maintainer on 2026-10-17 (see the Notes for the implementer: -- `js/net` already owns its connection's `Allocator` - (`js/net/src/connection/reload.ts`), but Rust callers build one from - `send_bandwidth()` themselves (`rs/moq-cli`, `rs/moq-c`, `rs/moq-ffi`), so - the session can't see their reservations. Settle who owns the Rust - allocator, and keep it across reconnects the way the estimate is. -- Wire: none. Report the public API in the PR, mirrored across Rust and JS, - and carry it through moq-ffi and the bindings per the cross-package sync - table. +- Rust callers build their `Allocator` from `send_bandwidth()` themselves + (`rs/moq-cli`, `rs/moq-c`, `rs/moq-ffi`), so the session can't see their + reservations. Settle who owns it, and keep it across reconnects the way the + estimate is. +- Wire: none. Report the public API in the PR, shaped so the `js/net` mirror + can match it, and carry it through moq-ffi and the bindings per the + cross-package sync table. -Tests with mocked time, Rust and JS: the send target follows reservations +Tests with mocked time, in Rust: the send target follows reservations being added, updated, and dropped, demanded or not; the session hands it to its sender; opting out probes nothing; SETUP still advertises `Report`. diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 61f337dc37d..0ab687b2f5b 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -95,6 +95,12 @@ once, when its header decodes: - With fairness on, rank received groups within their broadcast's domain first, as sends are, so one broadcast's priorities never evict another's partial groups. +- Ranking inside domains still leaves the session-wide window to share, so + a broadcast that fills it would block every other one. Add a fair domain + tier ahead of the ranks, mirroring the byte-fair send tier: a stuck window + evicts from the domain holding the most beyond an even share of the window + across the domains with partial groups, then by rank within that domain. + A broadcast that fills the window alone may keep it until another arrives. - Re-rank a receive stream when its subscription's priority or group order changes, instead of keeping the rank from its header. @@ -130,7 +136,9 @@ broadcasts on one session with fairness on: neither starves, a downstream 255 does not change the upstream order, and with fairness off the strict order is unchanged. On the receive side, with fairness on, a high priority in one broadcast never makes a stuck window evict another broadcast's partial groups -first, and a priority or order update moves an already-ranked stream. The io_uring workers apply the same setting. Move +first, a broadcast that filled the window before another began receiving +yields down to its even share instead of blocking the newcomer, and a priority +or order update moves an already-ranked stream. The io_uring workers apply the same setting. Move `doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md` (IETF 128 maps to 127) to the new range and mapping. diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md index a46f22c9da3..b4ce34d08bd 100644 --- a/quest/m2/mux-vr-fields.md +++ b/quest/m2/mux-vr-fields.md @@ -11,13 +11,18 @@ boxes or elements imports as today. ## Plan -Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once -#5543 lands. +Decided with the maintainer on 2026-10-20, from #5543's follow-ups. #5543 has +landed the fields. - The fields are live state like `color` (#5543), so fill them the way the importers fill color (`rs/moq-mux/src/codec/color.rs`) and update them when the source's config changes. -- Derive `fov` from the equirectangular bounds. +- Derive `fov` from the equirectangular bounds. The catalog's `fov` is a + longitude span centred straight ahead over the full 180 degrees of latitude + (`rs/hang/src/catalog/video/projection.rs`), so refuse asymmetric left and + right bounds, any top or bottom crop, and a nonzero pose (`sv3d`'s `prhd`, + Matroska `ProjectionPoseYaw`/`Pitch`/`Roll`): importing them would silently + recenter or rotate the video. - Refuse what the catalog cannot describe, since an absent field claims flat video or plain channels: a cubemap or mesh projection, so Google's mesh-based VR180 is refused until the catalog has a mesh kind. For Opus @@ -35,8 +40,9 @@ Decided with the maintainer on 2026-10-20, from #5543's follow-ups. Start once Tests: a fixture per source (MP4 360, a 180-degree equirectangular MP4 with `equi` bounds, Matroska stereo, Opus first-order ambisonics) imports with the -expected fields, and a cubemap, a mesh VR180, an ambisonic stream with -non-diegetic stereo, and a malformed one are refused. +expected fields, and a cubemap, a mesh VR180, an equirectangular source with +asymmetric bounds, a vertical crop, or a nonzero pose, an ambisonic stream +with non-diegetic stereo, and a malformed one are refused. Public API: none beyond the catalog fields #5543 adds. Wire: none. diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index d513c207bc3..593c73342f6 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -63,6 +63,8 @@ Decided with the maintainer on 2026-10-20: native rung recovery needs, and viewer handles, viewer grants, the peer's PROBE target, and `Increase` came back here as [viewer targets](/quest/m2/probe/viewer-target.md), beside their consumers. + The `js/net` send target moved to [padding](/quest/m2/probe/padding.md), its + only sender. This README's own work, once the children land: diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index 2725c501f1a..df309c56f16 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -24,6 +24,13 @@ Decided with the maintainer on 2026-10-17 (see the implements the [target](/quest/m1/probe-target.md) quest's sender hook in `js/net`. Decided 2026-10-20: browser-only. moq-quic is the only Rust transport, so no native session needs it. +- **The browser's send target.** The `js/net` mirror of the + [send target](/quest/m1/probe-target.md) lands here, beside the sender that + uses it: the same reservation sum, opt-out, and sender seam, matching the + Rust API. `js/net` already owns its connection's `Allocator` + (`js/net/src/connection/reload.ts`). Moved here in review of + [#6102](https://github.com/moq-dev/moq/pull/6102), so m1 ships no browser + target without a sender. - **WebRTC's schedule.** Model it on GoogCC's `ProbeController` ALR probing. Rejected: [#5863](https://github.com/moq-dev/moq/pull/5863)'s exponential backoff to 60 s, which leaves a rendition waiting up to a minute after the @@ -45,6 +52,9 @@ Decided with the maintainer on 2026-10-17 (see the Tests, on `@moq/clock`'s `Manual`: +- The send target: it follows reservations being added, updated, and + dropped, demanded or not, reaches the padding sender, and opting out pads + nothing, as in the Rust tests. - The schedule: nothing while media meets the target or the sender isn't app-limited; a cluster about every five seconds at twice the estimate, capped at the target; a follow-up after one that validates; an early end diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md index 10310c121d1..83fee5893ba 100644 --- a/quest/m2/probe/viewer-target.md +++ b/quest/m2/probe/viewer-target.md @@ -5,7 +5,8 @@ A moq-net session and a `js/net` connection each keep a receive target: the sum of their viewer handles, sent to the peer as the PROBE target. A sending session probes to the larger of its own [send target](/quest/m1/probe-target.md) -and the peer's PROBE target, and advertises PROBE `Increase` where it has a +(in `js/net`, the one [padding](/quest/m2/probe/padding.md) adds) and the +peer's PROBE target, and advertises PROBE `Increase` where it has a sender. The two directions never mix: a session that publishes and watches doesn't probe its uplink for what it watches. diff --git a/quest/m3/watch-webxr.md b/quest/m3/watch-webxr.md index 644062b0a9f..b3ce89065ca 100644 --- a/quest/m3/watch-webxr.md +++ b/quest/m3/watch-webxr.md @@ -12,8 +12,7 @@ rendition, and a browser without WebXR layers, play as today. ## Plan Decided with the maintainer on 2026-10-20, from the follow-ups of -[#5543](https://github.com/moq-dev/moq/pull/5543), which adds the fields. -Start once #5543 lands. +[#5543](https://github.com/moq-dev/moq/pull/5543), which landed the fields. - `XRMediaBinding` layers take an `HTMLVideoElement`, which `` does not use (it decodes with WebCodecs), so an `XRWebGLBinding` layer fed From 3667e58cf7f6493d22959e5636af54b51a213fb6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 11:46:42 -0700 Subject: [PATCH 12/17] quest: keep subscribe pinned unless its output marks a restart Co-Authored-By: Claude Opus 5.5 --- quest/m1/sink-restart-follow.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index 77696ad483c..d7794f174dd 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -29,12 +29,13 @@ Readers with their own follow loop today move onto `announced_broadcast`: - The TS stitching follower (`rs/moq-mux/src/container/ts/follower.rs`), if `announced_broadcast` fits how it marks a break. -`subscribe` reads until its track ends, so it follows like the rest. Only a -finite read such as `fetch` stays on the one instance it resolved. +A finite read such as `fetch` stays on the one instance it resolved. -The stdout exports already do this: TS follows with `--stitch`, and the other -formats ride the old instance until its route dies and its tracks error. Audit -and fix the rest the same way: +The stdout exports (`subscribe`) already follow only where the output marks +the break: TS with `--stitch`. Every other format, and TS without `--stitch`, +stays pinned to the old instance until its route dies and its tracks error, +never concatenating independent instances into one stream. Keep that rule. +Audit and fix the rest the same way: - `export hls`: `moq-hls`'s server resolves per request; check that a restart moves new requests to the new instance and how a playlist marks the break From 1272c86c9f4b183581cfa299c912cb81ba1e4a87 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 17:36:52 -0700 Subject: [PATCH 13/17] quest: address review on restart failure, replica order, receive fairness, and probe targets Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 4 ++-- quest/m1/probe-target.md | 3 ++- quest/m1/track-priority-scope.md | 12 +++++++++--- quest/m2/probe/viewer-target.md | 5 +++-- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/quest/m1/README.md b/quest/m1/README.md index a5435f106e6..017d7073fac 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -55,7 +55,7 @@ lite-07 stream type here. - [Epoch correctness](/quest/m0/broadcast-epoch/README.md) - publisher identity, duplicate suppression, and catalog pinning gate the breaking cut -- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - every moq-cli and moq-gst reader, moqsrc and `moq play` included, follows instances through `announced_broadcast` and an epochless `Restart` where its output can mark it, and fails loud otherwise +- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - every moq-cli and moq-gst reader, moqsrc and `moq play` included, follows instances through `announced_broadcast` and an epochless `Restart` where its output can mark it; otherwise it stays on the old instance and fails once that route dies - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [Controlled time](/quest/m1/time/README.md) - every crate and package reads time through moq-clock or @moq/clock, with regression tests for the changed contracts @@ -104,7 +104,7 @@ lite-07 stream type here. - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end -- [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes with every frame once, on lite-07 and on moq-transport +- [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes with every frame exactly once and in order, on lite-07 and on moq-transport - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence - [Recovery verdicts](/quest/m1/recovery-verdicts.md) - group recovery refetches only on errors a new copy can fix, so a repeating error ends the group instead of looping - [Rust resume holds a declared end](/quest/m1/resume-rust-end.md) - a resumed Rust track keeps a declared end across copies, dedupes flapping copies, and judges retention inside the reader's window diff --git a/quest/m1/probe-target.md b/quest/m1/probe-target.md index f2670686c20..8d05ca4356a 100644 --- a/quest/m1/probe-target.md +++ b/quest/m1/probe-target.md @@ -58,7 +58,8 @@ Notes for the implementer: Tests with mocked time, in Rust: the send target follows reservations being added, updated, and dropped, demanded or not; the session hands it to -its sender; opting out probes nothing; SETUP still advertises `Report`. +its sender; opting out probes nothing; SETUP still advertises `Report`; after +a reconnect, reservation changes still move the new session's target. The sum fans out over reservations, so add a benchmark sweeping their count, wired into the benchmark CI, so an update that rescans every reservation diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 0ab687b2f5b..fa7da515250 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -43,8 +43,9 @@ default so a single-tenant deployment keeps strict priority across the link. A tenant-keyed domain (one bucket per customer, however many broadcasts they run) needs the tenant identity from the auth line first and is a later refinement of the same tier, not a different design. Opening more -subscriptions or broadcasts must never buy more bandwidth than the bucket -allows. +subscriptions must never buy a broadcast more than its bucket allows. Until +tenant keying lands, a peer that opens more broadcasts does get more shares, +on send and receive alike; tenant keying is what closes that. Decided 2026-10-08: the signed priority type lands here, so the priority API breaks once instead of twice. Subscribe ranges owns group order, so this quest @@ -94,13 +95,18 @@ once, when its header decodes: - With fairness on, rank received groups within their broadcast's domain first, as sends are, so one broadcast's priorities never evict another's - partial groups. + partial groups. Received FETCH streams map to a domain through the same + carrier the send side settles, or fall out with it if the goal narrows to + subscription delivery. - Ranking inside domains still leaves the session-wide window to share, so a broadcast that fills it would block every other one. Add a fair domain tier ahead of the ranks, mirroring the byte-fair send tier: a stuck window evicts from the domain holding the most beyond an even share of the window across the domains with partial groups, then by rank within that domain. A broadcast that fills the window alone may keep it until another arrives. + A full window admits no newcomer's bytes, so settle what enters a broadcast + into the fair set first (its subscription, or the header of a stream the + stuck-window eviction made room for), and test that it gets in. - Re-rank a receive stream when its subscription's priority or group order changes, instead of keeping the rank from its header. diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md index 83fee5893ba..92f6cb12a12 100644 --- a/quest/m2/probe/viewer-target.md +++ b/quest/m2/probe/viewer-target.md @@ -67,8 +67,9 @@ Decided with the maintainer on 2026-10-17 (see the Notes for the implementer: - Rust sessions request PROBE today only while an owned `recv_bandwidth()` - consumer is held (`doc/concept/standard.md`); the viewer handle may subsume - that. + consumer is held (`doc/concept/standard.md`). If the viewer handle subsumes + that, migrate those callers in the same change; a held consumer never + silently stops requesting PROBE. - Wire: none. PROBE already carries a target and SETUP the `Increase` level (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). Report the public API in the PR, mirrored across Rust and JS, and carry it From f3cd70d5d1217e88b5e9db3b1f061858eb3550f4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 17:57:50 -0700 Subject: [PATCH 14/17] quest: rung disable needs a sender, so iroh and CUBIC sessions keep every rung Co-Authored-By: Claude Opus 5.5 --- quest/m1/simulcast-rung-disable.md | 8 +++++++- quest/m2/probe/padding.md | 6 ++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/quest/m1/simulcast-rung-disable.md b/quest/m1/simulcast-rung-disable.md index 15e7db771ee..1a765439179 100644 --- a/quest/m1/simulcast-rung-disable.md +++ b/quest/m1/simulcast-rung-disable.md @@ -48,6 +48,11 @@ with padding. - The lowest rendition never disables. Native probing retransmits in-flight data, so a session with every rung stopped has nothing to probe with once its last packets are acknowledged, and could never re-enable a rung. +- Disable only on a session with a sender. Native probing needs moq-quic's + BBR3, so a session without it (iroh on noq, or moq-quic configured for + CUBIC or no congestion control) could never raise its estimate to resume a + stopped rung; there every rung keeps encoding and follows its grant down, + as today. Padding stays browser-only rather than covering these. - Assign descending track priority down the renditions so the allocator fills lower rungs first; [Scope track priority](/quest/m1/track-priority-scope.md) settles how that number also orders sends. @@ -60,7 +65,8 @@ Tests with mocked time: a shrinking grant disables the top rung first and keeps the lower ones at their share; a recovering grant re-enables it only past the hysteresis and after its viewers left; a jittering grant near the boundary does not flap the catalog; a grant below every boundary keeps the -lowest rung encoding. Prove one shaped-uplink run through moq-ffi, including +lowest rung encoding; a session without a sender never disables a rung. +Prove one shaped-uplink run through moq-ffi, including a path that reopens after the grant fell below the lowest rung. Public API: the shared rule in `moq_mux::rate` and whatever knobs the diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index df309c56f16..74eda97b146 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -22,8 +22,10 @@ Decided with the maintainer on 2026-10-17 (see the data instead ([native probing](/quest/m1/probe-native.md)). Padding is ordinary stream data that any controller counts and paces, and it implements the [target](/quest/m1/probe-target.md) quest's sender hook in - `js/net`. Decided 2026-10-20: browser-only. moq-quic is the only Rust - transport, so no native session needs it. + `js/net`. Decided 2026-10-20: browser-only. A native session without + native probing (iroh on noq, or moq-quic under CUBIC) has no sender, so + [native rung disable](/quest/m1/simulcast-rung-disable.md) never stops a + rung there. - **The browser's send target.** The `js/net` mirror of the [send target](/quest/m1/probe-target.md) lands here, beside the sender that uses it: the same reservation sum, opt-out, and sender seam, matching the From 0e6a2526862b285d88bbdb216e0715e026819851 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:04:15 -0700 Subject: [PATCH 15/17] quest: native probing requires evicted-group staleness; name which native backends probe Co-Authored-By: Claude Opus 5.5 --- quest/m1/probe-native.md | 5 ++++- quest/m2/probe/README.md | 6 ++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/quest/m1/probe-native.md b/quest/m1/probe-native.md index 853e966d9ab..8ccd6929279 100644 --- a/quest/m1/probe-native.md +++ b/quest/m1/probe-native.md @@ -38,7 +38,9 @@ mechanism wins first" step: - **Expired means reset.** Both moq-net publishers reset a stale group's stream as `Old`, even after its FIN while bytes await acknowledgment (`poll_expired_while_pending`), and moq-quic never resends a reset stream's - bytes, so probing never sends past a group's expiry. Rejected: requiring + bytes, so probing never sends past a group's expiry. A group the cache + evicted is only judged once [evicted-group staleness](/quest/m1/evicted-group-stale.md) + lands, so it is required, with a test that evicts a group mid-probe. Rejected: requiring [per-stream deadlines](/quest/m2/quic-deadline.md) first. They predict whether bytes can still arrive before the deadline, which tightens loss recovery too, but expiry itself already reaches moq-quic as a reset. @@ -78,6 +80,7 @@ maintainer instead of falling back to it. ## Required - [Session send target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - an evicted group's stream resets once stale, so probing never retransmits it ## Related diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 593c73342f6..6b8f86a2b9d 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -53,8 +53,10 @@ Decided with the maintainer on 2026-10-20: moved to m1, so Rust, FFI, and OBS publishers recover a stopped rendition in the next breaking release. Their rung disable needs the target and native probing, not padding. -- Padding is browser-only (WebTransport in `js/net`): moq-quic is the only - Rust transport, so no native session needs it. lite-07 reserves its stream +- Padding is browser-only (WebTransport in `js/net`). moq-quic with BBR3 is + the only native backend with a probing hook; other native backends (iroh + on noq, moq-quic under CUBIC) have no sender, keep `Report`, and never + disable a rung. lite-07 reserves its stream type before the cut ([lite-07 padding](/quest/m1/lite07-padding.md)), and the sender stays here. - The JS publisher's rung disable split into its own quest here, since it From e21672f490f4b6c7362b047146941f4df5df66dd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:10:06 -0700 Subject: [PATCH 16/17] quest: VR importers refuse stereo layouts the catalog cannot represent Co-Authored-By: Claude Opus 5.5 --- quest/m2/mux-vr-fields.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md index b4ce34d08bd..84cfaaf65ca 100644 --- a/quest/m2/mux-vr-fields.md +++ b/quest/m2/mux-vr-fields.md @@ -25,7 +25,10 @@ landed the fields. recenter or rotate the video. - Refuse what the catalog cannot describe, since an absent field claims flat video or plain channels: a cubemap or mesh projection, so Google's - mesh-based VR180 is refused until the catalog has a mesh kind. For Opus + mesh-based VR180 is refused until the catalog has a mesh kind. The same + goes for any stereo packing or eye order beyond mono, left-right, and + top-bottom (such as `st3d` right-left, or a Matroska right-eye-first, + interleaved, or anaglyph `StereoMode`), each with a fixture. For Opus family 2, RFC 8486 allows `(1 + n)^2 + 2j` channels with `j` 0 or 1; only `j = 0` with `n` of at least 1 (4, 9, 16, ... channels) maps to `ambisonic`, and zeroth order or a non-diegetic stereo pair (1, 3, 6, 11, From a041f488c134a4133680bd57f01a36018d713ecf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:15:56 -0700 Subject: [PATCH 17/17] quest: schedule evicted-group staleness before native probing Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/README.md b/quest/m1/README.md index 017d7073fac..bbf5a6796dc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -87,6 +87,7 @@ lite-07 stream type here. - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, sent and received, and a shared cluster session is fair across tenants - [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets - [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender validates headroom up to the target - [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund and resume them once probing raises the estimate - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain @@ -102,7 +103,6 @@ lite-07 stream type here. - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 -- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end - [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes with every frame exactly once and in order, on lite-07 and on moq-transport - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence