From 5d4979c17851503ff54a20d84e1a5aebd62949f8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:16:40 -0700 Subject: [PATCH 1/5] quest: apply the 2026-10-08 quest-tree audit Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 1 + quest/m0/broadcast-epoch/README.md | 11 +- quest/m0/broadcast-epoch/apps.md | 9 +- quest/m0/broadcast-epoch/bindings.md | 15 ++- quest/m0/broadcast-epoch/restart.md | 34 ++++-- quest/m0/broadcast-epoch/ts-restart.md | 11 +- quest/m0/qmux-credit-upstream.md | 14 +++ quest/m0/qmux-credit.md | 9 +- quest/m1/README.md | 1 + quest/m1/archive/dvr.md | 5 +- quest/m1/archive/replay-catalog.md | 6 + quest/m1/assets-release.md | 4 +- quest/m1/audio-encode-audiotoolbox.md | 5 +- quest/m1/audio-warmup.md | 6 +- quest/m1/bbr-ack-cleanup.md | 2 +- quest/m1/c/package.md | 1 + quest/m1/c/retire.md | 10 +- quest/m1/cache-max-age.md | 14 +-- quest/m1/cluster-routing/README.md | 2 +- quest/m1/cluster-routing/multi-cdn.md | 25 ++-- quest/m1/cluster-routing/routes.md | 21 +++- quest/m1/cmaf-frame-timestamp.md | 11 +- quest/m1/cmaf-sample-defaults.md | 2 +- quest/m1/e2ee/README.md | 2 + quest/m1/e2ee/cli.md | 3 +- quest/m1/gpu-runner.md | 2 +- quest/m1/hop-aligned-import.md | 15 ++- quest/m1/ietf-object-gaps.md | 22 ++-- quest/m1/iroh-capsule-bump.md | 3 + quest/m1/js-fetch.md | 5 + quest/m1/js-group-handover.md | 12 +- quest/m1/js-publish-timestamp.md | 7 +- quest/m1/lite-untimed.md | 27 ++--- quest/m1/media-audio-tone.md | 1 + quest/m1/obs-moq-video/vpx-obs.md | 2 +- ...relay-cpu-is-vdso-clock-reads-the-drive.md | 16 +-- quest/m1/perf/announce-replay.md | 4 + quest/m1/perf/group-cost.md | 3 +- quest/m1/publish-audio-channel-count.md | 1 + quest/m1/quic/bbr-app-limited-edges.md | 6 +- quest/m1/quic/bbr-app-limited.md | 8 +- quest/m1/quic/shard.md | 2 +- quest/m1/rs2ts/sans-io/lite.md | 7 +- quest/m1/rust-continuous.md | 32 +++++ quest/m1/rust-untimed-default.md | 4 +- quest/m1/stats/README.md | 6 +- quest/m1/stats/js.md | 7 ++ quest/m1/stats/rust.md | 7 ++ quest/m1/stats/schema.md | 4 +- quest/m1/subscribe-live-time.md | 8 +- quest/m1/subscribe-ranges/ietf.md | 6 +- quest/m1/subscribe-ranges/model.md | 4 + quest/m1/test-flakes-2/impaired-handshake.md | 4 + quest/m1/untimed-decisions.md | 4 +- quest/m2/README.md | 1 - quest/m2/announce-shapes.md | 109 ------------------ quest/m2/catalog-tracks.md | 7 ++ quest/m2/gpu-release.md | 8 +- quest/m2/intra-refresh/consumer-warmup.md | 11 +- quest/m2/native-enabled.md | 4 + quest/m2/quic-bbr-loss-parity.md | 4 + quest/m2/quic-ecn.md | 4 +- quest/m2/quic-qmux.md | 1 + quest/m2/rtsp-import.md | 4 +- quest/m2/teleop/robot.md | 6 +- quest/m2/tls-listener-mtls.md | 4 + quest/m2/video-vaapi.md | 6 +- quest/m3/cut-through/README.md | 9 +- quest/m3/cut-through/loss-delay.md | 8 +- quest/m3/cut-through/transport.md | 29 ++--- quest/m3/ladder/README.md | 6 +- quest/m3/ladder/controller.md | 18 +-- quest/m3/ladder/fetch.md | 6 +- quest/m3/teleop-mavlink.md | 8 +- 74 files changed, 417 insertions(+), 289 deletions(-) create mode 100644 quest/m0/qmux-credit-upstream.md create mode 100644 quest/m1/rust-continuous.md delete mode 100644 quest/m2/announce-shapes.md diff --git a/quest/m0/README.md b/quest/m0/README.md index fe50d085c55..091550f5269 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -46,6 +46,7 @@ a published `@moq/watch` break. - [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [Prefix route fronts](/quest/m0/prefix-route-fronts.md) - a prefix route cannot be made to mint one front per requested path - [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines +- [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on moq-dev/web-transport#412 and #413 to merge and ship, which qmux credit bumps to - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh route epoch, the newest wins a path, and only routes with the same epoch resume a subscription - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 4364ad7c2dc..c733e0e3ceb 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -6,10 +6,13 @@ A path and the epoch on its route are the only content identity, and no first-party publisher reuses a pair for different content. Only routes with the same epoch resume a subscription from the first frame it lacks; a route without one keeps its subscriptions until it goes. So epochs are what make -failover seamless, and a restart is a new epoch at the same path: the newest -epoch wins new requests and announce consumers see a `Restart` (or an end -and start on older versions), so viewers re-request rather than stall on a -replaced broadcast. Subscriptions already on the old one stay until the +failover seamless. Routes without an epoch never splice (maintainer, +2026-10-08): a `Restart` (or an end and start on older versions) tells every +downstream subscriber, downstream relays included, to drop its copy of the +old source and resubscribe fresh. A restart is a new epoch at the same +path: the newest epoch wins new requests and announce consumers see that +`Restart`, so viewers re-request rather than stall on a replaced +broadcast. Subscriptions already on the old one stay until the application drops them or its route goes. Without an epoch, a restarted publisher on the same hop chain as its lingering old session wins at once (the newest announcement breaks the tie), but one on a different chain of diff --git a/quest/m0/broadcast-epoch/apps.md b/quest/m0/broadcast-epoch/apps.md index 3c758d3b036..13e27991125 100644 --- a/quest/m0/broadcast-epoch/apps.md +++ b/quest/m0/broadcast-epoch/apps.md @@ -15,7 +15,14 @@ switches to a republish within an RTT. Logs show the epoch. archive replay, WHEP import, and transcode output; moq-boy; `@moq/publish`, the clock, and moq-boy's viewer feedback. What remains is below. - Watch sides handle "the broadcast changed" as a fresh catalog and decoder - reset. Test a republish mid-playback in the browser and native players. + reset. Players (`moq play`, `@moq/watch`, demo/web) start on `Start`, + restart on `Restart`, and stop on `End`, so a re-price or a same-epoch + failover (an `Update`) never restarts playback. #4970, which drove them + from announcements, closed unmerged. Test a republish mid-playback in the + browser and native players. - Update `doc/bin/cli.md` and every example invocation that shows a published path. +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - the `Restart` announce event the players follow diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index d1c883b7531..dddf0d1a1f7 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -4,15 +4,19 @@ `moq-ffi` and the py, swift, kt, go, and dart wrappers can announce an epoch like Rust, with a minting helper. The generated C and C++ bindings pick it up from moq-ffi; libmoq gets no new API. The epoch on an announced route is -readable, and a publisher can pass an explicit one. The -reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. +readable, and a publisher can pass an explicit one. Every wrapper surfaces +the `Restart` announce event. The reconnect counter `session.epoch()` is +renamed so "epoch" has one meaning. ## Plan - Expose the parsed epoch (text and time) and an explicit-epoch publish argument. Keep the surface to what a binding consumer needs. -- Rename `session.epoch()` in every binding (for example to `connects()`). - That is a break. +- Rename the reconnect counter, `moq_tokio::Connection::epoch()` and + `session.epoch()` in every binding (for example to `connects()`). That is + a break. +- `MoqAnnounceEvent::Restart` lands in moq-ffi with + [Restart](/quest/m0/broadcast-epoch/restart.md); each wrapper maps it. - Update `doc/lib/{py,swift,kt,go,dart}` per the cross-package sync table, and run `just test smoke --all`. @@ -23,3 +27,6 @@ Decided in the 2026-10-05 audit: this lands before the same wrappers and keeps `epoch()` today. It rebases onto this quest and adopts the epoch surface and the rename, so the wrappers break once each. +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - adds the `Restart` announce event the wrappers expose diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index 097a1d36b65..94f0675628a 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -16,6 +16,13 @@ route goes, so the application decides whether to stay on the old broadcast or follow the new one. New requests resolve the current winner and never join a front pinned to a replaced route. +Routes without an epoch never splice (maintainer, 2026-10-08). A `Restart` +(or an `End` then `Start` on older wires) tells every downstream subscriber, +a downstream relay included, to drop its copy of the old source and +resubscribe fresh. A copy resumes or splices only across routes with an +identical epoch, so the old copy's cached groups never reach a subscriber of +the new source. + ## Plan Decided in planning (2026-10-07, from #4970's review): @@ -71,7 +78,11 @@ Decided in planning (2026-10-07, from #4970's review): stays on its first route (`pick`'s `Some(None)` arm in `origin.rs`, the module docs in `model/front.rs`), so a request joins it even after the winner changed, and a player that re-requests gets the dead broadcast - again. JS already swaps per path. + again. JS already swaps per path. The same holds when the route entry + stays put but its source changed behind it, as for a downstream relay + whose upstream session delivers the `Restart` (or END then START): the + relay retires that copy for new requests and opens a fresh one, never + joining or resuming into the old copy. - **Wire.** lite-07 (`moq-lite-07-wip`) gains an explicit restart message on the announce stream. Older lite versions and moq-transport send `ANNOUNCE_END` then `ANNOUNCE_START` for a source change, a new rule for a @@ -86,13 +97,15 @@ Decided in planning (2026-10-07, from #4970's review): lite-07 changelog's "ends subscriptions to the older one". The rule that a subscription between routes without an Epoch "stays on its route and ends with it" holds as written. -- **Players.** `moq play` (#4970) and `@moq/watch` restart on `Restart` - instead of treating every epochless `Update` as a restart, so a re-price - that keeps its winner, or a same-epoch failover, no longer restarts - playback. An epochless drain onto a different entry still does. - `moqsrc` (planned in #4960) switches on `Restart` too. On lite-06 and +- **Players** follow `Restart` in [Apps](/quest/m0/broadcast-epoch/apps.md); + `moqsrc` (planned in #4960) switches on it too. On lite-06 and moq-transport, a pair not coalesced reaches players as `End` then `Start`: a stop, then a fresh play. +- **Every Rust consumer** of announce events handles `Restart` in the same + PR, since the enum match is exhaustive: moq-ffi's `MoqAnnounceEvent` gains + `Restart` (its wrappers follow in + [Bindings](/quest/m0/broadcast-epoch/bindings.md)), and moq-c, moq-stats, + moq-relay, moq-room, moq-boy, moq-cli, moq-rtc, and moq-tokio map it. - **Rejected** (in #5013): `@moq/watch` resubscribing on `Internal` or `SessionClosed` (#4999), since players recover on announcements, not errors; announcing only once the old front dies, since viewers stay blank @@ -118,8 +131,11 @@ on `B`. Add a regression case where an epochless replacement at equal cost and chain length, on a different hop chain whose hash is the larger one (the pinned `pool/job-0` pair in `origin.rs` has one), competes with the lingering old route: no `Restart` and new requests stay on the old route until it is -withdrawn, then `Restart` and a re-request lands on the replacement. Run -`just drafts check` and `just test interop --all`. +withdrawn, then `Restart` and a re-request lands on the replacement. With +mocked time, a lite-06 relay chain where an epochless publisher restarts: the +downstream relay's cached groups from the old instance never reach a new +subscriber mixed with the new instance's groups. Run `just drafts check` and +`just test interop --all`. Docs: update `doc/concept/moq-lite.md` (publisher epochs) and `doc/lib/{rs,js}` announce sections inline, plus `doc/bin/rtmp.md`, @@ -134,4 +150,4 @@ send END then START where they sent UPDATE for a source change. ## Related -- [Apps](/quest/m0/broadcast-epoch/apps.md) - #4970 drives `@moq/watch` and `moq play` from announcements, which this relies on +- [Apps](/quest/m0/broadcast-epoch/apps.md) - the players that follow `Restart` diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index 1633ab9f0e1..4db2980675f 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -20,8 +20,9 @@ and a flagged forward jump publishes break markers and carries on. Decided (maintainer, 2026-09-30): - A rewind is new content, so it is always a new broadcast at a new epoch, - never a continuation of the old one. Viewers follow it because the newest - epoch wins the path. + never a continuation of the old one. The newest epoch wins the path, and + viewers follow the `Restart` announce it produces (an end and start on + older versions). - `decode` stops at the flagged rewind and reports it. The caller finishes the old broadcast (a clean end, not an abort, so its viewers read to its end), publishes a new broadcast at the same path, minting a fresh epoch, and calls @@ -42,8 +43,10 @@ connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. Public API: breaking in moq-mux, `ts::Import::decode` reports a restart and `restart` is new. Wire: none. - - ## Closes - [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import + +## Related + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event viewers follow onto the new epoch diff --git a/quest/m0/qmux-credit-upstream.md b/quest/m0/qmux-credit-upstream.md new file mode 100644 index 00000000000..0a93b670dd9 --- /dev/null +++ b/quest/m0/qmux-credit-upstream.md @@ -0,0 +1,14 @@ +# [XS] web-transport releases the qmux credit and close fixes + +## Goal + +Waiting on moq-dev/web-transport: the qmux credit and close fixes merge and +ship in a 0.6.x release and a 0.5.x release after 0.5.2. Check with +`gh pr view 412 -R moq-dev/web-transport` (0.6, targets `main`), the same for +413 (0.5, targets `qmux-v0.5.x`), and the published `qmux` versions on +crates.io. Advance it by pushing the upstream review along. Delete this quest +once both releases are out. + +## Related + +- [qmux credit](/quest/m0/qmux-credit.md) - bumps `main` and `release` once these ship diff --git a/quest/m0/qmux-credit.md b/quest/m0/qmux-credit.md index 7fa52101703..a4329d5996c 100644 --- a/quest/m0/qmux-credit.md +++ b/quest/m0/qmux-credit.md @@ -43,9 +43,8 @@ targets `qmux-v0.5.x`): delivering past its initial window, and a peer reads the close code after a close issued mid-write. -Remaining: merge both, release patched 0.5.x (after 0.5.2) and 0.6.x -containing them, then bump `main` to that 0.6.x and backport `release`'s pin -to that 0.5.x. `release` stays on 0.5: 0.6 needs web-transport-trait 0.5, a +Remaining here, once both ship: bump `main` to that 0.6.x and backport +`release`'s pin to that 0.5.x. `release` stays on 0.5: 0.6 needs web-transport-trait 0.5, a breaking change. Why m0: the WebSocket fallback and the planned edge-to-core `tls://` links @@ -53,6 +52,10 @@ both run on qmux, and MoQ drops streams constantly. Public API: none. Wire: none. +## Required + +- [web-transport releases the fixes](/quest/m0/qmux-credit-upstream.md) - #412 and #413 merge and ship as patched 0.6.x and 0.5.x + ## Related - [qmux on noq-proto](/quest/m2/quic-qmux.md) - replaces these stream maps later diff --git a/quest/m1/README.md b/quest/m1/README.md index 1848aff7eed..91d357ac811 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -158,6 +158,7 @@ blocks. The quests that gated m0 lines moved under them. - [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption or subtitle track survives conversion to a hang catalog - [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling - [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay` +- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust container consumer reports a frame after a subscribe or discontinuity as non-continuous, like JS, for the tune-in and warmup trims - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them - [Watch decode errors](/quest/m1/watch-decode-error.md) - a WebCodecs error ends the subscription and the element reports it - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft diff --git a/quest/m1/archive/dvr.md b/quest/m1/archive/dvr.md index 367c01531b2..2bd2007fed0 100644 --- a/quest/m1/archive/dvr.md +++ b/quest/m1/archive/dvr.md @@ -48,7 +48,10 @@ timeline (decided 10-05), so an HLS seek past it needs the explicit no linger (the `hls-linger` quest was dropped, because an unannounced broadcast can't be FETCHed and a linger would only serve the cache). Test the handover: a live HLS session keeps its playlist URIs and media sequence -numbers when the name moves from the live publisher to the archive. +numbers when the name moves from the live publisher to the archive, which +announces under the recorded epoch ([Replay +catalog](/quest/m1/archive/replay-catalog.md)), so a subscription resumes +rather than restarts. ## Required diff --git a/quest/m1/archive/replay-catalog.md b/quest/m1/archive/replay-catalog.md index 539b035498b..2d22521b102 100644 --- a/quest/m1/archive/replay-catalog.md +++ b/quest/m1/archive/replay-catalog.md @@ -32,6 +32,12 @@ this by hand-building a catalog. `moq-cli` only passes the URL and the opt-out. Select the catalog track by catalog format as `export archive` does: hang and hang.z are stamped, MSF is refused. +- The replay announces under the epoch the recording's `.info` keeps + (decided in the 2026-10-08 audit), not a freshly minted one: it is the + same content, so a live-to-archive handover at one path resumes instead of + restarting viewers. A recording whose source had no epoch replays without + one, and that handover is a `Restart`. Today `moq import archive` mints + per run (#4942); change it. - The recorded catalog's `archive` entry describes the source's live timelines, not the recording's, so replace it with the timelines the reader replays rather than trusting the recorded ones. diff --git a/quest/m1/assets-release.md b/quest/m1/assets-release.md index 57052b2e0ac..5a85130c425 100644 --- a/quest/m1/assets-release.md +++ b/quest/m1/assets-release.md @@ -10,7 +10,7 @@ this quest and every `Required` entry that links it. ## Plan -As of 2026-10-02 `main` carries `assets()` and the newest releases predate it -(`@moq/watch` 0.6.1, `@moq/publish` 0.5.1 in the repo). Check with +As of 2026-10-08 `main` carries `assets()` (#4518) but `release` does not, so +the newest releases (`@moq/watch` 0.6.2, `@moq/publish` 0.5.2) still lack it. Check with `npm view @moq/watch version` and `npm view @moq/publish version` for a newer version, then confirm its `exports` lists `./assets/*`. diff --git a/quest/m1/audio-encode-audiotoolbox.md b/quest/m1/audio-encode-audiotoolbox.md index a293f3b563e..8868f115016 100644 --- a/quest/m1/audio-encode-audiotoolbox.md +++ b/quest/m1/audio-encode-audiotoolbox.md @@ -3,7 +3,10 @@ ## Goal On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's -layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS. +layout, mono through 5.1 and 7.1, and the result plays in the browser, +`moq play`, and OBS. 6.1 is refused: since #4973 a synthesized ASC names no +program config element. Carrying the converter's magic cookie verbatim would +lift that once a caller needs it. ## Plan diff --git a/quest/m1/audio-warmup.md b/quest/m1/audio-warmup.md index 96beac58052..fc23444dad2 100644 --- a/quest/m1/audio-warmup.md +++ b/quest/m1/audio-warmup.md @@ -15,7 +15,8 @@ frames decode independently and set nothing; HE-AAC is out of scope. publish `warmup` for Opus; `js/publish` does the same for its Opus track. - `rs/moq-audio/src/decode` already trims Opus `pre_skip` at stream start; the warmup trim is the same mechanism keyed on the container consumer's - non-continuous signal (added in Rust by the open-GOP quest), and the + non-continuous signal (added in Rust by + [Rust non-continuous signal](/quest/m1/rust-continuous.md)), and the subscription's maximum age grows by `warmup` as the video consumer quest does. `js/watch` audio mirrors it. - The trim replaces `LEGACY_WARMUP_CALLBACKS` in `js/watch/src/audio/decoder.ts`, @@ -28,8 +29,9 @@ frames decode independently and set nothing; HE-AAC is out of scope. ## Required - [Catalog warmup](/quest/m1/catalog-warmup.md) - the field this reads and writes -- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - adds the Rust non-continuous signal the trim keys on +- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the signal the trim keys on ## Related +- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims video at tune-in from the same signal - [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - the video side of the same field diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index 67a203f188c..331a6841706 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -51,7 +51,7 @@ packet-lifetime comments inline; no new user guide is needed. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork +- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`, where this lands; the core and its BBR3 are already in `rs/moq-quic` ## Related diff --git a/quest/m1/c/package.md b/quest/m1/c/package.md index 4f4c6b7632d..78b434e7c37 100644 --- a/quest/m1/c/package.md +++ b/quest/m1/c/package.md @@ -31,3 +31,4 @@ under the same names. ## Required - [FFI shape](/quest/m1/ffi-shape/README.md) - moq-c 0.8.0 ships the reshaped moq-ffi, so C breaks once +- [C++ package](/quest/m1/cpp/README.md) - the `cpp/moq` build, generator pin, and release workflow this mirrors (#4079) diff --git a/quest/m1/c/retire.md b/quest/m1/c/retire.md index d54db0c9f21..25c240d6eff 100644 --- a/quest/m1/c/retire.md +++ b/quest/m1/c/retire.md @@ -2,18 +2,22 @@ ## Goal -The hand-written C crate is gone: its last release points users at the -generated `moq-c` 0.8.0, and the source, workflows, and docs that only served +The hand-written C crate is gone: its final `moq-c` 0.7.x release points +users at the generated `moq-c` 0.8.0, and the source, workflows, and docs that only served it are deleted. `doc/setup/upgrade.md` tells C users how to move. ## Plan - #4288 renamed libmoq to `moq-c` and left a code-free `rs/libmoq` stub whose last release points at `moq-c`; - `quest/m1/libmoq-retire.md` deletes that stub. This quest retires the + [Retire the libmoq stub](/quest/m1/libmoq-retire.md) deletes that stub. This quest retires the hand-written `rs/moq-c` itself, so fold in or delete that quest, whichever is still open. ## Required - [C consumers](/quest/m1/c/consumers.md) - nothing in the repository still calls the hand-written ABI + +## Related + +- [Retire the libmoq stub](/quest/m1/libmoq-retire.md) - deletes the `rs/libmoq` stub under the old name diff --git a/quest/m1/cache-max-age.md b/quest/m1/cache-max-age.md index 9f19f5d5bb3..9b1fcb28fdd 100644 --- a/quest/m1/cache-max-age.md +++ b/quest/m1/cache-max-age.md @@ -2,9 +2,9 @@ ## Goal -`max_age` means the same thing in Rust and js/net, for both publisher -retention (`track::Info::max_age`) and a subscriber's budget -(`Subscription::max_age`). A group other than the newest is stale once either +Publisher retention (`track::Info::max_age`) and a subscriber's budget +(`Subscription::max_delay`, renamed from `max_age` in #4917) apply the same +staleness rule in Rust and js/net. A group other than the newest is stale once either its wall-clock age since its successor arrived at this hop, or its media-time age (the live edge minus its reach), reaches the budget. The newest group is never stale. An untimed group has no media time, so the wall clock alone @@ -13,7 +13,7 @@ judges it. That one rule also gives up a resumed group no route continues after a failover, on untimed tracks too, and lets an untimed track's start replay what isn't stale instead of jumping to the latest group. The pool's (Rust) or -cache window's (JS) wall-clock idle bound stays separate from `max_age`. +cache window's (JS) wall-clock idle bound stays separate from both. ## Plan @@ -34,8 +34,8 @@ Decided (2026-10-06, maintainer): arrival once N+1 shows up. If the successor aborts, the clock falls to the next servable successor's arrival, or stops if there is none. - Accepted: during a total upstream stall, a reader still on a superseded - group is skipped forward after `max_age`, where media time alone would let - it wait. That reader is `max_age` of real time behind live, and the newest + group is skipped forward after its budget, where media time alone would let + it wait. That reader is its budget of real time behind live, and the newest group is never evicted. - Applies to both retention and subscriber budgets, which share `is_stale` in `rs/moq-net/src/model/track.rs` today. @@ -55,7 +55,7 @@ Decided (2026-10-06, maintainer): no longer decides the semantics. - Ranked in the clock chain right after the untimed model, because that model ships the failover regression below until this lands. -- Docs update inline: `track::Info::max_age` and `Subscription` docs, +- Docs update inline: `track::Info::max_age` and `Subscription::max_delay` docs, js/net's `Info.maxAge` doc, `doc/concept`, the relay config docs, the Expiration section and Max Age field definitions in `drafts/draft-lcurley-moq-lite.md` (which today exclude wall-clock diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 1dceeb222a9..7cb7a118a3b 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -86,7 +86,7 @@ vector the 2026-09-30 cache-tiers audit kept: Kept from 2026-09-30: core links are configured and may skip PoPs; Warm and Cold collapse to one cost ([One route cost](/quest/m1/route-cost.md)); -`--hop` removal and One route cost land on their own. Decided 2026-10-06: a +One route cost lands on its own (`--hop` was replaced by `--epoch` in #4969). Decided 2026-10-06: a path plus its [publisher epoch](/doc/concept/moq-lite.md#publisher-epochs) is a source's identity, whoever serves it. Anything specific to moq.pro's deployment is planned in moq.pro. diff --git a/quest/m1/cluster-routing/multi-cdn.md b/quest/m1/cluster-routing/multi-cdn.md index c4134ed48bc..5149145c8c3 100644 --- a/quest/m1/cluster-routing/multi-cdn.md +++ b/quest/m1/cluster-routing/multi-cdn.md @@ -4,10 +4,13 @@ A client or publisher holds sessions to several CDNs at once, ranked by its own preference: moq.pro as primary, Cloudflare as secondary. A subscription -goes over the most preferred link that has a route and resumes on the next -one when that route goes away; a publisher pushes the same path to every CDN, -so the move resumes instead of restarting. The secondary needs nothing from us: -a moq-transport relay that speaks no ROUTE is just a link. +goes over the most preferred link that has a route and moves to the next +one when that route goes away; a publisher pushes the same path to every CDN. +The move resumes only between lite-07 routes with the same epoch. The +secondary needs nothing from us: a moq-transport relay that speaks no ROUTE is +just a link, but its routes carry no epoch, so moving onto it is a `Restart` +([Restart](/quest/m0/broadcast-epoch/restart.md)) and the player +re-requests. ## Plan @@ -31,13 +34,19 @@ Decided 2026-10-01 (moq-dev/moq#4694): in the bindings that expose connect config. Pick the smallest shape that covers both publish and subscribe. -Test with mocked time: a subscriber linked to a lite relay (preferred) and a -moq-transport relay (secondary), with a publisher pushing one path to both; -losing the preferred relay resumes the subscription on the secondary with no -timestamp rewind, and its return moves it back. +Test with mocked time: a subscriber linked to a lite-07 relay (preferred) and +a second lite-07 relay, with a publisher pushing one path and epoch to both; +losing the preferred relay resumes the subscription on the second with no +timestamp rewind, and its return moves it back. With a moq-transport relay as +the secondary, the same loss delivers `Restart` (or an end and start) and a +re-request lands on the secondary. Docs: a multi-CDN section in the routing concept page and the client connect docs. Public API: per-upstream preference in client config, in Rust, JS, and the bindings. Wire: none. + +## Related + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - an epochless secondary takes over as a restart, not a resume diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 3210f62b05d..c3a234a9d00 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -7,8 +7,8 @@ lite-07 (the current wip version, decided 2026-10-05), for every session. A ROUT origin node; an ANNOUNCE says a prefix lives at a route's node and carries no path. A link flap or relay loss sends one ROUTE change per origin whose best route changed, never a re-announce per broadcast; ending a broadcast reaches -each node about once and nothing hunts; failover to another neighbour is -seamless; and no state of disagreeing neighbours keeps a dead broadcast +each node about once and nothing hunts; failover to another neighbour with +the same epoch is seamless; and no state of disagreeing neighbours keeps a dead broadcast alive. ## Plan @@ -22,7 +22,11 @@ Decided 2026-10-01 (see the [line's decisions](/quest/m1/cluster-routing/README. it; the bit rides UPDATE so a route moving between a mesh path and a CDN fallback changes it without retracting its announces. ANNOUNCE_START carries the prefix (keeping today's Path Base/Keep - compression), a Route ID, and the origin's cost for that prefix. + compression), a Route ID, the origin's cost for that prefix, and the epoch, + and lite-07's restart message from + [Restart](/quest/m0/broadcast-epoch/restart.md) keeps its meaning. On a + route without an epoch, the source is the origin node and its ANNOUNCE: a + new one at the same path is a restart. ANNOUNCE_UPDATE re-prices it and ANNOUNCE_END ends one broadcast while the route stays up. An announce never changes its Route ID: another origin serving the same path is another ANNOUNCE. An ANNOUNCE naming an unknown @@ -68,9 +72,10 @@ Decided 2026-10-01 (see the [line's decisions](/quest/m1/cluster-routing/README. No per-announce seqno. - Origin selection keeps `route_order`'s shape and swaps its inputs: the candidates become the origin nodes announcing the path, ranked by longest - prefix, then the link's preference + prefix, then the newest epoch, then the link's preference ([Multi-CDN endpoints](/quest/m1/cluster-routing/multi-cdn.md)), then the - route metric to the node, then the path-keyed rendezvous hash. + route metric to the node, then the path-keyed rendezvous hash, with the + origin node id breaking a full tie. - Down-only bit: set on a route learned on an upstream link, kept across other links, and a route carrying it is never sent on an upstream link (extending the `upstream` link mark in `doc/bin/relay/cluster.md`). @@ -80,7 +85,7 @@ Decided 2026-10-01 (see the [line's decisions](/quest/m1/cluster-routing/README. A relay advertising routes to a client sends them as usual; node ids reveal nothing about the backbone. - Every hop re-selects; SUBSCRIBE names no origin, and the reply names none - either: any route announcing a path resumes it. + either: any route announcing a path under the same epoch resumes it. - Mixed versions: a lite-06 peer keeps today's path vector, translated at the relay that speaks both, for the rollout window only. @@ -121,3 +126,7 @@ release. ## Required - [Simulate the split](/quest/m1/cluster-routing/sim.md) - the numbers that confirm the design before the wire is written + +## Related + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - the lite-07 restart message ANNOUNCE_START sits beside diff --git a/quest/m1/cmaf-frame-timestamp.md b/quest/m1/cmaf-frame-timestamp.md index 0a3e26717a1..0a54e733cb5 100644 --- a/quest/m1/cmaf-frame-timestamp.md +++ b/quest/m1/cmaf-frame-timestamp.md @@ -30,10 +30,12 @@ shifts `trun` data offsets. the quest. - `main`: a behavior fix with no API change. -Open PR [#4826](https://github.com/moq-dev/moq/pull/4826) implements this. It -lands after [#4822](https://github.com/moq-dev/moq/pull/4822) (the untimed -model), which brings untimed frames to `main`. Timedness is per track there, so the decoder can check the track -rather than each frame. +Open PR [#4826](https://github.com/moq-dev/moq/pull/4826) implements this. +Its blocker, [#4822](https://github.com/moq-dev/moq/pull/4822) (the untimed +model), has merged. Timedness is per track there, so the decoder can check the +track rather than each frame. It lands first among the CMAF decode changes: +#5037 (in-band parameter sets), #5015 (catalog init), then +[CMAF sample defaults](/quest/m1/cmaf-sample-defaults.md) rebase onto it. Test: in Rust and JS, a fragment whose `tfdt` disagrees with its frame timestamp decodes at the frame timestamp, with B-frame offsets preserved, and @@ -45,3 +47,4 @@ means. ## Related - [Shared clock](/quest/m1/shared-clock.md) - the first publisher to rely on it +- [CMAF sample defaults](/quest/m1/cmaf-sample-defaults.md) - the same `decode` functions, landing after this diff --git a/quest/m1/cmaf-sample-defaults.md b/quest/m1/cmaf-sample-defaults.md index af694d0bc5f..c3af16c7dc3 100644 --- a/quest/m1/cmaf-sample-defaults.md +++ b/quest/m1/cmaf-sample-defaults.md @@ -37,5 +37,5 @@ Public API: none. Wire: none. ## Related -- [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - touches the same `decode` functions; land either first and rebase +- [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - touches the same `decode` functions; #4826, #5037, and #5015 land first and this rebases - [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md) - the export side of the same flags diff --git a/quest/m1/e2ee/README.md b/quest/m1/e2ee/README.md index c2ad19770c2..91c476db613 100644 --- a/quest/m1/e2ee/README.md +++ b/quest/m1/e2ee/README.md @@ -20,6 +20,7 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro ### Epoch and identity - Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is the shared [`Epoch`](/doc/concept/moq-lite.md#publisher-epochs) primitive. Subscribers resolve `` and take the epoch from its route, where the newest wins; on a wire without route epochs the application supplies it. +- An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). A redundant pair under one `moq --epoch`, or the same-epoch importers of [Same-epoch importers](/quest/m1/hop-aligned-import.md), would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. - The epoch is untrusted and unauthenticated. A wrong epoch fails authentication and a withheld one denies service; neither can make a nonce repeat, because only the publisher instance chooses what it encrypts under. This is the same trust a cache needs to serve the right instance. Plaintext broadcasts adopt the same epoch by default through [broadcast epochs](/quest/m0/broadcast-epoch/README.md). - Nothing in the path says the bytes are encrypted. The format after decryption (`meeting.hang`) is inside the opaque name; a plaintext player, exporter, or matcher that opens a protected broadcast finds no catalog it can read and fails with its usual typed refusal, the same as for any format it does not support. - One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains. A grouped frame uses the 96-bit nonce `uint64_be(group) || uint32_be(frame)`; a datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. @@ -67,3 +68,4 @@ The Rust and TypeScript cores expose the same surface, and nothing else: ## Related - [archive](/quest/m1/archive/README.md) - protected broadcasts are deliberately outside recording and replay formats +- [Same-epoch importers](/quest/m1/hop-aligned-import.md) - the shared-epoch redundancy an encrypting publisher refuses diff --git a/quest/m1/e2ee/cli.md b/quest/m1/e2ee/cli.md index dde132ea4c4..01bf0ff222b 100644 --- a/quest/m1/e2ee/cli.md +++ b/quest/m1/e2ee/cli.md @@ -11,7 +11,8 @@ Existing plaintext commands remain the default; an explicit application credenti - Integrate the Rust E2EE layer into `moq-cli` publication and playback before semantic mux output and after protected track input. Keep codec, capture, playback, and synchronization logic outside the crypto layer. - Accept the credential through a dedicated file descriptor, otherwise-unused stdin, or a permission-checked file (`0600` on Unix), never a command argument or environment variable. Redact errors and tracing, zeroize owned secret bytes, and document shell-safe invocation. - Inject opaque physical names into mux, video, audio, timeline, and catalog construction. Take the semantic broadcast name from the user and publish under its opaque derivation; mint a UUIDv7 epoch per publisher run and discover the newest one under the opaque prefix when playing; derive and decrypt the protected catalog before existing selection, and suppress every plaintext Hang or MSF catalog representation. -- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, clean authentication errors, and both lite and IETF transports. +- Refuse `--epoch` together with a credential, and any other path that hands an encrypting publisher an epoch it did not mint, before connecting (maintainer, 2026-10-08): a shared epoch repeats AES-GCM nonces. +- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--epoch` with a credential refused, clean authentication errors, and both lite and IETF transports. ## Required diff --git a/quest/m1/gpu-runner.md b/quest/m1/gpu-runner.md index e1045304493..0cabbe6fddd 100644 --- a/quest/m1/gpu-runner.md +++ b/quest/m1/gpu-runner.md @@ -12,6 +12,6 @@ this quest and every `Required` entry that links it. ## Plan -As of 2026-09-30 `gh api repos/moq-dev/moq/actions/runners` lists none. +As of 2026-10-08 `gh api repos/moq-dev/moq/actions/runners` still lists none. Register it with the dedicated label and hardening that [GPU CI](/quest/m1/gpu-ci.md) describes. diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index b589952e458..a18270761b9 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -12,12 +12,14 @@ failover `export ts` sees a timestamp rewind and exits (#4354). ## Plan -Decided: every publisher of one path MUST publish the same broadcasts and -tracks, since any route covering a path resumes its subscriptions. A redundant -pair is keyed by a shared explicit epoch (decided 2026-10-03: `--hop` no -longer exists to key it). Make every container importer (ts, fmp4, flv, mkv, -and the SRT, RTMP, and HLS gateways that reuse them) meet the contract when -fed one encoded stream. Capture is out: two encoders never align. +Decided: every publisher of one path and epoch MUST publish the same +broadcasts and tracks, since routes with the same epoch resume each other's +subscriptions. A redundant pair is keyed by a shared explicit epoch (decided +2026-10-03: `--hop` no longer exists to key it). Make every container importer +that `moq import --epoch` accepts (ts, fmp4, flv, mkv) meet the contract when +fed one encoded stream. The SRT, RTMP, and RTC gateways and `ts --program all` +are out: they mint an epoch per ingest connection (#4962), so two of them +never share one. Capture is out too: two encoders never align. - A group's sequence derives from its keyframe's media timestamp (PTS in TS), not a per-process counter. Decide how both processes agree across a @@ -60,3 +62,4 @@ issues' 1+1 setup (one relay, two `import ts` sharing one `--epoch`, two ## Related - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a redundant pair shares one epoch +- [E2EE](/quest/m1/e2ee/README.md) - an encrypting publisher refuses a shared epoch, so a redundant pair is plaintext only diff --git a/quest/m1/ietf-object-gaps.md b/quest/m1/ietf-object-gaps.md index da389f3c4f2..409e29dde6e 100644 --- a/quest/m1/ietf-object-gaps.md +++ b/quest/m1/ietf-object-gaps.md @@ -2,17 +2,23 @@ ## Goal -A moq-transport group whose object IDs skip (legal per draft-22 section -11.3.1, but not representable in the model) is refused the same way a -non-zero subgroup is: the group aborts, a warning is logged, and the stream -is stopped with the error, in Rust and JS. An object ID that overflows +A moq-transport group whose object IDs skip after an object was delivered +(legal per draft-22 section 11.3.1, but not representable in the model) is +refused the same way a non-zero subgroup is: the group aborts, a warning is +logged, and the stream is stopped with the error, in Rust and JS. A headless +subgroup on drafts 14-17 (a non-zero first object ID, since those drafts have +no FIRST_OBJECT bit) is not a gap: it stays a quiet drop that keeps the +subscription, as #5019 made it in JS. An object ID that overflows closes the session with PROTOCOL_VIOLATION in Rust, as the draft requires. ## Plan Decided 2026-10-06, while declining object-level identity in #4926: the model is the product, so subgroups, gapped object IDs, and arbitrary object -properties stay unsupported. Refusals must be loud and consistent. +properties stay unsupported. Refusals must be loud and consistent, except +the headless drop: a relay joining at the live edge sends one on every +subscribe, so it is expected, not a fault. Rust's headless drop is planned +separately in #5041. Facts from `main`: @@ -26,8 +32,10 @@ Facts from `main`: `rs/moq-net/src/ietf/session.rs` only aborts the stream, even for a protocol violation. Closing the session on overflow needs a new route from the subgroup task to session teardown, like `run_subscribe_namespace`'s. -- JS: `Frame.decode` in `js/net/src/ietf/object.ts` throws on a gap, and - `handleGroup` in `subscriber.ts` stops the stream without logging. +- JS: `Frame.decode` in `js/net/src/ietf/object.ts` throws `ObjectIdGap` on + any non-zero delta. Since #5019, `handleGroup` in `subscriber.ts` drops a + headless group on drafts 14-17 at debug level; any other gap fails the + group (`open().close(e)`) and stops the stream, with no warning logged. Neither closes the session for a gap; that would punish a peer following the spec. JS refuses any non-zero delta before adding it, so it has no diff --git a/quest/m1/iroh-capsule-bump.md b/quest/m1/iroh-capsule-bump.md index 0be13a6f3a1..944dc405d6a 100644 --- a/quest/m1/iroh-capsule-bump.md +++ b/quest/m1/iroh-capsule-bump.md @@ -11,3 +11,6 @@ reason instead of `(0, "stream closed")`. ## Plan Only the version moves; the fix and its regression test live upstream. +As of 2026-10-08 #419 has merged (2026-10-07), but the newest +`web-transport-iroh`, 0.8.2, was published hours before it, and `main` +floors 0.8.1. Wait for the next release. diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index 6ba95f3bc4d..3d72e2ffe4c 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -19,6 +19,11 @@ codes, cancellation, and clean stream finish. Match the existing Rust response contract, including saved object prefixes. Unsupported versions or request forms must receive the protocol's explicit refusal rather than hang. +Datagrams are never fetchable (#4982): Rust refuses a FETCH that reaches a +datagram with `NotFetchable` (0x3a on moq-lite-07, `NotFound` earlier). +`@moq/net` has no such code yet. Add it and refuse the same way, on lite and +IETF. + Verify with an in-memory application responder: a browser publisher serves a native IETF subscriber after a group is evicted or was never cached. Run the supported-draft matrix and `just test interop --all` through CI. diff --git a/quest/m1/js-group-handover.md b/quest/m1/js-group-handover.md index e2e85063f2f..81ec871ca80 100644 --- a/quest/m1/js-group-handover.md +++ b/quest/m1/js-group-handover.md @@ -3,8 +3,9 @@ ## Goal A `js/net` track subscription survives its broadcast's route swapping to -another provider, such as a relay migration after a GOAWAY, and resumes from -the new provider at the first frame it has not delivered. A viewer at the live +another provider with the same epoch, such as a relay migration after a +GOAWAY, and resumes from the new provider at the first frame it has not +delivered. A viewer at the live edge with no latency budget never loses a group across the swap, and never has to notice the swap to keep reading. @@ -38,6 +39,9 @@ settle along the way: at its own live edge. - Failover compatibility: Rust refuses to resume onto a source whose track properties differ (timescale, retention, priority, order). Match it. +- Resume only between routes with the same epoch. Any other swap is a new + broadcast that announce consumers see as a `Restart`, and players follow + it with a fresh subscription. - `js/watch` and `js/hang` consumers that re-subscribe on `active` changes. Check whether they still need to. - Giving up a resumed group no route continues. Mirror Rust's rule from @@ -51,3 +55,7 @@ budget note in its README). Public API: likely a behavior change to `Origin.Requesting.active` and track subscriptions across a swap. Report it in the PR. + +## Related + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event a swap to another epoch produces instead of a handover diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index 1158f3b282f..6a1e206dc92 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -9,9 +9,10 @@ payload published without a timestamp goes out untimed. ## Plan -Today the json and flate snapshot and stream producers default -`at = Timestamp.now()`, the json window producer always uses now, and js/net's -`writeString`, `writeJson`, and `writeBool` stamp now. +The remaining work is these defaults (checked 2026-10-08): the json and +flate snapshot and stream producers default `at = Timestamp.now()`, the json +window producer always uses now, and js/net's `writeString`, `writeJson`, and +`writeBool` (`js/net/src/group.ts`) stamp now. Decided (2026-10-01): `@moq/net` exports `Timed` (`{ value: T; at?: Time.Timestamp }`), the Rust name and shape. Each producer diff --git a/quest/m1/lite-untimed.md b/quest/m1/lite-untimed.md index a3f8962fdf0..34eb3382d5a 100644 --- a/quest/m1/lite-untimed.md +++ b/quest/m1/lite-untimed.md @@ -13,18 +13,12 @@ Decided (2026-10-05, maintainer): timedness is per track (the untimed model, [#4822](https://github.com/moq-dev/moq/pull/4822)), and an untimed track sends no TIMESCALE and no Timestamp. On lite-07 that likely means an optional Timescale in TRACK_INFO and no Timestamp fields on an untimed track. The -per-frame shift below was planned for an absent timestamp inside a timed -track, which no longer exists (settled 2026-10-06: a mismatched frame is -refused), so re-plan the encoding on that shape and drop the shift if -nothing needs it. - -Decided (2026-10-01, maintainer): shift the FRAME Timestamp Delta and the -DATAGRAM Timestamp by one, so 0 means absent. An absent frame doesn't move -the delta baseline. Rejected: a bare 0 as a sentinel, which collides with a -real pts of 0. - -Decided (2026-10-02): one PR for both languages, after both -model quests. Shipping one language first would break Rust-JS interop on +2026-10-01 shift-by-one (0 means an absent timestamp) is dropped: it served an +absent timestamp inside a timed track, which no longer exists (settled +2026-10-06: a mismatched frame is refused). + +Decided (2026-10-02): one PR for both languages. Both model quests have +landed (#4822). Shipping one language first would break Rust-JS interop on lite-07-wip in between. Draft work: @@ -36,14 +30,13 @@ Draft work: valid", and expiration's "reach" (the first frame timestamp of the next group) for an untimed group. - Check how a lite track that has no timescale says so on lite-07. -- lite-07 varints carry the full 64 bits, so the shift can't represent the - top value: a DATAGRAM Timestamp of 2^64-1, or a delta whose zigzag - encoding is 2^64-1. Wrapping would turn either into the absence marker. - Recommended: the encoder refuses those values and the draft says so, - rather than widening the encoding for timestamps no real track reaches. Test: an untimed frame and an untimed datagram round-trip Rust-to-JS and JS-to-Rust on lite-07. lite-06 still receives a timestamp. Run `just drafts check` and `just test interop --all`. Public API: none. Wire: lite-07-wip only, which is unpublished. + +## Related + +- [Rust untimed default](/quest/m1/rust-untimed-default.md) - touches the same Timescale defaults in `rs/moq-net` and lands first; this rebases onto it diff --git a/quest/m1/media-audio-tone.md b/quest/m1/media-audio-tone.md index ef951c58283..c1b8f1bc518 100644 --- a/quest/m1/media-audio-tone.md +++ b/quest/m1/media-audio-tone.md @@ -21,3 +21,4 @@ loaded check. - [More tests under load](/quest/m1/test-flakes-2/README.md) - shares the loaded-check validation - [Media late join](/quest/m1/test-flakes-2/media-late-join.md) - shares the media fixture, but tracks a separate failure +- [Forced channel count](/quest/m1/publish-audio-channel-count.md) - another source of audio gaps on the JS publish path; rule it in or out first diff --git a/quest/m1/obs-moq-video/vpx-obs.md b/quest/m1/obs-moq-video/vpx-obs.md index dc7fe469898..9502e37aaf3 100644 --- a/quest/m1/obs-moq-video/vpx-obs.md +++ b/quest/m1/obs-moq-video/vpx-obs.md @@ -6,7 +6,7 @@ The OBS MoQ source plays VP8 and VP9 (8-bit 4:2:0) on every platform it ships fo ## Plan -- moq-video decodes both codecs behind its opt-in `vpx` feature, with libvpx supplied by the build host (`libvpx-native-sys`, `VPX_STATIC=1`). Turn it on in moq-ffi and libmoq for the OBS builds only, not for every binding artifact. +- moq-video decodes both codecs behind its opt-in `vpx` feature, with libvpx supplied by the build host (`libvpx-native-sys`, `VPX_STATIC=1`). Turn it on in moq-ffi for the OBS builds only, not for every binding artifact. - macOS and Linux build through Nix, which already provides libvpx. The Windows MSVC build runs without Nix and needs a static libvpx: evaluate vcpkg's `libvpx:x64-windows-static` against an in-tree vendored libvpx build (C-only config first, SIMD later) and pick one. The vendored build is also what a crates.io consumer without libvpx would need. - Verify decoded pixels in the source, CPU delivery, reconnect, and rendition changes, and inspect the plugin's imports for libvpx, avcodec, and avutil on each platform. diff --git a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md index 29f45b7e5be..b6a10d62f11 100644 --- a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md +++ b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md @@ -29,18 +29,18 @@ point. Where the reads are: - The drive loop reads once per turn to fire timers - (`self.shared.timers.borrow_mut().fire(Instant::now())`, - rs/moq-uring/src/worker.rs:183). -- The noq driver reads the clock for - `close` (rs/moq-uring/src/quic/noq/connection.rs:239), `handle_timeout` - (:671), and `poll_transmit` (:786). The last one runs once per GSO train, + (`self.shared.timers.borrow_mut().fire(Instant::now())` in + rs/moq-uring/src/worker.rs). +- The noq driver (rs/moq-uring/src/quic/noq/connection.rs) reads the clock + for `close`, `handle_timeout`, and `poll_transmit`. The last one runs once per GSO train, since `flush` stages one train per turn (see [Run to quiescence](/quest/m1/perf/uring-quiescence.md)). The same profile shows the timer heap at ~1.6%: -`::set` 0.92% plus -`btree::search::search_tree` 0.65%. `timer::Heap` is a -`BTreeMap<(Instant, u64), Rc>` (rs/moq-uring/src/timer.rs:19-20), so +`moq_uring::timer::Timer::set` 0.92% (profiled as a `moq_net::runtime::Timer` +impl, a trait since removed) plus `btree::search::search_tree` 0.65%. +`timer::Heap` (rs/moq-uring/src/timer.rs) keys a +`BTreeMap<(Instant, u64), Rc>`, so every QUIC timeout re-arm is an O(log n) map removal and insertion with `Rc` traffic. The #2875 design note called for a timer wheel. Not urgent at these connection counts, but it is on the same hot path and grows with it. diff --git a/quest/m1/perf/announce-replay.md b/quest/m1/perf/announce-replay.md index 3a59f0c7cb7..2785d9bd79e 100644 --- a/quest/m1/perf/announce-replay.md +++ b/quest/m1/perf/announce-replay.md @@ -22,3 +22,7 @@ hashing and `Path` comparison, so check whether a faster hasher for path-keyed maps pays off on both. Keep the replay's order and its last-update-wins semantics. + +## Related + +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - reshapes the same announce stream; measure the replay on its wire too diff --git a/quest/m1/perf/group-cost.md b/quest/m1/perf/group-cost.md index 1bf3bdeccfd..d4a11ac4212 100644 --- a/quest/m1/perf/group-cost.md +++ b/quest/m1/perf/group-cost.md @@ -33,7 +33,8 @@ as candidates to measure, not separate quests. the lite and IETF publishers. That is lock, clock, and atomic work that may allocate nothing, so time it rather than count allocations: CPU per viewer-group for fast fanout and flow-controlled readers, over SUBSCRIBE - and FETCH. It protects a drain longer than `latency_max`, so keep + and FETCH. It keeps a group alive through a drain longer than the pool's + idle expiry, so keep per-frame liveness and `slow_prefetch_reader_survives_expiry` (rs/moq-net/src/model/track.rs); fewer refresh calls alone are not a win. - Owned decode copies: `rs/moq-net/src/coding/decode.rs` decodes `Vec` diff --git a/quest/m1/publish-audio-channel-count.md b/quest/m1/publish-audio-channel-count.md index 63f4bad8f5e..377b200eb1d 100644 --- a/quest/m1/publish-audio-channel-count.md +++ b/quest/m1/publish-audio-channel-count.md @@ -57,3 +57,4 @@ be cheaper than a full media run, if one can be made to fail reliably. ## Related - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - the other place browser-side capture and encode costs get measured +- [Media audio-tone check](/quest/m1/media-audio-tone.md) - a test that misses tone samples, possibly from the same cause diff --git a/quest/m1/quic/bbr-app-limited-edges.md b/quest/m1/quic/bbr-app-limited-edges.md index 8884cf0aee0..1cdc4ff13fb 100644 --- a/quest/m1/quic/bbr-app-limited-edges.md +++ b/quest/m1/quic/bbr-app-limited-edges.md @@ -10,8 +10,8 @@ pins that policy. ## Plan The app-limited fix notifies `Controller::on_app_limited(in_flight)` only -when a transmit poll sends nothing. In moq-dev/noq -`noq-proto/src/connection/mod.rs`: +when a transmit poll sends nothing. In +`rs/moq-quic/src/connection/mod.rs`: - A poll that sends some packets and then runs dry is not marked. Mark it, as Linux does when its write queue empties @@ -34,7 +34,7 @@ change is intended. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork +- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`, where this lands; the core and its BBR3 are already in `rs/moq-quic` ## Related diff --git a/quest/m1/quic/bbr-app-limited.md b/quest/m1/quic/bbr-app-limited.md index 6d819956549..22ab852390c 100644 --- a/quest/m1/quic/bbr-app-limited.md +++ b/quest/m1/quic/bbr-app-limited.md @@ -4,7 +4,7 @@ After minutes of keep-alive-only idle, a BBRv3 (`delay`) sender paces its next burst near the bandwidth it learned before, not at a trickle, and a -regression test in the fork proves it. +regression test in `moq-quic` proves it. ## Plan @@ -20,18 +20,18 @@ minutes took 5.2 s at 50 ms RTT, against 0.5 s with CUBIC. The fix plausibly covers it. The fork's max-bw filter ages only on non-app-limited samples, and before #5 every other keep-alive was stamped non-app-limited. Nothing measures it, though. Add a virtual-time transport -test in the fork: learn the bandwidth, idle on keep-alives for about five +test in `rs/moq-quic`, which carries the fix: learn the bandwidth, idle on keep-alives for about five minutes, send 250 KB, and assert the pacing rate stays at or above about 0.9x the earlier max bandwidth. Check that it fails on 1.3.0. If it still stalls, find the remaining cause, such as ProbeRTT entered during -the idle or a stale `bw_shortterm`, and fix it in the fork. Dropping the +the idle or a stale `bw_shortterm`, and fix it in `moq-quic`. Dropping the estimate after a long idle is a policy change for the m2 study, not this quest. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork +- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`, where this lands; the core and its BBR3 are already in `rs/moq-quic` ## Closes diff --git a/quest/m1/quic/shard.md b/quest/m1/quic/shard.md index 49be8b2331d..f4d64e9a748 100644 --- a/quest/m1/quic/shard.md +++ b/quest/m1/quic/shard.md @@ -13,7 +13,7 @@ are gone. ## Plan Decided in the 2026-09-30 plan: the library shards and the runtime drives. -The library does not own threads, so embedders (libmoq, moq-ffi) keep their +The library does not own threads, so embedders (moq-ffi and the bindings over it) keep their own threading model. - `moq_sock::shard` (the group, claims, and steering filter) stays in diff --git a/quest/m1/rs2ts/sans-io/lite.md b/quest/m1/rs2ts/sans-io/lite.md index bc54106b68e..67974918d74 100644 --- a/quest/m1/rs2ts/sans-io/lite.md +++ b/quest/m1/rs2ts/sans-io/lite.md @@ -4,8 +4,11 @@ The lite session is a state machine fed bytes, stream open and close events, and `tick(now)`; it returns bytes to write and events for the model. No -`web_transport_trait` stream types, no timers of its own, no async outside -the `async` feature. +transport stream types, no timers of its own, no async outside the `async` +feature. The starting point: since #4709 the session already runs over +moq-net's own poll interface (`transport::poll::Session` in +`rs/moq-net/src/transport.rs`), not `web_transport_trait`, but it still +drives that interface from async tasks. ## Plan diff --git a/quest/m1/rust-continuous.md b/quest/m1/rust-continuous.md new file mode 100644 index 00000000000..748c6fa9b76 --- /dev/null +++ b/quest/m1/rust-continuous.md @@ -0,0 +1,32 @@ +# [S] Rust non-continuous signal + +## Goal + +`moq_mux::container::Consumer` tells its reader whether a frame picks up +exactly where the previous one left off, like `continuous` in +`js/hang/src/container/consumer.ts`: false on the first frame after the +subscribe and after every discontinuity, true otherwise. +`rs/moq-video/src/decode` and `rs/moq-audio/src/decode` pass it through, so +the open-GOP trim, audio warmup, and consumer warmup key on one signal +instead of each adding its own. + +## Plan + +Split out of [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) +in the 2026-10-08 audit, so audio warmup no longer waits on #4645. + +Today `poll_read` returns a bare frame, and `discontinuity()` is a counter +bumped on a declared marker group, an unproven delivered hole, or a latency +skip, but not on the subscribe itself. Report the flag with each frame and +let the counter go if nothing else needs it. Mirror the JS name. + +Tests: the first frame after a subscribe, a marker group, a delivered hole, +and a latency skip each read as non-continuous, and every other frame as +continuous. + +Public API: breaking in moq-mux (the consumer's read result changes). Wire: +none. + +## Related + +- [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - withholds frames after the same signal diff --git a/quest/m1/rust-untimed-default.md b/quest/m1/rust-untimed-default.md index 10a28b4543a..e530220439d 100644 --- a/quest/m1/rust-untimed-default.md +++ b/quest/m1/rust-untimed-default.md @@ -35,4 +35,6 @@ untimed). Wire: none. ## Related -- [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - the same publishers stop filling in a timestamp +- [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - the same publishers stop filling in a timestamp; this lands first, since a data track declaring milliseconds refuses an untimed write, so that quest covers only tracks declared untimed +- [FFI shape](/quest/m1/ffi-shape/README.md) - #4519 moves the moq-ffi json and flate tracks this edits; whichever lands second rebases +- [lite-07 untimed](/quest/m1/lite-untimed.md) - the same `rs/moq-net` lines; this lands first and it rebases diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 2880bcfd52c..55a62fa7758 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -11,7 +11,9 @@ its own connection. A dashboard reads both the same way a publisher does. One shared model turns either report into a health verdict, and a bounded preflight run reports which media layer of a broadcast is broken. Stats and feedback cost nothing on the network unless someone subscribes. Not here: the -relay's `moq-stats` layout, which stays as it is; clock synchronization; any +relay's `moq-stats` layout, which this line does not change (the +[broadcast epoch](/quest/m0/broadcast-epoch/README.md) line reshapes it); +clock synchronization; any requirement that a client report; and feedback as an input to billing, authorization, or route selection. @@ -26,7 +28,7 @@ catalog keyed by rendition, not a stats track per rendition and not a sum per kind. - **Media stats leave moq-stats.** The relay is media-agnostic and keeps - `Traffic`, `Presence`, and `.stats/node/` unchanged. Media stats are + `Traffic`, `Presence`, and `.stats/node/` as this line found them. Media stats are hang tracks, discovered through the catalog, so no `Producer` extension, `Merge` wrapper, or flattened generic is needed. One layout for relay and clients is given up on purpose. diff --git a/quest/m1/stats/js.md b/quest/m1/stats/js.md index ac6eaf2d4d1..b8d4bac05b2 100644 --- a/quest/m1/stats/js.md +++ b/quest/m1/stats/js.md @@ -32,7 +32,14 @@ echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. - The demo sets both attributes, so the media test can read a browser viewer's feedback through `moq export echo`. - `doc/lib/js` documents the attributes. +- An encrypted (E2EE) broadcast refuses the stats track and the `echo` attribute: they would publish rendition + IDs and per-track counters in plaintext beside it. Recommended in the + 2026-10-08 audit over encrypting them through the E2EE `Generation`. ## Required - [Schema](/quest/m1/stats/schema.md) - the zod schemas this fills + +## Related + +- [E2EE](/quest/m1/e2ee/README.md) - protected broadcasts expose no semantic metadata diff --git a/quest/m1/stats/rust.md b/quest/m1/stats/rust.md index 4ff222367a5..4b468deb44e 100644 --- a/quest/m1/stats/rust.md +++ b/quest/m1/stats/rust.md @@ -41,7 +41,14 @@ - The media test publishes with `--stats` and plays with `--echo` against a publisher that solicits feedback. It asserts that the publisher's frame count matches what was sent and that the viewer's newest arrival advances. +- An encrypted (E2EE) broadcast refuses `--stats` and `--echo`: they would publish rendition + IDs and per-track counters in plaintext beside it. Recommended in the + 2026-10-08 audit over encrypting them through the E2EE `Generation`. ## Required - [Schema](/quest/m1/stats/schema.md) - the sections and snapshot types + +## Related + +- [E2EE](/quest/m1/e2ee/README.md) - protected broadcasts expose no semantic metadata diff --git a/quest/m1/stats/schema.md b/quest/m1/stats/schema.md index f2dd402c9e3..b327a1b2d59 100644 --- a/quest/m1/stats/schema.md +++ b/quest/m1/stats/schema.md @@ -15,7 +15,9 @@ and the hang draft specs both. Nothing produces them yet. the wire when absent. `path` is relative to the broadcast serving the catalog and resolves through `try_resolve`, like a rendition's `broadcast`; `.echo` is appended to the result. A path that escapes - the root refuses the catalog. Shared fixtures pin both in both languages. Additive on main. + the root refuses the catalog. Shared fixtures in `rs/hang/fixtures` (beside + `catalog-clock.json`, which JS mirrors) pin both in both languages. + Additive on main. - `rs/hang/src/stats.rs`: the publisher snapshot, `Snapshot { transport, renditions: BTreeMap, #[serde(flatten)] ext: E }`. The generic lets moq-mux flatten `{ mpegts: ts::stats::Snapshot }` in beside it, the diff --git a/quest/m1/subscribe-live-time.md b/quest/m1/subscribe-live-time.md index a3bffbd1e32..6ab4b4c854f 100644 --- a/quest/m1/subscribe-live-time.md +++ b/quest/m1/subscribe-live-time.md @@ -43,9 +43,11 @@ Decided in planning (2026-10-03): and no receiver invents one. - **lite-07 only.** It is still WIP (`moq-lite-07-wip`), so the field is added without negotiation. Older versions keep the gap rule. -- **API: `track::Subscriber::live().await`** resolves once the route answered, to - `Live { start, latest: Option, time: Option }`: the resolved - start, the largest group/frame, and the live media time. Mirrored in js/net. +- **API: `track::Subscriber::answered().await`** resolves once the route + answered, to `LiveEdge { start, latest: Option, time: + Option }`: the resolved start, the largest group/frame, and the + live media time. Mirrored in js/net. Not `live`/`Live`: #5029's lite-07 + `live` flag already takes that name. - **Independent of [Subscribe ranges](/quest/m1/subscribe-ranges/README.md)**, which rewrites the same messages: whichever lands second rebases. - `js/watch/src/sync.ts` stays as it is: its latency range (from #1620) is diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 4c3d9eed16f..117d09e1b1a 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -14,7 +14,11 @@ This absorbs the relay half of fetch-span (#4558) and builds on fetch-fill's checks (#4544). Receiving a multi-group FETCH stream means several groups on one stream. Absent sequences between the FETCH's groups become drops, and a group already cached is discarded as a duplicate. Cap a downstream FETCH at -the Largest Object, as the moq-transport drafts require. +the Largest Object, as the moq-transport drafts require. A relay with only +fetch demand learns the upstream's Largest from TRACK_STATUS without a +SUBSCRIBE, as #4974 makes fetch-only demand do. +[Cross-relay FETCH over moq-transport](/quest/m1/ietf-peer-fetch-old.md) +fixes the same FETCH path refusing held groups as `old`. Serving downstream lifts the one-group refusal ("FETCH spanning several groups not supported") in `run_fetch_stream` diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 6cbf17070bc..26fdb7afb57 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -24,3 +24,7 @@ Guidance: `moq_relay::fetch_group` (added in the 2026-10-05 audit). - `max_delay` caps every range. - Benchmark range count and span as separate axes (AGENTS.md fan-out rule). + +## Required + +- [Coalesce dynamic tracks](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic track per name with sequences kept across replacements, which range requests build on (#4929) diff --git a/quest/m1/test-flakes-2/impaired-handshake.md b/quest/m1/test-flakes-2/impaired-handshake.md index ef4bb96a723..736e2d0b700 100644 --- a/quest/m1/test-flakes-2/impaired-handshake.md +++ b/quest/m1/test-flakes-2/impaired-handshake.md @@ -25,3 +25,7 @@ that. Confirm with a qlog of a failing seed, then fix it at the cause, without raising a timeout or retrying the connect. Public API: none. Wire: none. + +## Related + +- [Switch](/quest/m1/quic/fork/switch.md) - moves the runtimes from noq to `moq-quic`, whose idle-timer arming a fix may land in instead diff --git a/quest/m1/untimed-decisions.md b/quest/m1/untimed-decisions.md index dec9a215294..e0fb33ec48e 100644 --- a/quest/m1/untimed-decisions.md +++ b/quest/m1/untimed-decisions.md @@ -22,9 +22,9 @@ answered. replay an untimed track untimed. 2. **A malformed object in a FETCH.** On a TIMESCALE track, a subgroup object without a Timestamp ends the whole track with `MalformedTrack` - (`rs/moq-net/src/ietf/subscriber.rs`, `run_group`), as js/net does + (`rs/moq-net/src/ietf/subscriber.rs`, `recv_group`), as js/net does ([#4968](https://github.com/moq-dev/moq/pull/4968)), and so does one in a - joining FETCH's fill. The same object in a standalone group FETCH, which a + joining FETCH's fill (`recv_fill`). The same object in a standalone group FETCH, which a relay sends to fill a cache miss (`run_group_fetch`), fails only that group. - Recommended: end the track too. The publisher broke the track, however the object arrived. diff --git a/quest/m2/README.md b/quest/m2/README.md index d025baa96ec..093d8196a6a 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -107,7 +107,6 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [Egress profile](/quest/m2/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them - [Compressed tracks](/quest/m2/flate.md) - moq-ffi and every wrapper expose flate tracks through a `flate` namespace like `json` -- [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table - [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, carrying the cluster route layer - [MSFTS convergence](/quest/m2/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where the two still differ: program tables and the ES payload unit - [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them diff --git a/quest/m2/announce-shapes.md b/quest/m2/announce-shapes.md deleted file mode 100644 index a21ec92ad97..00000000000 --- a/quest/m2/announce-shapes.md +++ /dev/null @@ -1,109 +0,0 @@ -# [XL] Announcement shapes in moq-lite - -## Goal - -A moq-lite announcement carries its shape, prefix, exact, suffix, or -prefix+suffix, and relays preserve it across hops. A subscriber can request -announcements by any shape (`**/transcode.pro`), and a publisher can -advertise one, so a fleet-wide service claims every matching path once -instead of per prefix. An exact broadcast at `/a` stays hidden from a reader -scoped to `/a/b` on every hop, not only on the origin holding it. - -moq-lite only: IETF sessions stay prefix-only. Routing only: token claim -patterns keep their suffix support unchanged. - -## Plan - -Decided 2026-09-29 (quest-plan interview): - -- [#4479](https://github.com/moq-dev/moq/pull/4479) does not land. It hid an - exact broadcast from a narrower reader only on the origin holding it: no - wire carries exactness, so relays install forwarded announcements through - `Producer::dynamic` as prefix routes and the broadcast's existence leaks to - narrower readers downstream. Exactness and suffixes are one problem, a - route's shape on the wire, so they are one quest. -- IETF stays prefix-only: moq-transport will not support exact or suffix - announcements (PUBLISH_NAMESPACE and NAMESPACE are prefix routes), so a - session negotiated as IETF never carries a shape and there is no draft to - converge with. -- The quest grew from the suffix-announce quest rather than a new m1 quest, - because that quest already holds the benchmark-first plan and the - version-gated wire approach both shapes need. -- Moved from m3 to m2 in the 2026-09-30 audit: it has no external gate, and - the exact-scope leak is a real bug. -- The old gate ("a deployment needs a suffix claim a service prefix cannot - express") is removed: the exact-scope leak is reason enough. - -### Wire - -The shape rides on both ANNOUNCE_REQUEST (interest) and ANNOUNCE_START -(advertisement), version- or setup-gated like `hidden`. A new announce Type is -not an option: an old receiver skips an unknown type without assigning it an -id (`rs/moq-net/src/lite/announce.rs`), so the id streams diverge. An older -peer gets prefix-only behavior; decide per shape whether downgrading it to a -prefix is safe (an exact route widened to a prefix still leaks) or whether the -route is withheld. Update `js/net` and `drafts/draft-lcurley-moq-lite.md` in -the same PR. - -Today ANNOUNCE_START carries a path relative to the requested prefix, which -the receiver joins back on (`rs/moq-net/src/lite/subscriber.rs`). A suffix -interest (`**/transcode.pro`) has no literal prefix to join, and a matching -route is not its suffix, so the draft must define how each advertisement is -anchored and rebased for each interest shape, with the cross-shape overlap -cases as vectors both languages test. - -Only these four shapes go on the wire. A richer interest pattern -(`pid/*/chat`) stays a consume-side filter over the widest shape that covers -it. Path patterns already shipped for that filtering and for token claims -(`moq-pattern`, `@moq/pattern`, -[#3746](https://github.com/moq-dev/moq/pull/3746), and the -[auth line](/quest/m1/auth/README.md)). - -### Model - -The origin model needs an `exact` route kind distinct from `source`: today -only a local broadcast (`source` set) is exact, and a forwarded route is -always a prefix. Carrying the kind also tightens `serves()` for a remote exact -route. An exact and a prefix route can share a path, but `sync_cursor` -presents one best entry per path and the lite announce state -(`AnnounceRun.live`, pending updates) is keyed by path alone, so today one -shape hides the other on the wire. Shape likely joins that identity. The -known exact-scope spots: - -- Rust: `sync_cursor` in `rs/moq-net/src/model/origin.rs` admits an exact - entry by prefix overlap; match it against the reader's patterns instead. - `cursor_keeps_an_overlapping_prefix_above_its_scope` covers a prefix route - and stays. -- JS: `Scope.projectRoutes` in `js/net/src/origin.ts` treats every entry - above the root as covering, and `Candidate.exact` is local-only today. -- Test in both languages, locally and across a relay hop: an exact broadcast - at `/a` and a prefix route at `/a` both survive a root-scoped hop, and read - through a `/a/b` scope yield only the prefix. #4479's regressions and - benchmark are a starting point. - -### Benchmark first - -The route table is a trie keyed by path segment (`rs/moq-net/benches/origin.rs`). -A suffix cannot walk it, so a naive match costs the whole announce table on -every announcement and every new cursor. Requests hit the same wall: -`request_broadcast` resolves through `best_route`, which walks the prefix trie -for the longest covering claim, so a suffix advertisement must also be found -by SUBSCRIBE and FETCH resolution. Longest prefix cannot rank `a/**` against -`**/z` for `a/x/z`, so define one total cross-shape precedence and tie rule -that Rust, JS, and relays share; path patterns' structural specificity is the -natural starting point. - -Extend `rs/moq-net/benches/origin.rs` with suffix and exact cursors and route -lookups, each swept over publishers and subscribers, and extend -`js/net/bench/forward.ts` the same way, since `Scope.projectRoutes` scans -routes independently of Rust. The slopes decide between a reversed-segment -index and dropping suffix shapes from the quest. - -A shaped advertisement is authorized against the sender's publish claim, as -Wildcard (#4403) does for prefix advertisements today -(decided in the 2026-10-06 audit). Token patterns (`moq-pattern`, -`moq_auth::Claims`) already match suffixes, so no auth change is needed. - -## Related - -- [Cluster routing](/quest/m1/cluster-routing/README.md) - forwards announcements between relays, which must keep their shape diff --git a/quest/m2/catalog-tracks.md b/quest/m2/catalog-tracks.md index 96d3fdac8dd..91bf4d6f4c6 100644 --- a/quest/m2/catalog-tracks.md +++ b/quest/m2/catalog-tracks.md @@ -23,6 +23,13 @@ catalog can keep both, or a new [broadcast epoch](/quest/m0/broadcast-epoch/READ when the whole broadcast restarts. The catalog may still add and remove tracks; a removed name is never reused for different content. +Only a track's defining fields are immutable: codec and its config bytes, +resolution, audio layout, and anything else a decoder needs. Live state that +describes the track's delivery changes freely under the same name: `enabled`, +the jitter and delay figures, and `warmup`. Name the split in the catalog +docs and the hang draft so a catalog update that changes only live state is +never mistaken for a new identity (split in the 2026-10-08 audit). + Cover codec changes, rendition switches, reconnects, and late joiners in Rust, JS, and HLS/watch tests. diff --git a/quest/m2/gpu-release.md b/quest/m2/gpu-release.md index 14bf2e82cb7..be4dab0a24b 100644 --- a/quest/m2/gpu-release.md +++ b/quest/m2/gpu-release.md @@ -3,12 +3,13 @@ ## Goal The `release` branch and crates.io carry the neutral `Surface::Vulkan`, the -Vulkan Video encoder, and VA-API import of an external Vulkan image, so a -consumer pinned to `release` (moq.pro is) can drop its vendor code. +Vulkan Video encoder, VA-API import of an external Vulkan image, and the +vendor-neutral GPU capacity and health report, so a consumer pinned to +`release` (moq.pro is) can drop its vendor code, its GPU admission included. ## Plan -Release all three together: the VA-API and AMD proofs are what show the +Release them together: the VA-API and AMD proofs are what show the surface is right, and shipping it before them risks a second breaking change. The surface is a breaking `moq-video` change on `main`, and releases are @@ -25,3 +26,4 @@ maintainer at release time: - [One external GPU image for every encoder](/quest/m2/gpu-surface.md) - the neutral surface and auto-selection - [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - the AMD encoder - [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - the Intel proof +- [GPU capacity and health](/quest/m2/gpu-health.md) - keyed by the same device identity; moq.pro's admission still needs vendor code without it diff --git a/quest/m2/intra-refresh/consumer-warmup.md b/quest/m2/intra-refresh/consumer-warmup.md index 3985655fd91..f8fb31a2dc2 100644 --- a/quest/m2/intra-refresh/consumer-warmup.md +++ b/quest/m2/intra-refresh/consumer-warmup.md @@ -22,7 +22,8 @@ replaces both: the rule is timestamp arithmetic on the group start. - Withhold rule, keyed on the same non-continuous signal in both consumers: `js/hang/src/container/consumer.ts` `next()` reports `continuous: false` after a subscribe, a declared discontinuity, or any skip (`#gap`). The Rust - `moq_mux::container::Consumer` gains the equivalent in the open-GOP quest + `moq_mux::container::Consumer` gains the equivalent in + [Rust non-continuous signal](/quest/m1/rust-continuous.md) (today `poll_read` returns a bare frame and only the `discontinuity()` counter moves); this quest reuses it, and `rs/moq-video/src/decode/consumer.rs` propagates it. For the first @@ -38,7 +39,7 @@ replaces both: the rule is timestamp arithmetic on the group start. types). Rust has the NAL walkers in `rs/moq-mux/src/codec/{h264,h265}`; JS needs a small length-prefixed walker beside the codec description parsing in `js/hang`. Other codecs never set `warmup`, so no check is needed there. -- Join earlier: the subscription's maximum age becomes the latency target plus +- Join earlier: the subscription's maximum delay becomes the latency target plus `warmup`, so the group start lands `warmup` before the target and the first presented frame is on time. JS sets the subscription's `maxDelay` in `js/net`; Rust adds it to the decode consumer's `Options::max_delay`, which reaches the @@ -60,4 +61,8 @@ replaces both: the rule is timestamp arithmetic on the group start. ## Required - [Catalog warmup](/quest/m1/catalog-warmup.md) - the field this reads -- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - adds the Rust non-continuous signal this keys on, and trims frames stamped before the keyframe where this trims frames after the start +- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims frames stamped before the keyframe where this trims frames after the start + +## Related + +- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust half of the signal this keys on diff --git a/quest/m2/native-enabled.md b/quest/m2/native-enabled.md index b5a3fb4469a..ad8cb7c08fc 100644 --- a/quest/m2/native-enabled.md +++ b/quest/m2/native-enabled.md @@ -19,3 +19,7 @@ Test mixed and all-disabled catalogs, plus disable/re-enable transitions. A C `moq_consume_audio_enabled` getter is added only if a C consumer needs it; any FFI/C API change updates all wrappers and their docs in the same PR. Update native consumer docs for the selection behavior. + +## Related + +- [Audio ranked](/quest/m1/audio-ranked.md) - its audio `ranked()` orders enabled renditions first, the audio half of the shared eligible selection diff --git a/quest/m2/quic-bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md index b3413bf83ae..834d6ec23eb 100644 --- a/quest/m2/quic-bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -39,3 +39,7 @@ traffic yet. ## Required - [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + +## Related + +- [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) - edits the same `bbr3/mod.rs` packet bookkeeping and lands first; this keeps the metadata it preserves diff --git a/quest/m2/quic-ecn.md b/quest/m2/quic-ecn.md index 8e6db1d0df6..a0a61ce38d5 100644 --- a/quest/m2/quic-ecn.md +++ b/quest/m2/quic-ecn.md @@ -11,8 +11,8 @@ marks fall back to no ECN, and a viewer's session is unaffected. ECT(0) marking and ACK ECN counts are carried end to end, and BBR's classic CE response ([moq-dev/noq#12](https://github.com/moq-dev/noq/pull/12), in -moq-noq 1.3.2) is the baseline. This quest adds the scalable policy separately. -noq-proto has no ECN knob: `sending_ecn` starts on per path and validation +moq-noq 1.3.2; `main` pins moq-noq-proto 2.0.1) is the baseline. This quest +adds the scalable policy separately. noq-proto has no ECN knob: `sending_ecn` starts on per path and validation failure or an ACK without counts turns it off, so both `off` and `ect1` need the fork. diff --git a/quest/m2/quic-qmux.md b/quest/m2/quic-qmux.md index 18c5dd3da19..0d068f8e666 100644 --- a/quest/m2/quic-qmux.md +++ b/quest/m2/quic-qmux.md @@ -87,3 +87,4 @@ the fork plan the same day kept it there. ## Related - [noq#812](https://github.com/n0-computer/noq/issues/812) - the qmux proposal to n0 +- [tls:// peer certificates](/quest/m2/tls-listener-mtls.md) - needs a peer-certificate accessor on qmux's TLS session, upstream or in-tree diff --git a/quest/m2/rtsp-import.md b/quest/m2/rtsp-import.md index 903dcea7f07..cacf1f02fa5 100644 --- a/quest/m2/rtsp-import.md +++ b/quest/m2/rtsp-import.md @@ -45,7 +45,9 @@ Decided 2026-10-01: sharing it under a fresh epoch, per [Broadcast epochs](/quest/m0/broadcast-epoch/README.md), with a fresh catalog, tracks, and importers starting on a keyframe. The CLI publishes - each run (each reconnect) under a fresh epoch. Decided 2026-10-02 and + each run (each reconnect) under a fresh epoch, so `moq import rtsp` refuses + `--epoch` (`takes_epoch` is false for it, as for the other gateways); test + the refusal. Decided 2026-10-02 and 2026-10-05; shifting timestamps onto the existing catalog clock behind a `discontinuity()` marker was rejected. - Credentials ride the URL's userinfo, as every RTSP tool takes them. retina diff --git a/quest/m2/teleop/robot.md b/quest/m2/teleop/robot.md index ac5caaa1508..0b0d06b1056 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m2/teleop/robot.md @@ -92,7 +92,10 @@ The bridge is each broadcast's fixed catalog-root `clock: { wall, timescale }`, documented in `doc/concept/hang.md` (#4461). Media and command tracks keep their own timescales; convert PTS explicitly into the broadcast clock before joining samples. The robot's video and telemetry share a clock; the operator's -command broadcast supplies its own mapping. +command broadcast supplies its own mapping. Command and telemetry tracks +declare `Timescale::MILLI` explicitly: once an undeclared Rust timescale means +untimed ([Rust untimed default](/quest/m1/rust-untimed-default.md)), a track +that leaves it out carries no timestamps to join. The clock assumption: the two hosts' wall clocks are synchronized by the deployment, not by the library. State this beside the API, since a join across @@ -110,3 +113,4 @@ control then it is the wrong abstraction. ## Related - [arbitration](/quest/m2/teleop/arbitration.md) - which controller is obeyed +- [Rust untimed default](/quest/m1/rust-untimed-default.md) - why command and telemetry tracks declare their timescale diff --git a/quest/m2/tls-listener-mtls.md b/quest/m2/tls-listener-mtls.md index b743e3641dd..95a2d3f1341 100644 --- a/quest/m2/tls-listener-mtls.md +++ b/quest/m2/tls-listener-mtls.md @@ -30,3 +30,7 @@ that refusal for a server with a `tls://` listener and updates the refusal's test. Public API: relay config may gain a listener option. Wire: none. + +## Related + +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - moves qmux in-tree; if it lands first, the peer-certificate accessor lands here instead of upstream diff --git a/quest/m2/video-vaapi.md b/quest/m2/video-vaapi.md index 117828ec62f..da73c013229 100644 --- a/quest/m2/video-vaapi.md +++ b/quest/m2/video-vaapi.md @@ -16,7 +16,7 @@ encode, H.265 decode, pre-generated bindings, the resize pool) and cutting the release, then bumping the workspace requirement here. The resize-pool quest folds in for the same reason. -**Decode.** The H.264 decoder landed (moq-vaapi 0.0.4, `decode/backend/vaapi.rs`), +**Decode.** The H.264 decoder landed (`decode/backend/vaapi.rs`; the workspace pins moq-vaapi 0.1.0), with the default `decode::Config::output` of `Output::Native` handing out DMA-BUF surfaces the renderer imports without a download. H.265 decode is still missing, so a Linux box without NVDEC has no hardware path for it. @@ -27,13 +27,13 @@ converts them through VPP (`dmabuf`, `vpp`, `Encoder::encode_dmabuf`, without a download, and `Surface::resize` scales one through VPP. Validated on Intel Meteor Lake. What is left is H.265, below. -**H.265.** The VAAPI backend advertises H.264 only. `moq-vaapi` 0.0.2 vendors +**H.265.** The VAAPI backend advertises H.264 only. `moq-vaapi` 0.1.0 vendors the HEVC buffer types (`src/buffer/hevc.rs`) but its `Encoder` is hardcoded to `VAProfileH264Main` (with `VAEntrypointEncSlice`, or the low-power entrypoint where that is all a device has), so exposing an HEVC encoder is a change to that crate, not a flag here. -**Build cost.** `moq-vaapi` 0.0.3 dlopens libva (no `DT_NEEDED`), so a +**Build cost.** `moq-vaapi` dlopens libva (no `DT_NEEDED`), so a libva-less host starts and `backend::open` falls through to the next encoder. What remains is the build side: its build script runs bindgen over the vendored libva headers, so every consumer needs libclang on the build host. diff --git a/quest/m3/cut-through/README.md b/quest/m3/cut-through/README.md index a42d96e2afa..8310ae487d5 100644 --- a/quest/m3/cut-through/README.md +++ b/quest/m3/cut-through/README.md @@ -46,15 +46,16 @@ Decided 2026-09-30: received and the per-session pre-allocation `Budget` (`model/frame.rs`) does not apply. The group cache already charges each frame by bytes written (#4609), so several in-flight frames charge only what has arrived. -- `web-transport-trait` gains an unordered chunk read and an offset write whose - defaults report unsupported, and moq-net falls back to ordered I/O. Only the +- moq-net's `transport::poll` traits gain an unordered chunk read and an + offset write whose defaults report unsupported, and moq-net falls back to + ordered I/O. Only the `moq-quic` backends implement them; browsers, qmux, and iroh keep the defaults. Additive, so it lands on `main`. - Always on wherever both of the relay's streams support it. No config knob. - The relay's own egress is `moq-quic` for every native and browser viewer, so browser viewers benefit too; only the relay's side needs the feature. -Public API: additive `web-transport-trait` methods; the loss-delay counter on +Public API: additive `transport::poll` methods in moq-net; the loss-delay counter on `moq-stats` ingress rows. Wire: none for MoQ; the counter is a `moq-stats` field. @@ -69,7 +70,7 @@ stats field, which its quest documents inline. - [Bench](/quest/m3/cut-through/bench.md) - a lossy relay hop swept over loss, frame size, and egress headroom, measuring the post-hole drain time, with a go or no-go verdict - [Offset writes in moq-quic](/quest/m3/cut-through/quic.md) - send streams accept writes past a gap and send them right away - [Frame ranges](/quest/m3/cut-through/frames.md) - frames fill out of order, several at once per group, and a reader sees each range as it lands -- [Transport trait](/quest/m3/cut-through/transport.md) - `web-transport-trait` carries unordered reads and offset writes, implemented for `moq-quic` +- [Transport trait](/quest/m3/cut-through/transport.md) - moq-net's `transport::poll` carries unordered reads and offset writes, implemented for `moq-quic` - [Relay cut-through](/quest/m3/cut-through/relay.md) - lite and IETF group streams read out of order and write each range at its output offset ## Related diff --git a/quest/m3/cut-through/loss-delay.md b/quest/m3/cut-through/loss-delay.md index 807307827f5..d51eaf0afd2 100644 --- a/quest/m3/cut-through/loss-delay.md +++ b/quest/m3/cut-through/loss-delay.md @@ -22,10 +22,10 @@ Independent of the bench; it can start once `moq-quic` lands. when the application reads, so it stays meaningful once reads go unordered. When a stream ends with a hole still open (reset, stop, or session close), buffered bytes that have already waited one smoothed RTT are counted then. -- `moq-quic` exposes the per-stream count, and `web-transport-trait`'s - `RecvStream` gains an accessor returning `Option` (`None` when the backend - cannot see it), following the trait's `Stats` convention. Release the trait - and implement it in the in-tree `web-transport-moq`, as +- `moq-quic` exposes the per-stream count, and moq-net's + `transport::poll::RecvStream` gains an accessor returning `Option` (`None` + when the backend cannot see it), following the module's `Stats` + convention. The moq-tokio and moq-uring adapters implement it, as [poll_acked](/quest/m2/quic-ack-hook.md) does. - The lite and IETF subscribers read the count at each frame boundary and when the group stream ends, adding the delta to the broadcast's ingress row, so a diff --git a/quest/m3/cut-through/transport.md b/quest/m3/cut-through/transport.md index ec2962e3efe..48625bc3826 100644 --- a/quest/m3/cut-through/transport.md +++ b/quest/m3/cut-through/transport.md @@ -1,16 +1,20 @@ -# [M] Unordered reads and offset writes in web-transport-trait +# [M] Unordered reads and offset writes in moq-net's transport traits ## Goal -A released `web-transport-trait` lets a receive stream yield chunks with their -offsets in arrival order and lets a send stream write at an offset. The -`moq-quic` backends implement both; every other backend reports that it cannot. +moq-net's own poll transport traits (`transport::poll` in +`rs/moq-net/src/transport.rs`, since #4709) let a receive stream yield chunks +with their offsets in arrival order and let a send stream write at an offset. +The `moq-quic` backends implement both; every other backend reports that it +cannot. ## Plan -Decided 2026-09-30: additive methods with defaults, not a moq-net-private -extension trait, which would need per-session detection behind the generic -`Session`. +Decided 2026-09-30: additive methods with defaults, not a separate extension +trait, which would need per-session detection behind the generic `Session`. +Re-planned in the 2026-10-08 audit onto `transport::poll`, as +[poll_acked](/quest/m2/quic-ack-hook.md) was: moq-net no longer depends on +`web-transport-trait`, so no upstream release is needed. - `RecvStream` gains an unordered chunk read returning `(offset, Bytes)`, and `SendStream` gains an offset write, both in the poll style. Their defaults @@ -20,13 +24,12 @@ extension trait, which would need per-session detection behind the generic - quinn's assembler, which `moq-quic` keeps, allows no ordered read after an unordered one, so the unordered mode is entered once per stream and never left. -- Implement both in the in-tree `web-transport-moq` over the unordered - `read_chunk` and the [offset write](/quest/m3/cut-through/quic.md), and - natively in moq-uring's QUIC stream (today `rs/moq-uring/src/quic/noq/stream.rs`, +- Implement both in moq-tokio's adapter over the in-tree `web-transport-moq` + (its unordered `read_chunk` and the [offset write](/quest/m3/cut-through/quic.md)), + and natively in moq-uring's QUIC stream (today `rs/moq-uring/src/quic/noq/stream.rs`, renamed by the [switch](/quest/m1/quic/fork/switch.md)), which reads ordered - and drops the chunk offset. moq-tokio's poll adapter forwards them. - `web-transport-wasm`, qmux, and iroh keep the defaults. -- Release `web-transport-trait` and bump its pin here. + and drops the chunk offset. The WASM, qmux, and iroh adapters keep the + defaults. ## Required diff --git a/quest/m3/ladder/README.md b/quest/m3/ladder/README.md index 98e0b147fc6..479f0d3b0ed 100644 --- a/quest/m3/ladder/README.md +++ b/quest/m3/ladder/README.md @@ -46,17 +46,17 @@ controller only consumes that tiebreak. ### Adaptive bands -`moq_transcode::Rung::bitrate` (`rs/moq-transcode/src/ladder.rs:14-17`) stays +`moq_transcode::Rung::bitrate` (`rs/moq-transcode/src/ladder.rs`) stays the configured maximum and never follows the instantaneous target. For a rendition with configured maximum `max` and the next lower rendition's `lower`: ```text -stall = (max + 2 * lower) / 3 +disable = (max + 2 * lower) / 3 ``` The lowest rendition takes `lower = 0`, so its boundary is `max / 3`. An -encoder may adapt within `[stall, max]`; below the boundary the rung is +encoder may adapt within `[disable, max]`; below the boundary the rung is disabled (`enabled: false`) and stops encoding, and it is enabled again only once a target at or above the same boundary is successfully applied. Catalog state follows the last target the encoder *accepted*, not the one the controller requested, so a transient rate-control diff --git a/quest/m3/ladder/controller.md b/quest/m3/ladder/controller.md index 28a92a9bd3f..e5dbf442875 100644 --- a/quest/m3/ladder/controller.md +++ b/quest/m3/ladder/controller.md @@ -11,8 +11,8 @@ shedding drops the top of the ladder first. Add an optional bandwidth input to the transcode configuration and wire the CLI's publisher session into it. `transcode` is not stageable -(`rs/moq-cli/src/args.rs:593-596`), so it dials its own session -(`rs/moq-cli/src/main.rs:236`, `rs/moq-cli/src/transcode.rs:130-140`) and +(`rs/moq-cli/src/args.rs`), so it dials its own session +(`rs/moq-cli/src/main.rs`, `rs/moq-cli/src/transcode.rs`) and that session is the whole bandwidth domain. Supplying no input preserves today's fixed-rate behavior exactly and never publishes congestion-induced `enabled` state, which is what keeps this additive. @@ -20,16 +20,16 @@ today's fixed-rate behavior exactly and never publishes congestion-induced The controller subdivides that estimate across the ladder and applies the band boundary from the [questline](/quest/m3/ladder/README.md), including the lowest rung's `max / 3` case. `moq_transcode::Ladder` is ascending: `new` -sorts by configured maximum (`rs/moq-transcode/src/ladder.rs:101`) and -`rungs()` is lowest first (`:125-128`), so the next lower rendition the +sorts by configured maximum (`rs/moq-transcode/src/ladder.rs`) and +`rungs()` is lowest first, so the next lower rendition the formula reads is the preceding entry and the lowest rung is the one with none. ### One priority for allocation and send order Assign descending `track::Info::priority` down the ladder. Every rung is -stamped `PRIORITY.video` today (`rs/moq-transcode/src/rung.rs:133`, -`rs/moq-transcode/src/lib.rs:352`, `:409`). The allocator fills a tier +stamped `PRIORITY.video` today (`rs/moq-transcode/src/rung.rs`, +`rs/moq-transcode/src/lib.rs`). The allocator fills a tier before the next sees a bit, so that alone protects lower rungs' allocation. For send order, consume the publisher-priority tiebreak in `Priority::cmp` @@ -46,7 +46,7 @@ lower one still gets what it asked for. follows what the encoder accepted. A transient rate-control failure keeps the last applied target and retries on a later material movement. - **`BitrateUnsupported` is an explicit fallback, not a silent one.** Mirror - moq-video's handling (`rs/moq-video/src/encode/producer.rs:383-386`): such + moq-video's handling (`rs/moq-video/src/encode/producer.rs`): such an encoder keeps its configured maximum, is disabled (`enabled: false`) whenever the allocation is below it, and is enabled only when the full maximum fits again. It reclaims no encoder work by design, and it must be visible in @@ -59,9 +59,9 @@ lower one still gets what it asked for. Acceptance: one demanded rung reaching its configured maximum on a permissive uplink; several rungs sharing one uplink with lower ones protected; a -supported rung adapting down, clamping, stalling, and recovering without its +supported rung adapting down, clamping, disabling, and re-enabling without its advertised maximum moving; the 5 Mbps over 2.5 Mbps boundary landing near -3.33 Mbps; the default 350 kbps lowest rung stalling near 117 kbps; an +3.33 Mbps; the default 350 kbps lowest rung disabled near 117 kbps; an unsupported encoder holding its maximum and not recovering early; no bandwidth input preserving existing behavior exactly; and for send order, equal subscriber priority where the lower rung wins, conflicting subscriber diff --git a/quest/m3/ladder/fetch.md b/quest/m3/ladder/fetch.md index b9762de79f2..2e14f7d5f88 100644 --- a/quest/m3/ladder/fetch.md +++ b/quest/m3/ladder/fetch.md @@ -13,14 +13,14 @@ controller owns it. The FETCH path opens a new encoder per requested group at `Rung::bitrate`: `spawn_fetch` and `fetch` -(`rs/moq-transcode/src/rung.rs:460-481`) call `encode`, which sets -`config.bitrate = Some(self.info.bitrate)` (`:107-116`), so a constrained ladder +(`rs/moq-transcode/src/rung.rs`) call `encode`, which sets +`config.bitrate = Some(self.info.bitrate)`, so a constrained ladder still burns full-rate encodes on demand. Make it read the controller's applied target and participate in the same allocation. A disabled rung stays manually fetchable, and cache hits are untouched. Catalog mutations publish full HANG, HANGZ, and MSF snapshots today -(`rs/moq-mux/src/catalog/producer.rs:86-113`). Coalesce every rung state +(`rs/moq-mux/src/catalog/producer.rs`). Coalesce every rung state change from one controller iteration into a single publication, and make a later source catalog snapshot compose with current generated-rung state rather than overwrite it. diff --git a/quest/m3/teleop-mavlink.md b/quest/m3/teleop-mavlink.md index b78ced31e6e..f428f233ac5 100644 --- a/quest/m3/teleop-mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -26,7 +26,9 @@ naming imply one leg. Read the header only: the 24-bit msgid in v2, 8-bit in v1. Payloads stay opaque bytes and route to a delivery class through a config table, with an unknown -msgid falling to a default. +msgid falling to a default. Every track declares `Timescale::MILLI` +explicitly, since an undeclared Rust timescale means untimed +([Rust untimed default](/quest/m1/rust-untimed-default.md)). This is what makes frame-aware routing free of the dialect tax. CRC_EXTRA (the per-message schema hash) is only needed to validate a frame, never to read its @@ -78,3 +80,7 @@ small, real contribution and its own future quest. - [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - [Operator arbitration](/quest/m2/teleop/arbitration.md) + +## Related + +- [Rust untimed default](/quest/m1/rust-untimed-default.md) - tracks that leave out their timescale are untimed From 9a501d4160a648b4e2e72edd3127d9bd17cba381 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:18:10 -0700 Subject: [PATCH 2/5] quest: a relay's old copy serves only the subscriptions already on it Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/restart.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index 94f0675628a..52edd48a6f7 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -66,7 +66,9 @@ Decided in planning (2026-10-07, from #4970's review): epoch no longer ends subscriptions in flight with `Unroutable` (`Pick::Superseded`, `front.rs` `supersede`). The front keeps serving its subscribers until its route goes. A relay keeps its upstream subscription - on the old route while any downstream still holds it. JS `route()` + on the old route while any downstream still holds it, serving only those + subscriptions: it forwards the `Restart` so they resubscribe, and no new + request joins that copy. JS `route()` (`js/net/src/origin.ts`) closes the old front when it swaps to a better entry, so it changes too. Update the epoch tests from #4942 and the three gateway tests that assert `Unroutable` (`a_reconnect_replaces_the_stale_*` From 4d9064f5159258bf179a04e14b7a0a7c0855d2bd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:24:51 -0700 Subject: [PATCH 3/5] quest: archive replay keeps a fresh epoch Co-Authored-By: Claude Opus 5.5 --- quest/m1/archive/dvr.md | 6 +++--- quest/m1/archive/replay-catalog.md | 14 ++++++++------ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/quest/m1/archive/dvr.md b/quest/m1/archive/dvr.md index 2bd2007fed0..1bf89e5d70e 100644 --- a/quest/m1/archive/dvr.md +++ b/quest/m1/archive/dvr.md @@ -49,9 +49,9 @@ no linger (the `hls-linger` quest was dropped, because an unannounced broadcast can't be FETCHed and a linger would only serve the cache). Test the handover: a live HLS session keeps its playlist URIs and media sequence numbers when the name moves from the live publisher to the archive, which -announces under the recorded epoch ([Replay -catalog](/quest/m1/archive/replay-catalog.md)), so a subscription resumes -rather than restarts. +announces a fresh epoch ([Replay +catalog](/quest/m1/archive/replay-catalog.md)), so viewers follow a +`Restart` rather than resume. ## Required diff --git a/quest/m1/archive/replay-catalog.md b/quest/m1/archive/replay-catalog.md index 2d22521b102..7d7e5f5b204 100644 --- a/quest/m1/archive/replay-catalog.md +++ b/quest/m1/archive/replay-catalog.md @@ -32,12 +32,14 @@ this by hand-building a catalog. `moq-cli` only passes the URL and the opt-out. Select the catalog track by catalog format as `export archive` does: hang and hang.z are stamped, MSF is refused. -- The replay announces under the epoch the recording's `.info` keeps - (decided in the 2026-10-08 audit), not a freshly minted one: it is the - same content, so a live-to-archive handover at one path resumes instead of - restarting viewers. A recording whose source had no epoch replays without - one, and that handover is a `Restart`. Today `moq import archive` mints - per run (#4942); change it. +- The replay keeps minting a fresh epoch per run (#4942), so a + live-to-archive handover at one path is a `Restart`, not a resume (decided + in the 2026-10-08 audit, after #5043's review). Reusing the recorded + `.info` epoch was rejected for now: the archive writes its own + `.timeline.z` groups under the live names, and this quest rewrites + catalog groups, so the same name, epoch, and group number could carry + different bytes. Revisit only once replayed metadata is byte- and + sequence-identical to live. - The recorded catalog's `archive` entry describes the source's live timelines, not the recording's, so replace it with the timelines the reader replays rather than trusting the recorded ones. From 3164fa08d9a5166cbabda4e9c0b514dc67675efb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:29:59 -0700 Subject: [PATCH 4/5] quest: address review findings on the audit Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 5 +++-- quest/m0/broadcast-epoch/restart.md | 12 ++++++++---- quest/m0/broadcast-epoch/ts-restart.md | 1 + quest/m1/archive/replay-catalog.md | 4 +++- quest/m1/hop-aligned-import.md | 13 ++++++++----- quest/m1/subscribe-ranges/ietf.md | 2 +- quest/m2/intra-refresh/consumer-warmup.md | 4 ++-- quest/m2/quic-bbr-loss-parity.md | 2 +- 8 files changed, 27 insertions(+), 16 deletions(-) diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index c733e0e3ceb..3e5c5e72293 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -8,8 +8,9 @@ the same epoch resume a subscription from the first frame it lacks; a route without one keeps its subscriptions until it goes. So epochs are what make failover seamless. Routes without an epoch never splice (maintainer, 2026-10-08): a `Restart` (or an end and start on older versions) tells every -downstream subscriber, downstream relays included, to drop its copy of the -old source and resubscribe fresh. A restart is a new epoch at the same +downstream subscriber to stop using its copy of the old source and +resubscribe fresh; a downstream relay retires its copy for new requests and +forwards the `Restart`. A restart is a new epoch at the same path: the newest epoch wins new requests and announce consumers see that `Restart`, so viewers re-request rather than stall on a replaced broadcast. Subscriptions already on the old one stay until the diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index 52edd48a6f7..846b89d6346 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -17,9 +17,11 @@ or follow the new one. New requests resolve the current winner and never join a front pinned to a replaced route. Routes without an epoch never splice (maintainer, 2026-10-08). A `Restart` -(or an `End` then `Start` on older wires) tells every downstream subscriber, -a downstream relay included, to drop its copy of the old source and -resubscribe fresh. A copy resumes or splices only across routes with an +(or an `End` then `Start` on older wires) tells every downstream subscriber +to stop using its copy of the old source and resubscribe fresh. A downstream +relay retires its copy for new requests and forwards the `Restart`; the +subscriptions already on that copy follow it as their own applications +decide. A copy resumes or splices only across routes with an identical epoch, so the old copy's cached groups never reach a subscriber of the new source. @@ -107,7 +109,9 @@ Decided in planning (2026-10-07, from #4970's review): PR, since the enum match is exhaustive: moq-ffi's `MoqAnnounceEvent` gains `Restart` (its wrappers follow in [Bindings](/quest/m0/broadcast-epoch/bindings.md)), and moq-c, moq-stats, - moq-relay, moq-room, moq-boy, moq-cli, moq-rtc, and moq-tokio map it. + moq-relay, moq-room, moq-boy, moq-cli, moq-rtc, moq-tokio, and moq-bench + map it. `rs/hang/examples/subscribe.rs` compiles through its catch-all arm + but must follow a `Restart` rather than bail on it. - **Rejected** (in #5013): `@moq/watch` resubscribing on `Internal` or `SessionClosed` (#4999), since players recover on announcements, not errors; announcing only once the old front dies, since viewers stay blank diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index 4db2980675f..048fa0dcb49 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -43,6 +43,7 @@ connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. Public API: breaking in moq-mux, `ts::Import::decode` reports a restart and `restart` is new. Wire: none. + ## Closes - [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import diff --git a/quest/m1/archive/replay-catalog.md b/quest/m1/archive/replay-catalog.md index 7d7e5f5b204..e5c1ad3bfaa 100644 --- a/quest/m1/archive/replay-catalog.md +++ b/quest/m1/archive/replay-catalog.md @@ -39,7 +39,9 @@ this by hand-building a catalog. `.timeline.z` groups under the live names, and this quest rewrites catalog groups, so the same name, epoch, and group number could carry different bytes. Revisit only once replayed metadata is byte- and - sequence-identical to live. + sequence-identical to live. So `moq import archive` refuses `--epoch` + (`takes_epoch` false for `Archive`), and any `moq-archive` host mints its + own epoch or takes one from its caller, never defaulting to `.info`'s. - The recorded catalog's `archive` entry describes the source's live timelines, not the recording's, so replace it with the timelines the reader replays rather than trusting the recorded ones. diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index a18270761b9..210ede966a1 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -15,11 +15,14 @@ failover `export ts` sees a timestamp rewind and exits (#4354). Decided: every publisher of one path and epoch MUST publish the same broadcasts and tracks, since routes with the same epoch resume each other's subscriptions. A redundant pair is keyed by a shared explicit epoch (decided -2026-10-03: `--hop` no longer exists to key it). Make every container importer -that `moq import --epoch` accepts (ts, fmp4, flv, mkv) meet the contract when -fed one encoded stream. The SRT, RTMP, and RTC gateways and `ts --program all` -are out: they mint an epoch per ingest connection (#4962), so two of them -never share one. Capture is out too: two encoders never align. +2026-10-03: `--hop` no longer exists to key it). Make every importer that +`moq import --epoch` accepts for one encoded stream (ts with one program, +fmp4, flv, avc3, and the HLS pull that reuses them) meet the contract when +fed one encoded stream. RTMP and SRT imports, the WHIP listener, and +`ts --program all` are out: they mint an epoch per ingest connection +(#4962), so two of them never share one. The WHEP pull and archive replay +are out too (each pull's RTP session and each replay is its own instance), +and so is capture: two encoders never align. - A group's sequence derives from its keyframe's media timestamp (PTS in TS), not a per-process counter. Decide how both processes agree across a diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 117d09e1b1a..85ac0d011b8 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -16,7 +16,7 @@ one stream. Absent sequences between the FETCH's groups become drops, and a group already cached is discarded as a duplicate. Cap a downstream FETCH at the Largest Object, as the moq-transport drafts require. A relay with only fetch demand learns the upstream's Largest from TRACK_STATUS without a -SUBSCRIBE, as #4974 makes fetch-only demand do. +SUBSCRIBE, as open #4974 does for fetch-only demand. [Cross-relay FETCH over moq-transport](/quest/m1/ietf-peer-fetch-old.md) fixes the same FETCH path refusing held groups as `old`. diff --git a/quest/m2/intra-refresh/consumer-warmup.md b/quest/m2/intra-refresh/consumer-warmup.md index f8fb31a2dc2..03ad02019c2 100644 --- a/quest/m2/intra-refresh/consumer-warmup.md +++ b/quest/m2/intra-refresh/consumer-warmup.md @@ -61,8 +61,8 @@ replaces both: the rule is timestamp arithmetic on the group start. ## Required - [Catalog warmup](/quest/m1/catalog-warmup.md) - the field this reads -- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims frames stamped before the keyframe where this trims frames after the start +- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust signal this keys on ## Related -- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust half of the signal this keys on +- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims frames stamped before the keyframe where this trims frames after the start diff --git a/quest/m2/quic-bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md index 834d6ec23eb..5bc4ca1f0da 100644 --- a/quest/m2/quic-bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -38,7 +38,7 @@ traffic yet. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`, where this lands; the core and its BBR3 are already in `rs/moq-quic` ## Related From ccfd00702d7cd1b3e2fac15335f93ff114e167ed Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 19:34:32 -0700 Subject: [PATCH 5/5] quest: the WHEP pull refuses --epoch Co-Authored-By: Claude Opus 5.5 --- quest/m1/hop-aligned-import.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 210ede966a1..700440875bf 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -22,7 +22,10 @@ fed one encoded stream. RTMP and SRT imports, the WHIP listener, and `ts --program all` are out: they mint an epoch per ingest connection (#4962), so two of them never share one. The WHEP pull and archive replay are out too (each pull's RTP session and each replay is its own instance), -and so is capture: two encoders never align. +and so is capture: two encoders never align. Since the CLI still accepts +`--epoch` for `rtc --connect`, make it refuse one (`takes_epoch` false, as +[Replay catalog](/quest/m1/archive/replay-catalog.md) does for archive), with +a regression test. - A group's sequence derives from its keyframe's media timestamp (PTS in TS), not a per-process counter. Decide how both processes agree across a