From ec21f3ac185bf159a877aee892f4672a0adb76e7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:15:38 -0700 Subject: [PATCH 01/10] quest: apply audit fixes (group 1) Co-Authored-By: Claude Opus 5.5 --- quest/m0/audio-jitter-target/watch.md | 8 ++- quest/m0/broadcast-epoch/claim-epochs.md | 9 ++- .../publish-catalog-restart.md | 10 +++ quest/m0/broadcast-epoch/restart.md | 43 ++++++------ quest/m0/broadcast-epoch/stats-split.md | 11 ++- quest/m0/held-group-wakes.md | 14 +++- quest/m0/idle-fronts.md | 2 +- quest/m0/ietf-end-of-group-status.md | 8 ++- quest/m0/ietf-end-of-track-location.md | 67 ++++++------------- quest/m0/ietf-location-filter-22.md | 8 +++ quest/m0/largest-regression.md | 19 +++++- quest/m0/qmux-credit-upstream.md | 2 +- quest/m0/track-stream-demand.md | 20 +++++- quest/m1/bot-workflows-permission.md | 14 ++-- quest/m1/cache-max-age.md | 21 +++--- quest/m1/cluster-routing/multi-cdn.md | 23 ++++--- quest/m1/cluster-routing/sim.md | 26 +++++-- quest/m1/cmaf-frame-timestamp.md | 37 +++++----- quest/m1/cmaf-sample-defaults.md | 3 +- quest/m1/cross-relay-bursts.md | 7 +- quest/m1/ffi-shape/codec.md | 34 +++++++++- quest/m1/iroh-capsule-bump.md | 4 +- quest/m1/js-publish-timestamp.md | 17 +++-- quest/m1/merge-queue-settings.md | 9 +++ quest/m1/publish-timestamp.md | 22 +++--- quest/m1/quest-flat-lines.md | 20 +++--- quest/m1/rust-untimed-default.md | 27 +++++--- 27 files changed, 328 insertions(+), 157 deletions(-) diff --git a/quest/m0/audio-jitter-target/watch.md b/quest/m0/audio-jitter-target/watch.md index 707f044d5a7..543af19a990 100644 --- a/quest/m0/audio-jitter-target/watch.md +++ b/quest/m0/audio-jitter-target/watch.md @@ -49,7 +49,13 @@ about 22 s with skip-aheads on the way down. 88 to 275 ms/s drift the issue reported stand unconfirmed. If drift survives, the suspects are `writeFrame` opening a group per audio frame under WebTransport stream credit and the main-thread task queue delivering encoder - output. Turn that into its own quest rather than fixing it here. + output. The audio encoder's `groupDuration` (#4910, default 0: a group per + frame) tests the first: A/B it against a group of 100 ms or so in the same + run. Turn that into its own quest rather than fixing it here. + +Decided 2026-10-08: moves to m1 with the rest of the line. The estimator +defaults on and only this manual proof is left, so it no longer gates a +release. ## Related diff --git a/quest/m0/broadcast-epoch/claim-epochs.md b/quest/m0/broadcast-epoch/claim-epochs.md index ffe32fdf1a8..aef6101a5ac 100644 --- a/quest/m0/broadcast-epoch/claim-epochs.md +++ b/quest/m0/broadcast-epoch/claim-epochs.md @@ -70,6 +70,8 @@ Decisions (2026-10-07, proposed for the maintainer): never hands a returning viewer the old instance's group. This is a lite-07 wire change, so it lands before the version is cut. +Decided 2026-10-08: moves to m1. lite-07 is opt-in and these decisions are +still proposed, so it gates the lite-07 cut, not the m0 release. Verification: a relay integration test with two claim workers (mocked time). A worker restarting an output within the linger delivers the new instance from @@ -86,9 +88,12 @@ new epoch. Public API: Rust and JS, the broadcast's epoch and what `accept` does with it. Wire: lite-07 TRACK_INFO gains `Epoch`. -## Related +## Required - [Restart](/quest/m0/broadcast-epoch/restart.md) - the join rule and sticky subscriptions this builds on + +## Related + - [Idle fronts](/quest/m0/idle-fronts.md) - ends an unread front and its per-path state after the linger on every version -- [Upstream position regression](/quest/m0/largest-regression.md) - catches a restart on versions without this field +- [Upstream position regression](/quest/m0/largest-regression.md) - catches the same restart from the answer's largest position on lite-07 and moq-transport; lite-05 and 06 stay uncovered - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - waits on this wire change diff --git a/quest/m0/broadcast-epoch/publish-catalog-restart.md b/quest/m0/broadcast-epoch/publish-catalog-restart.md index 60bff880fbc..acaad9c8dc9 100644 --- a/quest/m0/broadcast-epoch/publish-catalog-restart.md +++ b/quest/m0/broadcast-epoch/publish-catalog-restart.md @@ -22,4 +22,14 @@ re-announce. `js/publish/src/broadcast.ts` mints the epoch once and keeps the publisher across unannounce and announce on purpose, which points at continuing the sequence. +Open PR #4929 makes Rust's `create_track` continue a name's sequence across +replacements, but leaves JS `createTrack` starting at 0. If this reproduces, +consider fixing it there, in `@moq/net`'s `createTrack`, so every JS +publisher continues the sequence the way Rust does, rather than in +`@moq/publish` alone. Rebase onto #4929 if it lands first. + Public API: none expected. Wire: none. + +## Related + +- [Coalesce dynamic tracks](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - #4929, continuous sequences per track name in Rust diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index c8201093a82..52ba06ce794 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -3,9 +3,8 @@ ## Goal When the source behind a path changes, an announce consumer sees an -explicit `Restart` event, in Rust (`AnnounceEvent::Restart`) and `@moq/net`: -always on lite-07, and on older versions and moq-transport when the END and -START arrive together (otherwise an `End` then a `Start`). +explicit `Restart` event, in Rust (`AnnounceEvent::Restart`) and `@moq/net`, +on lite-07. Older versions and moq-transport deliver an `End` then a `Start`. The source changes on a newer epoch, or, on a route without an epoch, when a different route entry wins. A re-price or a same-source failover stays an `Update`. Players start on `Start`, restart on `Restart`, and stop on `End`. @@ -47,6 +46,14 @@ path kept its worker just resubscribes to the same source. Decided in planning (2026-10-07, from #4970's review): +- **`Restart` only on lite-07 (2026-10-08).** Older wires send and deliver + END then START. Coalescing a pending pair into one `Restart` depends on + read timing, so it is dropped rather than tested as either outcome. +- **Rename the existing message first.** lite-06's `ANNOUNCE_RESTART` (type 2: + `AnnounceBroadcast::Restart` in `rs/moq-net/src/lite/announce.rs`, the + `"restart"` status in `js/net/src/lite/announce.ts`) is the draft's + ANNOUNCE_UPDATE, a metadata update. Rename it to Update in both languages + before adding the new message, so `Restart` means one thing. - **Supersedes #5013's hard switch.** #5013 decided (2026-10-07) that a better route without an epoch takes over with a hard switch, ending subscriptions in flight. The maintainer chose sticky subscriptions plus @@ -110,9 +117,8 @@ Decided in planning (2026-10-07, from #4970's review): path. Older lite versions and moq-transport send `ANNOUNCE_END` then `ANNOUNCE_START` for a source change, a new rule for a relay's winner moving between entries (the draft only says so for a - publisher replacing its own epoch), and a receiver delivers an end and - start for the same prefix that are both pending before delivery as one - `Restart` (no timer). `ANNOUNCE_UPDATE` stays a metadata update with no + publisher replacing its own epoch), and a receiver delivers them as an + `End` then a `Start`. `ANNOUNCE_UPDATE` stays a metadata update with no content claim. Draft edits in `drafts/draft-lcurley-moq-lite.md`: the new message; the routing rule that a per-subscriber winner change travels as ANNOUNCE_UPDATE (it does only without a source change); the SHOULD that a @@ -121,9 +127,9 @@ Decided in planning (2026-10-07, from #4970's review): subscription between routes without an Epoch "stays on its route and ends with it" holds as written. - **Players** follow `Restart` in [Apps](/quest/m0/broadcast-epoch/apps.md), - and [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) 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. + and [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) switches on it too. On + older wires the pair 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 @@ -144,9 +150,8 @@ in both languages, including a reconnect with identical route metadata; a re-price delivers `Update`; an old subscription keeps receiving after a replacement until its route goes; a re-request after `Restart` resolves the new route, over a relay on lite-06, lite-07, and moq-transport. On lite-06 -and moq-transport, coalescing depends on read timing, so those tests accept -`Restart` or `End` then `Start`. Flip `better_route_keeps_the_incumbent` -(`rs/moq-net/tests/route_change.rs`: the better route wins new requests and +and moq-transport, those tests expect `End` then `Start`. Flip +`better_route_keeps_the_incumbent` (`rs/moq-net/tests/route_change.rs`: the better route wins new requests and announces, while the incumbent's subscriptions continue) and `identical_reannounce_is_invisible` (`origin.rs`) for routes without an epoch. `route_dies_without_an_epoch` keeps its expectation, but its @@ -162,16 +167,16 @@ downstream relay's cached groups from the old instance never reach a new subscriber mixed with the new instance's groups. With mocked time, on lite-06 and lite-07, a prefix pool of epoch-less workers announced as `pool` behind two relays, where one path's winner changes under an unchanged prefix winner: -the downstream relay gets a `Restart` of `pool`, drops its cached copies of +the downstream relay gets a `Restart` of `pool` (END then START on lite-06), drops its cached copies of the nested paths, and the next subscribes reach the right workers, the moved path on its new worker and the rest on theirs. 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`, -`doc/bin/srt.md`, `doc/bin/rtc.md`, and `doc/bin/relay/cluster.md`, which -describe the hard switch: a reconnect "replaces it at once", stale -subscriptions end with `Unroutable` (`rtmp.md`, `srt.md`), and a flapping -moq-lite 07 link "cuts the viewers" (`cluster.md`). +Docs: open PR #5033 rewrites the publisher-restart docs to match today's +hard switch; land it first, then update `doc/concept/moq-lite.md` (publisher +epochs), the `doc/lib/{rs,js}` announce sections, and the gateway and +cluster pages under `doc/bin` wherever they still describe the hard switch +(a reconnect replacing the stale viewer, stale subscriptions ending with +`Unroutable`, a flapping lite-07 link cutting viewers). Public API: breaking, a new `AnnounceEvent::Restart` variant (Rust) and `"restart"` kind (JS). Wire: a new lite-07 announce message; older versions diff --git a/quest/m0/broadcast-epoch/stats-split.md b/quest/m0/broadcast-epoch/stats-split.md index 52c4261beb0..62a16200885 100644 --- a/quest/m0/broadcast-epoch/stats-split.md +++ b/quest/m0/broadcast-epoch/stats-split.md @@ -96,7 +96,10 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): - **Sessions** (decided 2026-10-05). `sessions.json` is keyed by auth root and loses pruned roots the same way, so fold per-tier `Presence` into the totals (session counts) and serve per-root detail as a requested track, - the same model as prefix tracks. + the same model as prefix tracks. Open PR #5046 (session outcomes) adds to + `sessions.json`, which this retires; it is rewritten against these totals + and the per-root requested track, and lands after this (decided + 2026-10-08). - **Retire the map tracks** (`publisher.json`, `subscriber.json`, `sessions.json`, and their `.json.z` siblings) in the same release. Decide while implementing whether totals and prefix tracks keep `.json.z` @@ -109,6 +112,10 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): nodes when a reader requests it, so a multi-node consumer serves the same format it reads. +Decided 2026-10-08: if prefix tracks and self counters hold up the rest, +split them into a follow-up quest and land totals, sessions, and the map +retirement first. + Public API: `moq-stats` producer and consumer types. Wire: stats track names and payloads. @@ -121,4 +128,4 @@ across nodes. - [Media stats](/quest/m1/stats/README.md) - publisher and viewer media stats stay hang tracks, separate from the relay's stats -- [QoS](/quest/m1/qos/README.md) - stats-split lands first, then #4133 rebases its lag and drift histograms onto the totals and prefix tracks +- [QoS](/quest/m1/qos/README.md) - stats-split lands first; the egress lag histogram split out of #4133 requires it and rebases onto the totals and prefix tracks diff --git a/quest/m0/held-group-wakes.md b/quest/m0/held-group-wakes.md index fc76d31537a..ecd9a2c5571 100644 --- a/quest/m0/held-group-wakes.md +++ b/quest/m0/held-group-wakes.md @@ -12,14 +12,20 @@ Split from the expiry-wakes quest, which landed the deadline index (`model::expiry::Wakes`, owned by `cache::Track`) for `GroupServe` reads. `Recover::poll` in `rs/moq-net/src/model/resume.rs` gives up a held group on -an old route through `Consumer::poll_stale`, which registers only on the -track state. Register the held group in the same `Wakes` index instead. One +an old route through `track::Consumer::poll_stale`, which registers only on +the track state. Register the held group in the same `Wakes` index instead. One mechanism, not a per-reader helper beside the index. Two differences the index must carry: an entry can wait on its successor's first stamp with no deadline yet, and Recover's entry lives in the serving copy's index (a different track from the one holding the group), so it moves when the route changes. +Decided 2026-10-08: this is the one wake mechanism for held groups, and it +moves to m1 beside [One max_age meaning](/quest/m1/cache-max-age.md). That +quest's wall-clock budget (successor arrival plus budget) becomes a deadline +on the same `Wakes` entry rather than a second per-reader timer. Whichever +lands second adds its trigger to the entry. + Tests: add #4950's `a_group_no_route_continues_wakes_when_its_successor_is_stamped` to `resume.rs` (it would fail today), and extend it to the successor aborting and a newer group stamping the edge. @@ -29,3 +35,7 @@ Public API: none. Wire: none. ## Closes - [#4950](https://github.com/moq-dev/moq/issues/4950) - a group held across a route switch is not woken when its successor gets its first timestamp + +## Related + +- [One max_age meaning](/quest/m1/cache-max-age.md) - arms its wall-clock deadline on this entry diff --git a/quest/m0/idle-fronts.md b/quest/m0/idle-fronts.md index 2c6d8d96d48..4d39c8aa338 100644 --- a/quest/m0/idle-fronts.md +++ b/quest/m0/idle-fronts.md @@ -95,7 +95,7 @@ Public API: none expected. Wire: none. - [Restart](/quest/m0/broadcast-epoch/restart.md) - a request joins a front only while its route still wins, the routing half of the same report - [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - on lite-07, a worker's restarted output is a new instance and never spliced - [Upstream position regression](/quest/m0/largest-regression.md) - fails loud on the stale splice where the answer shows it -- [Prefix route fronts](/quest/m0/prefix-route-fronts.md) - bounds how many fronts a prefix route can mint at once; this reclaims idle ones - [Front parking](/quest/m1/origin-front-parks.md) - a front waiting for coverage must survive this; the filtered-front leak moved here from it - [Route wakes](/quest/m1/route-wakes.md) - indexes fronts per route, so an ended front must drop its entries +- [Front deadline index](/quest/m1/front-deadline-index.md) - indexes a front's per-track linger deadlines in the same `front.rs`; it rebases onto this - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - restarted publishers mint a fresh epoch, the documented fix for a re-served path diff --git a/quest/m0/ietf-end-of-group-status.md b/quest/m0/ietf-end-of-group-status.md index d3e79786d1a..b7abe86220a 100644 --- a/quest/m0/ietf-end-of-group-status.md +++ b/quest/m0/ietf-end-of-group-status.md @@ -13,8 +13,8 @@ Triaged from Fastly's follow-up on #5020 (#issuecomment-6046932019, runs of 2026-10-07 on `0f310a5`). d16 ยง10.4.2 says the bit only lets a subscriber infer the group's end at FIN, and nothing forbids sending the status too. -Where it lives: `IngestPhase::Status` in `rs/moq-net/src/ietf/subscriber.rs` -(around line 3992) accepts 0x3 only when `!self.has_end` and otherwise +Where it lives: the `IngestPhase::Status` arm in +`rs/moq-net/src/ietf/subscriber.rs` accepts 0x3 only when `!self.has_end` and otherwise returns `Unsupported`, which aborts the local group producer (`recv_group` then returns `Ok`, so the session is not stopped). A downstream reader only gets the rest of the group if the model's fetch path recovers it. Accept the @@ -24,3 +24,7 @@ Test: a d18 stream with the END_OF_GROUP bit, objects 0..4, then a 0x3 status at 5 delivers a finished group with five frames. Public API: none. Wire: none. + +## Related + +- [JS papercuts](/quest/m1/papercuts-js.md) - edits the same status branch in `js/net/src/ietf/object.ts`; whichever lands second rebases diff --git a/quest/m0/ietf-end-of-track-location.md b/quest/m0/ietf-end-of-track-location.md index 02ada23445a..d7517a40e59 100644 --- a/quest/m0/ietf-end-of-track-location.md +++ b/quest/m0/ietf-end-of-track-location.md @@ -1,52 +1,29 @@ -# [S] End of Track keeps its Location +# [XS] A capped IETF stream never claims END_OF_GROUP ## Goal -A relay forwards END_OF_TRACK at the Location its upstream sent, in -`rs/moq-net` and `js/net`. An upstream that ends the track at 5/5 on group -5's stream yields 5/5 on group 5's stream downstream, not 6/0 on a new -stream. A track whose last group stream has already closed still gets the -standalone marker at the next group's object 0, as today. +A subgroup stream cut short by the subscription's end Location does not set +the END_OF_GROUP bit in its header, in `rs/moq-net` and `js/net`. Today it +does, so a subscriber infers the group ended at the cap when objects past it +exist. ## Plan Triaged from Fastly's follow-up on #5020 (runs of 2026-10-07 on `0f310a5`, -d18 and d21, cells `status-end-of-track` and `publish-done`). PUBLISH_DONE -was already right; only the marker moved. A subscriber still learns that -group 5 ended after object 4 from the subgroup header's END_OF_GROUP bit, -so the reasons are conformance with the upstream's Location and one stream -fewer. - -Root cause, both sides: - -- Ingress: `rs/moq-net/src/ietf/subscriber.rs` (`Ended::Track`, around line - 2688) finishes the group producer, then calls `end_track(group + 1)`. An - egress reader that sees the group finish cannot yet know the track ends - after it. Set the end first, and abort the group producer if `end_track` - returns `ProtocolViolation`, so it is never left unfinished. -- Egress: `write_end_of_track` in `rs/moq-net/src/ietf/publisher.rs` always - opens its own stream at `end`/0. When a group stream reaches the group's - real end (the slice has no `until`, and the group finished rather than - aborted or expired) and the track's `final_sequence()` is that group + 1, - append END_OF_TRACK at (group, next object ID) before FIN, and skip the - standalone marker for that subscription. A stream capped by the - subscription's end Location (`GroupSlice::until`) keeps the standalone - marker, since appending would deny objects past the cap that do exist. - -The capped stream has a related false claim on `main`: its header still -sets the END_OF_GROUP bit (`has_end` defaults to true). Clear it when -`until` cuts the group short. - -`js/net` mirrors both: `#runEndOfTrack` in `js/net/src/ietf/publisher.ts` -runs after every group, and its ingress closes the group before -`track.finishAt`. - -Test: a d18 subscriber stream that ends 5/0..5/4 then END_OF_TRACK at 5/5, -forwarded through the ietf publisher, reaches the downstream as 5/5 on the -group 5 stream, with no extra stream and a PUBLISH_DONE count to match. -A track finished after its last group closed still gets 6/0. A -subscription whose end Location falls inside the last group gets 6/0 and a -header without END_OF_GROUP. - -Public API: none. Wire: none (the marker's Location and a capped stream's -header bit change, their formats do not). +d18 and d21, cells `status-end-of-track` and `publish-done`). + +Decided 2026-10-08: shrunk to this bug. Moving END_OF_TRACK onto the +upstream's Location (5/5 on group 5's stream rather than 6/0 on a new +stream) is conformance polish with no lost data; deferred to an m1 +follow-up. + +Rust: the subscription's group header in `rs/moq-net/src/ietf/publisher.rs` +takes `has_end` from `GroupFlags::default()`, which is true. Clear it when +`GroupSlice::until` cuts the group short. JS: the matching header in +`js/net/src/ietf/publisher.ts` hard-codes `hasEnd: true`. + +Test: a subscription whose end Location falls inside a group gets that +group's stream with a header without END_OF_GROUP, in both languages. + +Public API: none. Wire: none (a capped stream's header bit changes, not its +format). diff --git a/quest/m0/ietf-location-filter-22.md b/quest/m0/ietf-location-filter-22.md index b73345a4695..0805e768b1b 100644 --- a/quest/m0/ietf-location-filter-22.md +++ b/quest/m0/ietf-location-filter-22.md @@ -53,8 +53,16 @@ that Draft22 must leave, and `subscribe.rs`; JS `ietf.test.ts`, `filter.test.ts`). `test/interop` cannot catch this, since every client shares the codec. +Open PR #5028 ([parameters per draft](/quest/m0/ietf-params-per-draft.md)) +reworks the same 0x21 handling in `parameters.ts`, `fetch.rs`, and +`subscribe.rs`; rebase onto it once it lands. + Public API: none. Wire: moqt-22 LOCATION_FILTER changes to the draft's form. ## Closes - [#4847](https://github.com/moq-dev/moq/issues/4847) - draft-22 LOCATION_FILTER should drop the Length and carry the Location Filter Type + +## Related + +- [Parameters per draft](/quest/m0/ietf-params-per-draft.md) - #5028, the same parameter decode; this rebases onto it diff --git a/quest/m0/largest-regression.md b/quest/m0/largest-regression.md index 73aa85d5d17..ef2cfbcfdc2 100644 --- a/quest/m0/largest-regression.md +++ b/quest/m0/largest-regression.md @@ -12,7 +12,8 @@ publisher that restarted at group 0 gets the old instance's cached group and then nothing until the new sequence passes it. Covers lite-07 and moq-transport, whose answers carry the largest position. -lite-05 and 06 can't tell, and keep waiting on the floor. +lite-05 and 06 stay uncovered on purpose: their only hint is the first +group's sequence, and they keep waiting on the floor. ## Plan @@ -27,6 +28,17 @@ copy of every broadcast nested under it (maintainer, 2026-10-08, in [Restart](/quest/m0/broadcast-epoch/restart.md)). Only a restart behind an unchanged route reaches a copy unannounced. +Decided 2026-10-08: shrunk to the two answer-carrying wires and moved to m1. +The heuristic is unproven and risks a false failover, so it builds on the +front and route shapes Restart and Idle fronts leave rather than ahead of +them. + +Where it lands: since #4914, a rejoining copy goes idle (`set_idle`) and the +route's answer reaches `set_live`, which holds readers in `Feed::Answered` +until the cache shows the answered position. An answer below what the cache +already shows goes straight to `Feed::Live` and keeps the old floor; that is +the case to end instead, when it qualifies below. + A lower largest group alone doesn't prove a restart: a same-epoch resume onto a replica that has fallen behind reports one legitimately, and must keep waiting as today. The copy ends only when the answer comes from the route it @@ -41,6 +53,11 @@ keeps the copy and resumes it. Public API: none. Wire: none. +## Required + +- [Restart](/quest/m0/broadcast-epoch/restart.md) - route changes reach a copy as a `Restart`, leaving only same-route restarts for this to catch +- [Idle fronts](/quest/m0/idle-fronts.md) - reclaims the unread fronts whose lingering copies this judges + ## Related - [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - prevents the splice on lite-07 by naming the instance diff --git a/quest/m0/qmux-credit-upstream.md b/quest/m0/qmux-credit-upstream.md index 0a93b670dd9..9f1e9d43505 100644 --- a/quest/m0/qmux-credit-upstream.md +++ b/quest/m0/qmux-credit-upstream.md @@ -3,7 +3,7 @@ ## 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 +ship in a 0.6.x release after 0.6.2 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 diff --git a/quest/m0/track-stream-demand.md b/quest/m0/track-stream-demand.md index ae6f57dd9c2..dde4dd19e4b 100644 --- a/quest/m0/track-stream-demand.md +++ b/quest/m0/track-stream-demand.md @@ -12,6 +12,10 @@ encoders and waits for the next keyframe. It happens under a prefix claim and for an exact announce alike. lite-04 and moq-transport don't do this. Rust, JS, and the lite draft. +The other edge holds too: in `@moq/net`, a TRACK or FETCH requester that +resets its stream or loses its session before the answer releases its hold, +and `Broadcast.Demand` drops once no requester is left, as in Rust. + ## Plan Facts from `main`: @@ -50,6 +54,17 @@ Decisions (2026-10-07): - Not pipelining TRACK and SUBSCRIBE, which the draft already allows: it still races, and every hop would have to buffer frames until TRACK_INFO. - Consumers never debounce demand; the docs promise clean edges. +- JS query lifetime (folded in from the JS probe-lifetime quest, 2026-10-08: + the same publisher plumbing). Rust's query is a consumer of the track state + that drops with the serve (`TrackInfoServe`). In JS, `resolveTrackInfo` + (`js/net/src/broadcast.ts`) pins demand for as long as the lookup runs, + whoever still wants it. Give it a cancel signal, and have the lite + publisher (`runTrackInfo`, `runFetch`, and `#resolveTrackInfo` in + `js/net/src/lite/publisher.ts`) release its hold when the TRACK or FETCH + stream is reset; the shared per-front query ends with its last holder. + Also from #4956's review: `removeTrack` on a name cached only by a + `consume()` subscription is outside its documented contract; document or + refuse it. - Scope: Rust and JS, plus one sentence in the draft's Track Stream section. Run `just test interop --all`. @@ -60,7 +75,10 @@ fails on `main` today. The relay case controls the ordering so the downstream TRACK FIN is handled before its SUBSCRIBE. A boundary test fills the per-session subscription cap with held TRACK streams, turns each into a live SUBSCRIBE with no `unused` edge, and checks that one more TRACK closes -the session with TOO_MANY_REQUESTS. JS counterparts for the JS side. +the session with TOO_MANY_REQUESTS. JS counterparts for the JS side, plus a +JS requester (TRACK or FETCH) that disconnects before the answer and drops +broadcast demand, while a second requester keeps it pinned until it leaves +too. Public API: none. Wire: semantics only (holding the TRACK stream open), no new fields. diff --git a/quest/m1/bot-workflows-permission.md b/quest/m1/bot-workflows-permission.md index 0ac1460fb96..c06268de9a6 100644 --- a/quest/m1/bot-workflows-permission.md +++ b/quest/m1/bot-workflows-permission.md @@ -8,9 +8,15 @@ which pushes with a moq-bot app token) can push a `release` into `main` merge that carries changes under `.github/workflows/`. Without it, GitHub refuses that push and the back-merge stalls until someone merges by hand. -Check: the app's installation permissions on moq-dev/moq list Workflows as -read and write (Settings > GitHub Apps > moq-bot > permissions, or -`gh api /repos/moq-dev/moq/installation` with an app JWT). Delete this quest -once it does. +Check: `gh api orgs/moq-dev/installations --jq '.installations[] | +select(.app_slug == "moq-bot") | .permissions.workflows'` prints `write` +(it prints `null` as of 2026-10-08). Advance it by asking the maintainer to +grant it (Settings > GitHub Apps > moq-bot > permissions). + +Once it holds, the token step in `back-merge.yml` must also ask for it +(`permission-workflows: write` beside `permission-contents` and +`permission-pull-requests`), since an app token carries only the +permissions it requests. Make that one-line change in the PR that deletes +this quest. Planned as a follow-up of the 2026-10-05 audit. diff --git a/quest/m1/cache-max-age.md b/quest/m1/cache-max-age.md index 9b1fcb28fdd..aba966b8f4a 100644 --- a/quest/m1/cache-max-age.md +++ b/quest/m1/cache-max-age.md @@ -3,7 +3,7 @@ ## Goal Publisher retention (`track::Info::max_age`) and a subscriber's budget -(`Subscription::max_delay`, renamed from `max_age` in #4917) apply the same +(`Subscription::max_delay`) 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 @@ -44,12 +44,15 @@ Decided (2026-10-06, maintainer): max(wall, pts), whose worry was a congestion stall (answered by starting the clock at the successor), and the retired untimed-failover quest's no-clock rule, which this rule replaces. -- Blocked readers need a deadline wake. `TrackState::poll_stale` re-checks - only when the track state changes, and after a failover the successor may - be the last change, so a lazily checked wall term never fires for a reader - parked in `Recover::poll` or a subscriber waiting on a superseded group. - Arm a wake at successor arrival + budget on those reader paths, re-armed - when the successor changes. +- Blocked readers need a deadline wake. `track::Consumer::poll_stale` + re-checks only when the track state changes, and after a failover the + successor may be the last change, so a lazily checked wall term never fires + for a reader parked in `Recover::poll` or a subscriber waiting on a + superseded group. Arm a wake at successor arrival + budget on those reader + paths, re-armed when the successor changes. Decided 2026-10-08: one wake + mechanism. The deadline rides the held group's `expiry::Wakes` entry from + [Held group wakes](/quest/m0/held-group-wakes.md), not a wake of its own; + whichever lands second adds its trigger to that entry. - The swept benchmark measures cost and picks between evaluating the wall term on a timer and evaluating it lazily on access, for retention only. It no longer decides the semantics. @@ -119,8 +122,8 @@ encoding change; Max Age semantics in the lite draft change. ## Related -- [Subscriber max-delay](https://github.com/moq-dev/moq/pull/4917) - renames the subscriber budget to `max_delay`; the rule applies under either name +- [Held group wakes](/quest/m0/held-group-wakes.md) - the `Wakes` entry this quest's wall-clock deadline rides on +- [lite-07 Live flag](/quest/m1/lite-live.md) - its untimed `Live` start (the latest group) follows this rule instead: replay what is not stale - [JS track handover](/quest/m1/js-group-handover.md) - mirrors the failover rule in JS - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - relay memory past the expiry window, in the same cache -- [Cache shard](/quest/m2/cache-shard.md) - the pool's shared counters under many workers - [Generated @moq/net](/quest/m1/rs2ts/README.md) - retires js/net's hand-written model diff --git a/quest/m1/cluster-routing/multi-cdn.md b/quest/m1/cluster-routing/multi-cdn.md index 5149145c8c3..42bdcac71ed 100644 --- a/quest/m1/cluster-routing/multi-cdn.md +++ b/quest/m1/cluster-routing/multi-cdn.md @@ -16,8 +16,9 @@ re-requests. Decided 2026-10-01 (moq-dev/moq#4694): -- Ranking: longest prefix, then the link's preference, then the metric, then - the rendezvous hash. Preference is a per-link rank the node sets (lower +- Ranking: longest prefix, then the newest epoch, then the link's + preference, then the rest of today's order (metric, hop count, rendezvous + hash). Preference is a per-link rank the node sets (lower wins, equal by default), separate from the additive link cost, so metrics from different operators are never added together or compared; within one preference the metric decides as before. Babel permits any choice among @@ -30,23 +31,25 @@ Decided 2026-10-01 (moq-dev/moq#4694): and epoch resumes, so failover across them needs only that. The publisher side is a redundant pair under one explicit epoch, from one process. - API: the Rust client config and `js/net` accept several upstream URLs, each - with its preference (and cost), feeding one shared origin. Mirror the shape - in the bindings that expose connect config. Pick the smallest shape that - covers both publish and subscribe. + with its preference (and cost), feeding one shared origin. Pick the + smallest shape that covers both publish and subscribe. Decided + 2026-10-08: Rust and JS only; the bindings follow when a consumer asks. 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. +the secondary, the same loss delivers `Restart` and a re-request lands on +the secondary; the move back when the preferred relay returns is the same +restart and re-request, since the secondary's routes carry no epoch. 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. +Public API: per-upstream preference in client config, in Rust and JS. Wire: +none. -## Related +## Required - [Restart](/quest/m0/broadcast-epoch/restart.md) - an epochless secondary takes over as a restart, not a resume +- [One route cost](/quest/m1/route-cost.md) - reshapes the route cost this ranks beside diff --git a/quest/m1/cluster-routing/sim.md b/quest/m1/cluster-routing/sim.md index 6ebf7f85352..f25fdf02d63 100644 --- a/quest/m1/cluster-routing/sim.md +++ b/quest/m1/cluster-routing/sim.md @@ -14,8 +14,24 @@ messages and bytes by kind, convergence time, stale-path seconds, transient subscribe loops, and whether a two-uplink mesh ever carries CDN traffic. moq-dev/moq.pro#2136 rewrote that quest for the split (merged 2026-10-02), -and moq-dev/moq.pro#2152 (open) measures the tiered route and mesh failures. -To check: the report merges via moq.pro#2152. To advance: ask the maintainer -to review and land #2152. Delete this quest once the report is -in and [Routes and announces](/quest/m1/cluster-routing/routes.md) is -confirmed or revised by it. +and moq-dev/moq.pro#2152 (draft) measures the tiered route and mesh failures. +Its report says the split needs a design revision before its wire ships, so +the condition is now the maintainer's decision on that revision, not only a +merge. To check: #2152 merges, or the maintainer decides the revision. To +advance: ask the maintainer to review #2152's findings. Delete this quest +once [Routes and announces](/quest/m1/cluster-routing/routes.md) is +confirmed or revised by them. + +## Plan + +Findings from #2152 (as of 2026-10-03) for +[Routes and announces](/quest/m1/cluster-routing/routes.md), which should +carry them now rather than wait for the merge: + +- A five-node ring keeps a working longer backup yet stays starved for good + until the origin advances its sequence. The report recommends Babel + sequence-number requests. +- On origin-end over the live tiers, the split sends far fewer bytes than + path vector but still about 2150 client updates against an 840 minimum + (up to 9 per relay and path) and 655 re-announces, against that quest's + goal that ending a broadcast reaches each node about once. diff --git a/quest/m1/cmaf-frame-timestamp.md b/quest/m1/cmaf-frame-timestamp.md index 0a54e733cb5..fffb71245de 100644 --- a/quest/m1/cmaf-frame-timestamp.md +++ b/quest/m1/cmaf-frame-timestamp.md @@ -18,33 +18,40 @@ on the publisher was rejected: it can force a v0 to v1 box upgrade, which shifts `trun` data offsets. - A sample's time is the frame timestamp plus its PTS offset from the - fragment's first sample. The encoder already stamps the frame with that - first sample's PTS (`fmp4::encode`), so today's output decodes unchanged. + fragment's earliest sample, not its first: the passthrough importer already + stamps the earliest PTS, and the two differ on open-GOP leading pictures or + a fragment cut mid-GOP. `fmp4::encode` stamps the first sample today, so it + moves to the earliest too. - Rust's decode gets the frame timestamp from the caller. The fMP4 exporter and moq-hls re-fragment decoded frames, so they follow without changes; confirm with a test. -- Check the TS exporter's verbatim carriage, which keeps PES PTS inside the - payload. Rewrite those from the frame timestamp, or refuse a mismatch. +- The TS exporter needs no change: verbatim PES tracks carry only the PES + payload, and export writes a fresh PES header from the frame timestamp. - An untimed CMAF frame decodes at its `tfdt` (decided 2026-10-05, replacing the 2026-10-02 decision to refuse it). Rejected: refusing it, and parking the quest. -- `main`: a behavior fix with no API change. - -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. +- JS `Format.decode` takes the frame timestamp, a breaking `@moq/hang` + change; moq-mux's decode is crate-private. + +Open PR [#4826](https://github.com/moq-dev/moq/pull/4826) implements this +(held since 2026-10-06, branch still under `m2`). 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. Decided 2026-10-08: no forced order among the CMAF +decode changes. This, #5015 (catalog init), and +[CMAF sample defaults](/quest/m1/cmaf-sample-defaults.md) touch the same +module; whichever lands second rebases. 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 an untimed fragment decodes at its `tfdt`. -Public API: none. Wire: none; this states what the frame timestamp already -means. +Public API: breaking in `@moq/hang` (`Format.decode` and +`decodeDataSegment` take the frame timestamp). Wire: none; this states what +the frame timestamp already 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 +- [CMAF sample defaults](/quest/m1/cmaf-sample-defaults.md) - the same `decode` functions; whichever lands second rebases +- [fMP4 init from the catalog](/quest/m1/fmp4-catalog-init.md) - #5015, the same fMP4 module diff --git a/quest/m1/cmaf-sample-defaults.md b/quest/m1/cmaf-sample-defaults.md index c3af16c7dc3..140ee03c8bd 100644 --- a/quest/m1/cmaf-sample-defaults.md +++ b/quest/m1/cmaf-sample-defaults.md @@ -37,5 +37,6 @@ Public API: none. Wire: none. ## Related -- [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - touches the same `decode` functions; #4826, #5037, and #5015 land first and this rebases +- [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - #4826, the same `decode` functions; no forced order (decided 2026-10-08), whichever lands second rebases +- [fMP4 init from the catalog](/quest/m1/fmp4-catalog-init.md) - #5015, the same fMP4 module; whichever lands second rebases - [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md) - the export side of the same flags diff --git a/quest/m1/cross-relay-bursts.md b/quest/m1/cross-relay-bursts.md index 693da237efc..11bd4d75317 100644 --- a/quest/m1/cross-relay-bursts.md +++ b/quest/m1/cross-relay-bursts.md @@ -36,8 +36,10 @@ used and against `main`: (seed 11025055814286623932). Several 30 s timers of that era have since been removed or shortened (#4606, #4741). That drill uses a lite peer link; over a `moq-transport-19` peer link, a - related refusal does reproduce: FETCHes answered `old` for groups the origin - still holds ([IETF peer FETCH refused old](/quest/m1/ietf-peer-fetch-old.md)). + related refusal reproduces every run: FETCHes answered `old` for groups the + origin still holds. Both, the lite seed included, belong to + [Cross-relay FETCH serves held groups](/quest/m1/ietf-peer-fetch-old.md), + widened to any peer link (decided 2026-10-08). - **Queueing.** FETCHes beyond a session's stream credit wait for it, one cross-relay round trip per slot, so with tight credit a gap's FETCH can outlast a 2 s deadline without being lost. @@ -51,3 +53,4 @@ used and against `main`: ## Related - [Routes and announces](/quest/m1/cluster-routing/routes.md) - owns the stale and flapping announcements from the same report +- [Cross-relay FETCH serves held groups](/quest/m1/ietf-peer-fetch-old.md) - owns the FETCH refused `old` over either peer link, with this quest's lite seed diff --git a/quest/m1/ffi-shape/codec.md b/quest/m1/ffi-shape/codec.md index f097a6d9abc..b55db2b1b1e 100644 --- a/quest/m1/ffi-shape/codec.md +++ b/quest/m1/ffi-shape/codec.md @@ -2,13 +2,29 @@ ## Goal -`audio` and `video` each own an encoder and a decoder constructed from the -handles moq-audio and moq-video take (the broadcast and its catalog), with one shape between them. `BroadcastProducer` loses +`audio` and `video` each own a broadcast-bound producer, a codec-only +encoder, and a decoder, mirroring moq-audio's and moq-video's types, with one +shape between them. `video.Producer` and `audio.Producer` mirror Rust's +`encode::Producer` and are constructed from the handles it takes (the +broadcast and its catalog). `video.Encoder` and `audio.Encoder` mirror +`encode::Encoder` and take only a codec config. `BroadcastProducer` loses `encode_audio`/`encode_video` and `BroadcastConsumer` loses -`decode_audio`/`decode_video`. +`decode_audio`/`decode_video`. The audio encoder's frame duration defaults +to the codec's own frame in every binding. ## Plan +Decided by the maintainer in the 2026-10-06 audit: the binding names mirror +Rust, so every moq-ffi type maps to the Rust type of the same name. The +broadcast-bound types are `video.Producer`/`audio.Producer` +(`rs/moq-video/src/encode/producer.rs`, `rs/moq-audio/src/encode/producer.rs`), +and this quest also owns the codec-only `video.Encoder`/`audio.Encoder` +(`encode::Encoder` in `encoder.rs`). The OBS adapters +([video](/quest/m1/obs-moq-video/adapter.md), +[audio](/quest/m1/obs-moq-video/audio-publish.md)) consume these rather than +adding their own. Rejected: shipping only the Producers here and leaving the +codec-only Encoder to the OBS audio quest. + Mirror moq-audio's and moq-video's `encode`/`decode` modules. Today the two disagree on where the track name goes (`encode_audio` takes it as an argument, `encode_video` reads `output.track`), and decode passes the catalog @@ -29,4 +45,16 @@ The audio and video frame and decoder-output records carry microsecond fields (`timestamp_us`, `max_delay_us`, `frame_duration_us`); in Python and Go they should become owned `timedelta` / `time.Duration` records like net's. +Frame duration default (folded in from its own quest, 2026-10-08, so callers +take one break on the reshaped type): the audio encoder output's +`frame_duration_us` defaults to 0, the codec's own frame, instead of 20000, +so an AAC encoder works without an explicit 0 in every binding; Opus still +encodes 20 ms frames by default. Decided in +[#4183](https://github.com/moq-dev/moq/pull/4183). `rs/moq-ffi/src/audio.rs` +already treats 0 as the codec's frame; the +`default_frame_duration_matches_moq_audio` test that pins 20000 goes with the +literal. Update the wrappers and docs that restate 20000 (the Python test +asserting the default, `doc/lib/{py,swift,kt,go,dart}`). libmoq already +reads 0 as the default. + Public API: breaking in every binding. Wire: none. diff --git a/quest/m1/iroh-capsule-bump.md b/quest/m1/iroh-capsule-bump.md index 944dc405d6a..31961c5cd6d 100644 --- a/quest/m1/iroh-capsule-bump.md +++ b/quest/m1/iroh-capsule-bump.md @@ -13,4 +13,6 @@ reason instead of `(0, "stream closed")`. 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. +floors 0.8.1. The release PR, +[moq-dev/web-transport#418](https://github.com/moq-dev/web-transport/pull/418), +cuts 0.8.3 with the fix. Advance it by merging #418, then floor 0.8.3. diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index 6a1e206dc92..a066045a3c2 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -12,15 +12,22 @@ payload published without a timestamp goes out untimed. 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. +`writeBool` (on the group and track producers) stamp now, as does `zod.write` +through `writeJson`. + +Decided 2026-10-08: delete `writeString`, `writeJson`, and `writeBool` +rather than re-typing them to take a timestamp; `writeFrame` already takes +one. `zod.write` takes the timestamp or goes with them. Their callers +(`js/clock`, `js/net/examples/publish.ts`) write frames with their clock's +now explicitly. Decided (2026-10-01): `@moq/net` exports `Timed` (`{ value: T; at?: Time.Timestamp }`), the Rust name and shape. Each producer takes a `Timed`; an absent `at` is untimed, never now. The consumers return the same type in [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md). -Callers in the repository (js/hang catalog, js/publish, js/room) pass their -clock's now explicitly. Update `doc/lib/js/{json,flate,net}.md`. +Callers in the repository (js/hang catalog, js/publish, js/room, js/clock) +pass their clock's now explicitly. Update `doc/lib/js/{json,flate,net}.md`. Decided (2026-10-05, types settled 2026-10-06): timedness is per track, as the untimed model ([#4822](https://github.com/moq-dev/moq/pull/4822)) decided and `@moq/net` @@ -32,6 +39,8 @@ timed track today. Decided (2026-10-07): `@moq/net` has no default timescale. Omitting `Track.Info.timescale` declares an untimed track, so every timed publisher -names its units, unlike Rust's millisecond default. +names its units, as Rust will once +[An undeclared Rust timescale means untimed](/quest/m1/rust-untimed-default.md) +lands. Public API: breaking. Wire: none. diff --git a/quest/m1/merge-queue-settings.md b/quest/m1/merge-queue-settings.md index 6416b954419..b80f2452adf 100644 --- a/quest/m1/merge-queue-settings.md +++ b/quest/m1/merge-queue-settings.md @@ -24,12 +24,21 @@ merge method `SQUASH` and a moq-bot bypass actor with `bypass_mode` `pull_request`. Delete this quest once both hold and the Dependabot check below is done. +Advance it by backporting #4619's `sh/gh/back-merge.sh` to `release` (a +backport PR, per `CONTRIBUTING.md`); as of 2026-10-08 `release` still runs +`gh pr merge --auto`, and the ruleset has no `merge_queue` rule. Then ask the +maintainer to flip the ruleset. + ## Plan Decided in #4619 (2026-10-05): a squash queue with a pull_request-only bot bypass for the back-merge, landed by the `land` job; the back-merge may land against a `main` that moved during its CI run, accepted. +`CONTRIBUTING.md`'s Merge queue section and the `land` job's comment in +`check.yml` already describe the queue as live. They become true when this +clears; if the plan changes instead, fix them in the same PR. + Check once both settings are on: `.github/workflows/dependabot.yml` merges with the same moq-bot app token through `gh pr merge --auto --squash`, without `--admin`, so its merges may still enqueue rather than bypass. On the next diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md index 2584cfe7571..637ce841a59 100644 --- a/quest/m1/publish-timestamp.md +++ b/quest/m1/publish-timestamp.md @@ -22,7 +22,9 @@ removes every place that fills one in. Today `Timed.at: None` means "stamp when written": moq-json and moq-flate fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and moq-mux's data producers fill the broadcast clock's `now()`. The FFI raw -`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0. +`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` are optional, but a +raw track published through moq-ffi is always timed, and the Python and +Swift wrappers default them to 0. - `moq_net::Timed` drops its unused clock parameter `T` (decided 2026-10-06: here rather than in #4822, which is already large). That's a breaking @@ -41,13 +43,13 @@ data producers fill the broadcast clock's `now()`. The FFI raw chat, examples) pass their clock's now explicitly. - moq-ffi: data producers take an optional timestamp in microseconds on the broadcast clock, unchecked, as Rust does. moq-ffi exposes the broadcast - clock's `now()` so callers have a value to stamp with. The raw frame and - datagram records' `timestamp_us` is optional since [#4822](https://github.com/moq-dev/moq/pull/4822), but only - on the receive side (decided 2026-10-07 by OneTooMany): a raw track - published through moq-ffi is always timed, and a write without a timestamp - is refused. Add a way to publish an untimed raw track. `MoqTrackInfo`'s - null `timescale` means microseconds when publishing and an untimed track on - a received one, so a received info doesn't round-trip yet. The wrappers' + clock's `now()` so callers have a value to stamp with. + Decided 2026-10-08, replacing the 2026-10-07 rule that a raw track + published through moq-ffi is always timed: `MoqTrackInfo`'s null + `timescale` means untimed when publishing, as it already does on a + received track. A received info then round-trips, and an untimed raw track + needs no API of its own. A timed raw track names its timescale, and a + write that doesn't match the track's timedness is refused. The wrappers' `= 0` defaults go with it. - Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added @@ -61,6 +63,10 @@ data producers fill the broadcast clock's `now()`. The FFI raw Public API: breaking. Wire: none here; absence on the wire lands with the untimed implementation quests. +## Required + +- [An undeclared Rust timescale means untimed](/quest/m1/rust-untimed-default.md) - each track declares its timescale first, so a publisher that stops stamping writes onto a track that already says whether it is timed + ## Related - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same change in the JS packages diff --git a/quest/m1/quest-flat-lines.md b/quest/m1/quest-flat-lines.md index e6387c96505..8953badbc79 100644 --- a/quest/m1/quest-flat-lines.md +++ b/quest/m1/quest-flat-lines.md @@ -59,18 +59,22 @@ Remaining: Landed so far: #4403 wildcard, #4034 archive (with #4255 folded in), #4080 obs-moq-video, #4162 audio-jitter-target, #4180 transport-upgrade, #4437 rs2ts (with #4438 folded in), #4640 tstd, and #4653 test-flakes-2. As of - 2026-10-06 four lines remain, each waiting before it lands: - - #4039 auth waits on its `wip-version.md` child: AUTH still turns on for - lite-06, but wire work belongs on the wip version. - - #4079 cpp waits on its `cpp-generated-newline.md` child: `OBS (macOS)` - fails until the generated-newline fork tag is cut. + 2026-10-08 four lines remain, and all four conflict with `main` and need + it merged in again. + - #4039 auth: its `wip-version.md` child landed on the line (#5004). The + line's UNAUTHORIZED stream code collides with `main`'s NOT_FETCHABLE + (0x3A) and moves to 0x3B before it lands. + - #4079 cpp: the generated-newline fork tags exist + (`v0.11.0-kixelated.3` and `.4`); bump the line's `uniffi-bindgen-cpp` + pin from `.2`, then check `OBS (macOS)`. - #4519 ffi-shape waits on [Bindings](/quest/m0/broadcast-epoch/bindings.md). - - #4133 qos waits on [Lag across a splice](/quest/m1/qos/lag-splice.md). + - #4133 qos: lag-splice landed on the line (#5009). Its egress `lag` + histogram splits into its own quest requiring stats-split (decided + 2026-10-08); follow the qos README for what the line lands without it. - Child PRs still based on a line merge into it first, or GitHub closes them with the branch: #4675 (auth/request-token) needs the updated auth line - merged in. #4645 (tstd/delay) now targets `main`; #4732 and #4863 - landed. + merged in. Done when `flake.nix` pins the new quest, no `quest/*README` branch remains, and `quest check` passes. diff --git a/quest/m1/rust-untimed-default.md b/quest/m1/rust-untimed-default.md index e530220439d..26b7bf9d312 100644 --- a/quest/m1/rust-untimed-default.md +++ b/quest/m1/rust-untimed-default.md @@ -16,18 +16,25 @@ timescale as untimed and `@moq/publish` declares milliseconds): - Remove the implicit millisecond default: `impl Default for Timescale` (`rs/moq-net/src/model/time.rs`) and its use in `track::Info::default()` and `accept(None)` (`rs/moq-net/src/model/track.rs`). -- Declare milliseconds, stamped from the shared broadcast clock, in every - Rust data track that relies on the default today: `hang` catalog - (`default_track_info`), moq-mux MSF and timeline tracks, moq-boy status, - moq-c `data_track`, and moq-ffi json and flate tracks. moq-ffi and moq-c - media tracks already pin microseconds. The shared timeline itself is - [Shared import clock](/quest/m1/shared-clock.md)'s; this quest only makes - each data track declare and use it. +- Declare milliseconds in every Rust track that relies on the default today, + in the same PR, or its writers' stamped frames are refused on a track that + turned untimed. Known: `hang` catalog (`default_track_info`), moq-mux MSF + and timeline tracks, moq-boy status, moq-c `data_track`, moq-ffi json and + flate tracks, moq-room chat (`chat::info`), and moq-stats' JSON tracks + (`create_track(name, None)`). Find the rest by `Info::default()`, + `create_track(_, None)`, and `accept(None)`. moq-ffi and moq-c media tracks + already pin microseconds. The shared timeline itself is + [Shared import clock](/quest/m1/shared-clock.md)'s. +- This quest only declares the timescale. Who stamps a frame, and with which + clock, is [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md)'s + (decided 2026-10-08); writers keep stamping as they do today until it + lands. - The untimed model (#4822) keeps `Default` as the timescale a lite encoder declares for an untimed track's send times, and the lite datagram decoder falls back with `entry.timescale.unwrap_or_default()` (`rs/moq-net/src/lite/subscriber.rs`); both name `Timescale::MILLI` - explicitly instead. + explicitly instead, as does moq-audio's decode quantum floor + (`rs/moq-audio/src/decode/consumer.rs`). - Update the bindings and `doc/lib` pages that describe the default. Public API: breaking (`Timescale` loses `Default`; an undeclared track is @@ -35,6 +42,6 @@ untimed). Wire: none. ## Related -- [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 +- [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - requires this: the same publishers stop filling in a timestamp once each track declares its timescale - [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 +- [lite-07 untimed](/quest/m1/lite-untimed.md) - requires this: the same `rs/moq-net` lines From 7616102c185f3d06502a266bf86605fa481fc968 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:10:57 -0700 Subject: [PATCH 02/10] quest: apply audit fixes (group 2) Co-Authored-By: Claude Opus 5.5 --- quest/m0/audio-jitter-target/README.md | 4 +- quest/m0/broadcast-epoch/README.md | 14 +-- quest/m0/broadcast-epoch/apps.md | 8 +- quest/m0/broadcast-epoch/bindings.md | 7 +- quest/m0/broadcast-epoch/dynamic-epoch.md | 2 +- quest/m0/broadcast-epoch/moqsrc.md | 48 ++++------ quest/m0/broadcast-epoch/ts-restart.md | 6 ++ quest/m0/ietf-d14-root-prefix.md | 10 +- quest/m0/ietf-params-per-draft.md | 9 +- quest/m0/qmux-credit.md | 9 +- ...bandwidth-grant-in-moq-audio-instead-of.md | 2 + quest/m1/archive/README.md | 18 ++-- quest/m1/archive/replay-catalog.md | 6 +- quest/m1/archive/replay-history.md | 3 +- quest/m1/audio-encode-audiotoolbox.md | 10 +- quest/m1/auth/README.md | 4 +- quest/m1/auth/request-token.md | 94 ++++++------------- quest/m1/auth/wip-version.md | 4 +- 18 files changed, 118 insertions(+), 140 deletions(-) diff --git a/quest/m0/audio-jitter-target/README.md b/quest/m0/audio-jitter-target/README.md index ee6bb64f904..b66b61753d6 100644 --- a/quest/m0/audio-jitter-target/README.md +++ b/quest/m0/audio-jitter-target/README.md @@ -25,7 +25,9 @@ its conformance corpus, `js/watch` `Sync` holds the deepest track's target in `"auto"`, and `moq play --delay` defaults to `auto`. Both are the default for every viewer, so `"auto"` shipped ahead of the Chrome and Safari proof the Watch quest still owes; the maintainer accepted that, and the re-measured -replay budgets, on 2026-10-04. +replay budgets, on 2026-10-04. Decided 2026-10-08: the line no longer gates +the release and moves to m1, since the defaults are on and only the manual +browser proof is left. What the line still owes once Watch lands: its recorded trace replayed through the native decode path too, asserting the same target series the browser's diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 3f129a354d2..404ca5a451a 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -54,13 +54,14 @@ Decided: explicit `Restart` announce event tells players to follow, through [Restart](/quest/m0/broadcast-epoch/restart.md). When the newest goes and an older one is still live, the older one wins again as a new broadcast. -- On lite-07 a claim's answer will carry the served broadcast's own epoch - ([Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md), planned - 2026-10-07), which adds it to TRACK_INFO. +- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md), where a + lite-07 claim's answer carries the served broadcast's own epoch, no longer + gates this line (decided 2026-10-08): it is a lite-07 opt-in, so it moved + to m1. - A catalog `broadcast` reference by name follows the newest epoch, since a path cannot name one. -- Every first-party publisher that can restart mints its own: the apps, - moq-boy, and moq-room through [Apps](/quest/m0/broadcast-epoch/apps.md), the +- Every first-party publisher that can restart mints its own: the apps and + moq-boy through [Apps](/quest/m0/broadcast-epoch/apps.md), the ingest gateways, moqsink, and the bindings below. moq-stats mints one per [group announcement](/doc/concept/stats.md#broadcasts), which also gated the release (decided 2026-10-04). @@ -93,12 +94,11 @@ then. MoQ Pro's VOD `storage.json` moves from the same seed to its own epoch. ## Required -- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch - [Restart](/quest/m0/broadcast-epoch/restart.md) - a replaced broadcast reaches announce consumers as an explicit Restart, subscriptions stay sticky, and new requests never join a replaced route's front +- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch - [Publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) - `@moq/publish` never reuses catalog group numbers under one name and epoch after a re-announce - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch - [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and let a publisher announce one - [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) - moqsrc switches to the new broadcast on a `Restart`, keeping its pads by rendition name -- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - a claim's answer names the instance that served it, so a restarted output is never spliced and a per-output epoch costs no restart - [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the same release retires the per-path stats maps for totals and on-demand prefix tracks (decided 2026-10-05) - [Dynamic epoch update](/quest/m0/broadcast-epoch/dynamic-epoch.md) - an epoch change through `Dynamic::update` announces a `Restart` downstream, so subscribers drop the old copy and resubscribe, while the origin keeps serving diff --git a/quest/m0/broadcast-epoch/apps.md b/quest/m0/broadcast-epoch/apps.md index 13e27991125..fff3c3e78c9 100644 --- a/quest/m0/broadcast-epoch/apps.md +++ b/quest/m0/broadcast-epoch/apps.md @@ -2,8 +2,8 @@ ## Goal -`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, `demo/web`, -moq-boy, and moq-room announce a freshly minted epoch per run. Each publish +`moq-cli` publish and play, `@moq/publish`, `@moq/watch`, `demo/web`, and +moq-boy announce a freshly minted epoch per run. Each publish run is a new epoch, so a restart while the old route lingers is a new broadcast rather than a resume into the old one, which stalls viewers until the new run's group sequence catches up. A viewer @@ -20,8 +20,8 @@ switches to a republish within an RTT. Logs show the 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. +- moq-room is out (decided 2026-10-08): it only discovers participants, and + the caller that publishes into a room mints the epoch. ## Required diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index dddf0d1a1f7..9dde2edea77 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -5,8 +5,8 @@ `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. Every wrapper surfaces -the `Restart` announce event. The reconnect counter `session.epoch()` is -renamed so "epoch" has one meaning. +the `Restart` announce event. The reconnect counter `session.epoch()` and the +audio timeline re-anchor `reset_epoch` are renamed so "epoch" has one meaning. ## Plan @@ -15,6 +15,9 @@ renamed so "epoch" has one meaning. - Rename the reconnect counter, `moq_tokio::Connection::epoch()` and `session.epoch()` in every binding (for example to `connects()`). That is a break. +- Rename the audio re-anchor the same way (decided 2026-10-08, since it also + says "epoch"): `moq_audio::encode::Producer::reset_epoch`, its moq-ffi + method, the wrappers that expose it, and moq-boy's copy. - `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, diff --git a/quest/m0/broadcast-epoch/dynamic-epoch.md b/quest/m0/broadcast-epoch/dynamic-epoch.md index f8c79c6372f..be5ef04730f 100644 --- a/quest/m0/broadcast-epoch/dynamic-epoch.md +++ b/quest/m0/broadcast-epoch/dynamic-epoch.md @@ -16,7 +16,7 @@ since two epochs may carry the same content; a handler that wants fresh content under the new epoch closes its old broadcast itself. Non-goals: the epoch a claim-served answer carries -([#5010](https://github.com/moq-dev/moq/pull/5010)'s claim-epochs plan), and +([Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md)), and same-epoch repricing, which keeps every handle and stays an `Update`. ## Plan diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md index 93202f3e8ed..0d2c9be381d 100644 --- a/quest/m0/broadcast-epoch/moqsrc.md +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -6,8 +6,8 @@ When the source behind `moqsrc`'s path restarts (an announce `Restart`), the pipeline keeps running and switches to the new broadcast: a fresh catalog on the same pads, with no error on the bus. Once subscriptions are sticky, `moqsrc` would otherwise keep playing the replaced broadcast until its route -goes, then end or error. A broadcast that ends with no successor still ends as -it does today, unless the opt-in `linger` holds it. +goes, then end or error. A broadcast that ends holds its pads until the path +is announced again, like a player going offline and back online. ## Plan @@ -31,8 +31,7 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered subscriptions, so a catalog error posts the session error and a track error logs and ends that pad, as today. The earlier rule treating `Unroutable` as a switch in flight is dropped: it could not tell a switch from a dead route - and could hang. Only `linger` below defers an error, and only for its - window. + and could hang. - **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without waiting for their subscriptions to end. - **Pads (decided 2026-10-07, reconfirmed after the Restart re-scope).** @@ -48,22 +47,15 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered restarts at 0) as late. An in-run caps or container change keeps its pad the same way. A rendition the new catalog drops ends with EOS; a new or renamed one gets a new pad. -- **Linger (decided 2026-10-07).** A `linger` property, default 0, that - covers a lite-06 or moq-transport restart whose END and START are not - coalesced into a `Restart`, and a crashed or withdrawn source. While - `linger` > 0, a track that ends or loses its source (the route went, - `Dropped`, or the upstream session closed) hands its pad back without EOS, - since tracks, the catalog, and `End` arrive on different streams in either - order. A rendition the catalog already retired still drains to EOS as today. - The window starts on the first of `End`, the catalog finishing (a prefix - can stay announced after its output finishes), or the catalog losing its - source. A `Start` or `Restart` in it resumes on the same pads. At expiry - every held pad gets EOS, and the session error posts only if the catalog - lost its source; a pump still streaming ends as it would without linger. A - held track whose catalog and path stay live waits the same bound from its - own end, then ends its pad as it would at 0; opening the window cancels - those per-track timers, so held pads follow the window's expiry. The bound - keeps this from becoming a silent hang. At 0 nothing changes from today. +- **Hold pads from `End` to `Start` (decided 2026-10-08, replacing the + `linger` timer).** This covers a lite-06 or moq-transport restart whose END + and START are not coalesced into a `Restart`, and a withdrawn source. A + track that ends or loses its source hands its pad back without EOS, since + tracks, the catalog, and `End` arrive on different streams in either order; + the next `Start` resumes on the same pads. A rendition the catalog retired + still drains to EOS. No timer and no property: announcements already say + when the source is back, and a timer cannot tell a slow restart from a + dead source. - **Where.** The logic stays in `rs/moq-gst/src/source`. If [Apps](/quest/m0/broadcast-epoch/apps.md) lands a shared helper for following announcements first, use it instead. @@ -73,20 +65,16 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered Cover an epochless source change that also switches, a `Restart` of a prefix route covering the path that switches too, a same-epoch re-announce (`Update`) that does not, a switch with new caps that keeps the - pad, and with `linger` set: an `End` then `Start` that resumes on the same - pads (media FIN, a delay, catalog FIN, `End`, then `Start`), an old - publisher's session closed (not finished) over a relay that resumes on the - next `Start`, and a finished output under a still-announced prefix that - gets EOS by the deadline, and a lone track losing its source while its - siblings and the catalog stay live, which ends only that pad. With - `linger` at 0, each of these ends or errors as today. Drive the linger - window with mocked time. + pad, an `End` then `Start` that resumes on the same pads (media FIN, a + delay, catalog FIN, `End`, then `Start`), and an old publisher's session + closed (not finished) over a relay that resumes on the next `Start`. Update the `moqsrc` section of `doc/bin/gstreamer.md`: a restart keeps each pad by rendition name, a format change keeps its pad, a dropped rendition gets -EOS, and `linger`. +EOS, and an ended broadcast holds its pads until the next `Start`. -Public API: a new `linger` property on `moqsrc`. Wire: none. +Public API: no new property, but an ended broadcast no longer sends EOS on +its pads. Wire: none. ## Required diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index 048fa0dcb49..f809dd58bab 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -37,6 +37,11 @@ Decided (maintainer, 2026-09-30): - Callers: `moq import ts` (`rs/moq-cli`) and `moq-srt`'s `Publisher`, single program and `Program::All`. +Decided 2026-10-08: when the operator gave `--epoch`, a flagged rewind is +fatal like an unsignalled one, so the supervisor restarts the process and +both hosts of a redundant pair keep the operator's epoch. A fresh epoch per +rewind would split the pair. + Tests: a fixture with a flagged rewind publishes two broadcasts, the second starting at the rewound PTS; the same rewind unflagged still errors; one SRT connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. @@ -51,3 +56,4 @@ and `restart` is new. Wire: none. ## Related - [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event viewers follow onto the new epoch +- [#5003](https://github.com/moq-dev/moq/pull/5003) - `import ts --passthrough`, which waits on this quest's `decode` change diff --git a/quest/m0/ietf-d14-root-prefix.md b/quest/m0/ietf-d14-root-prefix.md index 3c3fc0866d2..61e39cb1618 100644 --- a/quest/m0/ietf-d14-root-prefix.md +++ b/quest/m0/ietf-d14-root-prefix.md @@ -27,10 +27,12 @@ affected pair and scoped links already work. Rejected: subscribing per prefix on demand when a local subscriber misses, and routing unknown SUBSCRIBEs upstream; both need a hook on origin misses. -Where it lives: `subscribe_prefixes` (`rs/moq-net/src/ietf/subscriber.rs`, -around line 600) returns `interest_prefixes(origin.allowed())`, which is -`[""]` for an unscoped origin. `run_subscribe_namespace` (around line 861) -sends it. Log at debug when the root is skipped. The note belongs in +In flight as [#5018](https://github.com/moq-dev/moq/pull/5018), which also +covers draft-15 peers. + +Where it lives: `subscribe_prefixes` (`rs/moq-net/src/ietf/subscriber.rs`) +returns `interest_prefixes(origin.allowed())`, which is `[""]` for an +unscoped origin. `run_subscribe_namespace` sends it. Log at debug when the root is skipped. The note belongs in `doc/bin/relay/cluster.md`. Test: a d14 session with an unscoped origin sends no SUBSCRIBE_NAMESPACE, diff --git a/quest/m0/ietf-params-per-draft.md b/quest/m0/ietf-params-per-draft.md index fd81987dca6..f1f1a2f33a6 100644 --- a/quest/m0/ietf-params-per-draft.md +++ b/quest/m0/ietf-params-per-draft.md @@ -30,8 +30,8 @@ Decided 2026-10-07: audit every message against every draft rather than patch FORWARD alone, since the report's EXPIRES case (fixed in #4195) and this one are the same class. -Where it lives: the `decode_params!` macro (`rs/moq-net/src/ietf/parameters.rs`, -around line 473) returns `InvalidValue` for any key outside a message's list. +Where it lives: the `decode_params!` macro (`rs/moq-net/src/ietf/parameters.rs`) +returns `InvalidValue` for any key outside a message's list. Its call sites are in `fetch.rs`, `publish_namespace.rs`, `publish.rs`, `subscribe_namespace.rs`, `request_stream.rs`, `request.rs` and `subscribe.rs`. `Parameters::skip` ignores unknown keys, but only d14 @@ -45,8 +45,8 @@ it only sets FORWARD on the PUBLISH messages it triggers, and we send none for that subscription (Subscribe Options 0x01). Coordinate with [moq-transport request codes](/quest/m2/ietf-request-codes.md), -which accepts the delivery-timeout parameters on REQUEST_UPDATE; whichever -lands second drops the overlap. +which accepts the delivery-timeout parameters on REQUEST_UPDATE; it lands +after this and drops the overlap. Tests: one codec test per gap the audit finds, plus one per rule above (unknown and misplaced, on each side of the d16 and d17 boundaries). Mirror @@ -58,3 +58,4 @@ Public API: none. Wire: none new; decoding moves closer to the drafts. ## Related - [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) - owns the other session-closing cases +- [Draft-22 LOCATION_FILTER](/quest/m0/ietf-location-filter-22.md) - touches the same 0x21 parameter and `fetch.rs`/`subscribe.rs` decodes; it rebases onto this diff --git a/quest/m0/qmux-credit.md b/quest/m0/qmux-credit.md index a4329d5996c..38b04a5a72e 100644 --- a/quest/m0/qmux-credit.md +++ b/quest/m0/qmux-credit.md @@ -1,4 +1,4 @@ -# [M] qmux returns every byte's credit and sends its close frame +# [XS] qmux returns every byte's credit and sends its close frame ## Goal @@ -45,9 +45,10 @@ targets `qmux-v0.5.x`): 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. +breaking change. Sized XS (2026-10-08), since the fixes live upstream and only +the pin bumps remain here. -Why m0: the WebSocket fallback and the planned edge-to-core `tls://` links +Why m0: the WebSocket fallback and the edge-to-core `tls://` links (#4816) both run on qmux, and MoQ drops streams constantly. Public API: none. Wire: none. @@ -58,4 +59,4 @@ Public API: none. Wire: none. ## Related -- [qmux on noq-proto](/quest/m2/quic-qmux.md) - replaces these stream maps later +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - replaces these stream maps later diff --git a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md index d49a72fb2c4..0d9a6ac4fc7 100644 --- a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md +++ b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md @@ -57,6 +57,8 @@ grant; `Options::bandwidth` documents that reservation before video sees a bit and audio is squeezed only once the link cannot carry audio alone. Worth doing for that tail, not worth blocking on. +Decided 2026-10-08: moved to m2, since that tail is the only gain. + Tests: retain the shared `Control` tests; an Opus Producer whose grant drops below its configured bitrate reports the lower `bitrate()` after one policy step, holds it on a `None` grant, and ramps back when the grant diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index df457f644b1..1b7d0286050 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -71,7 +71,7 @@ prefix. A new group whose first timestamp precedes the recorded end fails the recording instead of overlapping media time. A DVR deletes unreferenced objects and unneeded timeline objects one grace period after recovery. `moq_archive::Reader` (`rs/moq-archive/src/reader/mod.rs`) replays every timeline -onto a supplied `broadcast::Producer` and serves FETCH through `track::Dynamic` +onto a supplied `broadcast::Producer` and serves FETCH through `broadcast::Dynamic` with a byte-bounded object LRU, stitching a group split across records and growing a group whose records do not reach its end yet. `Reader::refresh` follows by listing each timeline's keys after its cursor; `Reader::finish` @@ -111,13 +111,13 @@ work landed in #4034 and its children are this line's own): The target comes from each timeline's declared duration, which replaces the broadcast-wide `durationMax` (09-29 planning). -For triage, not blocking: two Codex P2s arrived after #4280 merged and are -unanswered. A timeline record whose `sequence` differs from its window index -is passed through unvalidated -([review](https://github.com/moq-dev/moq/pull/4280#pullrequestreview-5332725290)), -and `Timelines::track` re-enrolling a name while its old `Recorder` is alive -leaves two handles on one segmenter -([r4117516035](https://github.com/moq-dev/moq/pull/4280#discussion_r4117516035)). +This README owns one small fix (triaged 2026-10-08): `moq-mux`'s +`timeline::Consumer` passes a record whose `sequence` differs from its window +index through unvalidated +([review](https://github.com/moq-dev/moq/pull/4280#pullrequestreview-5332725290)); +refuse it as malformed, as `timeline::Producer::resume` already does. The +other #4280 Codex finding is fixed: `Timelines::track` refuses a name that is +still recording. ### Format @@ -172,5 +172,5 @@ owned by that prerequisite, not duplicated in archive storage. ## Related -- [Catalog track identity](/quest/m2/catalog-tracks.md) - explore immutable definitions or explicit version binding independently of archives +- [Catalog track identity](/quest/m2/catalog-tracks.md) - a track's definition never changes for its name, so any recorded catalog describes every group of the tracks it lists - [e2ee](/quest/m1/e2ee/README.md) - protected broadcasts are excluded initially diff --git a/quest/m1/archive/replay-catalog.md b/quest/m1/archive/replay-catalog.md index e5c1ad3bfaa..643e4ab942a 100644 --- a/quest/m1/archive/replay-catalog.md +++ b/quest/m1/archive/replay-catalog.md @@ -9,8 +9,10 @@ its recorded catalog live, stamped with the recording's `store` and `version`, so an exporter in history mode treats its timeline as durable and lists past `--window`. A `--follow` replay grows like an event playlist. -Choosing which catalog applies to which media group stays with -[Catalog track identity](/quest/m2/catalog-tracks.md). +A track's definition never changes for its name +([Catalog track identity](/quest/m2/catalog-tracks.md)), so the newest +recorded catalog describes every group of the tracks it lists; nothing here +picks a catalog per group. ## Plan diff --git a/quest/m1/archive/replay-history.md b/quest/m1/archive/replay-history.md index 06f923e2018..f31a1c25060 100644 --- a/quest/m1/archive/replay-history.md +++ b/quest/m1/archive/replay-history.md @@ -13,8 +13,7 @@ lists from its middle. Found by #4978 (bounded HLS playlists), which kept the full listing behind `moq_hls::export::Config::history` and confirmed the gap with a 4-record limit: 12 replayed segments listed from `EXT-X-MEDIA-SEQUENCE:8`. The archive test -missed it because its hand-built timeline repeats every record. Start after -#4978 lands. +missed it because its hand-built timeline repeats every record. Decided 2026-10-07: read the stored timeline groups in history mode rather than only the restated tail, so the exporter or the archive reader replays diff --git a/quest/m1/audio-encode-audiotoolbox.md b/quest/m1/audio-encode-audiotoolbox.md index 8868f115016..50ec083d5cb 100644 --- a/quest/m1/audio-encode-audiotoolbox.md +++ b/quest/m1/audio-encode-audiotoolbox.md @@ -31,9 +31,15 @@ the encode seam as the platform candidate on macOS and iOS. so a zero epoch stamps `[0, 0, 0, 20_000]`, and `decode::Consumer` reads the duplicates as holes and resets AAC between them. Shift the whole timeline by the deficit instead, including the terminal end (found in #4081 review). -- Until [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) - lands, binding callers pass `frame_duration_us: 0` with `aac()`. +- Until [FFI codec namespaces](/quest/m1/ffi-shape/codec.md) fixes the + frame duration default, binding callers pass `frame_duration_us: 0` with + `aac()`. ## Required - [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it + +## Related + +- [MediaCodec AAC encode](/quest/m2/audio-encode-mediacodec.md) - the same encode seam on Android +- [Media Foundation AAC encode](/quest/m2/audio-encode-mediafoundation.md) - the same encode seam on Windows diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index 590759740de..c7ffc0a6c54 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -105,8 +105,8 @@ published version in place, so AUTH and its stream code land in - [Relay tokens](/quest/m1/auth/relay-refresh.md) - the relay verifies tokens sent in band, unions their grants, and cancels only work that loses access - [Request tokens](/quest/m1/auth/request-token.md) - an `AUTHORIZATION - TOKEN` on a moq-transport request authorizes that request when the session - grant does not, and REQUEST_UPDATE refreshes it + TOKEN` on a moq-transport request decodes by the draft's rules, closing the + session on the forms the draft forbids - [Expired token error](/quest/m1/auth/expired-error.md) - an expired token reports `Error::Expired`, not `Unauthorized`, in Rust, JS, and the bindings - [Bindings](/quest/m1/auth/bindings.md) - grants and tokens reach every diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index 01e86fdf740..6d4b3c4e6a8 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -1,21 +1,26 @@ -# [M] A token on a request authorizes that request +# [S] A token on a request decodes by the draft's rules ## Goal -A moq-transport peer that is not on moq-dev can present or refresh a -credential the draft-17+ way, with the `AUTHORIZATION TOKEN` parameter -(`0x03`) on SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, PUBLISH_NAMESPACE, +The `AUTHORIZATION TOKEN` parameter (`0x03`) on a moq-transport request +(SUBSCRIBE, REQUEST_UPDATE, PUBLISH, FETCH, PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, TRACK_STATUS, or any other request that carries -parameters. A request is authorized by the session's grant first; when that -does not cover it, by the token on the request; with neither it is refused -`UNAUTHORIZED`. The token's grant covers only the request it rode on and -lives exactly as long as that request, and a REQUEST_UPDATE carrying a new -token replaces it, which is how a peer refreshes. It scopes by path, never -by method. Every request already decodes the key and ignores it, so a token -no longer fails the session; this quest gives it meaning. +parameters) decodes with the same structure and rules as the SETUP option. +A token the draft says must close the session closes it with the draft's +code; a `USE_VALUE` token is read and, for now, grants nothing, so a request +outside the session grant is still refused `UNAUTHORIZED`. Today every +request decodes the key and ignores it. ## Plan +Decided 2026-10-08: this quest is the decode-and-close change only. A +request token authorizing its own request (the fallback after the session +grant, refresh by REQUEST_UPDATE, and a per-request relay lease on +`moq_auth::Client`) is deferred until a moq-transport peer needs it; re-plan +it then from [#4675](https://github.com/moq-dev/moq/pull/4675), which built +it. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) +nor a lease. + - Decode with the SETUP option's structure and rules (`rs/moq-net/src/ietf/token.rs`, `js/net/src/ietf/token.ts`): `USE_VALUE` yields the token. `REGISTER` closes the session with `AUTH_TOKEN_CACHE_OVERFLOW` (0x13): we @@ -33,6 +38,8 @@ no longer fails the session; this quest gives it meaning. `decode_params!` path, where each request reads the repeatable key into an ignored `Vec`, and draft-14's `Parameters::skip`, which consumes it unread. `js/net` keeps every instance in `Parameters` and reads none. +- Land after [moq-transport parameters per draft](/quest/m0/ietf-params-per-draft.md) + (#5028), which reworks the same per-message decode. - 0x13 and 0x17 join the shared session registry: `SessionError` (`rs/moq-net/src/error.rs`) and `SessionCode` (`js/net/src/error.ts`). Lite codes below 32 carry moq-transport's meaning, so add both rows to the @@ -40,60 +47,17 @@ no longer fails the session; this quest gives it meaning. `session_codes_round_trip`, as [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) does for its codes. No per-version mapping. That adds two codes to moq-lite's wire registry. -- Ship the decode-and-close change as this quest's first PR. It needs - neither [Relay tokens](/quest/m1/auth/relay-refresh.md) nor the - per-request lease, so the validator's REGISTER and malformed-token rows - need not wait for the rest of the quest. -- Fallback only: a request the session grant already covers is served - without verifying its token. Otherwise its token becomes an - `auth::Request` on the session's `auth::Handle`, the seam an AUTH stream's - token takes, marked as belonging to that one request (its path and kind). - The `Grant` the acceptor answers is checked against that request alone, - never joins the session union, and ends when the request ends. With no - `requests()` consumer the default acceptor rejects a non-empty token - `Unsupported`, so an app that does not opt in refuses every request that - needs one. -- The request waits on its token's verdict before it is resolved. A refused - or insufficient token refuses the request with the verdict's code - (`UNAUTHORIZED`, `EXPIRED_AUTH_TOKEN`, `MALFORMED_AUTH_TOKEN`, or - `NOT_SUPPORTED`) through `to_code` for the draft; the session continues. -- Refresh: a REQUEST_UPDATE with a token verifies it the same way and, once - accepted, replaces the request's grant; a refused one leaves the old grant - until it lapses. When a request's grant expires or is revoked, that request - alone ends with `EXPIRED_AUTH_TOKEN` or `UNAUTHORIZED`. A session grant - that shrinks cancels the requests it covered, as for any request, through - `auth::Handle::authorize`. -- Relay: each such request gets its own lease from a per-request call on - `moq_auth::Client`, not the `Client::attach` that [Relay - tokens](/quest/m1/auth/relay-refresh.md) builds. `attach` connects with the - connection's id, and the auth server treats that as one more grant on the - session that never POSTs `end`, so a request token would widen the whole - connection for its life. The per-request call carries the token in - `moq_auth::Request.token` with its kind and the request's path, is never - counted as a session grant, and ends when the request ends. Two requests carrying the same bytes - get two leases. The request is resolved against the origin with the path - checked against that lease's grant, not through the session's scoped - origin handle. Name the call while implementing. -- `js/net` mirrors the decode and the default refusal. -- Docs: `doc/bin/relay/auth.md` states the order (session grant, then the - request's token, then `UNAUTHORIZED`), that a request token covers only its - request, and how a peer refreshes with REQUEST_UPDATE. -- Tests: a SUBSCRIBE outside the session grant succeeds with a covering token - and is refused `UNAUTHORIZED` without one; its token grants nothing to a - second SUBSCRIBE, and through the relay the auth server never counts it as - a session grant and sees its lease end with the request; a request inside the session grant never calls the - verifier; a REQUEST_UPDATE token keeps a subscription alive past the old - token's expiry; an expired request token ends only that request; with no - consumer a token-bearing request is refused `Unsupported`; one legacy and - one strict draft, Rust and JS. Regression tests for the decode: a - `REGISTER` token on a request closes with `AUTH_TOKEN_CACHE_OVERFLOW`, a - `DELETE` or `USE_ALIAS` one with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a - malformed request token with `KEY_VALUE_FORMATTING_ERROR`. +- `js/net` mirrors the decode. +- Tests, one legacy and one strict draft, Rust and JS: a `REGISTER` token on + a request closes with `AUTH_TOKEN_CACHE_OVERFLOW`, a `DELETE` or + `USE_ALIAS` one with `UNKNOWN_AUTH_TOKEN_ALIAS`, a malformed request token + with `KEY_VALUE_FORMATTING_ERROR`, and a `USE_VALUE` token on a request + outside the session grant is still refused `UNAUTHORIZED`. -Public API: additive on `moq_net::auth::Request` (the request it belongs -to) and on `moq_auth::Client` (the per-request lease). Wire: none new; the parameter already exists in every supported draft. +Public API: none beyond the two session codes. Wire: session codes 0x13 and +0x17 are named; the parameter already exists in every supported draft. -## Required +## Related -- [Relay tokens](/quest/m1/auth/relay-refresh.md) - supplies the lease - revalidation the per-request lease reuses +- [moq-transport parameters per draft](/quest/m0/ietf-params-per-draft.md) - the same per-message decode; lands first +- [Relay tokens](/quest/m1/auth/relay-refresh.md) - the lease a deferred per-request grant would reuse diff --git a/quest/m1/auth/wip-version.md b/quest/m1/auth/wip-version.md index 24ec28ced14..7f6d064d047 100644 --- a/quest/m1/auth/wip-version.md +++ b/quest/m1/auth/wip-version.md @@ -2,7 +2,7 @@ ## Goal -The lite Auth Stream (0x7) and the 0x3A UNAUTHORIZED stream code exist only +The lite Auth Stream (0x7) and the 0x3B UNAUTHORIZED stream code exist only on the wip lite version (`moq-lite-07-wip` today), in Rust, JS, the draft, and the interop matrix. A lite-06 session never opens or accepts an Auth Stream, so no published version changes in place. @@ -28,6 +28,8 @@ The gate is one predicate on each side: `Version::has_auth` has no grant and opens no Auth Stream. - Check the docs (`doc/concept`, `doc/lib/rs/moq-net.md`, `doc/lib/js/net.md`) name the wip version, not lite-06. +- Renumber UNAUTHORIZED from 0x3A to 0x3B in Rust, JS, and the draft + (decided 2026-10-08): `main` gave 0x3A to NOT_FETCHABLE. Public API: none. Wire: AUTH and UNAUTHORIZED leave lite-06; the line has not landed, so no released peer speaks them there. From 08fe2db418852bbabfbb2d1ef39acbae153728fd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:12:44 -0700 Subject: [PATCH 03/10] quest: apply audit fixes (group 3) Co-Authored-By: Claude Opus 5.5 --- quest/m1/bbr-ack-cleanup.md | 8 ++++---- quest/m1/bench-buckets.md | 2 +- quest/m1/binding-surface.md | 2 +- quest/m1/browser-benchmarks.md | 2 ++ quest/m1/c/README.md | 2 +- quest/m1/c/package.md | 5 +++-- quest/m1/c/retire.md | 10 ++++------ quest/m1/capture-alsa-link.md | 12 +++++++++++- quest/m1/cli-packaging.md | 5 ++--- quest/m1/cli-serve.md | 4 ---- quest/m1/cluster-routing/README.md | 5 ++++- quest/m1/cluster-routing/link-quality.md | 4 ++++ quest/m1/cluster-routing/routes.md | 20 ++++++++++++++++--- quest/m1/cpal-alsa-runtime.md | 6 ++++++ quest/m1/cpp/README.md | 6 +++--- quest/m1/data-consumer-timestamps.md | 4 ++-- quest/m1/e2ee/README.md | 4 ++-- quest/m1/e2ee/browser.md | 3 ++- quest/m1/e2ee/cli.md | 3 ++- quest/m1/e2ee/interop.md | 2 +- quest/m1/e2ee/rust-publish.md | 3 ++- quest/m1/e2ee/typescript.md | 2 +- quest/m1/export-ts-linger.md | 6 ++++-- quest/m1/fetch-ok-properties.md | 14 +++++++------ quest/m1/flv-export-delay.md | 25 ++++++++++++++---------- quest/m1/fmp4-catalog-init.md | 5 +++++ quest/m1/frame-slot-charge.md | 24 +++++++++++------------ quest/m1/front-deadline-index.md | 2 ++ quest/m1/ietf-fetch-only.md | 5 ++--- quest/m1/ietf-object-gaps.md | 23 +++++++++++++++++----- quest/m1/ietf-peer-fetch-old.md | 24 +++++++++++++++-------- quest/m1/interop-browser-timeouts.md | 4 ---- quest/m1/js-bundle-trims.md | 5 +++-- 33 files changed, 160 insertions(+), 91 deletions(-) diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index 331a6841706..5226a843a6e 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -46,15 +46,15 @@ flights, and explain any remaining logarithmic or amortized cost. Keep the regressions in CI and the benchmark matrix at least nightly. Do not substitute one hardware-specific millisecond limit for the scaling check. +Decided 2026-10-08: Switch is Related, not Required; BBR3 already lives in +`rs/moq-quic`, so this local fix lands without waiting for the switch. + Offer the fix upstream to quinn or record why not. Update internal packet-lifetime comments inline; no new user guide is needed. -## Required - -- [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 +- [Switch](/quest/m1/quic/fork/switch.md) - not a blocker: the core and its BBR3 are already in `rs/moq-quic` - [BBR starvation edges](/quest/m1/quic/bbr-app-limited-edges.md) - also edits `bbr3/mod.rs`; one owner there at a time - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - reusable measurement guidance, not a prerequisite for this fix - [Loss sampling](/quest/m2/quic-bbr-loss-parity.md) - preserve packet metadata needed by the separate loss-sample repair; both edit `bbr3/mod.rs`, so sequence them diff --git a/quest/m1/bench-buckets.md b/quest/m1/bench-buckets.md index 4ded72ea577..1aa63ef4c3c 100644 --- a/quest/m1/bench-buckets.md +++ b/quest/m1/bench-buckets.md @@ -31,7 +31,7 @@ so the bench emits mergeable buckets. Approved as recommended. on one clock and buckets from several hosts merge without skew; `latency_clock_skew` keeps flagging a violation. Replace the README's advice to NTP-sync separate publisher and subscriber hosts - (`rs/moq-bench/README.md:117-118`) with this rule. + (`rs/moq-bench/README.md`, "Machine-readable output") with this rule. - A test sums fixture buckets from two runs and checks the percentiles against the concatenated samples, binned by the same layout and the same overflow bucket (60,000 ms and above today) before the percentile is diff --git a/quest/m1/binding-surface.md b/quest/m1/binding-surface.md index 3de1ba7110a..4b94d60d919 100644 --- a/quest/m1/binding-surface.md +++ b/quest/m1/binding-surface.md @@ -18,7 +18,7 @@ configure and observe audio playout delay. Decided in the 2026-10-06 audit: the native decode delay API is on `main` (#4162, `rs/moq-audio/src/decode/consumer.rs`), so this no longer waits on -the m0 jitter-target line, whose remaining Watch proof bindings do not use. +the jitter-target line, whose remaining Watch proof bindings do not use. It waits on Codecs instead, so each wrapper adds delay to the reshaped audio decoder rather than to `BroadcastConsumer.decode_audio`, which Codecs removes. diff --git a/quest/m1/browser-benchmarks.md b/quest/m1/browser-benchmarks.md index 5498eeb8f18..eb960c385ec 100644 --- a/quest/m1/browser-benchmarks.md +++ b/quest/m1/browser-benchmarks.md @@ -8,6 +8,8 @@ microbenchmarks do not exercise. ## Plan +Decided 2026-10-08: m2, since nothing in m1 waits on browser measurements. + The JS microbenchmarks already exist: the seven Bun sweeps in `js/net/bench` (`broadcasts`, `forward`, `frames`, `lite-varint`, `reader`, `track`, `varint`) run nightly and cover the origin map, forwarded route re-pricing, diff --git a/quest/m1/c/README.md b/quest/m1/c/README.md index f0b640e790b..e3039af5a26 100644 --- a/quest/m1/c/README.md +++ b/quest/m1/c/README.md @@ -49,7 +49,7 @@ and fetch quests were abandoned for this line, and hidden is done. - [C++ through moq-ffi](/quest/m1/cpp/README.md) - the generator fork, package recipe, and OBS move this line builds on - [moq-c package](/quest/m1/c/package.md) - the generated header ships as `moq-c` 0.8.0 with `moq::c`, pkg-config, and a release workflow - [C consumers](/quest/m1/c/consumers.md) - the C interop client and `doc/lib/c` samples move onto the generated API -- [Retire libmoq](/quest/m1/c/retire.md) - the hand-written crate is deleted after its final release points at the generated package +- [Retire the hand-written moq-c](/quest/m1/c/retire.md) - the hand-written crate is deleted after its final release points at the generated package ## Related diff --git a/quest/m1/c/package.md b/quest/m1/c/package.md index 78b434e7c37..7a0122f0d52 100644 --- a/quest/m1/c/package.md +++ b/quest/m1/c/package.md @@ -25,8 +25,9 @@ under the same names. `moq_shutdown_dispatcher`. - moq-c and moq-cpp each embed the moq-ffi staticlib, so one program can't link both; say so in the docs. -- Every Cross-Package Sync row that names libmoq for moq-ffi changes points at - the generated package instead; update `AGENTS.md` in this quest. +- The Cross-Package Sync rows that name the hand-written `rs/moq-c` (as the + target of `rs/moq-ffi` changes, and its `moq.h` C ABI) point at the + generated package instead; update `AGENTS.md` in this quest. ## Required diff --git a/quest/m1/c/retire.md b/quest/m1/c/retire.md index 25c240d6eff..27b8f8bb663 100644 --- a/quest/m1/c/retire.md +++ b/quest/m1/c/retire.md @@ -1,4 +1,4 @@ -# [S] Retire the hand-written libmoq +# [S] Retire the hand-written moq-c crate ## Goal @@ -8,11 +8,9 @@ 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`; - [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. +- #4288 renamed libmoq to `moq-c` (`rs/moq-c`); this quest deletes that + hand-written crate. The code-free `rs/libmoq` stub left under the old name + is [Retire the libmoq stub](/quest/m1/libmoq-retire.md)'s, separately. ## Required diff --git a/quest/m1/capture-alsa-link.md b/quest/m1/capture-alsa-link.md index 91ab3adadbc..df6fed45ccd 100644 --- a/quest/m1/capture-alsa-link.md +++ b/quest/m1/capture-alsa-link.md @@ -27,7 +27,17 @@ comments that call libasound a build-time link. Verify by building in the Nix shell, then running the shipped binary on a host without libasound: it starts, lists devices, and captures where a backend exists. Inspect the binary to prove no load-time requirement on -libasound. The PR 3850 capture gate keeps the coverage. +libasound. The PR 3850 capture gate keeps the coverage until the last step. + +Last step, folded in from the deleted capture-default quest (decided +2026-10-08): once libasound loads at runtime, turn `capture` on by default in +moq-video and moq-audio, keeping the flag so a minimal build can opt out, and +delete the separate capture gate (`just rs capture`, `just rs capture-test`, +and the capture branches in `sh/rs/select.sh`) since default `just check` then +covers it. Keep the platform jobs. Update the Cargo feature comments and +`doc/` wherever capture is described as opt-in. Verify that a +`default-features = false` consumer (for example +`cargo tree -p moq-ffi -e features`) pulls no capture dependency. ## Required diff --git a/quest/m1/cli-packaging.md b/quest/m1/cli-packaging.md index 0166a2160b2..b2eb2253b01 100644 --- a/quest/m1/cli-packaging.md +++ b/quest/m1/cli-packaging.md @@ -51,9 +51,8 @@ libpipewire-0.3 to load, the same load-time requirement Decided in the 2026-09-30 audit: the v4l2 encode quest folded in here, since its remaining work was one release feature flag and a doc note. -Decided in the 2026-10-06 audit: this does not wait on -[Capture by default](/quest/m1/capture-default.md). moq-cli's `capture` -feature enables `moq-video/capture` and `moq-audio/capture` explicitly, so +Decided in the 2026-10-06 audit: this does not wait on the library +`capture` defaults. moq-cli's `capture` feature enables `moq-video/capture` and `moq-audio/capture` explicitly, so making it default-on does not depend on the library defaults. ## Required diff --git a/quest/m1/cli-serve.md b/quest/m1/cli-serve.md index 3a15f77bced..cb5b6f496f2 100644 --- a/quest/m1/cli-serve.md +++ b/quest/m1/cli-serve.md @@ -28,10 +28,6 @@ startup on any other invalid auth config. - Test: a listening import drains its viewers on SIGTERM within `drain_timeout`, and its sessions show up in stats. -Decided in the 2026-09-30 audit: no longer waits on -[`moq relay`](/quest/m3/moq-relay-subcommand.md). - ## Related -- [`moq relay`](/quest/m3/moq-relay-subcommand.md) - the CLI later hosts the whole relay - [Drain handshakes](/quest/m1/drain-handshakes.md) - moves where the drain count is taken diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 7cb7a118a3b..636673fb67d 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -90,6 +90,9 @@ One route cost lands on its own (`--hop` was replaced by `--epoch` in #4969). De 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. +Decided 2026-10-08: [Link quality](/quest/m1/cluster-routing/link-quality.md) +is Related, not Required, and moves to m2; measured cost is opt-in and the +line ships on static costs. ### Simulator findings @@ -134,10 +137,10 @@ Once every child has landed: - [Multi-CDN endpoints](/quest/m1/cluster-routing/multi-cdn.md) - an endpoint holds sessions to several CDNs, uses its preferred one, and fails over to the next - [Simulate the split](/quest/m1/cluster-routing/sim.md) - moq.pro's simulator compares the route layer with path vector before the wire is written - [Routes and announces](/quest/m1/cluster-routing/routes.md) - ROUTE per origin node and path-less ANNOUNCE on one stream, loop-free by Babel feasibility -- [Link quality](/quest/m1/cluster-routing/link-quality.md) - a radio link's cost follows its measured quality without flapping routes ## Related +- [Link quality](/quest/m1/cluster-routing/link-quality.md) - a radio link's cost follows its measured quality without flapping routes; not a blocker, since static costs are the default - [P2P](/quest/m3/p2p/README.md) - browser and native peers that become routing nodes over this layer - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static cost - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - the importer half of a redundant pair under one explicit epoch diff --git a/quest/m1/cluster-routing/link-quality.md b/quest/m1/cluster-routing/link-quality.md index 4fc03107745..dcb32776f09 100644 --- a/quest/m1/cluster-routing/link-quality.md +++ b/quest/m1/cluster-routing/link-quality.md @@ -13,6 +13,10 @@ local policy feeding the one metric on the wire, with no wire change. Decided 2026-10-01: the wire carries one additive metric and each node computes its own link costs. +Decided 2026-10-08: m2, and Related rather than Required for the +[cluster routing line](/quest/m1/cluster-routing/README.md): static costs are +the default and measured cost is opt-in, so the line ships without it. + - Derive the cost from what QUIC already measures (smoothed RTT, loss); an ETX-style estimate (Babel RFC 8966 Appendix A, B.A.T.M.A.N.'s TQ) is the reference. Pick the formula from the harness, not from intuition. diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index c3a234a9d00..1dc36f11048 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -98,14 +98,27 @@ Separating "the path changed" (ROUTE) from "the broadcast ended" (ANNOUNCE) removes that trade, and the failover tests must show no front loses its route while a working one exists. Decide whether #4642's hold can then go. +Simulator findings so far, from moq-dev/moq.pro#2152 (open, awaiting the +maintainer's decision on a design revision): + +- Live origin-end costs 134.5 KiB against path vector's 3668.1/1243.0 KiB, + but still emits 2150 client updates against an 840 once-only minimum and + re-announces 655 times. The Goal's "reaches each node about once" is not + met yet; find where the extra updates come from before the wire is written. +- A deterministic five-node ring keeps a working longer backup yet stays + starved until the origin advances its seqno. The simulator recommends + Babel seqno requests. + Open, for the implementer to settle and record: - Seqno lifetime across restarts of a node with a configured stable id (persist it, fold an incarnation into the id, or Babel's seqno request). -- Whether starvation recovery needs a request message, or session restart - covers it. +- Starvation recovery: the simulator's ring says session restart does not + cover it; confirm a seqno request message or record why not. - The window where an origin's ANNOUNCE_END and a next-hop change cross in - flight, and whether it needs more than the next END to arrive. + flight, and whether it needs more than the next END to arrive. The + simulator keeps this open until snapshot authority has deterministic + acceptance tests. - How much of today's route trie, fronts, and `route_order` survives intact. Tests, time mocked: #4644's live-graph withdrawal and failover tests @@ -125,6 +138,7 @@ release. ## Required +- [One route cost](/quest/m1/route-cost.md) - the single cost this splits into the announce seed and the route metric - [Simulate the split](/quest/m1/cluster-routing/sim.md) - the numbers that confirm the design before the wire is written ## Related diff --git a/quest/m1/cpal-alsa-runtime.md b/quest/m1/cpal-alsa-runtime.md index 5d9e2dc5f6a..e10a4f40525 100644 --- a/quest/m1/cpal-alsa-runtime.md +++ b/quest/m1/cpal-alsa-runtime.md @@ -19,6 +19,12 @@ diwic/alsa-sys if the loading lives there). Posting there needs maintainer approval, which is pending: on 2026-10-06 the maintainer chose not to post yet. Once the release is out, delete this quest. +Decided 2026-10-08: the capture chain (this quest, +[capture-alsa-link](/quest/m1/capture-alsa-link.md), and +[Ship capture and playback](/quest/m1/cli-packaging.md)) moves to m2 and parks +until cpal ships runtime ALSA loading. Nothing is posted upstream and no fork +is taken meanwhile. + ## Plan State as of 2026-10-05: cpal 0.18.2 (pinned here) and cpal master (0.19.0) diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index a84d440f9fe..65dda4ecacf 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -44,9 +44,9 @@ on a future under `__cpp_impl_coroutine`, `std::expected` under Distribution is a release tarball with a CMake package config and pkg-config file (mirroring `moq-c.yml`), so consumers never need a Rust toolchain or the bindgen fork. Decided in the 2026-09-30 audit: this line promises the tarball -only. A [vcpkg registry](/quest/m2/cpp-vcpkg.md) (m2) and a -[Conan remote](/quest/m3/cpp-conan.md) (m3) fetch the same tarball later and -stay deferred. +only. A [vcpkg registry](/quest/m2/cpp-vcpkg.md) and a +[Conan remote](/quest/m3/cpp-conan.md) fetch the same tarball later and stay +deferred. Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): diff --git a/quest/m1/data-consumer-timestamps.md b/quest/m1/data-consumer-timestamps.md index 11df5f2a686..b8d95ff60ad 100644 --- a/quest/m1/data-consumer-timestamps.md +++ b/quest/m1/data-consumer-timestamps.md @@ -13,8 +13,8 @@ Requested by an external consumer (OneTooMany, Discord), who translates MAVLink into application telemetry and must keep its timestamps to stay in sync with video. -Every `moq_net::Frame` has a timestamp, but the consumers decode only -`frame.payload` and drop it: `moq_mux::{json,binary}::Consumer::next` and the +Every `moq_net::Frame` carries an optional timestamp (`None` when untimed, +since #4822), but the consumers decode only `frame.payload` and drop it: `moq_mux::{json,binary}::Consumer::next` and the moq-json and moq-flate snapshot and stream consumers they wrap. Each snapshot state carries the timestamp of the frame that produced it. diff --git a/quest/m1/e2ee/README.md b/quest/m1/e2ee/README.md index 91c476db613..0de561fa755 100644 --- a/quest/m1/e2ee/README.md +++ b/quest/m1/e2ee/README.md @@ -32,7 +32,7 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro The Rust and TypeScript cores expose the same surface, and nothing else: - `Credential { context, kid, secret }` accepts the application-owned secret. The application generates and distributes it over its authenticated channel; the library does not mint a secret it cannot return. `credential.path(semantic)` derives the epoch-free opaque broadcast name. Credential is cheap to clone, never serializes the secret, and redacts it from `Debug`. -- `credential.generation(epoch)` binds a discovered or minted epoch. `Generation` owns `name(semantic)` for opaque track names, `produce(track)` and `consume(track)` for protected `moq-net` tracks, and `Epoch::mint()` returns a fresh UUIDv7. Clones share publisher claims so reopening a track cannot reset its nonce counters. +- A core produces only under an epoch it minted itself (decided 2026-10-08). Only the credential mints a producing generation, and that call takes no epoch: it mints a fresh UUIDv7 and returns a generation owning `epoch()` for the route, `name(semantic)` for opaque track names, and `produce(track)` for protected `moq-net` tracks. A discovered epoch binds a consume-only generation with `name(semantic)` and `consume(track)`. The two are separate types, so producing under a discovered or shared epoch does not compile; [Rust protected publisher seams](/quest/m1/e2ee/rust-publish.md) owns the Rust change and proposes the names. Clones of a producing generation share publisher claims so reopening a track cannot reset its nonce counters. - `track::Producer` appends groups and datagrams and allocates identities; `track::Consumer` yields groups and datagram events. `group::Producer` and `group::Consumer` wrap the whole group lifecycle so every AEAD call has the canonical physical name and transport identity. - Errors are the draft's typed codes plus the transport's. Nothing catalog-, hang-, or MSF-shaped lives here: a catalog is a track under a derived name, and compression is the catalog owner's job. - Stateless `seal`/`open` primitives with caller-chosen identities, HKDF labels and info builders, raw key bytes, and process-global claims are not public. The vectors are tested inside each core. @@ -41,7 +41,7 @@ The Rust and TypeScript cores expose the same surface, and nothing else: - Deterministic secret-derived physical names hide catalog, codec, role, quality, timeline, and custom-track semantics. Authorized clients derive the encrypted catalog track name, then learn the remaining opaque names from its decrypted contents. Every catalog representation is encrypted; Rust publishers must not emit a plaintext MSF catalog. - A platform that forwards and meters protected bytes must never preview, record, archive, transmux, transcode, transcribe, compose, or inspect them, rejecting those paths before opening a processing session or writing product state. Applications needing those operations terminate E2EE outside the platform. A platform classifies protected broadcasts by its own credential or product state, never by name; the moq.pro (downstream) exclusion classifier and dashboard work stay downstream. -- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams; JavaScript has no MoQ Transport datagram delivery yet. +- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams. JavaScript has no MoQ Transport datagram delivery until [#4979](https://github.com/moq-dev/moq/pull/4979) (open) lands; once it does, the proof covers MoQ Transport datagrams too. ## Required diff --git a/quest/m1/e2ee/browser.md b/quest/m1/e2ee/browser.md index 711d749af90..88a1ea6f2aa 100644 --- a/quest/m1/e2ee/browser.md +++ b/quest/m1/e2ee/browser.md @@ -11,7 +11,8 @@ Existing plaintext operation remains the default; an explicit application creden - Integrate the TypeScript E2EE layer before the existing Hang publish and after the existing Hang subscribe boundaries, keeping codec selection, synchronization, and rendering in the post-decryption pipelines. - Accept keys through a programmatic property/API only, never an HTML attribute, URL, persistent browser storage, analytics event, or log. Clear owned secret bytes when the component is replaced or disconnected; do not make extractability a hidden requirement. - Derive the opaque broadcast name from the semantic one, discover the newest epoch under that prefix, derive the encrypted catalog name from that generation, decrypt it before existing Hang selection, then subscribe to its opaque media and timeline tracks. Publish every catalog representation and semantic track name through the same protected naming contract. -- Cover camera/microphone publication, audio/video playback, late subscription, bounded WebCrypto backpressure, a restarted publisher under a new epoch, bad-group termination, and bad-datagram events in browser tests. +- Refuse the stats track and the `echo` attribute while a credential is set: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists. +- Cover camera/microphone publication, the stats and `echo` refusal, audio/video playback, late subscription, bounded WebCrypto backpressure, a restarted publisher under a new epoch, bad-group termination, and bad-datagram events in browser tests. ## Required diff --git a/quest/m1/e2ee/cli.md b/quest/m1/e2ee/cli.md index 01bf0ff222b..dec9e479d17 100644 --- a/quest/m1/e2ee/cli.md +++ b/quest/m1/e2ee/cli.md @@ -12,7 +12,8 @@ Existing plaintext commands remain the default; an explicit application credenti - 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. - 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. +- Refuse `--stats` and `--echo` together with a credential: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists. +- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--epoch` with a credential refused, `--stats` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports. ## Required diff --git a/quest/m1/e2ee/interop.md b/quest/m1/e2ee/interop.md index 480252ceb92..4576434ed87 100644 --- a/quest/m1/e2ee/interop.md +++ b/quest/m1/e2ee/interop.md @@ -10,7 +10,7 @@ Ordinary relays forward, cache, and meter the proof without receiving a content - Add automated browser-to-CLI and CLI-to-browser audio/video cases for both transport dialects using the same application credential and public client APIs. - Assert successful late subscription and decode, plaintext absence at the relay boundary, opaque physical names, deterministic failure under ciphertext or identity tampering, and that a restarted publisher lands under a new epoch that the old keys cannot open. -- Exercise grouped frames on both transport dialects and datagrams on moq-lite against the shared known-answer and negative vectors. Include relocation across tracks, groups, frames, epochs, and transport domains, plus replay-window and sequence-exhaustion cases. +- Exercise grouped frames on both transport dialects and datagrams on moq-lite against the shared known-answer and negative vectors, and exchange datagrams browser-to-CLI and CLI-to-browser, not only vectors. Add MoQ Transport datagrams once [#4979](https://github.com/moq-dev/moq/pull/4979) gives JavaScript that delivery. Include relocation across tracks, groups, frames, epochs, and transport domains, plus replay-window and sequence-exhaustion cases. - Verify the documented browser queue and native processing bounds under 20 ms Opus and representative video. Keep the proof deterministic rather than choosing new implementation defaults or adding timing sleeps. ## Required diff --git a/quest/m1/e2ee/rust-publish.md b/quest/m1/e2ee/rust-publish.md index 5ab78c6923a..76729ae5e72 100644 --- a/quest/m1/e2ee/rust-publish.md +++ b/quest/m1/e2ee/rust-publish.md @@ -4,10 +4,11 @@ Rust media and catalog publishers accept opaque physical names and emit no plaintext semantic catalog in E2EE mode. -The reusable crypto crate remains independent of Hang and codec-specific publisher policy. +The core produces only under an epoch it minted itself. The reusable crypto crate remains independent of Hang and codec-specific publisher policy. ## Plan +- Core change (decided 2026-10-08): `Credential::generation(epoch)` (`rs/moq-e2ee/src/credential.rs`) lets a caller produce under any epoch. Replace it with a minting call that takes no epoch and returns the producing generation, plus a consume-only binding for a discovered epoch, as separate types so producing under a discovered or shared epoch does not compile. The known-answer vectors need fixed epochs; keep that constructor crate-private. Propose the names in the PR; the TypeScript core mirrors them. - Provide injectable opaque-name allocation or explicit-name constructors for mux, video, audio, timeline, and catalog publishers that currently derive semantic names. - Derive the protected catalog name from its well-known logical role, then put media roles, codecs, quality, timelines, and custom-track mappings only inside the encrypted catalog. - Encrypt both Hang catalog representations and encrypt or suppress the MSF catalog. Compress protected catalog bodies before encryption and retain ordinary plaintext publication unchanged outside E2EE mode. diff --git a/quest/m1/e2ee/typescript.md b/quest/m1/e2ee/typescript.md index 5f9625b31d7..8c27ea5ef5f 100644 --- a/quest/m1/e2ee/typescript.md +++ b/quest/m1/e2ee/typescript.md @@ -10,7 +10,7 @@ the Rust crate name for name, without putting keys or crypto policy in `@moq/net From the Rust fix (#4994): a grouped authentication or identity failure wakes every parked frame, group, and datagram read and releases the track and group demand; dropping the track consumer releases demand even while a group handle is held; a bad datagram stays an event until its key is exhausted. Use the same error and event types. -- Add the package above `@moq/net`. `Credential` accepts a 32-byte secret or a nonextractable HKDF `CryptoKey` with `deriveBits` usage, rejects extractable keys, and never serializes the secret. `credential.path(semantic)` returns the opaque broadcast name and `credential.generation(epoch)` returns a `Generation` with `name()`, `produce()`, `consume()`, and epochs come from the shared `@moq/net` `Epoch`. +- Add the package above `@moq/net`. `Credential` accepts a 32-byte secret or a nonextractable HKDF `CryptoKey` with `deriveBits` usage, rejects extractable keys, and never serializes the secret. `credential.path(semantic)` returns the opaque broadcast name. Mirror the Rust split (decided 2026-10-08): only a credential call that takes no epoch mints a producing generation (`epoch()`, `name()`, `produce()`), and a discovered `@moq/net` `Epoch` binds a consume-only one (`name()`, `consume()`), with the names the Rust core settles. - Mirror the Rust modules: `Track.Producer`, `Track.Consumer`, `Group.Producer`, `Group.Consumer`, `Datagram.Event`, and a `Failure` whose `code` is the draft's typed set. No catalog helpers, no exported constants beyond the profile limits an application sizes payloads with, no stateless `protect`/`open` with caller-chosen identities, and no test-only methods on public classes. - WebCrypto AES-GCM is async, so each producer and consumer runs a serial pump: one AEAD call in flight, completions in submit order, a bounded waiter queue that throws when full. Depth one keeps frame ordinals equal to the inner `@moq/net` write order without reservation sets; raise it only when a measured capture burst needs it. Propagate backpressure, cancellation, and authentication failure explicitly; never reorder media or fall back to plaintext. - Identity state is two counters per key (invocations, plaintext bytes) and one monotonic sequence per track. Check payload size before taking a frame ordinal so a rejected write never burns an identity. Datagram receivers keep a 1024-bit sliding bitmask marked only after a successful open; failed opens count against the key; a grouped authentication failure closes the ordered track. diff --git a/quest/m1/export-ts-linger.md b/quest/m1/export-ts-linger.md index d0fd7a703c7..56eec425189 100644 --- a/quest/m1/export-ts-linger.md +++ b/quest/m1/export-ts-linger.md @@ -8,7 +8,9 @@ waiting out the linger (`rs/moq-cli/src/subscribe.rs`). ## Plan -Reported by t0ms while grading #4645, who offered to do the CLI side. +Reported by t0ms while grading #4645, who offered to do the CLI side. In +progress as [#4947](https://github.com/moq-dev/moq/pull/4947) on a non-quest +branch (`cli/linger-export-failure`). The error alone can't tell the cases apart: a publisher drop or SIGKILL usually surfaces as a track `Err` too, and that must keep lingering (see the @@ -26,4 +28,4 @@ Public API: none. Wire: none. ## Related -- [#4645 report](https://github.com/moq-dev/moq/pull/4645#issuecomment-6013366214) - the motivating `missed a decode deadline` failure exists only on #4645's branch +- [#4645 report](https://github.com/moq-dev/moq/pull/4645#issuecomment-6013366214) - the motivating `missed a decode deadline` failure diff --git a/quest/m1/fetch-ok-properties.md b/quest/m1/fetch-ok-properties.md index df6a7408a76..5257db1e281 100644 --- a/quest/m1/fetch-ok-properties.md +++ b/quest/m1/fetch-ok-properties.md @@ -13,9 +13,9 @@ Found (2026-10-01) in #4647: a group FETCH with no prior SUBSCRIBE_OK now reads its max age from FETCH_OK, but our publisher sends an empty block. -- `rs/moq-net/src/ietf/publisher.rs` sends FETCH_OK with - `properties: Default::default()`. SUBSCRIBE_OK fills them in the block near - `publisher.rs:655`. Share that code so the two can't diverge. +- `run_fetch_stream` (`rs/moq-net/src/ietf/publisher.rs`) sends FETCH_OK + with `properties: Default::default()`. `run_subscribe_stream` fills them in + its `ietf::SubscribeOk` encode. Share that code so the two can't diverge. - Our group-fetch accept path reads only the max age from FETCH_OK and hardcodes a microsecond timescale. Apply the same properties SUBSCRIBE_OK does (timescale, priority, group order) there too. @@ -43,13 +43,15 @@ sends an empty block. carry, a standalone FETCH's objects arrive stamped, and INCLUDE_PROPERTIES = 0 empties the block. +Decided 2026-10-08: [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) +lands first, since both change how a fetch-only reader learns the track's +properties. + Public API: none. Wire: FETCH_OK gains its properties on drafts that define the block. Interop: run `just test interop --all`. ## Required +- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - lands first ([#4974](https://github.com/moq-dev/moq/pull/4974)); it asks TRACK_STATUS for the same properties when a publisher omits them - [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - draft-20 FETCH is served at all, and edits the same `run_fetch_stream` -## Related - -- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - asks TRACK_STATUS for the same properties when a publisher omits them diff --git a/quest/m1/flv-export-delay.md b/quest/m1/flv-export-delay.md index 2a482f554ea..f82470319dd 100644 --- a/quest/m1/flv-export-delay.md +++ b/quest/m1/flv-export-delay.md @@ -1,24 +1,29 @@ -# [S] FLV export releases frames on a fixed delay +# [S] FLV and MKV exports release on a fixed delay ## Goal -`moq export flv --delay ` interleaves tracks through the shared -jitter buffer, so its tag order is a function of the media, not -of arrival, as the TS export's is. +`moq export flv --delay ` and `moq export mkv --delay ` interleave +tracks through the shared jitter buffer, so their tag and block order is a +function of the media, not of arrival, as the TS export's is. ## Plan -Today `pick_next_track` (`rs/moq-mux/src/container/flv/export.rs`) takes the -smallest *pending* timestamp, so which track goes first depends on which frame -has arrived. Replace it with the jitter buffer the TS export uses +Today each exporter's `pick_next_track` +(`rs/moq-mux/src/container/flv/export.rs`, +`rs/moq-mux/src/container/mkv/export.rs`) takes the smallest *pending* +timestamp, so which track goes first depends on which frame has arrived. +Replace both with the jitter buffer the TS export uses (`rs/moq-mux/src/jitter.rs`), with the same `--delay` flag and the same late-frame drop. Update `doc/bin/cli.md`. Decided in the 2026-10-06 audit: `--delay` replaces the staleness flag, as it replaced `--max-age` on TS, so one knob sets both the release delay and the sources' staleness budget. [#4917](https://github.com/moq-dev/moq/pull/4917) -renames that flag to `--max-delay` first; this quest then replaces -`--max-delay` with `--delay`. Rejected: excluding flv from the #4917 rename. +already renamed that flag to `--max-delay` (`with_max_delay` on both +exporters); this quest replaces `--max-delay` with `--delay` for flv and mkv. -Public API: breaking, the exporter's staleness setting becomes the delay +Decided 2026-10-08: FLV and MKV land together in one quest, so the CLI and the +exporters' builder API break once. + +Public API: breaking, each exporter's staleness setting becomes the delay setting. Wire: none. diff --git a/quest/m1/fmp4-catalog-init.md b/quest/m1/fmp4-catalog-init.md index 1d367e739a8..b9091d906a5 100644 --- a/quest/m1/fmp4-catalog-init.md +++ b/quest/m1/fmp4-catalog-init.md @@ -27,3 +27,8 @@ Decided (2026-10-04), carried over from the export track-set work: Today a returning Annex-B rendition is compared by its avcC/hvcC, SPS bytes included; with in-band parameter sets the comparison covers only the catalog-derived record, so an encoder that restarts with a new SPS can return. + +## Related + +- [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - #4826 edits the same fMP4 code; whichever lands second rebases, with no forced order +- [Finish in-band CMAF parameter sets](/quest/m1/cmaf-inline-followups.md) - the readers that must handle the avc3/hev1 tracks this writes diff --git a/quest/m1/frame-slot-charge.md b/quest/m1/frame-slot-charge.md index 8ac314fc252..284f7e94d28 100644 --- a/quest/m1/frame-slot-charge.md +++ b/quest/m1/frame-slot-charge.md @@ -24,19 +24,19 @@ up to. Two gaps follow: - `GroupState::release` (on abort, too-large, or a dropped producer) calls `frames.clear()`, which keeps the capacity, then zeroes `cache` and clears the charge. A consumer still holding the group pins those slots uncharged. - Dropping the deque's storage on release is likely enough here. -The fix is not a bigger constant. The charge has to follow the deque's -capacity: charge the growth at each `charge.add` site (`write_frame`, the -`write_frames` loop, and `GroupState::charge_partial` for a streamed frame), keeping -`FRAME_SLOTS` as the part `CACHE_OVERHEAD` already paid. +Decided 2026-10-08, two changes and no more: -Decide what `MAX_CACHE_BYTES` compares against before touching any of it. -`GroupState::would_overflow` reads `cache` as a payload limit, and the tests -and its doc ("maximum total size of frames") read it that way, so folding -slots into `cache` silently changes the per-group ceiling. Either keep a -separate payload counter for that check or restate the limit; do not let one -field mean both. +- Free the deque's storage in `GroupState::release`, not just `clear()` it. +- Charge the growth past `FRAME_SLOTS` to the pool at each `charge.add` site + (`write_frame`, the `write_frames` loop, and `GroupState::charge_partial` + for a streamed frame), keeping `FRAME_SLOTS` as the part `CACHE_OVERHEAD` + already paid. The fix is not a bigger constant. + +`MAX_CACHE_BYTES` stays a payload limit: `GroupState::would_overflow` keeps +reading `cache` as payload bytes, so slot charges go to the pool charge and +never into `cache`. Restating that limit needs a measurement first and is not +this quest. `rs/moq-net/tests/group_charge.rs` weighs the process with a counting allocator and is the place to prove it: add a many-small-frames shape beside @@ -46,4 +46,4 @@ boundary and asserts the pool charge moved. Found by CodeRabbit on #3523, which fixed the one-frame-per-group undercount that was OOM-killing relays serving chat, and deliberately left out of it. -Public API: none, unless `MAX_CACHE_BYTES` is restated. Wire: none. +Public API: none. Wire: none. diff --git a/quest/m1/front-deadline-index.md b/quest/m1/front-deadline-index.md index 548d7acfa65..03fe528b5bc 100644 --- a/quest/m1/front-deadline-index.md +++ b/quest/m1/front-deadline-index.md @@ -35,4 +35,6 @@ Public API: none. Wire: none. ## Related +- [Idle fronts](/quest/m0/idle-fronts.md) - lands first and changes what a front holds; rebase onto it +- [Route wakes](/quest/m1/route-wakes.md) - narrows which fronts a route change wakes, in the same origin driver; one owner of `origin.rs` at a time - [Front parking](/quest/m1/origin-front-parks.md) - also changes what a front holds, and wants a churn benchmark over requesters diff --git a/quest/m1/ietf-fetch-only.md b/quest/m1/ietf-fetch-only.md index c904d30e600..07d4a865c34 100644 --- a/quest/m1/ietf-fetch-only.md +++ b/quest/m1/ietf-fetch-only.md @@ -32,7 +32,7 @@ Decided (2026-10-01): twice. Before draft 20 there's no opt-out, so it ignores the duplicate. - First decouple object timestamps from INCLUDE_PROPERTIES: the publisher derives its serving timescale from `properties_wanted` - (`publisher.rs:628`), so opting out today strips the Timestamp property + (`run_subscribe_stream` in `rs/moq-net/src/ietf/publisher.rs`), so opting out today strips the Timestamp property from every object and the subscriber falls back to arrival time. Test TRACK_STATUS plus the opt-out with source timestamps that differ from arrival. @@ -44,6 +44,5 @@ Decided (2026-10-01): ## Related -- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - the publisher side of the same properties - +- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - the publisher side of the same properties, which lands after this - [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher answers these fetches diff --git a/quest/m1/ietf-object-gaps.md b/quest/m1/ietf-object-gaps.md index 409e29dde6e..db5e88f1e1c 100644 --- a/quest/m1/ietf-object-gaps.md +++ b/quest/m1/ietf-object-gaps.md @@ -7,8 +7,8 @@ A moq-transport group whose object IDs skip after an object was delivered 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 +no FIRST_OBJECT bit) is not a gap: it is a quiet drop that keeps the +subscription, in Rust as in JS since #5019. An object ID that overflows closes the session with PROTOCOL_VIOLATION in Rust, as the draft requires. ## Plan @@ -17,8 +17,12 @@ 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, 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. +subscribe, so it is expected, not a fault. + +Decided 2026-10-08: the Rust headless drop is part of this quest, not its own, +since both change how `next_object_id`'s refusal is handled and the +order matters. Do the headless drop first, so a headless subgroup is never +caught by the louder gap refusal. Facts from `main`: @@ -28,6 +32,14 @@ Facts from `main`: A non-zero subgroup returns `Err`, which the session's `stop_on_error` turns into STOP_SENDING. An overflowing object ID (`BoundsExceeded`) is aborted with the group the same way. +- Rust headless subgroups: drafts 14-17 have no FIRST_OBJECT bit, so the + header decode sets `first_object` true (`rs/moq-net/src/ietf/group.rs`) and + `open_group`'s "dropping a group with no head" path never runs. A non-zero + first object ID then reaches `next_object_id`, which warns, and + `recv_group` aborts the group. Apply #5019's rule: on a draft without the + bit, a non-zero first object ID takes the same drop path as a cleared + FIRST_OBJECT bit on d18, before a group exists. A gap after an object was + delivered is still the refusal below. - A data stream's error never reaches the session: `stop_on_error` in `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 @@ -41,7 +53,8 @@ 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 overflow to close on; the overflow case is Rust-only. -Tests: a gapped group yields `Err(Unsupported)` from `recv_group` and +Tests: a d14 and a d16 subgroup opening at object 2 is dropped at debug and +the subscription delivers the next group; a gapped group yields `Err(Unsupported)` from `recv_group` and stops its stream, while the subscription keeps flowing (beside `a_non_zero_subgroup_leaves_the_track_flowing`); an overflowing object ID closes the session (Rust). diff --git a/quest/m1/ietf-peer-fetch-old.md b/quest/m1/ietf-peer-fetch-old.md index 387e7229cfc..b5fa8e1b408 100644 --- a/quest/m1/ietf-peer-fetch-old.md +++ b/quest/m1/ietf-peer-fetch-old.md @@ -1,11 +1,11 @@ -# [M] Cross-relay FETCH over moq-transport serves held groups +# [M] Cross-relay FETCH serves held groups on any peer link ## Goal -With the cluster peer link on moq-transport, a cross-relay FETCH for a group -the origin still holds is served, not refused as `old`. The burst drill then -gains a moq-transport peer link as a third `PeerLink` variant, and its -impaired lane passes. +With the cluster peer link on moq-lite or moq-transport, a cross-relay FETCH +for a group the origin still holds is served, not refused as `old`. The burst +drill gains a moq-transport peer link as a third `PeerLink` variant, its +impaired lane passes, and the lite seed below no longer loses a group. ## Plan @@ -17,6 +17,13 @@ groups the origin still held, e.g. `groups lost: [(5, Failed("old")), 6755536760138253279, 17984197590923068922, 10974424043511566981. The loopback lane and the flapping drill passed. +Lite too (decided 2026-10-08, widening this quest rather than opening +another): [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) saw +`bursts_cross_a_cluster` on a lite peer link, on `main` at `fe0113ff2`, lose +group 89 in 1 of 40 runs to a live `Old` reset whose FETCH was also refused +`old` (seed 11025055814286623932). It may share the moq-transport cause or +not; reproduce both before fixing either. + Facts (2026-10-07): the IETF FETCH path (`run_fetch_stream`, `rs/moq-net/src/ietf/publisher.rs`) has no explicit `Old` check. An `Old` can come from reading a group the cache's wall-clock expiry aborts mid-read @@ -25,12 +32,13 @@ from a lite peer's `StreamError::Old` reset passing through (unconfirmed: no caller chain into this FETCH path was traced). `Old` has no moq-transport code, so it goes out as INTERNAL_ERROR and comes back as `Error::Remote`. -- Reproduce with the seeds, find which path refuses, and fix it at the - cause. A held group must not be refused. +- Reproduce with the seeds on both peer link versions, find which path + refuses, and fix it at the cause. A held group must not be refused. +- Keep the lite seed as a regression case beside the drill. - Add the moq-transport peer link case to the drill. Public API: none expected. Wire: none expected. ## Related -- [Cross-relay bursts re-run](/quest/m1/cross-relay-bursts.md) - the #4349 `Stream(Old)` stalls, not reproduced over a lite peer link +- [Cross-relay bursts re-run](/quest/m1/cross-relay-bursts.md) - the #4349 `Stream(Old)` stalls and the lite seed this quest now owns diff --git a/quest/m1/interop-browser-timeouts.md b/quest/m1/interop-browser-timeouts.md index 1dd84434af7..6ae1156bb17 100644 --- a/quest/m1/interop-browser-timeouts.md +++ b/quest/m1/interop-browser-timeouts.md @@ -23,7 +23,3 @@ FFI publisher's 2 s audio max age parked hundreds of group serves. - Never raise the timeout or add a retry. Public API: none expected. Wire: none. - -## Related - -- [CI runner stalls](/quest/m1/ci-runner-stalls.md) - shorter freezes of both interop tracks on CI runners diff --git a/quest/m1/js-bundle-trims.md b/quest/m1/js-bundle-trims.md index 9b939a64878..47d4b69223d 100644 --- a/quest/m1/js-bundle-trims.md +++ b/quest/m1/js-bundle-trims.md @@ -16,8 +16,8 @@ cannot remove. Measured in bundled, minified form (2026-09-26): ## Plan Decided in planning: all three trims are in scope (worklet minification -landed with the strict-CSP worklet change). Mediabunny is its own -quest. +landed with the strict-CSP worklet change). Mediabunny already loads only +when a file source needs it (#4893). Guidance: @@ -40,4 +40,5 @@ Guidance: ## Related +- [Safari WebTransport](/quest/m3/safari-webtransport.md) - also edits the WebKit and iOS gate in `browser.ts`; the bowser replacement must expose the Safari and iOS versions that gate needs - [Size report](/quest/m1/size-report.md) - tracks these entries nightly From e7e3094c4be249514992253bbfd964d50cf711a8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:16:29 -0700 Subject: [PATCH 04/10] quest: apply audit fixes (group 4) Co-Authored-By: Claude Opus 5.5 --- quest/m1/js-fetch.md | 9 +-- quest/m1/js-group-handover.md | 11 ++- quest/m1/js-request-window.md | 9 ++- quest/m1/js-session-parity.md | 10 +-- quest/m1/listener-deadlines.md | 7 +- quest/m1/lite-live.md | 33 +++++---- quest/m1/lite-untimed.md | 5 +- quest/m1/lite07-finalize.md | 18 +++-- quest/m1/mkv-lacing.md | 2 +- quest/m1/obs-moq-video/README.md | 2 +- quest/m1/obs-moq-video/adapter.md | 2 +- quest/m1/obs-moq-video/audio-publish.md | 2 +- quest/m1/obs-moq-video/source.md | 3 + quest/m1/open-gop-leading-pictures.md | 21 +++--- quest/m1/origin-front-parks.md | 15 ++--- quest/m1/papercuts-js.md | 12 +++- quest/m1/papercuts-rs.md | 27 +++----- quest/m1/perf/README.md | 27 ++++---- quest/m1/perf/group-cost.md | 11 ++- quest/m1/perf/ingest-batch.md | 34 +++++----- quest/m1/perf/kio-channel-contention.md | 16 ++--- quest/m1/perf/lock-profile.md | 89 +++++++++++++++++++------ quest/m1/perf/uring-one-enter.md | 29 ++++---- quest/m1/performance-comparisons.md | 4 +- quest/m1/pipeline-fetch-info.md | 8 ++- quest/m1/publish-audio-channel-count.md | 11 +-- quest/m1/qos/README.md | 10 ++- quest/m1/qos/lag-dashboard.md | 6 +- quest/m1/qos/lag-histogram.md | 35 ++++++++++ quest/m1/qos/publisher-timeliness.md | 18 ++--- quest/m1/quic/README.md | 14 ++-- quest/m1/quic/bbr-app-limited-edges.md | 6 +- quest/m1/quic/bbr-app-limited.md | 10 +-- quest/m1/quic/scheduler.md | 4 +- 34 files changed, 317 insertions(+), 203 deletions(-) create mode 100644 quest/m1/qos/lag-histogram.md diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index 3d72e2ffe4c..5ab16a9fa80 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -19,10 +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. +Datagrams are never fetchable (#4982): Rust answers an IETF FETCH that +reaches a datagram with DOES_NOT_EXIST; match it. Decided 2026-10-08: JS adds +no `NotFetchable` code, since nothing would send it. Only lite-07 has the +code, and lite-07 drops FETCH for [ranges](/quest/m1/subscribe-ranges/lite.md); +lite-05 and lite-06 answer `NotFound`. 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 diff --git a/quest/m1/js-group-handover.md b/quest/m1/js-group-handover.md index 81ec871ca80..4ffb5b5a9f5 100644 --- a/quest/m1/js-group-handover.md +++ b/quest/m1/js-group-handover.md @@ -41,7 +41,10 @@ settle along the way: 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. + it with a fresh subscription. A route without an epoch never resumes, as + in Rust, so `drain.ts`'s publisher mints an epoch, and the + [transport upgrade](/quest/m1/transport-upgrade/js.md) test publishes + under one too. - `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 @@ -53,9 +56,13 @@ Add unit coverage at the origin level against stand-in sessions, then flip `test/drain` to zero budget (drop the resubscribe loop in `drain.ts` and the budget note in its README). +Decided 2026-10-08: Restart and One max_age meaning land first, so this +mirrors their final shape instead of chasing it. + Public API: likely a behavior change to `Origin.Requesting.active` and track subscriptions across a swap. Report it in the PR. -## Related +## Required - [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event a swap to another epoch produces instead of a handover +- [One max_age meaning](/quest/m1/cache-max-age.md) - the rule that gives up a resumed group no route continues diff --git a/quest/m1/js-request-window.md b/quest/m1/js-request-window.md index e873acdf245..7d0a16beb9c 100644 --- a/quest/m1/js-request-window.md +++ b/quest/m1/js-request-window.md @@ -11,10 +11,9 @@ so the peer stalls after about 21k requests. ## Plan Advertise a finite window and send MAX_REQUEST_ID to grant more as requests -close. Refuse an incoming ID past the window with the draft's error. This -can start before request caps (#4820), since the JS bug exists on main; use -the drafts as the contract and align with Rust's landed window when -available. A mocked-time test drives more than 21k requests through one -session. +close. Refuse an incoming ID past the window with the draft's error. Mirror +Rust's window, which landed with request caps (#4820), in +`rs/moq-net/src/ietf/control.rs`. A mocked-time test drives more than 21k +requests through one session. Public API: none. Wire: behaviour within the drafts; no format change. diff --git a/quest/m1/js-session-parity.md b/quest/m1/js-session-parity.md index 2d29a038a61..85586afcffa 100644 --- a/quest/m1/js-session-parity.md +++ b/quest/m1/js-session-parity.md @@ -2,7 +2,7 @@ ## Goal -Three Rust moq-net session behaviors hold in `@moq/net` too, so a JS peer or +Two Rust moq-net session behaviors hold in `@moq/net` too, so a JS peer or relay behaves like a Rust one. ## Plan @@ -15,13 +15,13 @@ relay behaves like a Rust one. wait for missing groups below a declared end until the tail settles, mirror the hold. JS readers still end at the end with groups missing (`doc/lib/js/net.md`). -- Resolved epoch (#4904 and #4967, landed): Rust `broadcast::Info::epoch` - carries the epoch of the route a request resolved through. Check that JS - (`broadcast.Consumer.epoch`) and the bindings (moq-ffi) surface the same - value. Test each against the Rust behavior, with mocked time. +Decided 2026-10-08: the resolved-epoch check is done for JS +(`broadcast.Consumer.epoch` mirrors `broadcast::Info::epoch`), and the +bindings' epoch surface is [Bindings](/quest/m0/broadcast-epoch/bindings.md)'s. + ## Related - [JS request window](/quest/m1/js-request-window.md) - JS grants request IDs as requests close, the other half of JS request limits diff --git a/quest/m1/listener-deadlines.md b/quest/m1/listener-deadlines.md index bb1a0a1db26..60f3c718abe 100644 --- a/quest/m1/listener-deadlines.md +++ b/quest/m1/listener-deadlines.md @@ -29,9 +29,10 @@ that ACKs every PING), and the iroh backend honors `quic.keep_alive`. Set the PING keep-alive too, for dead peers. Apply both to the HTTPS listener and the `[internal]` listener, which also gets the HTTP/1 header timer. -- iroh (`rs/moq-tokio/src/iroh.rs`): set iroh 1.3's - `keep_alive_interval` from `quic.keep_alive`, and fix the docs that say iroh - has no knob (`rs/moq-tokio/src/quic.rs`, `doc/bin/relay/config.md`). +- iroh (`rs/moq-tokio/src/iroh.rs`): set `keep_alive_interval` from + `quic.keep_alive` (the locked iroh 1.2 already has it), and fix the docs + that say iroh has no knob (`quic.rs`, `iroh.rs`, and + `doc/bin/relay/config.md`). - Tests on a paused clock where the runtime allows: a stalled io_uring handshake closes at the deadline, and an HTTP/2 client that ACKs PINGs but never sends a request, or trickles one request's headers, is dropped at the diff --git a/quest/m1/lite-live.md b/quest/m1/lite-live.md index e73a6f5564b..710fc3e7731 100644 --- a/quest/m1/lite-live.md +++ b/quest/m1/lite-live.md @@ -30,10 +30,15 @@ Decided (maintainer, 2026-10-07): `Subscriber Max Age` has not expired, when that position sorts below the floor. That is the start lite-06 already resolves for `Group Start` 0, so a buffering subscriber keeps its backlog, and a max age of 0 still means the - latest group. On an untimed track no group expires by max age, so `Live` - means the latest group there (as `model/subscription.rs` documents today), - not the whole cache. Comparing positions, not groups, means a merged floor - of (3, 5) with group 3 as the latest still delivers frames 0-4. + latest group. On an untimed track the wall clock alone judges staleness + ([One max_age meaning](/quest/m1/cache-max-age.md)), so `Live` starts at + the oldest group that isn't stale there too; until that lands it means the + latest group (as `model/subscription.rs` documents today). Comparing + positions, not groups, means a merged floor of (3, 5) with group 3 as the + latest still delivers frames 0-4. +- [Model ranges](/quest/m1/subscribe-ranges/model.md) replaces the floor + with ranges after this lands: the floor becomes the lowest range start, and + `Live` stays its own flag. - The model mirrors the wire: `Subscription { floor: Option<(group, frame)>, live }` in Rust and `@moq/net`. - Merging across subscribers (`Subscription::poll_combined`, JS @@ -50,14 +55,13 @@ Decided (maintainer, 2026-10-07): `Largest Object` is a floor at the next object; draft-20 `Relative(1)` is `live`; `Absolute Start` is a floor. - When merged subscriptions need both `live` and a floor that an older - upstream wire cannot express in one SUBSCRIBE, a moq-transport upstream MAY - first be asked TRACK_STATUS for the largest group, subscribing from the lower - of the two. That covers only a `live` reaching the latest group. A buffered - `live` (max age > 0) needs the oldest unexpired group, which the relay - can't learn upstream: the ordinary join (`subscribe_join`) fetches only the - latest group's prefix. So a buffered `live` merged with a floor subscribes - from `Absolute Start` at group 0, and the relay filters locally by age and - floor. For an empty track the `live` mapping alone covers both, since + upstream wire cannot express in one SUBSCRIBE, a moq-transport upstream is + subscribed from `Absolute Start` at group 0, and the relay filters locally + by age and floor. The relay can't learn the oldest unexpired group + upstream: the ordinary join (`subscribe_join`) fetches only the latest + group's prefix. Decided 2026-10-08: no TRACK_STATUS step to find the + largest group first, since it covers only an unbuffered `live` and adds a + round trip. For an empty track the `live` mapping alone covers both, since moq-transport starts it at {0, 0}. moq-lite has no TRACK_STATUS, so a lite-06 or lite-03 to 05 upstream is subscribed at floor 0 and the relay filters locally. On lite-06 that is `Group Start` 0, exactly @@ -78,10 +82,11 @@ merged with a floor above the live edge, a frame floor merged with `live`, a merged `{floor: 2, live}` through a lite-03 to 05 upstream with groups 2-4 retained that delivers all three, a buffered `live` merged with a floor-5 subscriber over a moq-transport upstream with fresh groups 2-4 that still -delivers 2-4, an untimed `live` merged with a floor that starts at the latest -group, and the codec mapping of each older wire. +delivers 2-4, an untimed `live` merged with a floor, and the codec mapping +of each older wire. ## Related +- [One max_age meaning](/quest/m1/cache-max-age.md) - decides where an untimed `Live` starts - [Late lower group](/quest/m1/lite-late-lower-group.md) - requires this; #5000 rebases onto it and drops its own floor-combining change - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - names undelivered groups once publishers report them diff --git a/quest/m1/lite-untimed.md b/quest/m1/lite-untimed.md index 34eb3382d5a..b5e288c68a5 100644 --- a/quest/m1/lite-untimed.md +++ b/quest/m1/lite-untimed.md @@ -21,6 +21,9 @@ 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. +Decided 2026-10-08: [Rust untimed default](/quest/m1/rust-untimed-default.md) +lands first, since both edit the same Timescale defaults. + Draft work: - The draft describes only the current wire. Add the lite-07 encoding, the @@ -37,6 +40,6 @@ JS-to-Rust on lite-07. lite-06 still receives a timestamp. Run Public API: none. Wire: lite-07-wip only, which is unpublished. -## Related +## Required - [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/lite07-finalize.md b/quest/m1/lite07-finalize.md index 162fe049643..df8dc10f7f4 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -28,12 +28,17 @@ The route layer of [Cluster routing](/quest/m1/cluster-routing/README.md) (ROUTE_START/UPDATE/END, path-less ANNOUNCE, the hop list dropped) lands in lite-07, decided 2026-10-05. That removes lite-07's `Hop Base`/`Hop Keep` announce compression along with the hop list, and moq.pro's lite-07 rollout -(moq.pro#2210) has to plan for a lite-07 without hop lists. +(under Related) has to plan for a lite-07 without hop lists. Only +[Routes and announces](/quest/m1/cluster-routing/routes.md) gates the cut, +not the rest of the cluster-routing line (decided 2026-10-08). + +Decided 2026-10-08: Restart and AUTH join Required, since both change the +lite-07 wire. SUBSCRIBE_OK carrying live media time was dropped: no reader +was named, and `set_live` covers it. The cut: -- Every quest under Required has landed, including the cache bug that only - bites once lite-07 ships. +- Every quest under Required has landed. - The identifier becomes `moq-lite-07` in `rs/moq-net` and `js/net`, in the draft (whose text already names the rename), and at every site spelling the wip ALPN: `rs/moq-tokio/src/connect.rs` and `listen.rs`, @@ -67,11 +72,12 @@ is published; older versions are unchanged. ## Required -- [Cluster routing](/quest/m1/cluster-routing/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone -- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07 restores SUBSCRIBE_DROP in place of `Stream Count` - [lite-07 Live flag](/quest/m1/lite-live.md) - SUBSCRIBE carries `Live` apart from its floor +- [Restart](/quest/m0/broadcast-epoch/restart.md) - lite-07 carries the `Restart` announce +- [AUTH on the wip lite version](/quest/m1/auth/wip-version.md) - lite-07 carries the Auth Stream and UNAUTHORIZED +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07 restores SUBSCRIBE_DROP in place of `Stream Count` - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS -- [Live media time](/quest/m1/subscribe-live-time.md) - SUBSCRIBE_OK carries the publisher's live media time - [Untimed lite-07](/quest/m1/lite-untimed.md) - an untimed track crosses the wire untimed - [One route cost](/quest/m1/route-cost.md) - ANNOUNCE carries one cost - [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - TRACK_INFO carries the epoch of the instance that answered diff --git a/quest/m1/mkv-lacing.md b/quest/m1/mkv-lacing.md index cc32fb00c2f..3fc4da89743 100644 --- a/quest/m1/mkv-lacing.md +++ b/quest/m1/mkv-lacing.md @@ -25,4 +25,4 @@ Public API: none. Wire: none. ## Related -- [MKV export delay](/quest/m1/mkv-export-delay.md) - the export side of the same container +- [Export delay](/quest/m1/flv-export-delay.md) - the export side of the same container diff --git a/quest/m1/obs-moq-video/README.md b/quest/m1/obs-moq-video/README.md index 0cab6487df0..cf6c4e7a209 100644 --- a/quest/m1/obs-moq-video/README.md +++ b/quest/m1/obs-moq-video/README.md @@ -12,7 +12,7 @@ Attempt GPU delivery immediately on macOS decode; other platforms keep the CPU p Initial video decoding covers H.264, HEVC, and AV1 where moq-video has an available backend. Unsupported codecs produce an actionable error; do not retain an FFmpeg fallback. VP8/VP9 return through their own follow-up quest. Audio playback covers Opus, AAC-LC, and PCM. -Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. The line PR must call out the video default changes #4099 made: NVENC P4 to P1, and openh264 medium to low complexity. Known gap: VAAPI reports Low latency whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation and VideoToolbox are owned by [Windows GPU input](/quest/m2/obs-windows.md) and [macOS GPU input](/quest/m2/obs-macos.md). +Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. The line PR must call out the video default changes #4099 made: NVENC P4 to P1, and openh264 medium to low complexity. Known gap: VAAPI reports Low latency whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation is owned by [Windows GPU input](/quest/m2/obs-windows.md), and VideoToolbox by [VideoToolbox presets](/quest/m1/videotoolbox-presets.md), split out of macOS GPU input (decided 2026-10-08) since the mapping needs no GPU input. The quests separate portable decoding, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094); a surface decode exposes the platform surface as a borrowed view, which each platform GPU quest extends to its own surface type. diff --git a/quest/m1/obs-moq-video/adapter.md b/quest/m1/obs-moq-video/adapter.md index 5a3ed6231ed..d6e858c1641 100644 --- a/quest/m1/obs-moq-video/adapter.md +++ b/quest/m1/obs-moq-video/adapter.md @@ -7,7 +7,7 @@ One opt-in Use MoQ encoders choice publishes OBS video and audio through moq-vid ## Plan - Register an internal OBS video encoder, backed by `moq_video::encode::Sink`. Retain `MoQOutput::EncodedPacket` and existing catalog handling. Do not replace the output with raw publication: OBS's encoded-output flag is output-wide, and bypassing it would duplicate A/V integration. -- Add a clean codec-only moq-ffi encoder type with owned handles and packet draining, extending shared primitives from the audio adapter where appropriate. Avoid backend internals and caller cleanup callbacks. The existing raw-video publishing API couples encoding to publication and is not the packet adapter. +- Drive the codec-only `video.Encoder` that [Codecs](/quest/m1/ffi-shape/codec.md) adds, rather than adding an encoder type here (decided 2026-10-06 on #4519: Codecs owns `video.Encoder` beside the broadcast-bound `video.Producer`). It needs owned handles and packet draining, with no backend internals or caller cleanup callbacks; extend Codecs where it lacks them. `video.Producer` couples encoding to publication and is not the packet adapter. - Start with H.264 by default and HEVC where supported. Keep reordering disabled; resolve Annex-B headers/decoder configuration, DTS/PTS and drain semantics explicitly, since Rust encoded output carries only timestamp, payload, and keyframe flag. Do not advertise unsupported AV1 encoding. - Use the shared Low latency, Balanced, and Quality presets with bitrate separate, defaulting to Balanced: `moq_video::encode::Preset` in, `Applied` (the preset and controls that took effect) out for Stats. Neither reaches moq-ffi yet, so carry both through it and its bindings. Expose a single Use MoQ encoders option only once audio and video adapters both work. Retain the existing OBS encoder selection as an explicit alternative; do not silently switch back to OBS codecs after a MoQ codec failure. - Establish bounded submission/packet queues, explicit raw-frame drop behavior, thread confinement, cancellation, late completion, device loss, resize and color metadata. Never block OBS's graphics thread on network backpressure. The CPU path is a correctness/fallback baseline; platform quests establish accelerated input. diff --git a/quest/m1/obs-moq-video/audio-publish.md b/quest/m1/obs-moq-video/audio-publish.md index 71400f200a2..44e8b46009f 100644 --- a/quest/m1/obs-moq-video/audio-publish.md +++ b/quest/m1/obs-moq-video/audio-publish.md @@ -6,7 +6,7 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving ## Plan -- Expose `moq_audio::encode::Encoder` through a codec-only moq-ffi type with owned encoder/packet handles, so every binding gets it. The existing raw audio producer combines encoding and publication and must not create a second publication alongside the OBS encoded output. Reuse frame sizing, bitrate updates, catalog configuration, and finish/padding behavior. +- Drive `audio.Encoder`, the codec-only moq-ffi type for `moq_audio::encode::Encoder` that [Codecs](/quest/m1/ffi-shape/codec.md) adds with owned encoder/packet handles, so every binding gets it (decided 2026-10-06 on #4519). `audio.Producer` combines encoding and publication and must not create a second publication alongside the OBS encoded output. Reuse frame sizing, bitrate updates, catalog configuration, and finish/padding behavior. - Implement the OBS audio encoder interface, including fixed input frame size, mono/stereo PCM conversion, timestamps, codec headers, final padding, and packet release. Ask OBS for the input layout the encoder supports; moq-audio does not implement arbitrary channel remapping. Keep capture/mixing/device ownership in OBS. - Publish Opus initially. `encode::Codec::Aac` lets the adapter offer AAC where a platform encoder exists; until then leave AAC with the existing OBS mode and defer PCM publishing UI, since the output currently declares AAC/Opus. Correct stale binding documentation that describes the raw codec parser as Opus-only if that API is touched. - Apply the shared presets (`moq_audio::encode::Preset` via `Settings::with_preset`, not yet in moq-ffi) and independent audio bitrate. Test 10/20 ms packetization, frame-size changes at stream boundaries, partial final frames, silence, reconnect, saturation, and stop with pending output. Verify decoded audio and A/V timestamps with a real subscriber. diff --git a/quest/m1/obs-moq-video/source.md b/quest/m1/obs-moq-video/source.md index 0fce5ea5c19..79695a87239 100644 --- a/quest/m1/obs-moq-video/source.md +++ b/quest/m1/obs-moq-video/source.md @@ -14,9 +14,12 @@ The MoQ source loads and plays supported video without FFmpeg's video libraries - Remove the video FFmpeg includes and swscale linkage. Audio still decodes through libavcodec until the audio playback quest replaces it, so whichever of the two lands second removes the remaining FFmpeg includes, CMake discovery/linkage, unit stubs, compile recipe requirements, and the unused swresample linkage. Update OBS build/install docs and `doc/lib/cpp` together. libobs/Qt and native OS/GPU dependencies remain. - Validate new code with decoded pixels and moving timestamps, GPU copy/readback traces, and p50/p95 decode-to-presentation delay. Exercise CPU fallback, unsupported codec, GPU import failure, device loss, repeated start/stop, rendition change, and delayed terminal completion. Verify no SWScale imports (and no AVCodec/AVUtil/SWResample imports once audio playback has landed) using platform binary inspection. Load the artifact against the oldest supported OBS release and current stable release, using the repo's supported version policy at implementation time. +Decided 2026-10-08: [Codecs](/quest/m1/ffi-shape/codec.md) lands first, so the source consumes the `video` decoder once instead of the decoder on `BroadcastConsumer` it removes. + ## Required - [C++ through moq-ffi](/quest/m1/cpp/README.md) - the plugin is on the generated C++ before decode changes +- [Codecs](/quest/m1/ffi-shape/codec.md) - the video decoder lands once, in the `video` namespace ## Related diff --git a/quest/m1/open-gop-leading-pictures.md b/quest/m1/open-gop-leading-pictures.md index 441c921cf87..e6fb70d2bee 100644 --- a/quest/m1/open-gop-leading-pictures.md +++ b/quest/m1/open-gop-leading-pictures.md @@ -49,9 +49,11 @@ decode, and the JS test should drive the software decoder. into a later GOP lacks its references just like a cold join. Every continuous group is passed through untouched. - The same rule in the Rust decode path (`moq-video` decode consumers), so - native playback and the transcoder tune in the same way. + native playback and the transcoder tune in the same way, keyed on the + non-continuous signal from [Rust non-continuous + signal](/quest/m1/rust-continuous.md). - The same rule in `moq export ts`. Decided (2026-10-01): the fixed-delay - export (#4645) still sends a join's orphaned leading pictures, so 3 of 500 + export still sends a join's orphaned leading pictures, so 3 of 500 frames on the open-GOP fixture decode after they present (`dts-before-pts`). Trim them at tune-in from the same signal, on the export's first group only, and make `just test ts --open-gop` pass under @@ -62,20 +64,19 @@ decode, and the JS test should drive the software decoder. every picture today; rewrite them to expect the first group's orphaned leading pictures trimmed and every later group's kept. Rejected: dropping this bullet and keeping the grader. -- This quest owns the Rust non-continuous signal, which audio warmup and - consumer warmup reuse rather than each adding one. Today - `moq_mux::container::Consumer::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. - Add the equivalent of JS `continuous`: false on the first frame after the - subscribe and after every bump, true otherwise. It changes the moq-mux - consumer API. - Tests: a synthetic group with a keyframe followed by two earlier-stamped deltas is trimmed on the first group and kept on the second; and a viewer that plays continuously, then latency-skips into a later open GOP, has that group's leading pictures trimmed too, so an implementation that only trims the initial group fails. Both cases in both languages. +Decided 2026-10-08: the Rust non-continuous signal is its own quest, so +audio warmup and consumer warmup don't wait on this one. + +## Required + +- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust decode path keys the trim on it + ## Related - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - the `recovery_frame_cnt > 0` case this rule does not cover diff --git a/quest/m1/origin-front-parks.md b/quest/m1/origin-front-parks.md index f7266e7747d..0f5f31627a6 100644 --- a/quest/m1/origin-front-parks.md +++ b/quest/m1/origin-front-parks.md @@ -20,10 +20,11 @@ parking, while `routed_broadcast` stays registered until its route completes. The front ends only once every parked requester has been handled, so one requester's disposition never ends another's wait. -Worth confirming before building it: that the retry loop costs something. A -benchmark swept over requesters and route-table churn would show whether the -re-mint is a real slope or noise, and it is the same benchmark that would -show the replacement is cheaper. +Decided 2026-10-08: benchmark first. Land a benchmark swept over requesters +and route-table churn, and build the parked front only if the re-mint shows +as a real slope; the same benchmark then shows the replacement is cheaper. A +measured no-win deletes this quest. The `origin/viewer_*` benches do not +cover the retry loop. The filtered front a peer session leaves behind, folded in here on 2026-10-05, moved to [Idle fronts](/quest/m0/idle-fronts.md) on 2026-10-07: @@ -33,7 +34,5 @@ Public API: no signature change expected. `routed_broadcast` and `request_broadcast` keep their contracts; only where the waiting happens changes. -Decided in the 2026-09-30 audit: this may move to m2 if that benchmark shows -the retry loop's re-mint is noise. Fronts are now keyed by effective exclusion -(`Horizon::effective`), so viewers share them; the `origin/viewer_*` benches -do not cover the retry loop. +Fronts are keyed by effective exclusion (`Horizon::effective`), so viewers +share them. diff --git a/quest/m1/papercuts-js.md b/quest/m1/papercuts-js.md index e079ab7a2f9..111cf5fcb1c 100644 --- a/quest/m1/papercuts-js.md +++ b/quest/m1/papercuts-js.md @@ -13,13 +13,13 @@ regression test that fails without it: ## Plan -- `js/net/src/ietf/object.ts` (around line 350) returns `new Frame()` with an +- `Frame.decode` in `js/net/src/ietf/object.ts` returns `new Frame()` with an undefined payload for status 0, and `subscriber.ts` breaks out of the subgroup on that. Rust delivers an empty object and continues (`rs/moq-net/src/ietf/subscriber.rs`), and the JS file's own TODO agrees. Only third-party publishers hit this, since Rust peers set the end bit. -- `js/watch/src/audio/decoder.ts` awaits `ring.wait` (around lines 462 and - 562) without racing the effect's abort. Mute freezes the playhead, so the +- `js/watch/src/audio/decoder.ts` awaits `ring.wait` (in `#runLegacyDecoder` + and `#runCmafDecoder`) without racing the effect's abort. Mute freezes the playhead, so the previous spawn never settles until something flushes the ring. Race it against the effect. - `js/watch/src/element.ts` and `js/publish/src/element.ts`: `new URL(bad)` @@ -28,9 +28,15 @@ regression test that fails without it: invalid value warns and falls back to the default, as `parseDelay` and `parseVisible` already do. +Decided 2026-10-08: [End of Group status](/quest/m0/ietf-end-of-group-status.md) +edits the same status branch in `Frame.decode`; it is m0 and lands first, so +this rebases onto it. + Public API: none. Wire: none. ## Related +- [End of Group status](/quest/m0/ietf-end-of-group-status.md) - the same `Frame.decode` status branch, landing first + - [Rust papercuts](/quest/m1/papercuts-rs.md) - the Rust half of the same audit - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - owns the audio ring and its backpressure diff --git a/quest/m1/papercuts-rs.md b/quest/m1/papercuts-rs.md index 159968b5efa..29c972286ff 100644 --- a/quest/m1/papercuts-rs.md +++ b/quest/m1/papercuts-rs.md @@ -2,16 +2,13 @@ ## Goal -Four small Rust fixes from the 2026-10-07 code audit, each with a regression +Two small Rust fixes from the 2026-10-07 code audit, each with a regression test that fails without it: - HTTP `/announced` and `/fetch` refusals count in the relay's refusal metrics, as QUIC, WebSocket, and io_uring refusals already do. - A replaced route whose newest group is `u64::MAX` keeps delivering that group from the old copy instead of being capped at group 0. -- A future draft version sends stream-reset `GOING_AWAY` as 0x4, not as an - internal error. -- A `UDP_GRO` cmsg of 0 cannot panic an io_uring worker. ## Plan @@ -19,27 +16,19 @@ test that fails without it: and `serve_fetch`) return the error with `?` and never call `cluster.refusals.record`. The missing-subscriber 401 in each handler is uncounted too. Record each refusal the way `websocket.rs` does. -- `rs/moq-net/src/model/resume.rs` (around line 267): `Position::after_group` +- `Copy::wire` in `rs/moq-net/src/model/resume.rs`: `Position::after_group` returns `None` for the last group, meaning "no end", and `unwrap_or_default()` turns that into position 0. `until` is `Option>`, and an inner `None` (replaced before any group) must still end at 0; only `after_group`'s overflow is unbounded. Reuse `let_go`'s `until.map_or(Some(0), |last| last.checked_add(1))` and test both cases. lite-07 varints can carry `u64::MAX`, so this is reachable from the wire. -- `rs/moq-net/src/ietf/error.rs`: `has_going_away` lists Draft18 through - Draft22 explicitly. Flip it to `!matches!(older drafts)` like - `has_too_far_behind` and `has_malformed_track` next to it, keeping Draft14 - through Draft17 excluded (0x4 is UNKNOWN_OBJECT_STATUS in 16 and 17), so a new draft - variant falls forward. This also changes `from_stream_code`; update its doc, - which says values a later draft may add stay `Unknown`. -- `rs/moq-uring/src/udp.rs`: `RecvMeta::parse` stores a stride of 0 as - `Some(0)`, and `Packet::segments` then calls `chunks_mut(0)`. Drop a zero - stride in the parser. Linux only emits `UDP_GRO` when `gso_size != 0`, so - this is defensive and lives in m1, not m0's peer-input hardening (decided - 2026-10-07). - -Public API: none. Wire: none (the `GOING_AWAY` change only affects drafts -that do not exist yet). + +Decided 2026-10-08: the `GOING_AWAY` fallback for future drafts and the +zero `UDP_GRO` stride were dropped. Neither is reachable today: no newer +draft exists, and Linux never emits a zero stride. + +Public API: none. Wire: none. ## Related diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index 726fc5be552..c6fb7633c2e 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -47,27 +47,30 @@ row per io_uring worker. Decided in the 2026-09-30 audit: io_uring is off by default and ships in no package, and none of the uring micro-opts is measured on noq. The unmeasured -ones moved out (3129, 3200, 3202, the open contract, and cache shard to m2; -3201 and 3204 to m3), and NAPI busy polling (3203), registered wait -arguments (3205), and the priority `set_track` wakes were dropped. Egress -requeue folded into Run to quiescence; egress keep-alive and owned decode -copies folded into Group cost. The benchmark noise estimate and the noq -re-profile come first, since every quest here accepts "within noise". Lock -profile and One enter per turn rank next: they produce the numbers that decide -the rest. +ones moved out (3200 to m2; 3129 with the open contract, 3201, 3202, and 3204 +to m3), and NAPI busy polling (3203), registered wait arguments (3205), and +the priority `set_track` wakes were dropped. Egress requeue folded into Run to +quiescence; egress keep-alive folded into Group cost. The benchmark noise +estimate comes first, since every quest here accepts "within noise". The +profiling recipe and One enter per turn rank next: they produce the numbers +that decide the rest. + +Decided 2026-10-08: the CPU and allocation profile merged into the profiling +recipe ([Relay profiling](/quest/m1/perf/lock-profile.md)), so the relay has +one recipe with capture modes; #3199 moved to m2 beside 3200, since it is an +equally unmeasured ring micro-opt; cache shard was deleted, since #5031's +profile shows no pool contention. ## Required - [Performance comparisons](/quest/m1/performance-comparisons.md) - the noise estimate every "within noise" verdict here depends on -- [Performance profiles](/quest/m1/performance-profiles.md) - the reproducible noq profile the quests below re-measure on -- [Lock profile](/quest/m1/perf/lock-profile.md) - a bpftrace recipe reports each worker's time blocked on locks, by stack, with no code in kio +- [Relay profiling](/quest/m1/perf/lock-profile.md) - one recipe captures lock wait by stack (first), CPU stacks, and heap profiles, with no code in kio - [kio channel contention](/quest/m1/perf/kio-channel-contention.md) - workers spend less time blocked on kio channel-state mutexes (up to 215% of worker CPU on chat at 16 tokio workers) - [One enter per turn](/quest/m1/perf/uring-one-enter.md) - a parking turn pays one io_uring_enter, submits flush deferred completions, and SQEs per enter is a counter - [Group cost](/quest/m1/perf/group-cost.md) - count and cut the allocations and time spent relaying one small group to one viewer - [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - a received packet's reply is staged in the same turn, under a pass and train budget that keeps the fairness rule - [Announce replay](/quest/m1/perf/announce-replay.md) - the initial announce set replays in linear time, so joins don't slow with the route count - [Demand aggregate](/quest/m1/perf/demand-aggregate.md) - a track subscribe, leave, or preference update no longer walks every reader of the track -- [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per chunk burst instead of per chunk +- [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per burst of whole frames instead of per frame - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - moq-uring: ~2.5% of relay CPU is vdso clock reads; the drive loop and its callers each re-read Instant::now() -- [#3199](/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup - [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - egress, stream send and receive, and datagram receive stop copying where the QUIC core already allows it, after the fork diff --git a/quest/m1/perf/group-cost.md b/quest/m1/perf/group-cost.md index d4a11ac4212..4d2fc3cf655 100644 --- a/quest/m1/perf/group-cost.md +++ b/quest/m1/perf/group-cost.md @@ -25,8 +25,10 @@ keeps that waiter and skips re-registering on lists that still hold it the next largest source from there. A measured no-win abandons the quest, per this line's rules. -Decided in the 2026-09-30 audit: two suspected per-group costs merged here -as candidates to measure, not separate quests. +Decided in the 2026-09-30 audit: suspected per-group costs merge here as +candidates to measure, not separate quests. Decided 2026-10-08: owned decode +copies are no longer a candidate; since #4437 `Decoder::string` copies once +and nothing else decodes an owned buffer. - Egress cache refresh: `group::Consumer::keep_alive` takes a state read guard and calls `Charge::refresh` between completed frame writes on both @@ -37,8 +39,3 @@ as candidates to measure, not separate quests. 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` - through `Buf::copy_to_bytes` then `to_vec`, and `String` consumes that - vector. Measure on the real reader input types (contiguous and chained) - before assuming a copy; keep the owned return types, bounds checks, and - UTF-8 validation. diff --git a/quest/m1/perf/ingest-batch.md b/quest/m1/perf/ingest-batch.md index 746e4d8da0e..3714694ee29 100644 --- a/quest/m1/perf/ingest-batch.md +++ b/quest/m1/perf/ingest-batch.md @@ -2,31 +2,35 @@ ## Goal -Relay ingest pays a full group mutex acquisition, a waiter-list wake fanout, -and a real clock read for every received QUIC chunk. Egress is already -amortized (the `Prefetch` refills eight frames under one lock and stamps the -charge and stats once per batch); ingest has no equivalent. Make a burst of -received chunks pay one lock, wake, and clock cycle. +Relay ingest pays two group lock acquisitions (`create_frame_owned`, then +`frame_commit`), a waiter-list wake, and a clock read for every received +frame. A frame's payload chunks are already amortized per poll, but a burst of +small whole frames is not. Egress is already amortized (the `Prefetch` +refills eight frames under one lock and stamps the charge and stats once per +batch). Make a burst of whole frames received in one poll turn pay one lock, +wake, and clock cycle. ## Plan Where the path stands: - Both wire ingests drain a frame's payload through - `coding::Reader::poll_read_frame` (rs/moq-net/src/coding/reader.rs:168). + `coding::Reader::poll_read_frame` (`rs/moq-net/src/coding/reader.rs`). The group lock, the charge clock read, and the waiter drain run once at the - poll boundary, or once per `WAKE_BUDGET` bytes (reader.rs:33, since - transport readiness alone is not a bound on time), and once at - `frame_commit` (rs/moq-net/src/model/group.rs:715), which restarts the - retention clock so the deferral can never lose a stamp. + poll boundary, or once per `WAKE_BUDGET` bytes (since transport readiness + alone is not a bound on time), and once at `frame_commit` + (`rs/moq-net/src/model/group.rs`), which restarts the retention clock so + the deferral can never lose a stamp. - The batched machinery exists but is unused here: - `group::Producer::write_frames` (group.rs:534) takes a `frame::Buffer` and - pays one lock per batch, while the ingest path streams chunks through - `create_frame_owned` (group.rs:646) instead. `rs/moq-net/benches/group.rs` + `group::Producer::write_frames` takes a `frame::Buffer` and pays one lock + per batch, while the ingest path (lite's `FrameIngest`, the IETF + subscriber's object loop) creates each frame through `create_frame_owned` + instead. The `group_write_frames` bench in `rs/moq-net/benches/group.rs` compares the two as `single` against `batch32`, a `frame::Buffer::<32>` - flushed through `write_frames` (:71-73); take the before number from there. + flushed through `write_frames`; take the before number from there. -Remaining: +Remaining (decided 2026-10-08: the Goal is per frame, since per-chunk costs +are already amortized): - Where whole frames are available in one poll turn, feed them through `write_frames`/`frame::Buffer` instead of frame-at-a-time creation. This is diff --git a/quest/m1/perf/kio-channel-contention.md b/quest/m1/perf/kio-channel-contention.md index 473431bc556..f6ff3c1e7a6 100644 --- a/quest/m1/perf/kio-channel-contention.md +++ b/quest/m1/perf/kio-channel-contention.md @@ -28,17 +28,17 @@ across every thread (ramp included, unlike the table's steady window): - `Consumer::read` (`rs/kio/src/consumer.rs:131`): 11.7s, 1,079,139 contended acquires `kio::Lock` is a plain `std::sync::Mutex`, and every poll takes it: the -closure check, the closed check, and the waiter registration. The cache pool -line ([Cache shard](/quest/m2/cache-shard.md)) is not among the hot sites. +closure check, the closed check, and the waiter registration. The cache +pool's shared counters are not among the hot sites. `Shared::lock` (`rs/kio/src/shared.rs:47`) shows up too, but stays flat with the worker count. Decided (maintainer, 2026-10-07): - Decide the fix from the stacks. First run the - [lock profile](/quest/m1/perf/lock-profile.md) to name the contended - channels (track, group, broadcast, origin state) from the callers above - these sites. Then bring the options back with numbers. Candidates: a + [profiling recipe](/quest/m1/perf/lock-profile.md)'s lock-wait mode to + name the contended channels (track, group, broadcast, origin state) from + the callers above these sites. Then bring the options back with numbers. Candidates: a lock-free read path (a version counter lets poll and read skip the mutex when nothing changed); shrinking the closures that run under the lock; restructuring the hottest channel. Submitting staged io_uring SQEs before a @@ -48,8 +48,4 @@ Decided (maintainer, 2026-10-07): ## Required -- [Lock profile](/quest/m1/perf/lock-profile.md) - the bpftrace recipe that names the contended channels and measures before and after - -## Related - -- [Cache shard](/quest/m2/cache-shard.md) - stays parked: the pool line is not where the wait is +- [Relay profiling](/quest/m1/perf/lock-profile.md) - the recipe's lock-wait mode names the contended channels and measures before and after diff --git a/quest/m1/perf/lock-profile.md b/quest/m1/perf/lock-profile.md index d3891289c49..03da0a80415 100644 --- a/quest/m1/perf/lock-profile.md +++ b/quest/m1/perf/lock-profile.md @@ -1,44 +1,89 @@ -# [S] Profile lock wait off-CPU +# [M] One relay profiling recipe ## Goal -A `just` recipe runs a bench shape under bpftrace and reports, per relay -worker thread (`moq-uring-N`, `moq-quic-N`), the time spent blocked in futex -waits and the user stacks that blocked, as a share of that thread's CPU. Lock -wait becomes a number anyone can reproduce without code in `kio`. +One local `just` recipe runs a bench shape and captures a relay profile in +one of three modes, with enough metadata to reproduce it and to tell relay +cost from load-generator cost: + +- **Lock wait** (first): bpftrace reports, per relay worker thread + (`moq-uring-N`, `moq-quic-N`), the time spent blocked in futex waits and the + user stacks that blocked, as a share of that thread's CPU. Lock wait becomes + a number anyone can reproduce without code in `kio`. +- **CPU**: symbolized CPU stacks, with perf on Linux and samply on macOS. +- **Heap**: jemalloc heap snapshots and allocation churn. + +Profiling is opt-in and costs nothing when disabled. ## Plan -Decided (maintainer, 2026-10-07), after closing #5031, which timed every -contended `kio::Lock` acquire in code and added public API in three crates -plus five Prometheus families: +Decided 2026-10-08: the reproducible CPU and allocation profile quest merged +here, so the relay has one profiling recipe with capture modes rather than +two launchers. The lock-wait mode lands first, since +[kio channel contention](/quest/m1/perf/kio-channel-contention.md) waits on +it; the CPU and heap modes follow in the same recipe. + +Shared by every mode: + +- Reuse `bench/run.sh`'s lifecycle (builds, relay PID, workload, host + samples) rather than adding a second launcher. Select workload, duration, + and mode through one configuration. +- Build the relay with `[profile.profiling]` and + `RUSTFLAGS="-C force-frame-pointers=yes"`: the release build `bench/run.sh` + uses has neither debug info nor frame pointers, so stacks would stop at the + libc frame. +- Capture the relay process and all its workers, never the load generator. + Start after readiness and mark a steady window. Keep an uninstrumented + control run to quantify profiler overhead. +- Record the revision and dirty diff, build flags, features, compiler, + OS/kernel, CPU, runtime, affinity, allocator, and resolved workload with the + result, in a caller-selected artifact directory. On cancellation or a failed + capture, stop every owned child and keep the diagnostics. +- Local only, documented next to `just bench` and `just bench-runtime`. Not + in CI, since the modes need privileges. Probe tool and permission support + and refuse an unsupported capture clearly; never substitute wall-clock + timing for CPU samples. + +Lock wait (decided by the maintainer 2026-10-07, after closing #5031, which +timed every contended `kio::Lock` acquire in code and added public API in +three crates plus five Prometheus families): - Measure from outside the process: bpftrace on the futex syscalls of the relay's worker threads, aggregated by thread name and user stack. No instrumentation in `kio`, no new public API, no metrics. -- Build the relay with `[profile.profiling]` and - `RUSTFLAGS="-C force-frame-pointers=yes"`: the release build `bench/run.sh` - uses has neither debug info nor frame pointers, so `ustack` would stop at - the libc futex frame. `Consumer::poll` is generic and inlined, and - bpftrace doesn't expand inline frames, so the stacks name its callers. +- `Consumer::poll` is generic and inlined, and bpftrace doesn't expand inline + frames, so the stacks name its callers. - Count only stacks under the std mutex's contended path (`kio::Lock` is a `std::sync::Mutex`): futex waits also include allocator, condvar, and tokio waits, and a contended acquire that resolves while spinning never reaches the futex. - Add bpftrace to the Nix dev shell for Linux only (`lib.optionals stdenv.isLinux`), since the shell also builds for - `aarch64-darwin`. The recipe needs sudo (or `CAP_BPF`) and says so. -- Local only, documented next to the existing bench recipes (`just bench`, - `just bench-runtime`). Not in CI, since it needs privileges. + `aarch64-darwin`. The mode needs sudo (or `CAP_BPF`) and says so. - Shapes and worker counts follow #5031: fanout (`bench/workloads/fanout.toml`) - and chat (`rs/moq-bench/config/chat.toml`) at 1, 4, and 16 workers, with a - steady window after startup. Wait is off-CPU, so a thread's share can - exceed 1 when it blocks longer than it runs. + and chat (`rs/moq-bench/config/chat.toml`) at 1, 4, and 16 workers. Wait is + off-CPU, so a thread's share can exceed 1 when it blocks longer than it runs. +- Check that it roughly reproduces #5031's wait time (see kio channel + contention), not its contended-acquire counts, and that its stacks lead to + the same call sites. + +CPU and heap: -Check that it roughly reproduces #5031's wait time (see -[kio channel contention](/quest/m1/perf/kio-channel-contention.md)), not its -contended-acquire counts, and that its stacks lead to the same call sites. +- CPU stacks with perf on Linux and a maintained profiler such as + [samply](https://github.com/mstange/samply) on macOS; pin any newly + installed tool. +- Heap snapshots through `rs/moq-tokio/src/jemalloc.rs`'s existing + on-demand dumps, before load, at steady state, and after teardown. Include + allocation churn as well as retained bytes, since snapshots alone cannot + establish an allocation rate. Never send a profiling signal before + verifying the listener is active. +- Validate on one Linux host and macOS: a smoke capture holds resolved MoQ + frames, the intended PID and window, and nonempty samples. Exercise an + unavailable profiler and an interrupted run without leaving children + behind. ## Related - [kio channel contention](/quest/m1/perf/kio-channel-contention.md) - requires this for its before and after +- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - shares the workload lifecycle and artifact conventions +- [Release profile](/quest/m1/release-profile.md) - also changes the profile `[profile.profiling]` inherits; land one, then rebase the other diff --git a/quest/m1/perf/uring-one-enter.md b/quest/m1/perf/uring-one-enter.md index 9d8eb614424..a771b268a6e 100644 --- a/quest/m1/perf/uring-one-enter.md +++ b/quest/m1/perf/uring-one-enter.md @@ -11,27 +11,24 @@ a ratio of two totals. ## Plan Branch from main. The loop in `Worker::block_on` -(rs/moq-uring/src/worker.rs:164-187) runs one task pass, then `pump` -(`submit()` at worker.rs:250, then reap and dispatch), then `maybe_park`, -whose enter (`submit_and_wait(1)` or a timed `enter(to_submit, 1, -GETEVENTS|EXT_ARG|ABS_TIMER)`, worker.rs:400-417) carries whatever the SQ -holds. When nothing is `NOTIFIED`, the turn pays both. tokio-uring, monoio, +(`rs/moq-uring/src/worker.rs`) runs one task pass, then `pump` (`submit`, +then reap and dispatch), then `maybe_park`, whose enter +(`submit_and_wait(1)` or a timed `enter(to_submit, 1, +GETEVENTS|EXT_ARG|ABS_TIMER)`) carries whatever the SQ holds. When nothing is `NOTIFIED`, the turn pays both. tokio-uring, monoio, glommio, and compio all fold the tick's submit into the park enter. - `pump` submits only when the turn will not park: when the unpark word is `NOTIFIED`, or when the SQ is full enough that the park enter could not carry it. Otherwise the staged SQEs ride `maybe_park`'s enter. Reaping before the park stays as it is; it needs no enter. -- `DEFER_TASKRUN` (set at worker.rs:104-109) runs deferred completion work - only on an enter carrying `GETEVENTS`. The `io-uring` crate's `submit()` - adds that flag only when waiting or on CQ overflow - (io-uring-0.7.14/src/submit.rs:195) and never consults - `IORING_SQ_TASKRUN`, which liburing does. Reproduce first: a worker that - self-wakes every turn (a deep egress backlog does) and a completion that - arrives mid-burst; measure how many turns pass before it dispatches. Then - set `GETEVENTS` on any submit while `SubmissionQueue::taskrun()` reports - work, and add the regression test. The inline submit in `Shared::push` - (rs/moq-uring/src/shared.rs:111) and `submit_teardown` get the same flag. +- `DEFER_TASKRUN` (set in `Worker::new`) runs deferred completion work + only on an enter carrying `GETEVENTS`. The locked `io-uring` 0.7.15's + `Submitter::submit_and_wait` already adds that flag while + `IORING_SQ_TASKRUN` is set, as liburing does; 0.7.14, which the workspace + still allows, does not. Raise the workspace floor to 0.7.15 and pin it with + a regression test: a worker that self-wakes every turn (a deep egress + backlog does) dispatches a completion that arrives mid-burst within one + turn. A submit this quest folds into the park enter must keep the flag. - Metrics (rs/moq-uring/src/metrics.rs): `turns`, `sq_full_enters`, and a fixed-bucket histogram of SQEs per enter and CQEs per enter, one row per worker. `enters` stays for the ratio the docs already describe. @@ -44,7 +41,7 @@ to edit the driver moves to a follow-up after the fork. Acceptance: enters per turn on the chat and fanout shapes via `just bench BASE` on Linux and the new counters; the deferred-completion regression -fails without the flag. Latency must not regress. +fails on io-uring 0.7.14. Latency must not regress. ## Related diff --git a/quest/m1/performance-comparisons.md b/quest/m1/performance-comparisons.md index e2264a79680..95276d422b6 100644 --- a/quest/m1/performance-comparisons.md +++ b/quest/m1/performance-comparisons.md @@ -8,7 +8,7 @@ estimate and preserved evidence, so a small reported speedup can be evaluated. ## Plan `bench/run.sh --runtime` already repeats rounds (`MOQ_BENCH_RUNTIME_ROUNDS`, -default 3) and reports the median (`bench/run.sh:15`, `:322`), but the +default 3) and reports the median (`aggregate_runtime` in `bench/run.sh`), but the `just bench BASE` comparison still runs each relay workload once as base then current, without alternating execution order. `cleanup` deletes the run directory, including Criterion estimates, load/host JSONL, relay logs, and @@ -42,4 +42,4 @@ rather than creating another benchmark runner. ## Related - [Mergeable bench buckets](/quest/m1/bench-buckets.md) - owns histogram/window semantics -- [Relay profiling](/quest/m1/performance-profiles.md) - shares workload and artifact conventions +- [Relay profiling](/quest/m1/perf/lock-profile.md) - shares workload and artifact conventions diff --git a/quest/m1/pipeline-fetch-info.md b/quest/m1/pipeline-fetch-info.md index 28eeb54f200..0b81990e530 100644 --- a/quest/m1/pipeline-fetch-info.md +++ b/quest/m1/pipeline-fetch-info.md @@ -10,7 +10,9 @@ and passes the origin's consistency check. ## Plan Decided 2026-10-07, while landing #4974 (fetch-only IETF demand), which keeps -a sequential TRACK_STATUS before the first FETCH. Start after #4974 lands. +a sequential TRACK_STATUS before the first FETCH. Decided 2026-10-08: it +Requires [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) (#4974), +since that adds the TRACK_STATUS this pipelines. Why the round trip exists (facts, 2026-10-07): nothing in a FETCH request needs the info. Two serial gates do: @@ -47,3 +49,7 @@ released before its route's info passes. Measure the first-fetch latency before and after. Public API: none. Wire: none (ordering only). + +## Required + +- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - adds the sequential TRACK_STATUS before the first FETCH that this pipelines diff --git a/quest/m1/publish-audio-channel-count.md b/quest/m1/publish-audio-channel-count.md index 377b200eb1d..eb97455981c 100644 --- a/quest/m1/publish-audio-channel-count.md +++ b/quest/m1/publish-audio-channel-count.md @@ -15,11 +15,11 @@ decide. ## Plan -`js/publish/src/audio/capture.ts:245` sets +`js/publish/src/audio/capture.ts` sets `channelCountMode: requestedChannels !== undefined ? "explicit" : "max"`, so supplying `channelCount` is what puts the AudioWorklet behind a forced Web Audio downmix. Omitting it does not always take the `"max"` path: -`requestedChannels` (`capture.ts:183`) falls back to `requestedChannelCount`, +`requestedChannels` falls back to `requestedChannelCount(source.track)`, so an applied `getUserMedia` channelCount constraint forces `"explicit"` too. Account for that path when isolating the cause. @@ -38,13 +38,14 @@ running at 48 kHz: What is not established, and should be first: - The two overrides were removed together, so `channelCount` is implicated by - reading line 178, not by an isolated run. Re-run with `sampleRate` alone and - with `channelCount` alone before believing the attribution. + reading the `channelCountMode` choice, not by an isolated run. Re-run with + `sampleRate` alone and with `channelCount` alone before believing the + attribution. - The mechanism. A forced downmix starving or stalling the worklet is the obvious guess and is not evidence. - Whether a `getUserMedia` microphone track shows it, or only a destination-node track, whose channel count Web Audio reports as 2 by - default. `requestedChannelCount` (`capture.ts:318`) exists for the macOS + default. `requestedChannelCount` exists for the macOS mono-mic misreport, so that path has a real caller and cannot simply lose the override. diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index 0d1b291d8dd..5600d632d6c 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -45,6 +45,10 @@ and prefix tracks rather than the per-path `publisher.json` and Rejected: #4133 first, which would make stats-split carry the lag histogram and dropped counters across. +Decided (2026-10-08): the egress histogram is its own quest, +[viewer lag histogram](/quest/m1/qos/lag-histogram.md), since every other +child reads it and it exists only on the line branch. + Decided (2026-09-28): the line's moq-stats changes break the published crate. Client stats left the line (2026-09-29) when media stats moved out of moq-stats onto hang tracks, which are additive @@ -52,9 +56,9 @@ on `main`. ## Required -- [Lag across a splice](/quest/m1/qos/lag-splice.md) - a route switch - neither loses pending lag weight nor keeps weighing a segment replaced - before its first frame; the line does not land until it is fixed +- [Viewer lag histogram](/quest/m1/qos/lag-histogram.md) - the egress `lag` + histogram and `dropped` counters land on stats-split's totals and prefix + tracks - [Lag dashboard](/quest/m1/qos/lag-dashboard.md) - the demo stats dashboard shows viewer lag percentiles and dropped media - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - per diff --git a/quest/m1/qos/lag-dashboard.md b/quest/m1/qos/lag-dashboard.md index ebc6b92755a..03cd7906ca0 100644 --- a/quest/m1/qos/lag-dashboard.md +++ b/quest/m1/qos/lag-dashboard.md @@ -12,8 +12,9 @@ and per node like the existing counters. - Read both from [stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md), which lands first and retires the `publisher.json` rows they sit on today (decided in the - 2026-10-06 audit); #4133 rebases them onto the egress side of its per-group - totals and prefix tracks. `lag` is a cumulative byte count per bucket keyed + 2026-10-06 audit); [viewer lag histogram](/quest/m1/qos/lag-histogram.md) + lands them on the egress side of its per-group totals and prefix tracks + (decided 2026-10-08). `lag` is a cumulative byte count per bucket keyed by its upper edge (`"50ms"` to `"5s"`, then `"inf"`, empty buckets omitted); `dropped` is `{ duration, bytes, groups }` with the duration in fractional milliseconds. `doc/concept/stats.md` documents them. Diff two @@ -33,4 +34,5 @@ Public API: none. Wire: none. ## Required +- [Viewer lag histogram](/quest/m1/qos/lag-histogram.md) - the `lag` histogram and `dropped` counters the dashboard reads - [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the totals and prefix tracks the dashboard reads lag from diff --git a/quest/m1/qos/lag-histogram.md b/quest/m1/qos/lag-histogram.md new file mode 100644 index 00000000000..1674ceebb4d --- /dev/null +++ b/quest/m1/qos/lag-histogram.md @@ -0,0 +1,35 @@ +# [M] Viewer lag histogram + +## Goal + +The relay's `moq-stats` egress side reports, per broadcast, how far behind +its viewers are according to what the network has acknowledged: a +byte-weighted cumulative `lag` histogram and `dropped` counters (duration, +bytes, and groups dropped before they were acknowledged), on the totals and +prefix tracks of [stats totals and prefix +tracks](/quest/m0/broadcast-epoch/stats-split.md). A spliced subscription +stays exact across a route switch, and a closing subscription records its +last partial interval. + +## Plan + +Decided 2026-10-08: split out of the QoS line so the dashboard and publisher +timeliness can require a histogram that exists on `main`. The implementation +already lives on the line branch +([#4133](https://github.com/moq-dev/moq/pull/4133)): the sampler (#4298, +`rs/moq-net/src/stats.rs`), the splice fixes (#5009), and the final sample +(#4451). This quest lands it on `main` once stats-split has, rebased from the +per-path `publisher.json` and `subscriber.json` map rows it writes today onto +stats-split's totals and prefix tracks. + +Keep the histogram contract the dashboard reads: buckets keyed by upper edge +(`"50ms"` to `"5s"`, then `"inf"`, empty buckets omitted), cumulative and +monotonic so readers diff two samples and sum nodes bucket by bucket. Update +`doc/concept/stats.md` and the stats section of `doc/bin/relay/config.md`. + +Public API: breaking in `moq-stats`, as the line already decided. Wire: the +stats JSON gains the egress fields. + +## Required + +- [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the totals and prefix tracks the histogram lands on diff --git a/quest/m1/qos/publisher-timeliness.md b/quest/m1/qos/publisher-timeliness.md index 5760c94c39d..c1220b6d317 100644 --- a/quest/m1/qos/publisher-timeliness.md +++ b/quest/m1/qos/publisher-timeliness.md @@ -10,8 +10,9 @@ cooperation. ## Plan -This is the ingress mirror of the egress `lag` histogram (#4298, on the QoS -line) and needs no acknowledgments: the relay is the receiver, and a frame is measured +This is the ingress mirror of the egress `lag` histogram ([viewer lag +histogram](/quest/m1/qos/lag-histogram.md), which lands first so this reuses +its histogram type, decided 2026-10-08) and needs no acknowledgments: the relay is the receiver, and a frame is measured when its last byte arrives, because a partial frame is not useful. Frame timestamps are relative and jittered with no epoch, so measure each @@ -38,12 +39,12 @@ regressions: B-frame reordering makes presentation timestamps non-monotonic inside a group, and that is not a broken timeline. Sample where the relay completes a frame: the moq-lite subscriber's -`run_group` in `rs/moq-net/src/lite/subscriber.rs` (which already decodes the -zigzag timestamp delta) and the IETF subscriber's object path. Leave untimed -tracks out of the histogram rather than report a fiction: today pre-lite-05 -peers without a timescale are stamped with `Timestamp::now()` on arrival, -which would read as perfectly on time, and after the untimed model -([#4822](https://github.com/moq-dev/moq/pull/4822)) they arrive untimed. Update the stats section of `doc/bin/relay/config.md`. +`FrameIngest` in `rs/moq-net/src/lite/subscriber.rs` (which already decodes +the zigzag timestamp delta) and the IETF subscriber's object path. Leave +untimed tracks out of the histogram: since the untimed model +([#4822](https://github.com/moq-dev/moq/pull/4822)) pre-lite-05 frames arrive +untimed rather than stamped on arrival. Update the stats section of +`doc/bin/relay/config.md`. Tests: a paced publisher lands in the lowest bucket; publishers whose clocks run 100 ppm slow and 100 ppm fast both stay in the lowest bucket over a @@ -54,6 +55,7 @@ excluded. ## Required +- [Viewer lag histogram](/quest/m1/qos/lag-histogram.md) - the egress histogram whose type and edges this reuses - [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the totals and prefix tracks the drift histogram lands on ## Related diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index a1d386b7ed3..324ee903c5b 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -10,9 +10,9 @@ BBR correctness, reliable stream resets, hierarchical stream scheduling with per-broadcast fairness, wider limits for relay peers, and endpoint sharding. Per-stream acknowledgment progress, per-stream deadlines, qmux on the shared stream state machine, and the experiments (the egress profile, media probing, -L4S, careful resume, deadline keep-alive) live in [m2](/quest/m2/README.md); -GCC with receive timestamps lives in [m3](/quest/m3/README.md). None of them -gate this line. +ECN measurement, deadline keep-alive) live in [m2](/quest/m2/README.md); L4S, +careful resume, and a receive-timestamps spike toward GCC live in +[m3](/quest/m3/README.md). None of them gate this line. ## Plan @@ -47,7 +47,9 @@ This is a transport API change, not a MoQ wire change. Decided in the 2026-09-30 audit: deadlines, qmux, BBR loss parity, ECN measurement, ACK progress, and the ACK hook moved to m2, since no m1 quest -consumes them. +consumes them. Decided 2026-10-08: L4S and careful resume moved on to m3, +and GCC shrank to a receive-timestamps spike, since none has a consumer. +The BBR app-limited fixes land in `moq-quic` without waiting for the switch. ## Required @@ -73,5 +75,5 @@ consumes them. - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer -- [GCC egress experiment](/quest/m3/quic-gcc.md) - receive timestamps and a measured verdict on - WebRTC-style delay control +- [GCC egress experiment](/quest/m3/quic-gcc.md) - a receive-timestamps measurement spike, the + first step toward WebRTC-style delay control diff --git a/quest/m1/quic/bbr-app-limited-edges.md b/quest/m1/quic/bbr-app-limited-edges.md index 1cdc4ff13fb..bf84f2c596d 100644 --- a/quest/m1/quic/bbr-app-limited-edges.md +++ b/quest/m1/quic/bbr-app-limited-edges.md @@ -32,9 +32,9 @@ drains, a sender blocked only by `send_window`, and a stream blocked by receiver credit. Builds on the seven fixes released in moq-noq 1.3.1. No public API or wire change is intended. -## Required - -- [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` +Decided 2026-10-08: this does not wait for the +[switch](/quest/m1/quic/fork/switch.md), since 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 22ab852390c..57d910b5cc1 100644 --- a/quest/m1/quic/bbr-app-limited.md +++ b/quest/m1/quic/bbr-app-limited.md @@ -22,16 +22,18 @@ 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 `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. +0.9x the earlier max bandwidth. Check that it fails with #5's app-limited +marking reverted, since the test lives in `moq-quic` and cannot run 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 `moq-quic`. Dropping the estimate after a long idle is a policy change for the m2 study, not this quest. -## Required - -- [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` +Decided 2026-10-08: this does not wait for the +[switch](/quest/m1/quic/fork/switch.md). The core and its BBR3 are already in +`rs/moq-quic`, and local fixes there land on their own, as +[input validation](/quest/m1/quic/fork/input-validation.md) does. ## Closes diff --git a/quest/m1/quic/scheduler.md b/quest/m1/quic/scheduler.md index 661f8cb01e2..65d7f5d5c1f 100644 --- a/quest/m1/quic/scheduler.md +++ b/quest/m1/quic/scheduler.md @@ -119,8 +119,6 @@ where the new implementation makes it redundant. a policy consumer of the same hierarchy - [Scope track priority](/quest/m1/track-priority-scope.md) - owns the priority semantics this mechanism realizes, including the scheduling-domain - scope -- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type - this orders on; keep the ordering, not just the type + scope and the priority type change; keep the ordering, not just the type - [noq#816](https://github.com/n0-computer/noq/issues/816) - the send-group proposal to n0; this quest supersedes it - [noq#817](https://github.com/n0-computer/noq/issues/817) - the 64-bit priority ask; send groups replace the scalar, but the per-stream order within a group must still hold a 64-bit group sequence From 6957755af40fdbff0e78567b0d69c881e7f17dd2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:12:37 -0700 Subject: [PATCH 05/10] quest: apply audit fixes (group 5) Co-Authored-By: Claude Opus 5.5 --- quest/m1/relay-iroh-opt-in.md | 4 +- quest/m1/release-profile.md | 1 + quest/m1/rs2ts/README.md | 13 ++-- quest/m1/rs2ts/sans-io/lite.md | 4 ++ quest/m1/rs2ts/translator.md | 4 +- quest/m1/rust-continuous.md | 3 +- quest/m1/session-churn-held.md | 2 +- quest/m1/shared-clock.md | 3 +- quest/m1/size-report.md | 8 +-- quest/m1/stats/js.md | 9 +-- quest/m1/stats/rust.md | 9 +-- quest/m1/subscribe-ranges/README.md | 7 +- quest/m1/subscribe-ranges/ietf.md | 5 +- quest/m1/subscribe-ranges/js.md | 3 +- quest/m1/subscribe-ranges/lite.md | 5 +- quest/m1/subscribe-ranges/model.md | 1 + quest/m1/test-flakes-2/README.md | 1 + quest/m1/track-priority-scope.md | 66 +++++++++++++++---- quest/m1/transport-upgrade/js.md | 2 + quest/m1/ts-passthrough.md | 8 ++- quest/m1/tstd/README.md | 3 +- quest/m1/uring-drop-close.md | 3 + quest/m1/uring-ietf.md | 12 ++-- quest/m1/uring-tests-under-load.md | 5 +- quest/m1/watch-audio-time-stretch.md | 7 +- ...evc-and-av1-support-in-the-nvidia-codec.md | 3 + ...-the-webtransport-stream-header-at-open.md | 28 ++++---- ...tch-completion-wakeups-with-min-timeout.md | 6 +- ...fixed-file-slots-for-worker-udp-sockets.md | 9 +-- quest/m2/archive-recovery-listing.md | 10 +-- quest/m2/audio-encode-mediacodec.md | 4 ++ quest/m2/audio-encode-mediafoundation.md | 4 ++ quest/m2/bench-coverage.md | 22 +++---- 33 files changed, 180 insertions(+), 94 deletions(-) diff --git a/quest/m1/relay-iroh-opt-in.md b/quest/m1/relay-iroh-opt-in.md index 43d431568c2..e04fa66cd9e 100644 --- a/quest/m1/relay-iroh-opt-in.md +++ b/quest/m1/relay-iroh-opt-in.md @@ -12,8 +12,7 @@ Decided in planning: - Only the relay changes. moq-cli keeps iroh by default because the P2P questline dials native peers over it, which mDNS's LAN discovery doesn't - replace. `moq relay` (the planned verb) keeps iroh through moq-cli's - features. + replace. - Removing a default feature from a published crate, and flags from a shipped binary, is a published break. @@ -26,5 +25,4 @@ Guidance: ## Related -- [`moq relay`](/quest/m3/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's - [P2P](/quest/m3/p2p/README.md) - why moq-cli keeps iroh diff --git a/quest/m1/release-profile.md b/quest/m1/release-profile.md index 9bd60cc552f..f51a42b6be2 100644 --- a/quest/m1/release-profile.md +++ b/quest/m1/release-profile.md @@ -49,3 +49,4 @@ Guidance: - [Size report](/quest/m1/size-report.md) - the nightly job that shows what this changes over time - [Bindings size profile](/quest/m1/ffi-size-profile.md) - the opt-level trade this quest leaves out +- [Relay profiling](/quest/m1/perf/lock-profile.md) - the profiling recipe whose captures the `profiling` override keeps symbolized diff --git a/quest/m1/rs2ts/README.md b/quest/m1/rs2ts/README.md index b0a084ae070..87724982229 100644 --- a/quest/m1/rs2ts/README.md +++ b/quest/m1/rs2ts/README.md @@ -53,11 +53,16 @@ Decided in planning (2026-09-27), with the spike data in them; it is months out. Decided in the 2026-09-30 audit: the lite half stays in m1 with an explicit -go/no-go after the no-downgrade report below; a no-go stops the line before -anything else is generated. The IETF half (the sans-IO IETF session, -generated IETF, and IETF parameters) moved to m2 and waits on that go. +go/no-go. The IETF half (the sans-IO IETF session, generated IETF, and IETF +parameters) moved to m2 and waits on that go. -This README's own work is the no-downgrade report once generated lite ships: +Decided 2026-10-08: the go/no-go comes right after the +[translator](/quest/m1/rs2ts/translator.md), before the sans-IO refactors +break moq-net's published API. It compares the generated lite codec with +js/net's hand-written one on bundle size and per-frame CPU. A no-go stops the +line there. + +This README's own work is the final no-downgrade report once generated lite ships: bundle size, per-frame CPU, and first-frame latency against the hand-written js/net it replaces, measured with the [browser benchmarks](/quest/m1/browser-benchmarks.md). diff --git a/quest/m1/rs2ts/sans-io/lite.md b/quest/m1/rs2ts/sans-io/lite.md index 67974918d74..343b29847f7 100644 --- a/quest/m1/rs2ts/sans-io/lite.md +++ b/quest/m1/rs2ts/sans-io/lite.md @@ -29,3 +29,7 @@ Guidance: explicit instants as it is rewritten, so they translate with the code. Public API: breaks moq-net's session API. Wire: none. + +## Required + +- [rs2ts](/quest/m1/rs2ts/translator.md) - its go/no-go decides whether moq-net breaks its API for generated TypeScript diff --git a/quest/m1/rs2ts/translator.md b/quest/m1/rs2ts/translator.md index bd599f40f22..d1253d335e0 100644 --- a/quest/m1/rs2ts/translator.md +++ b/quest/m1/rs2ts/translator.md @@ -5,7 +5,9 @@ `rs/rs2ts` translates moq-net's lite codec into readable TypeScript inside js/net. The output is committed, a CI lane regenerates it and fails on drift, and the generated codec passes `just test interop --all` in place of -the hand-written one. +the hand-written one. The PR carries the line's go/no-go: the generated +codec's bundle size and per-frame CPU against js/net's hand-written codec. A +no-go stops the [line](/quest/m1/rs2ts/README.md) before the sans-IO work. ## Plan diff --git a/quest/m1/rust-continuous.md b/quest/m1/rust-continuous.md index 748c6fa9b76..a6032b7b82d 100644 --- a/quest/m1/rust-continuous.md +++ b/quest/m1/rust-continuous.md @@ -13,7 +13,8 @@ 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. +in the 2026-10-08 audit, so audio and consumer warmup need not wait on the +open-GOP trim. 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 diff --git a/quest/m1/session-churn-held.md b/quest/m1/session-churn-held.md index 124f172c99b..68328714be3 100644 --- a/quest/m1/session-churn-held.md +++ b/quest/m1/session-churn-held.md @@ -19,4 +19,4 @@ Public API: none. Wire: none. ## Related -- [Reproducible relay CPU and allocation profiles](/quest/m1/performance-profiles.md) - the profiling setup this can use +- [Relay profiling](/quest/m1/perf/lock-profile.md) - the `just` profiling recipe this can use diff --git a/quest/m1/shared-clock.md b/quest/m1/shared-clock.md index 7dc42414695..2606b209a2e 100644 --- a/quest/m1/shared-clock.md +++ b/quest/m1/shared-clock.md @@ -133,7 +133,8 @@ Guidance: - Test: a TS import carrying a `splice_insert` joins a clock already in use. In its TS export, `pts_time + pts_adjustment` lands on the exported video PTS of the splice point, and the section's CRC verifies. -- Test: start a synthetic capture, then import an fMP4 starting at PTS 0. Both +- Test: the first data-track test also runs with a synthetic capture taking + the clock in place of the data track, importing an fMP4 at PTS 0: both tracks advance from the capture's timeline with no rewind. Also cover the reverse order: an importer first on a default clock keeps its PTS verbatim. A passthrough fragment whose `tfdt` disagrees with its frame timestamp diff --git a/quest/m1/size-report.md b/quest/m1/size-report.md index 9dfb5ffe1cb..71174a84826 100644 --- a/quest/m1/size-report.md +++ b/quest/m1/size-report.md @@ -23,7 +23,6 @@ Decided in planning: - Scope: - moq-ffi, default and `--no-default-features`, as cdylib and staticlib - moq-c, moq-relay, and moq-cli - - the moq-wasm module, raw, gzip, and brotli - the consumer cost of the JS entries: `@moq/net`, `@moq/watch/element` with and without `/ui`, and `@moq/publish/element`. Measure them the way a consumer sees them: bundled and minified from the built packages, @@ -31,9 +30,10 @@ Decided in planning: - the packaged outputs nightly already builds. `nightly.yml` runs the Python, Kotlin, and Swift release builds, so read their wheel, AAR, and xcframework sizes instead of rebuilding them. -- Out of scope: Docker images, and per-target release assets nightly doesn't - build. The Docker quest measures its images once. Add others only if one of - them regresses unnoticed. +- Out of scope: moq-wasm, which [Remove moq-wasm](/quest/m1/rs2ts/remove-wasm.md) + deletes (decided 2026-10-08), Docker images, and per-target release assets + nightly doesn't build. The Docker quest measures its images once. Add + others only if one of them regresses unnoticed. - The job summary also carries `cargo bloat --crates` for the ffi build and a metafile breakdown for the publish element, so the cause of a jump is visible without a local rebuild. `cargo bloat` needs symbols, so build that diff --git a/quest/m1/stats/js.md b/quest/m1/stats/js.md index b8d4bac05b2..3e2dc8e4cdb 100644 --- a/quest/m1/stats/js.md +++ b/quest/m1/stats/js.md @@ -32,9 +32,10 @@ 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`. +- Decided 2026-10-08: no E2EE refusal here. The elements have no encrypted + broadcast yet, so [Encrypted browser components](/quest/m1/e2ee/browser.md) refuses the + stats track and the `echo` attribute when it adds one: they would publish + rendition IDs and per-track counters in plaintext beside it. ## Required @@ -42,4 +43,4 @@ echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. ## Related -- [E2EE](/quest/m1/e2ee/README.md) - protected broadcasts expose no semantic metadata +- [Encrypted browser components](/quest/m1/e2ee/browser.md) - refuses stats and feedback on an encrypted broadcast diff --git a/quest/m1/stats/rust.md b/quest/m1/stats/rust.md index 4b468deb44e..3ac342e2e3f 100644 --- a/quest/m1/stats/rust.md +++ b/quest/m1/stats/rust.md @@ -41,9 +41,10 @@ - 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`. +- Decided 2026-10-08: no E2EE refusal here. The CLI has no encrypted + broadcast yet, so [Encrypted native CLI](/quest/m1/e2ee/cli.md) refuses `--stats` and + `--echo` when it adds one: they would publish rendition IDs and per-track + counters in plaintext beside it. ## Required @@ -51,4 +52,4 @@ ## Related -- [E2EE](/quest/m1/e2ee/README.md) - protected broadcasts expose no semantic metadata +- [Encrypted native CLI](/quest/m1/e2ee/cli.md) - refuses stats and feedback on an encrypted broadcast diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index cd7d9356672..4f0a972d8d7 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -25,7 +25,7 @@ relay bounds a sparse FETCH only if the model can request ranges: - **Holes.** SUBSCRIBE_DROP (restored in lite-07 by [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)) names every sequence in the requested ranges the publisher won't deliver: never existed, expired, or - refused upstream. Datagram groups are always dropped in a past range (the datagrams-are-live-only quest, #4551). The + refused upstream. Datagram groups are always dropped in a past range (#4982). The publisher delivers what it has and fills the rest as upstream answers. - **Model.** `Subscription` gains `ranges` and `order`, mirroring the wire; `request_groups` as a separate API was rejected. A publisher's @@ -47,8 +47,8 @@ relay bounds a sparse FETCH only if the model can request ranges: - Ranges are frame-precise (`Position`), not whole groups. The IETF joining FETCH for a mid-group SUBSCRIBE's uncached prefix stays, because today's bridge relies on it (maintainer, 09-29). -- The relay half of fetch-span (#4558, from the finished Moxygen line) moves - here; #4558 lands only the no-handler skip. +- The relay half of fetch-span moves here; #4558 landed only the no-handler + skip. This line owns the end-to-end test: a relay with a sparse cache answers a wide past range plus live in both orders, over lite-07 and moq-transport, with @@ -56,6 +56,7 @@ every sequence delivered or dropped. ## Required +- [lite-07 Live flag](/quest/m1/lite-live.md) - the `Live` field the range list sits beside - [Model ranges](/quest/m1/subscribe-ranges/model.md) - `Subscription` carries ranges and order, and `Dynamic` fills misses by range - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 85ac0d011b8..5ee9b445c16 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -29,7 +29,4 @@ serves it. ## Required - [Model ranges](/quest/m1/subscribe-ranges/model.md) - the range requests this answers - -## Related - -- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - serves draft-20 FETCH through the same group-span path this widens +- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - serves draft-20 FETCH through the same group-span path this widens (#4971) diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index e404e0a471c..470861c9b84 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -9,8 +9,7 @@ publisher serves requested ranges that are no longer in its live cache. ## Plan -Mirror the Rust names. The JS FETCH cancel and JS FETCH quests shape the -current `fetchGroup` surface; fold whatever of them is still open into this. +Mirror the Rust names. Decided in the 2026-10-05 audit: the producer half of [JavaScript FETCH](/quest/m1/js-fetch.md) folds in here, so `@moq/net`'s diff --git a/quest/m1/subscribe-ranges/lite.md b/quest/m1/subscribe-ranges/lite.md index 39d0a047193..102dd8709f7 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -12,11 +12,14 @@ lite upstream by subscribing to the missing ranges. Update `drafts/draft-lcurley-moq-lite.md` in the same PR: the SUBSCRIBE and SUBSCRIBE_UPDATE fields, the Group Order section (the order is now a field), the removal of FETCH, and the lite-07 changelog. Fix the stale "offset by 1" -sentence on Group Start while there. Published versions (lite-03..06) keep +sentence on Group Start while there. This quest also owns the Order row of +the priority table in `doc/concept/moq-lite.md`: it now describes the field +(decided 2026-10-08, since subscribe ranges owns group order). Published versions (lite-03..06) keep FETCH, answered through the model's ranges. Run `just drafts check` and `just test interop --all`. ## Required +- [lite-07 Live flag](/quest/m1/lite-live.md) - reshapes the same SUBSCRIBE first - [Model ranges](/quest/m1/subscribe-ranges/model.md) - the model this serves - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07's DROP for holes diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 26fdb7afb57..1c925e05bc6 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -27,4 +27,5 @@ Guidance: ## Required +- [lite-07 Live flag](/quest/m1/lite-live.md) - reshapes the same `Subscription` first - [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/README.md b/quest/m1/test-flakes-2/README.md index e461891a9ba..b0fc70f158a 100644 --- a/quest/m1/test-flakes-2/README.md +++ b/quest/m1/test-flakes-2/README.md @@ -36,3 +36,4 @@ Public API: none. Wire: none. - [Import catalog finish](/quest/m1/test-flakes-2/import-catalog-finish.md) - `moq-cli`'s subprocess EOF catalog-finish test holds up under load with event-based fixture coordination - [Relay restart rebind](/quest/m1/test-flakes-2/relay-restart-rebind.md) - the crash drill restarts on its original UDP address under concurrent load - [Impaired handshake](/quest/m1/test-flakes-2/impaired-handshake.md) - the impaired cluster drills' clients never time out while connecting +- [Media audio tone](/quest/m1/media-audio-tone.md) - the `just test media` audio-tone check passes under load, fixed at its cause diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index a6820a319d4..1004111da75 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -1,4 +1,4 @@ -# [L] Scope track priority +# [XL] Scope and sign track priority ## Goal @@ -9,6 +9,11 @@ domain is the broadcast: when the relay enables it, broadcasts share the link fairly and priority orders streams only inside each broadcast, so one customer's viewers asking for 255 never starve another customer's broadcast. +In the same API break, every priority becomes an `i8`, higher first, with 0 as +the unset midpoint: `track::Info`, `Subscription`, and `group::Fetch` in Rust, +their JS counterparts, moq-ffi, moq-c, and every wrapper. Nobody has to know +that 127 is the middle of a `u8`. The wire stays a byte. + ## Plan Where the model stands today, all in `rs/moq-net`: @@ -40,6 +45,10 @@ refinement of the same tier, not a different design. Opening more subscriptions or broadcasts must never buy more bandwidth than the bucket allows. +Decided 2026-10-08: the signed priority type lands here, so the priority API +breaks once instead of twice. Subscribe ranges owns group order, so this quest +neither forbids an order knob nor edits the doc's Order row. + Direction to settle in the draft first, then the code: - On the last mile the viewer owns the whole session, so its audio and video @@ -55,11 +64,11 @@ Direction to settle in the draft first, then the code: Priority outside any subscription, so leaving them outside every bucket bypasses tenant isolation; settle their carrier beside the subscription one, or narrow the goal to subscription delivery. -- Keep the current ranking: track priority, then subscription, then newest - group; do not reintroduce a group-order direction knob. +- Rank by track priority, then subscription, then the subscription's own group + order (newest first until subscribe ranges adds a direction). - Decide whether the publisher's `track::Info::priority` breaks a tie between equal subscriber priorities in `Priority::cmp` - (`rs/moq-net/src/lite/priority.rs:48`). The + (`rs/moq-net/src/lite/priority.rs`). The [ladder controller](/quest/m3/ladder/controller.md), now in m3, wants that tiebreak; this quest owns the answer and the code change, so the controller only consumes it (2026-10-06 audit). Either way, make the docs agree: @@ -69,13 +78,44 @@ Direction to settle in the draft first, then the code: - A per-session cap on distinct ranks is a scheduling detail; whatever replaces the 255-entry sort must stay O(log n) per group under chat-shaped churn. -Prove with the existing lite publisher tests extended to two broadcasts on -one session with fairness on: neither starves, a downstream 255 does not -change the upstream order, and with fairness off the strict order is -unchanged. The io_uring workers apply the same setting. Update `doc/concept/moq-lite.md`, whose priority table still -describes a direction knob the wire does not carry. Public API impact: the -meaning of `Subscribe.priority` on a cluster session; report it with the draft -change. +Signed priority, decided with the maintainer: + +- moq-lite carries `p + 128` (flip the top bit). The mapping is one-to-one + and keeps order, so a given byte means what it means today; only the API + number changes. The default becomes byte 128. +- IETF carries `127 - p`. Both mappings are one-to-one over the whole `i8` + range, with no saturation. An unset priority goes out as IETF 127, not the + draft's usual 128, and an absent IETF priority decodes to 0, the unset + default. Pin both ends in tests. +- Keep one urgency on both wires (#4273), so the IETF byte is always `255 -` + the lite byte. Mapping IETF as `128 - p` to hit the draft's 128 would break + that, which is why the default is one step off the draft there. +- hang's built-in priorities (`hang::catalog::PRIORITY`, today all below the + 127 default) move above 0, so hang media outranks a track that never set + one. Rust and JS keep matching values; the spacing is the implementer's call. +- moq-c's `moq_track_info.priority` has no presence flag, so a zeroed struct + means least urgent today. With `i8`, zero is the default. +- Look for anything that does arithmetic on priority (the lite send queue, JS + send-order packing, the bandwidth allocator, the relay's max-of-subscribers) + and keep its ordering, not just its type. +- moq-archive's `Info::priority` follows. Its version-1 `.info` stores the + `u8`, so existing recordings must keep their meaning: store the moq-lite + byte (`p + 128`) or bump the format version, never reinterpret silently. +- The moxygen default (127, #4273) already shipped, so the default byte moves + a second time. Add an upgrade note to the release's upgrade page saying why. + Rejected: a mapping that keeps today's bytes (lite byte = p + 127). + +Prove scoping with the existing lite publisher tests extended to two +broadcasts on one session with fairness on: neither starves, a downstream 255 +does not change the upstream order, and with fairness off the strict order is +unchanged. The io_uring workers apply the same setting. Move +`doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md` +(IETF 128 maps to 127) to the new range and mapping. + +Public API impact: `u8` priority fields become `i8` in every language, and +`Subscribe.priority` on a cluster session changes meaning. Wire impact: none +in format, but the default byte moves from 127 to 128 on moq-lite and from 128 +to 127 on IETF. Report both with the draft change. ## Required @@ -84,5 +124,5 @@ change. ## Related -- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type, - not which streams it competes with +- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - owns the group + order a subscription asks for diff --git a/quest/m1/transport-upgrade/js.md b/quest/m1/transport-upgrade/js.md index 91f13807552..407ba8faec1 100644 --- a/quest/m1/transport-upgrade/js.md +++ b/quest/m1/transport-upgrade/js.md @@ -46,6 +46,8 @@ session to close on its own or at the handover cap. See the group across the upgrade, the WebSocket session closes within the cap, and the next connect to the same URL gives WebTransport the head start again; with no delay, WebTransport wins and no WebSocket session is ever opened. + The watched broadcast carries an epoch, since a track resumes across a + handover only between routes with the same epoch. - Public API: the `setup` mirror, if it is exported; `transportOf` already reports the live transport. Update `doc/lib/js` where the fallback race is described. diff --git a/quest/m1/ts-passthrough.md b/quest/m1/ts-passthrough.md index eb1197501a9..e5954f087af 100644 --- a/quest/m1/ts-passthrough.md +++ b/quest/m1/ts-passthrough.md @@ -49,7 +49,9 @@ Decided (2026-10-01), from a discussion with t0ms: epoch, so object timestamps never go backwards within one broadcast. A flagged forward jump starts a group, and an unflagged rewind is fatal (decided 2026-10-07 in the final-head audit of #4670, which had a backward - flag start a group in place). + flag start a group in place). When the operator pinned the epoch with + `--epoch`, a flagged rewind is fatal instead, as TS restart decides + (2026-10-08), so both hosts of a redundant pair keep the operator's epoch. - `randomAccess` is true only while the PAT lists a single program with at most one video PID, and every group has started at a `random_access_indicator`. The first group that starts without one (a @@ -109,6 +111,10 @@ discontinuity publishes two broadcasts, and the same rewind unflagged errors. A dropped object is counted, and the rest still go out on time. Rerun the #4613 netem rig (10% loss, 120 s) against it. +Lands in two PRs (decided 2026-10-08): #5003 is the import half and the +`m2ts` catalog section, and waits on TS restart; the export half follows on +the fixed-delay release stage. This quest finishes with the export. + Update `doc/bin/cli.md` for both flags, `doc/concept` for the section, and the draft's comparison section to say this repository now publishes both shapes. diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md index 76718224d40..5d8eb04b4d4 100644 --- a/quest/m1/tstd/README.md +++ b/quest/m1/tstd/README.md @@ -13,8 +13,7 @@ distribution. Without it, only the passthrough lane can. Decided (2026-09-30), from a discussion with t0ms and Gwendal's email: a TS export has to be a proper remux, not an interleave of demuxed tracks. Padding, pacing, and muxing all assume a fixed delay, so the export gets one -first. t0ms is testing whether T-STD compliance is feasible at all; record -the result here. If it isn't, re-plan this line. +first. Measured (2026-10-01, #4645): with the fixed-delay jitter buffer, per-PID admission against each PID's T-STD buffers, and PCRs at their byte position, a diff --git a/quest/m1/uring-drop-close.md b/quest/m1/uring-drop-close.md index aad4fac727a..4c3ba04f16c 100644 --- a/quest/m1/uring-drop-close.md +++ b/quest/m1/uring-drop-close.md @@ -19,6 +19,9 @@ fixed. Close with a generic application code on drop of the last handle, matching what the other backends do, with a test that drops a session and observes the peer's close. +Decided 2026-10-08: moved to m2, since the relay goes through moq's session +machine, which the `Connection` doc says closes explicitly. + Public API: none expected. Wire: none. ## Related diff --git a/quest/m1/uring-ietf.md b/quest/m1/uring-ietf.md index c860ec359de..474f69b0ca5 100644 --- a/quest/m1/uring-ietf.md +++ b/quest/m1/uring-ietf.md @@ -9,9 +9,10 @@ ring then drops no client protocol over raw QUIC. ## Plan -`rs/moq-relay/src/uring.rs` states "Sessions are moq-lite only": `bind` -keeps `versions.iter().filter(|v| v.is_lite())`, refuses the lite versions -that negotiate in SETUP, and warns about configured moq-transport versions. +The io_uring listener's bind in `rs/moq-relay/src/uring.rs` advertises only +the lite ALPNs (`is_lite`), refuses a lite version named in the config that +negotiates in SETUP, and only warns when the config lists moq-transport +versions. The tokio path already drives both wires through one session type, so the gap is in the worker's accept path, not in moq-net. @@ -27,9 +28,10 @@ gap is in the worker's accept path, not in moq-net. caveat. Additive, so it lands on main. moq.pro's fleet deploy of the -ring requires the release carrying it. +ring requires the release carrying it. Decided 2026-10-08: moved to m2 with +that fleet deploy, which is m2 work. ## Related - [Stream sessions](/quest/m2/uring-tcp/README.md) - the other protocol gap - on the ring, WebSocket and HTTP, deferred to m2 + on the ring, WebSocket and HTTP diff --git a/quest/m1/uring-tests-under-load.md b/quest/m1/uring-tests-under-load.md index f78534d09d3..3672bd3645e 100644 --- a/quest/m1/uring-tests-under-load.md +++ b/quest/m1/uring-tests-under-load.md @@ -11,7 +11,10 @@ shared an 8 MiB `RLIMIT_MEMLOCK`, and `deadline_fires_at_park` and Fix at the cause, never with a retry or longer timeout: -- Locked memory: measure what each test ring locks and whether tests can share +- Locked memory: start from the nextest `io-uring` test group + (`.config/nextest.toml`), which already holds one run to four ring tests at + a time; the failures came from several runs sharing one user's budget. + Measure what each test ring locks and whether tests can share or shrink rings. If configuration must change, make the supported dev-shell and CI setup actually allow the tests to pass under parallel load. `Error::ring` already reports `RLIMIT_MEMLOCK` on ENOMEM; check that this diff --git a/quest/m1/watch-audio-time-stretch.md b/quest/m1/watch-audio-time-stretch.md index 5ddae6d6197..a27b24b5588 100644 --- a/quest/m1/watch-audio-time-stretch.md +++ b/quest/m1/watch-audio-time-stretch.md @@ -12,7 +12,7 @@ Boundaries: no packet loss concealment; an underrun still renders a ramped gap. The target estimator and the ring's slack and re-stall are the [audio jitter target](/quest/m0/audio-jitter-target/README.md) line (#3517 was closed in favor of it); the clock the stretch converges toward is -[Plan: A/V clock](/quest/m1/av-clock.md). +[A/V clock](/quest/m1/av-clock.md). ## Plan @@ -22,8 +22,9 @@ was closed in favor of it); the clock the stretch converges toward is for a distance larger than the stretch can close within a bound. - Both rings expose the distance the same way, so the worklet code is shared between the isolated and the postMessage paths. -- Verification: replay the recorded arrival traces from the auto-latency - quest and assert zero skips and zero underruns after convergence, plus a +- Verification: replay the recorded arrival traces + (`test/audio-quality/traces/`, through `js/watch/src/audio/replay.ts`) + and assert zero skips and zero underruns after convergence, plus a listening check that a 2 ms/s drift is inaudible. ## Required diff --git a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md index 532a8543e66..c7bcd3fd255 100644 --- a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md +++ b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md @@ -12,6 +12,9 @@ Decided in the 2026-09-30 audit: AV1 encoding split out to [NVENC AV1](/quest/m3/nvenc-av1.md), because it needs an Ada GPU and the only GPU CI host is an RTX 3070 Ti. Main10 stays here since that host can verify it. +Decided 2026-10-08: moved to m3. No 10-bit encode pipeline or consumer +exists yet. + Extend the settled frame and NVENC contracts with Main10 surfaces, profile selection, and accurate codec metadata. Audit byte pitch, plane layout, CPU download, and P016 input/output together; a codec enum alone does not establish diff --git a/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md index c6f9e783364..424ab4948ba 100644 --- a/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md +++ b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md @@ -2,17 +2,19 @@ ## Goal -A web-mode `SendStream` (rs/moq-uring/src/quic/web.rs) has its WebTransport +A web-mode `SendStream` (`rs/moq-uring/src/quic/web.rs`) has its WebTransport header on the wire before `poll_open_uni` hands it back, so `finish()` never -owes one and the `finishing` state machine goes away. +owes one and the `finishing` state machine goes away. Concurrent openers, +cancellation, and flow-control backpressure on the open have settled, +documented semantics. ## Plan -Follow-up to #3105 (item 4), deliberately left out of #3110. Raised by Codex reviewing that PR and verified against the code. +Follow-up to #3105 (item 4). ##### Where it stands -A web-mode `SendStream` carries its WebTransport header as an owed `prefix` and writes it lazily on the first `poll_write`. #3110 stopped `finish()` from reporting connection-level backpressure as a terminal `Error::Web`: it now records that the header is still owed and returns `Ok`, and the FIN goes out on a later `poll_closed`, or on `Drop` if credit has returned by then. +A web-mode `SendStream` carries its WebTransport header as an owed `prefix` and writes it lazily on the first `poll_write`. When `finish()` finds no credit for the header, it records `finishing` and returns `Ok`, and the FIN goes out on a later `poll_closed`, or on `Drop` if credit has returned by then. That covers every in-tree caller, because moq-net always pairs `finish()` with `poll_closed`. What it does not cover is a direct consumer that finishes and drops in the same breath: @@ -21,23 +23,21 @@ send.finish()?; // no credit: the header is owed, returns Ok drop(send); // no ingress in between, so try_write still returns 0 ``` -There is no moment for credit to return between those two calls, so `Drop` falls through to the mapped reset and the peer sees a cancellation despite `finish()` having reported success. This is not a regression (before #3110 the same situation returned `Err` and callers dropped, resetting with a worse code), and #3110 documents it on `SendStream`, but `finish()` reporting success on a stream that ends up cancelled is still a wart. +There is no moment for credit to return between those two calls, so `Drop` falls through to the mapped reset and the peer sees a cancellation despite `finish()` having reported success. `SendStream` documents this, but it is still a wart. ##### The fix -Option 1 from #3105: queue the prefix before handing the opened stream back, so nothing is ever owed at finish time and the whole `finishing` state machine goes away. A WebTransport stream is arguably not open until its header is on the wire, so this is also the more honest shape. +Option 1 from #3105: queue the prefix before handing the opened stream back, so nothing is ever owed at finish time. A WebTransport stream is arguably not open until its header is on the wire, so this is also the more honest shape. -The reason it is not a small change: `poll_open_uni` would have to hold a half-open stream across polls while the header drains, and `Session` clones share one `Rc`. A single slot for the in-flight open would have concurrent openers fighting over it, so this needs a queue of half-open streams in `Web::state`, plus a decision about what `poll_open_uni` returning `Pending` on flow control means for callers that open before they read. +It is not a small change: `poll_open_uni` would have to hold a half-open stream across polls while the header drains, and `Session` clones share one `Rc`. A single slot for the in-flight open would have concurrent openers fighting over it, and a queue alone is not a chosen contract. Settle the contract first: -Worth confirming the trade too: making `open` block on credit moves the backpressure earlier, which is more correct but changes when a caller learns about it. +- How independent concurrent openers keep ownership of a half-open stream across `Pending` and cancellation (a dropped open future). +- Whether an open-before-read caller can deadlock when the header needs flow-control credit. Making `open` block on credit moves backpressure earlier, which is more correct but changes when a caller learns about it. +- Resource bounds on half-open streams. -Decided in the 2026-09-30 audit: moved to m2. No in-tree caller hits the -wart (moq-net always pairs `finish()` with `poll_closed`), and io_uring -ships in no package. +Present the viable ownership choices and a recommendation to the maintainer before implementing. Regression cases: concurrent openers, credit starvation, dropped open futures, and finish then drop. -## Required - -- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation +Decided 2026-10-08: the open-contract planning quest merged in here, and the quest moved to m3. No in-tree caller hits the wart and io_uring ships in no package. ## Closes diff --git a/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md index 3bf50216a67..747aafd1440 100644 --- a/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md +++ b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md @@ -2,7 +2,7 @@ ## Goal -`maybe_park` (rs/moq-uring/src/worker.rs:363) waits with a CQE batch target +`Worker::maybe_park` (`rs/moq-uring/src/worker.rs`) waits with a CQE batch target and a `min_wait_usec`, the three return paths are tested, and the benchmark matrix shows fewer wakeups per message without a p99 regression before any default changes. @@ -38,6 +38,10 @@ Benchmark chat, 1:1 video, and fanout workloads with `N = 1/4/8/16` and `t = 0/5 Decided in the 2026-09-30 audit: moved to m2. It trades latency for CPU, the win is unmeasured on noq, and io_uring ships in no package. +## Required + +- [One enter per turn](/quest/m1/perf/uring-one-enter.md) - reshapes the same park and enter path, and adds the per-enter metrics this measures + ## Closes - [#3200](https://github.com/moq-dev/moq/issues/3200) - close this issue when the quest finishes diff --git a/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md index 67f44fde701..7fdd1cd0745 100644 --- a/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md +++ b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md @@ -3,9 +3,9 @@ ## Goal Worker UDP sockets live in a ring-owned fixed-file table and every socket SQE -addresses a `types::Fixed` slot (today `types::Fd`, rs/moq-uring/src/udp.rs:934, -:976, :1014), with slot teardown ordered so a stale SQE can never hit a reused -fd. +addresses a `types::Fixed` slot (today the send and receive SQE builders in +`rs/moq-uring/src/udp.rs` use `types::Fd`), with slot teardown ordered so a +stale SQE can never hit a reused fd. ## Plan @@ -31,7 +31,8 @@ Registered files let SQEs address a stable table slot with `types::Fixed`. This Benchmark steady-state send/receive traffic and high socket-churn workloads. Record CPU, cycles, instructions, throughput, and socket lifetime cost. Keep the implementation only if the hot-path win justifies the slot-lifecycle complexity. Decided in the 2026-09-30 audit: moved to m2. The hot-path win is -unmeasured on noq, and io_uring ships in no package. +unmeasured on noq, and io_uring ships in no package. Decided 2026-10-08: +moved to m3 with the rest of the speculative ring work; no fleet demand. ## Closes diff --git a/quest/m2/archive-recovery-listing.md b/quest/m2/archive-recovery-listing.md index 1c62bb5dc89..2797aac43cf 100644 --- a/quest/m2/archive-recovery-listing.md +++ b/quest/m2/archive-recovery-listing.md @@ -3,17 +3,17 @@ ## Goal A DVR writer resuming a recording lists storage in proportion to what changed -since its last checkpoint, not every stored `groups/` object, while still never +since its last checkpoint, not every stored `segments/` object, while still never deleting a referenced object. ## Plan -- Recovery today reconciles a complete `groups/` listing of every recorded - track before accepting input. Compare bounding it with an ordered +- Recovery today (`recover` in `rs/moq-archive/src/recover.rs`) lists the + whole recording, every track's `segments/`, before accepting input. Compare bounding it with an ordered `list_with_offset` from the oldest retained range, with orphans below it left to a background sweep, against a checkpointed listing marker. - Benchmark recovery time and requests over archive size before and after. -## Required +## Related -- [Archive](/quest/m1/archive/README.md) - the recovery this bounds ships with the line +- [Archive](/quest/m1/archive/README.md) - the line whose recovery this bounds diff --git a/quest/m2/audio-encode-mediacodec.md b/quest/m2/audio-encode-mediacodec.md index f57cb9884fe..d971d6b4e1e 100644 --- a/quest/m2/audio-encode-mediacodec.md +++ b/quest/m2/audio-encode-mediacodec.md @@ -27,3 +27,7 @@ behind the `mediacodec` feature and the encode seam. ## Required - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - the round-trip regression decodes through it + +## Related + +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - the macOS and iOS backend, which may already add `flush` to `Encoder::encode` diff --git a/quest/m2/audio-encode-mediafoundation.md b/quest/m2/audio-encode-mediafoundation.md index 97b0d3b62b0..99622752f15 100644 --- a/quest/m2/audio-encode-mediafoundation.md +++ b/quest/m2/audio-encode-mediafoundation.md @@ -21,3 +21,7 @@ behind the encode seam on Windows. ## Required - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the round-trip regression decodes through it + +## Related + +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - the macOS and iOS backend, which may already add `flush` to `Encoder::encode` diff --git a/quest/m2/bench-coverage.md b/quest/m2/bench-coverage.md index faa6f92885a..7f27b4a0f68 100644 --- a/quest/m2/bench-coverage.md +++ b/quest/m2/bench-coverage.md @@ -1,29 +1,27 @@ -# [M] Benchmarks for patterns, containers, catalog, and auth +# [S] Benchmarks for patterns and containers ## Goal Hot paths that have no benchmark get Criterion targets, so CI tracks them: -`moq-pattern` path matching, `moq-mux` container import and export per frame, `hang` catalog encode, decode, and -update, and `moq-auth` token verification. +`moq-pattern` path matching, and `moq-mux` container import and export per +frame. ## Plan Deferred to m2 in the 2026-09-30 audit. The `moq-pattern` benchmark is the -one worth doing first, and could return to m1 as its own quest. The -`moq-stats` producer tick lives in `rs/moq-stats/benches/producer_tick.rs`; -[Binary delta stats](/quest/m2/stats-delta.md) gates on that profile. +one worth doing first, and could return to m1 as its own quest. + +Decided 2026-10-08: shrunk to patterns and containers, the paths that run +per announce or per frame. `hang` catalog updates and `moq-auth` token +verification run per update or per connection. - `moq-pattern`: matching swept over pattern count and path depth. Patterns shipped as `rs/moq-pattern` and `js/pattern`, so the matcher gets one bench here, not a second one elsewhere. - `moq-mux`: fMP4/CMAF and Annex-B import and export over checked-in or generated fixtures, with throughput in frames and bytes. Keep fixture - generation out of the timed region. -- `hang`: catalog encode and decode swept over rendition count, plus the - per-update cost a publisher pays. -- `moq-auth`: JWT verification per connection, swept over algorithm and claim - size. The in-band token path gets its bench with - [In-band token](/quest/m1/auth/token-in-band.md), not here. + generation out of the timed region. `rs/moq-mux/benches` holds only the + catalog churn bench today. Anything that fans out gets a sweep over both axes. Name each target after what it measures, so the CI comment reads without opening the file. From cb8551b29e4ef8715899143c8c3040aee440e1c0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:13:06 -0700 Subject: [PATCH 06/10] quest: apply audit fixes (group 6) Co-Authored-By: Claude Opus 5.5 --- quest/m1/videotoolbox-presets.md | 29 ++++++++++++ quest/m2/cpp-vcpkg.md | 4 ++ quest/m2/flate.md | 10 ++-- quest/m2/ietf-malformed-close.md | 56 ++++++++++------------ quest/m2/ietf-request-codes.md | 22 ++++++--- quest/m2/intra-refresh/h265-import.md | 2 +- quest/m2/latency-ledger.md | 30 ++++++------ quest/m2/mobile-capture-android.md | 10 ++-- quest/m2/mobile-capture-ios.md | 2 +- quest/m2/noq-socket-close.md | 8 ++-- quest/m2/obs-macos.md | 10 ++-- quest/m2/one-port/README.md | 30 ++++++------ quest/m2/one-port/shard-steering.md | 6 +-- quest/m2/one-port/tcp-demux.md | 14 +++++- quest/m2/one-port/udp-demux.md | 37 ++++++--------- quest/m2/quic-ack-hook.md | 2 +- quest/m2/quic-ack-progress.md | 6 ++- quest/m2/quic-bbr-loss-parity.md | 11 ++--- quest/m2/quic-careful-resume.md | 6 +-- quest/m2/quic-deadline.md | 12 +++-- quest/m2/quic-egress-profile.md | 18 +++---- quest/m2/quic-io-boundary.md | 6 ++- quest/m2/quic-keep-alive.md | 67 ++++++++++++--------------- quest/m2/rate-grant.md | 11 +++++ quest/m2/rate-websocket.md | 4 ++ quest/m2/relay-io-uring-package.md | 4 ++ quest/m2/rs2ts-ietf-params.md | 11 ++++- quest/m2/rtsp-import.md | 2 - 28 files changed, 251 insertions(+), 179 deletions(-) create mode 100644 quest/m1/videotoolbox-presets.md diff --git a/quest/m1/videotoolbox-presets.md b/quest/m1/videotoolbox-presets.md new file mode 100644 index 00000000000..8c3452bd206 --- /dev/null +++ b/quest/m1/videotoolbox-presets.md @@ -0,0 +1,29 @@ +# [XS] VideoToolbox honors encoder presets + +## Goal + +moq-video's VideoToolbox encoder (`rs/moq-video/src/encode/backend/videotoolbox.rs`) +maps each `Preset` to the controls VideoToolbox has, and `applied()` reports +what took effect. Today it applies real-time with no frame reordering for +every preset and reports `LowLatency`, so Balanced and Quality are silently +ignored. + +## Plan + +Decided 2026-10-08: split out of [macOS GPU input](/quest/m2/obs-macos.md), +since the mapping needs only an Apple machine, not the OBS GPU path. + +- Balanced and Quality keep frame reordering off and turn real-time off, + with quality or speed priority where the session accepts it. Follow how + the NVENC and openh264 backends map presets and report `Applied`. +- A property the session refuses falls back to the next preset down, and + `applied()` reports that, not what was asked. +- Measure per-frame encode time and bitrate at each preset on Apple + hardware, and put the numbers in the PR. + +Public API: none; `applied()` changes value for Balanced and Quality. + +## Related + +- [OBS native codecs](/quest/m1/obs-moq-video/README.md) - lists the per-backend preset gaps +- [macOS GPU input](/quest/m2/obs-macos.md) - feeds the same encoder from OBS diff --git a/quest/m2/cpp-vcpkg.md b/quest/m2/cpp-vcpkg.md index 2f2b2aa20ac..2112754e27c 100644 --- a/quest/m2/cpp-vcpkg.md +++ b/quest/m2/cpp-vcpkg.md @@ -23,6 +23,10 @@ CI on Windows, macOS, and Linux. built nightly on all three platforms; a mismatch between the port and the tarball fails the nightly, not the user. - Curated `microsoft/vcpkg` is out of scope; it wants source builds. +- Decided 2026-10-08: the tarballs this needs are the first C++ package + release, which #4079 adds as its own quest (`quest/m1/cpp-release.md`). + Once that file is on `main`, it replaces the line README as this quest's + Required entry. ## Required diff --git a/quest/m2/flate.md b/quest/m2/flate.md index 64beb25cc3b..2bc0aa0d076 100644 --- a/quest/m2/flate.md +++ b/quest/m2/flate.md @@ -10,7 +10,7 @@ the browser with `@moq/flate` and vice versa. ## Plan Decided in the 2026-09-30 audit: collapse the line into this quest and follow -the `json` namespace pattern that [#4526](https://github.com/moq-dev/moq/pull/4526) +the `json` namespace pattern that [#4519](https://github.com/moq-dev/moq/pull/4519) sets, rather than the per-wrapper siblings of the old bindings quest. `moq-flate` and `@moq/flate` own the snapshot and stream track modes @@ -19,8 +19,10 @@ already owns the per-group window a caller could otherwise desynchronize. Bind those track modes, not the bare codec: a `frame()` call across the FFI boundary invites the window desync the track modes exist to prevent. -#4526 removes moq-ffi's `publish_binary_*` and adds `MoqFlate*Producer::new` -constructed from a track producer, as `json` does. What remains: +Today moq-ffi publishes flate tracks through `publish_flate_snapshot` and +`publish_flate_stream` on the broadcast. #4519 replaces those with +`MoqFlate*Producer` constructors that wrap a track producer, as `json` does. +What remains: - moq-ffi has no consume side for flate tracks. Add consumers mirroring the `json` ones so each wrapper can read what it writes. @@ -31,7 +33,7 @@ constructed from a track producer, as `json` does. What remains: check that a wrapper-published group decodes with `@moq/flate`. Run `just test interop --all`. -Public API: additive on top of #4526. Wire, catalog, and relay: none. +Public API: additive on top of #4519. Wire, catalog, and relay: none. Compression stays invisible to `moq-net`; a compressed track is announced, routed, and cached like any other. diff --git a/quest/m2/ietf-malformed-close.md b/quest/m2/ietf-malformed-close.md index 83ca65b7e14..4bf2147cf9b 100644 --- a/quest/m2/ietf-malformed-close.md +++ b/quest/m2/ietf-malformed-close.md @@ -19,7 +19,6 @@ runner's scenario name, where it has one: - A zero-length namespace field, or a namespace or full track name over 4096 bytes. - A Request ID with the wrong parity: INVALID_REQUEST_ID. -- A GROUP_ORDER outside 1..2. - An understood key-value with a bad serialization: KEY_VALUE_FORMATTING_ERROR (`receive-understood-key-value-invalid-serialization`). @@ -31,9 +30,6 @@ runner's scenario name, where it has one: INVALID_REQUEST_ID, not a redirect. - A server SETUP carrying AUTHORITY or PATH: INVALID_AUTHORITY or INVALID_PATH. -- Repeated unknown or GREASE Setup Options are accepted - (`setup-unknown-grease-options-and-duplicates`, - `d21-grease-setup-options`). Only a repeated known option is a duplicate. - A server SETUP AUTHORIZATION TOKEN that is malformed closes with KEY_VALUE_FORMATTING_ERROR. A REGISTER that overflows our cache (size 0) falls back to USE_VALUE, as draft-21 ยง9.1.4 requires. @@ -43,14 +39,11 @@ runner's scenario name, where it has one: ## Plan -Decided in the 2026-10-06 audit: external draft PR -[#4927](https://github.com/moq-dev/moq/pull/4927) (mondain) owns two cases in -Rust and JS, GROUP_ORDER outside 1..2 and repeated unknown or GREASE Setup -Options. Do not implement them here. When #4927 merges, delete those two -cases from the Goal and their mapping lines (`group.rs`, the `parameters.rs` -GREASE entry); this quest keeps the rest. If #4927 stalls, they come back -here. Rejected: asking the contributor to retarget #4927 at this quest's -branch. +Decided 2026-10-08: start after [Parameters per +draft](/quest/m0/ietf-params-per-draft.md) +([#5028](https://github.com/moq-dev/moq/pull/5028)) lands. It rewrites the +same parameter decode and hands this quest one case: a follow-up message on +a request stream that fails to decode. Decided with the maintainer on 2026-10-04 and 2026-10-05: @@ -81,43 +74,40 @@ Where each case lives, mapped on 2026-10-04 (paths under `rs/moq-net/src/`): - The SETUP/GOAWAY uni stream runs as a task spawned inline in `run_unis` - (`ietf/session.rs`, around lines 751-874). SETUP and SETUP-parameter - decode failures there already close the session; only `run_goaway`'s - error is just logged. The gated server accept, which reads SETUP early, - calls `run_goaway` a second time (`goaway_recv`, around line 375) and - does the opposite: any error, even a stream reset, ends the session. + (`ietf/session.rs`). SETUP and SETUP-parameter decode failures there + already close the session; only `run_goaway`'s error is just logged. The + gated server accept, which reads SETUP early, calls `run_goaway` a second + time (`goaway_recv`) and does the opposite: any error, even a stream reset, ends the session. Make both sites agree, ideally by filtering inside `run_goaway`. Close on the errors `is_protocol_violation` (`ietf/subscriber.rs`) marks as the peer's fault, not on every error: a reset or transport failure on that stream must stay non-fatal, as `died_before_header` keeps it elsewhere. That fixes the second GOAWAY, the oversize URI, and an unknown type on that stream. On request - streams, an error from a follow-up message is only logged at debug in - `ietf/publisher.rs` (around line 500); promote decode errors there with - the same filter. + streams, a follow-up message (such as REQUEST_UPDATE on a SUBSCRIBE) that + fails to decode ends only that request with PUBLISH_DONE + (INTERNAL_ERROR), and the error is logged at debug in `handle_stream` + (`ietf/publisher.rs`). Close the session there instead, with the same + filter. - `died_before_header` (`ietf/session.rs`) treats a body cut short at FIN as the stream dying. A frame whose declared length passes FIN is malformed. - Responses decoded at `ietf/publisher.rs` (about lines 1858 and 1937) lack - the trailing-bytes check that the first message has. + The responses decoded in `advertise_namespace` and `update_namespace` + (`ietf/publisher.rs`) lack the trailing-bytes check that the first + message has. - Namespace bounds: `ietf/namespace.rs` checks only the 32-part limit. The track name in `ietf/subscribe.rs` is unbounded. - Request ID parity is known only in `Control::new` (`ietf/control.rs`), so thread it to where IDs are decoded. -- `ietf/group.rs` maps an invalid GROUP_ORDER, or 0, to Descending. - KV serialization errors must be told apart from other decode errors. - `From<&Error> for SessionError` (`error.rs`) maps every `Decode` error to + `From<&Error> for SessionError` (`error.rs`) maps `TooManyParameters` to + KEY_VALUE_FORMATTING_ERROR but every `Decode` error to PROTOCOL_VIOLATION, and `ietf/session.rs` and `ietf/publisher.rs` hard-code it in a few places. -- GREASE: `ietf/parameters.rs` (around line 122) keys every unknown ID as - `Unknown(u64)` in a HashMap, so any repeat fails as `Duplicate`. In this - tree that includes the plain duplicate-unknown case the report says now - passes, so check which build the report ran. - Client SETUP: `decode_peer_setup` (`ietf/session.rs`) ignores AUTHORITY and PATH and never parses the server's token. Reuse `ietf/token.rs`, which already does the server-side fallback. -- SUBSCRIBE_TRACKS is refused before its prefix is decoded - (`ietf/publisher.rs`, about lines 547 and 1609). Decode the prefix first, - then refuse. +- SUBSCRIBE_TRACKS is refused before its prefix is decoded (`handle_stream` + in `ietf/publisher.rs`). Decode the prefix first, then refuse. Test models: `an_unknown_uni_type_closes_the_session` and `an_unknown_bidi_type_closes_the_session` in `ietf/session.rs`, which drive @@ -129,6 +119,10 @@ Public API: new `SessionError` variants and `SessionCode` entries. Wire: new moq-lite session codes, with moq-transport's values; moq-transport behaviour moves closer to the drafts. +## Required + +- [Parameters per draft](/quest/m0/ietf-params-per-draft.md) - rewrites the parameter decode this builds on + ## Related - [Request tokens](/quest/m1/auth/request-token.md) - owns request-token decode and AUTH_TOKEN_CACHE_OVERFLOW diff --git a/quest/m2/ietf-request-codes.md b/quest/m2/ietf-request-codes.md index 694cfa69afe..39315b3955a 100644 --- a/quest/m2/ietf-request-codes.md +++ b/quest/m2/ietf-request-codes.md @@ -11,7 +11,8 @@ is worth and the fallback is recorded in `doc/concept/standard.md`: NOT_SUPPORTED (draft-19 and later). We advertise no MAX_FILTER_RANGES, so the default of 0 applies (draft-21 ยง9.1.6) and every Range Filter is over the limit. This covers SUBSCRIBE and FETCH alike: both refuse Range - Filters today (`ietf/publisher.rs`, around lines 605 and 1292). + Filters today (`run_subscribe_stream` and `run_fetch_stream` in + `ietf/publisher.rs`). - **Draft-21 reserved namespaces:** draft-21 ยง2.4.2 and the `.session` rules (ยง6.5) ask for REQUEST_ERROR DOES_NOT_EXIST, without passing the request to the application, for: @@ -28,8 +29,8 @@ is worth and the fallback is recorded in `doc/concept/standard.md`: matrix. - **OBJECT_DELIVERY_TIMEOUT (0x02) and SUBGROUP_DELIVERY_TIMEOUT (0x06)** on REQUEST_UPDATE are accepted and ignored, as SUBSCRIBE already does - (`ietf/subscribe.rs`). Today `ietf/request_stream.rs` refuses both as - unsupported. + (`ietf/subscribe.rs`). Today `ietf/request_stream.rs` decodes both and + marks the update unsupported. ## Plan @@ -47,10 +48,15 @@ Decided with the maintainer on 2026-10-04 and 2026-10-05: one costs more than it is worth, the fallback in the Goal applies. - **TIMEOUT, not a timer.** The 0 cap means nothing waits, so no request is ever parked. The reply depends only on whether the parameter asked for a - wait. `ietf/subscribe.rs` parses RENDEZVOUS_TIMEOUT and discards it - (around line 140); keep it as far as the publisher's track lookup - (`ietf/publisher.rs`, around line 617). `Error::Timeout` already maps to + wait. `ietf/subscribe.rs` parses RENDEZVOUS_TIMEOUT and discards it; + keep it as far as the publisher's track lookup (`run_subscribe_stream` + in `ietf/publisher.rs`). `Error::Timeout` already maps to TIMEOUT (`ietf/error.rs`). +- Decided 2026-10-08: start after [Parameters per + draft](/quest/m0/ietf-params-per-draft.md) + ([#5028](https://github.com/moq-dev/moq/pull/5028)), which rewrites the + same parameter decode and leaves the REQUEST_UPDATE delivery timeouts to + this quest. - One regression test per case, failing without its fix and asserting the draft's code, or the fallback recorded in `doc/concept/standard.md`. Mirror in `js/net/src/ietf` in the same PR. @@ -58,6 +64,10 @@ Decided with the maintainer on 2026-10-04 and 2026-10-05: Public API: none expected. Wire: none new; replies move closer to the drafts. +## Required + +- [Parameters per draft](/quest/m0/ietf-params-per-draft.md) - rewrites the parameter decode this builds on + ## Related - [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) - the session-level half of the same validator report diff --git a/quest/m2/intra-refresh/h265-import.md b/quest/m2/intra-refresh/h265-import.md index 009bb46a03f..3ffac61723f 100644 --- a/quest/m2/intra-refresh/h265-import.md +++ b/quest/m2/intra-refresh/h265-import.md @@ -28,7 +28,7 @@ a track with no keyframes at all and fails the group invariant. exactly as the H.264 quest does, sharing the measurement and catalog mutation. - Fixture: synthetic NAL sequences beside the existing suffix-SEI tests, since - x265 cannot produce intra refresh; a real NVENC HEVC clip is verified by hand + x265's intra refresh emits no recovery-point SEI; a real NVENC HEVC clip is verified by hand when the NVENC quest lands. ## Required diff --git a/quest/m2/latency-ledger.md b/quest/m2/latency-ledger.md index 0ccc99977a7..f9e29bd7b21 100644 --- a/quest/m2/latency-ledger.md +++ b/quest/m2/latency-ledger.md @@ -1,19 +1,23 @@ -# [M] Every source of playback latency is reportable, not just measurable in a test +# [M] A viewer's share of playback latency is reportable, not just measurable in a test ## Goal -A running session can report where its end-to-end audio delay went, stage by -stage, through the public API in both languages. The numbers a user reads when -debugging their own latency are the numbers the harness grades, because they -come from the same place. +A running viewer can report where its share of the audio delay went (jitter +buffer, decode, render, and output device), stage by stage, through the +public API in both languages. The numbers a user reads when debugging their +own latency are the numbers the harness grades, because they come from the +same place. Publisher and network stages, and an end-to-end total, wait for +a clock that spans the whole path; none exists today. ## Plan The audio quality harness (`test/audio-quality/`) landed on ad-hoc debug probes, which was the right trade to get it running. This quest promotes them. -- Take the stage schema the harness already defines (capture, encode, publish - flush, network, jitter buffer, decode, render) and expose it as fields of +- Decided 2026-10-08: scope to the viewer's stages. No clock spans + publisher to viewer, so the harness reports end-to-end as null. +- Take the viewer stages of the schema the harness already defines + (`jitter_buffer`, `decode`, `render`, `device`) and expose them as fields of the hang stats and feedback snapshots (`rs/hang/src/stats.rs`, `rs/hang/src/echo.rs`, and their `@moq/hang` mirrors), rather than a second readout: an observable value a stats or `.echo` track already @@ -23,13 +27,11 @@ probes, which was the right trade to get it running. This quest promotes them. each exported item: a stage nobody outside can act on stays internal. - Switch the harness over, deleting the probes it replaces. A ledger with no consumer is how this drifts from reality. -- The stages must sum to the measured end-to-end delay within a stated - tolerance, and that identity is itself a test. It only holds on the harness's - terms: one duration unit, every timestamp on a named clock, and stages as - exclusive spans that cannot both claim the same milliseconds. Inherit those - from the schema rather than restating them. An unaccounted remainder is the - bug this whole line exists to find, so it gets a name and a number rather - than being absorbed into a neighbouring stage. +- Keep the harness's terms: one duration unit, every timestamp on a named + clock, and stages as exclusive spans that cannot both claim the same + milliseconds. Inherit those from the schema rather than restating them, + so the sum-to-end-to-end identity (with its named `unaccounted` + remainder) can be added once a spanning clock exists. ## Required diff --git a/quest/m2/mobile-capture-android.md b/quest/m2/mobile-capture-android.md index 93fd8586356..f9784331796 100644 --- a/quest/m2/mobile-capture-android.md +++ b/quest/m2/mobile-capture-android.md @@ -1,9 +1,9 @@ -# [XL] Android capture and encode +# [XL] Android capture ## Goal -`moq-video` captures and encodes on Android: Camera2 or CameraX for the -camera, MediaProjection for the screen, and MediaCodec for encode and decode. +`moq-video` captures on Android: Camera2 or CameraX for the camera and +MediaProjection for the screen, feeding the existing MediaCodec encoder. ## Plan @@ -11,9 +11,7 @@ Rust owns capture and codecs on mobile, settled in the 2026-09-30 audit. MediaCo planning a second backend family. The remaining capture and native Surface integration needs NDK/JNI lifecycle, synchronization, and actual device proof. -This is the Android SDK's media path, not a Rust-only extra. `moq-kit`'s -Kotlin capture is the parallel stack the verdict retires once this lands. -Frames cross `moq-ffi` as opaque `HardwareBuffer`/`Surface` handles rather than +This is the Android SDK's media path, not a Rust-only extra. Frames cross `moq-ffi` as opaque `HardwareBuffer`/`Surface` handles rather than copies. Rust-native consumers benefit too (the same gap that made `iroh-live` reimplement the native layer). diff --git a/quest/m2/mobile-capture-ios.md b/quest/m2/mobile-capture-ios.md index e004759d667..f471518b08c 100644 --- a/quest/m2/mobile-capture-ios.md +++ b/quest/m2/mobile-capture-ios.md @@ -25,5 +25,5 @@ same everywhere. ## Related -- [Android capture and encode](/quest/m2/mobile-capture-android.md) - the other half of +- [Android capture](/quest/m2/mobile-capture-android.md) - the other half of mobile, and a much larger one diff --git a/quest/m2/noq-socket-close.md b/quest/m2/noq-socket-close.md index c5797710475..5c9ac2a90cf 100644 --- a/quest/m2/noq-socket-close.md +++ b/quest/m2/noq-socket-close.md @@ -1,8 +1,10 @@ -# [M] moq-quic releases an endpoint's socket on close +# [M] moq-tokio's QUIC endpoint releases its socket on close ## Goal -A `moq-quic` endpoint can close its UDP socket, and report when it has, without +moq-tokio's QUIC endpoint (quinn's async layer, which the hard fork imports +into moq-tokio; `moq-quic` is the sans-IO core and owns no socket) can close +its UDP socket, and report when it has, without waiting for every connection handle to drop. moq-tokio then deletes the closable socket wrapper that #4087 added to make `Listener::close` release the port. @@ -17,7 +19,7 @@ sends are dropped and receives end. Test it there and replace moq-tokio's wrappe ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - the endpoint is in-tree +- [Hard fork](/quest/m1/quic/fork/README.md) - imports the endpoint into moq-tokio ## Related diff --git a/quest/m2/obs-macos.md b/quest/m2/obs-macos.md index aa8265c9be7..737780f8abc 100644 --- a/quest/m2/obs-macos.md +++ b/quest/m2/obs-macos.md @@ -9,13 +9,13 @@ An OBS compositor frame reaches moq-video's VideoToolbox encoder without a GPU-t - Inspect OBS's OpenGL compositor, `encode_texture2`, and mac-videotoolbox input path. Determine whether the output allocation is IOSurface-backed and exportable. OBS's encoder currently copies CPU planes into its own pixel buffer; a CVPixelBuffer in moq-video alone does not remove that upstream readback. - Prefer retained IOSurface/CVPixelBuffer storage in the format VideoToolbox accepts. Otherwise prototype GPU color conversion/blit into an IOSurface-backed NV12 pool. Specify GL/Metal/CoreVideo interop, graphics-context thread affinity, completion fences, and when OBS may recycle the source. - Reuse the native PixelBuffer surface and the moq-video VideoToolbox backend. Retain the destination until encoding completes, including dropped submissions and cancellation. Bound the pool and handle resolution/HDR changes and device failure. -- Measure and map the encoder presets on VideoToolbox while on the - hardware. Today it applies real-time, no-reordering controls and reports - `LowLatency` whatever preset was asked; give Balanced and Quality the - controls VideoToolbox has (real-time off, quality or speed priority) - without reordering, and report what took. +- Decided 2026-10-08: the VideoToolbox preset mapping moved to [VideoToolbox presets](/quest/m1/videotoolbox-presets.md), which needs only an Apple machine. - Verify no CPU readback using GPU/API traces and copy counters. Compare direct import or GPU blit against the CPU baseline at 1080p60 and 4K where supported. Check decoded color bars and moving timestamps, latency percentiles, audio sync, stop/restart, and long-running pool reuse on Apple hardware. ## Required - [Encoder adapter](/quest/m1/obs-moq-video/adapter.md) - frame ownership, queue policy, packet output, and comparison baseline + +## Related + +- [VideoToolbox presets](/quest/m1/videotoolbox-presets.md) - maps Balanced and Quality on the encoder this feeds diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index fd9d8faff37..b1b652bd93f 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -4,16 +4,14 @@ A relay, or a binary embedding the gateway crates beside one, speaks everything it serves on one UDP port and one TCP port. UDP carries QUIC -(WebTransport and raw moq), STUN Binding answers, the WebRTC media path -(STUN, DTLS, SRTP) for WHIP and WHEP, and SRT. TCP carries TLS-terminated +(WebTransport and raw moq), the WebRTC media path (STUN, DTLS, SRTP) for +WHIP and WHEP, and SRT. TCP carries TLS-terminated HTTP (WebSocket qmux, WHIP and WHEP signaling, HLS, ops), RTMP, and RTMPS. -Upstream delivers the demux, the responder, and stacks that accept a fed -socket or stream; `moq-relay` itself serves QUIC, STUN, and HTTP on them, +Upstream delivers the demux and stacks that accept a fed socket or stream; +`moq-relay` itself serves QUIC and HTTP on them, and an embedder such as moq.pro's edge wires WebRTC, RTMP, and SRT, which the relay binary has never spoken. An operator opens 443 twice and is done; a client on -a network that permits only 443 reaches every protocol; a P2P client names -the relay as its STUN server and gets the lowest-RTT reflexive candidate -there is. +a network that permits only 443 reaches every protocol. The demux is a `moq-sock` primitive over the tokio backends. [`moq-uring`'s workers](/quest/m2/uring-demux.md) host it later; that is not @@ -68,13 +66,13 @@ decided. ### STUN -A Binding request is answered with a Binding success carrying -XOR-MAPPED-ADDRESS, no authentication, no other methods. The response is -larger than a minimal request (32 or 44 bytes against 20), so a spoofed -source is a small amplifier; a per-source token bucket and a global responder -budget bound it, and the drop counter makes it visible. Use str0m's -`StunMessage`, already a dependency, or a maintained STUN crate; do not -hand-roll the codec. +Decided 2026-10-08: the public STUN responder is left to P2P (m3), its +only consumer. Here, a Binding request carrying USERNAME is an ICE check +and goes to WebRTC; any other is dropped and counted. Notes for whoever +plans the responder: answer Binding with XOR-MAPPED-ADDRESS only; the reply +outsizes the request (32 or 44 bytes against 20), so bound spoofed +amplification with a per-source token bucket and a global budget; use a +maintained STUN crate, not a hand-rolled codec. ### TCP @@ -91,13 +89,13 @@ pre-accepted streams can stand behind. ## Required - [Steer only QUIC by connection ID](/quest/m2/one-port/shard-steering.md) - QUIC-bit greasing goes off and the reuseport filter leaves RTP, SRT, and STUN flows on one shard each -- [UDP demux](/quest/m2/one-port/udp-demux.md) - one socket carries QUIC and STUN answers, with a WebRTC hook for embedders +- [UDP demux](/quest/m2/one-port/udp-demux.md) - one socket carries QUIC, with a WebRTC hook for embedders - [WebRTC on the shared socket](/quest/m2/one-port/rtc-feed.md) - `moq-rtc` serves WHIP and WHEP media from the WebRTC hook and pins ICE tuples - [TCP acceptor](/quest/m2/one-port/tcp-demux.md) - one listener carries TLS-terminated HTTP, RTMP, and RTMPS - [SRT on the shared socket](/quest/m2/one-port/srt-demux.md) - moq-srt drives `srt-protocol` on demuxed packets and the flow table pins its 4-tuples ## Related -- [P2P](/quest/m3/p2p/README.md) - the client that names the relay as its STUN server +- [P2P](/quest/m3/p2p/README.md) - the only consumer of a public STUN responder, which it plans when it needs one - [One port on the io_uring workers](/quest/m2/uring-demux.md) - the io_uring workers host the UDP demux - [Stream sessions](/quest/m2/uring-tcp/README.md) - the io_uring workers that would host the TCP acceptor later diff --git a/quest/m2/one-port/shard-steering.md b/quest/m2/one-port/shard-steering.md index 8ca32d85f75..cd3e6cc6393 100644 --- a/quest/m2/one-port/shard-steering.md +++ b/quest/m2/one-port/shard-steering.md @@ -12,8 +12,8 @@ off so their peers' short headers stay recognizable. ## Plan -The filter (`moq-sock`'s `shard` module today, `moq-quic-udp` once -[quic/shard](/quest/m1/quic/shard.md) moves it) reads byte 1 or byte 6 by the +The filter (`moq_sock::shard`, which stays in `moq-sock` under +[quic/shard](/quest/m1/quic/shard.md)) reads byte 1 or byte 6 by the long-header bit and reduces it modulo the group size. A non-QUIC datagram goes through the same arithmetic: RTP and RTCP are steered by timestamp and SSRC bytes and scatter across shards, SRT data is steered by a sequence @@ -76,4 +76,4 @@ talking to each backend receives transport parameters without ## Related -- [Shard the QUIC endpoint](/quest/m1/quic/shard.md) - moves the filter this edits into `moq-quic-udp` +- [Shard the QUIC endpoint](/quest/m1/quic/shard.md) - makes `moq_sock::shard` the one filter both runtimes use, and moves the CID generator into `moq-quic` diff --git a/quest/m2/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md index 4b973b9584a..2047fa74973 100644 --- a/quest/m2/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -27,7 +27,18 @@ onto its own task with a bounded read timeout; that task peeks, optionally terminates TLS, and yields `Accepted`. An idle or slow client stalls only its own task, so a peer that connects and sends nothing cannot block later accepts. The peek is non-destructive on `TcpStream` and on the rustls -stream alike. +stream alike. Reuse the handshake bound `listen.timeout` already sets +(`moq_tokio::listen::Config::timeout`) rather than a new knob. + +The TLS arm also carries `tls://` qmux, served today by its own `listen.tcp` +listener with TLS. It negotiates a moq ALPN in the TLS handshake, so split +the decrypted arm on ALPN: a moq ALPN goes to the qmux server, and HTTP +ALPNs (or none) go to the router. + +Keep the accepted `TcpStream`'s handle reachable after it is boxed: the +relay already captures socket stats at accept for qmux (`SocketStats` in +`web.rs`), and [WebSocket bitrate caps](/quest/m2/rate-websocket.md) set +socket buffer sizes on the same socket. Tests: an HTTP request, a WebSocket upgrade, a raw RTMP C0, and an RTMPS C0 against one listener each land in the right arm. @@ -35,3 +46,4 @@ against one listener each land in the right arm. ## Related - [UDP demux](/quest/m2/one-port/udp-demux.md) - the UDP half +- [WebSocket bitrate caps](/quest/m2/rate-websocket.md) - sizes the kernel buffers of the socket this acceptor boxes diff --git a/quest/m2/one-port/udp-demux.md b/quest/m2/one-port/udp-demux.md index 3000f584b68..c200f3f9184 100644 --- a/quest/m2/one-port/udp-demux.md +++ b/quest/m2/one-port/udp-demux.md @@ -1,12 +1,11 @@ -# [L] UDP demux +# [M] UDP demux ## Goal -`moq-relay` reads one UDP socket and serves QUIC and STUN Binding answers from -it. A P2P client can list `stun::`. The WebRTC -media path is an embedder hook: the demux hands its class to an embedder such -as moq.pro's edge, which feeds it to `moq-rtc`, since `moq-relay` serves no -WHIP or WHEP. +`moq-relay` reads one UDP socket and serves QUIC from it. The WebRTC media +path (DTLS, RTP, and ICE's STUN checks) is an embedder hook: the demux hands +its class to an embedder such as moq.pro's edge, which feeds it to +`moq-rtc`, since `moq-relay` serves no WHIP or WHEP. ## Plan @@ -27,18 +26,12 @@ QUIC: `moq-tokio`'s noq server takes the virtual socket through `new_with_abstract_socket`. QUIC-bit greasing is already off, from [shard steering](/quest/m2/one-port/shard-steering.md). -STUN: a `stun` virtual socket answered by a small responder in `moq-sock`, -Binding request to Binding success with XOR-MAPPED-ADDRESS, str0m's -`StunMessage` or a maintained crate for the codec, behind a per-source token -bucket and a global budget since the answer is up to 2.2 times the request. -The per-source table is fixed-capacity with expiry, or a hashed/stateless -limiter; spoofed sources cannot grow it. -An ICE connectivity check is also a Binding request, so the STUN class splits -on the USERNAME attribute: a request carrying one belongs to a WebRTC session -and goes to the mux, which reads the local ufrag from it; a request without -one is a public query and goes to the responder. Public STUN clients never -send USERNAME and ICE agents always do. -Off by default in `moq-relay`, on with `--stun`. +STUN: an ICE connectivity check is a Binding request carrying USERNAME, so +it goes to the WebRTC hook, whose mux reads the local ufrag from it. A +Binding request without USERNAME is a public query; drop and count it. +Decided 2026-10-08: the public STUN responder is left to the P2P line +(m3), its only consumer, so `moq-sock` takes no STUN codec +dependency (str0m included). WebRTC: DTLS, RTP, and USERNAME-carrying STUN go to a `webrtc` hook that `moq-relay` leaves unconsumed and an embedder takes: the datagrams, a send @@ -46,14 +39,14 @@ path through the shared socket, and a way to pin a 4-tuple to WebRTC in the flow table and release it. [WebRTC on the shared socket](/quest/m2/one-port/rtc-feed.md) makes `moq-rtc` consume it. -Decided in the 2026-09-30 audit: narrowed to QUIC plus STUN in the relay, +Decided in the 2026-09-30 audit: the relay itself serves only QUIC here, because `moq-relay` has no `moq-rtc` dependency and serves no WHIP or WHEP. Decided 2026-10-05: feeding `moq-rtc` moved from the embedder to rtc-feed, because `moq-rtc` is an upstream, generic crate. Tests: a unit test per first-byte class routes to the right virtual socket, -including the WebRTC hook; an integration test runs a QUIC client and a STUN -Binding round trip against one bound port. `moq-relay` docs list the port once. +including the WebRTC hook; an integration test runs a QUIC client against +the demuxed port. `moq-relay` docs list the port once. ## Required @@ -61,5 +54,5 @@ Binding round trip against one bound port. `moq-relay` docs list the port once. ## Related -- [P2P](/quest/m3/p2p/README.md) - the client side of the STUN answer +- [P2P](/quest/m3/p2p/README.md) - the only consumer of a public STUN responder, which it plans when it needs one - [One port on the io_uring workers](/quest/m2/uring-demux.md) - runs this classifier and flow table on the io_uring workers diff --git a/quest/m2/quic-ack-hook.md b/quest/m2/quic-ack-hook.md index 80ec62cb024..7b5d9ad9802 100644 --- a/quest/m2/quic-ack-hook.md +++ b/quest/m2/quic-ack-hook.md @@ -26,7 +26,7 @@ fn poll_acked(&mut self, cx: &mut Context, offset: u64) -> Poll deadline - rtt`, send an `IMMEDIATE_ACK` (the - ACK-frequency extension noq already implements) on the next packet and arm + ACK-frequency extension `moq-quic` already implements) on the next packet and arm a shortened probe at `max(deadline - rtt - now, min_pto)`. Never probe past the congestion window; the probe is a scheduling choice, not extra credit. +- moq-net cannot call `moq-quic` directly, so the deadline crosses its own + `transport::poll::SendStream` trait, the way + [the ACK hook](/quest/m2/quic-ack-hook.md) does: a method whose default + reports unsupported, implemented by the moq-tokio and moq-uring adapters + over `moq-quic`. A backend without it sends as today. - moq-net: the per-group `GroupServe` machine in the lite and IETF publishers (`lite/publisher.rs`, `ietf/publisher.rs`) sets the deadline - when it opens the stream, from the subscription's latency target and the + when it opens the stream, from the subscription's `max_delay` and the group's expiry, whichever is sooner; a subscription with neither sets none. The reset error code maps to the existing group-expired code on the MoQ wire, so a viewer sees the same signal it sees for a relay-side expiry today. @@ -54,6 +59,7 @@ Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. - [QUIC GCC](/quest/m3/quic-gcc.md) - its receive timestamps give a measured forward delay that replaces the half-RTT estimate +- [ACK hook](/quest/m2/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic` - [Discover media headroom](/quest/m2/quic-probe.md) - can reuse retransmission machinery if redundant capacity probes prove worthwhile - [noq#813](https://github.com/n0-computer/noq/issues/813) - the per-stream deadline proposal to n0 diff --git a/quest/m2/quic-egress-profile.md b/quest/m2/quic-egress-profile.md index 1f3063e1f51..8ca35ce5529 100644 --- a/quest/m2/quic-egress-profile.md +++ b/quest/m2/quic-egress-profile.md @@ -20,12 +20,11 @@ workers versus io_uring workers, with the existing profiling captures: the io_uring path queues one SQE per train and submits them together. Count syscalls per second and CPU per Gbps, and confirm from the io_uring worker's `enters` counter that the ring already amortizes. -- Allocations: noq's `SendBuffer` keeps a write above 1452 bytes as the - caller's `Bytes` and coalesces smaller writes into a `BytesMut`. Count - allocations and bytes copied per frame, split by frame size, so the share - of sub-threshold copies is known. -- Bursts: noq paces inside `poll_transmit` on both runtimes (#4400, - rs/moq-uring/src/quic/noq/connection.rs:814-817), so the only open question +- Allocations: `moq-quic`'s `SendBuffer` keeps each write as the caller's + `Bytes`, with no coalescing copy. Count allocations and bytes copied per + frame above it, split by frame size, so any copy left is located. +- Bursts: the QUIC connection paces inside `poll_transmit` on both runtimes + (#4400; `moq-quic`'s `connection/pacing.rs`), so the only open question is whether a released GSO train leaves the NIC as a burst the bottleneck cannot absorb. On a netem bottleneck, compare inter-packet gaps and queue occupancy for a 64-segment train against the same bytes paced at the @@ -37,8 +36,10 @@ Then, only where the profile shows a cost: train ready across connections in one call, falling back to per-train `sendmsg` on partial failure the way the GSO fallback does. - A `BufFactory`-style seam on `SendBuffer` in the fork that takes buffers - from a pool sized from the send window and returns them on ACK. -- `SCM_TXTIME` stamps, one per train, at the time noq's pacer would have + from a pool sized from the send window and returns them on ACK. Design it + with [the I/O boundary redesign](/quest/m2/quic-io-boundary.md), which + reworks the same transmit buffers. +- `SCM_TXTIME` stamps, one per train, at the time the pacer would have released it, tested under both `etf` and `fq`. The socket is shared across connections per worker, so `SO_MAX_PACING_RATE` cannot express per-connection pacing. Measure on a real NIC as well as loopback, since @@ -54,6 +55,7 @@ hosts need. ## Related +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - redesigns the transmit buffers the pool lever would feed - [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - zero-copy on the same trains - [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - diff --git a/quest/m2/quic-io-boundary.md b/quest/m2/quic-io-boundary.md index 69b8beef509..333ed07f00f 100644 --- a/quest/m2/quic-io-boundary.md +++ b/quest/m2/quic-io-boundary.md @@ -27,8 +27,12 @@ and `SENDMSG_ZC` ([#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp- build on the transmit contract. Report relay CPU per Gbps before and after on the same workloads. +## Related + +- [Relay egress profile](/quest/m2/quic-egress-profile.md) - its send-buffer pool lever touches the same `SendBuffer` seam + ## Required - [Hard fork](/quest/m1/quic/fork/README.md) - the redesign breaks `moq-quic`'s API -- [Relay profiles](/quest/m1/performance-profiles.md) - the redesign targets measured costs +- [Relay profiling recipe](/quest/m1/perf/lock-profile.md) - the captures that rank the candidates - [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - the cheap wins land first, so the profile shows what is left diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index 52f7e80e969..e417872fe42 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -1,50 +1,43 @@ -# [S] Keep-alive by deadline +# [S] Keep-alive derives from the idle timeout ## Goal -A connection sends a PING only when its idle deadline is near, never on a -fixed clock. An idle connection with a 10 s idle timeout costs one packet per -roughly 10 s minus a few PTOs; a busy connection costs none. The -`keep_alive` setting on `quic::Client` and `quic::Server` becomes an optional -maximum, default none. Redefining it is a config and CLI break. +The QUIC keep-alive interval defaults to a value derived from the idle +timeout, not a fixed 3 s, so changing `quic.idle_timeout` never needs a +matching hand-tuned `quic.keep_alive`. An explicit `quic.keep_alive` +(`moq_tokio::quic::Config::keep_alive`) stays an override, for a NAT binding +that lives shorter than the idle timeout, and `0s` still disables it. ## Plan -noq-proto arms `Timer::KeepAlive` at `now + keep_alive_interval` on every -authenticated packet (`connection/mod.rs`, `reset_keep_alive`), so the -interval is a second, unrelated clock the operator has to keep below the idle -timeout by hand. Replace it in the fork: - -- The deadline is the negotiated idle timeout, the minimum of the local - setting and the peer's `max_idle_timeout` transport parameter, measured - from the last packet sent or received. Fire the PING at - `deadline - 3 * pto()`, bounded below at one PTO, so a lost PING and its - probe still land before the peer's timer. -- Keep `keep_alive_interval` as a maximum: `None` means "as late as - possible"; a value means "no later than this", for a NAT binding with a - shorter life than the idle timeout. That is the only knob. - -moq-tokio's `quic.keep_alive` (`rs/moq-tokio/src/quic.rs`) in the `[quic]` -sections, CLI flags, and env vars becomes that optional maximum, default none, -documented in `doc/bin/relay/config.md` for NAT-sensitive deployments. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, -5 s ping and 30 s deadline) already has this shape; make its wording match. - -iroh stays on upstream noq, which the fork does not touch, and -[Listener deadlines](/quest/m1/listener-deadlines.md) wires `quic.keep_alive` -into iroh's fixed `keep_alive_interval`. Decided in the 2026-10-05 audit: -when the maximum is `None`, iroh keeps a fixed interval derived from the idle -timeout, so an iroh session never loses its keep-alive. Rejected: requiring -an explicit maximum for iroh. - -Tests: an idle connection survives an idle timeout with exactly one PING per -period; a busy connection sends none; a lost PING is probed before the -deadline; the maximum knob shortens the period. +Decided 2026-10-08: shrunk to deriving the default. Replacing the keep-alive +timer with a PING fired near the idle deadline was not worth a config and +CLI break. + +Today `moq-quic` arms `Timer::KeepAlive` a fixed interval after each packet +(`reset_keep_alive`), and moq-tokio's `DEFAULT_KEEP_ALIVE` is a hand-picked +fraction of `DEFAULT_IDLE_TIMEOUT`. Derive the interval from the negotiated +idle timeout instead (the smaller of ours and the peer's `max_idle_timeout`, +which the connection already holds), keeping it under a third so a lost PING +and its probe land before the peer's timer. Pick how the config expresses +"derived" (an `Option`, or a sentinel) by what reads clearest in the +`[quic]` section and CLI; document it in `doc/bin/relay/config.md`. + +iroh stays on upstream noq. [Listener deadlines](/quest/m1/listener-deadlines.md) +wires `quic.keep_alive` into iroh's `keep_alive_interval`; with no explicit +value, iroh gets the same derivation from its idle timeout. The qmux +WebSocket keep-alive (`qmux::ws::KeepAlive`, a fixed 5 s ping and 30 s +deadline) is a different mechanism and stays as is. + +Tests: the derived interval follows a changed idle timeout, including a peer +that advertises a shorter one; an idle connection survives with the +default; an explicit value wins; `0s` disables. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- [Hard fork](/quest/m1/quic/fork/README.md) - the derivation lands in `moq-quic`, not the frozen fork ## Related - [Listener deadlines](/quest/m1/listener-deadlines.md) - wires the same setting into iroh's fixed interval -- [noq#810](https://github.com/n0-computer/noq/issues/810) - the proposal to n0; flub and matheus23 asked to keep a cap for NAT bindings, which the optional maximum covers +- [noq#810](https://github.com/n0-computer/noq/issues/810) - the deadline-driven proposal to n0; flub and matheus23 asked to keep a cap for NAT bindings, which the override covers diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index fb89c8db7a7..c85b56ffc8e 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -15,9 +15,20 @@ expiry; add the two rates in the same nested shape as the and container overhead under the cap. A grant change (refresh, union) re-clamps a live encoder. +The grant's wire shape is specified in `drafts/draft-lcurley-moq-auth.md` +(which the in-band auth line adds); update it in the same PR and run +`just drafts check`. Wire work targets the wip lite version until it is cut +(decided 2026-10-05, see [AUTH on the wip version](/quest/m1/auth/wip-version.md)), +and the Auth Stream exists only there, so the rates ride only the wip +version's grant. + Tests: a capped session's grant carries the rates; the publisher's video target never exceeds the cap minus overhead; a raised cap lets it climb back. +Public API: the grant types in `rs/moq-auth` and `js/auth` gain the two +rates, and the publishers gain a clamp. Wire: the AUTH grant gains optional +rates, on the wip lite version only. + ## Required - [In-band auth](/quest/m1/auth/README.md) - the AUTH grant this extends diff --git a/quest/m2/rate-websocket.md b/quest/m2/rate-websocket.md index 3b0c33b1f75..62050a53dfb 100644 --- a/quest/m2/rate-websocket.md +++ b/quest/m2/rate-websocket.md @@ -39,3 +39,7 @@ live session applies. ## Required - [Bitrate claim](/quest/m2/rate-claim.md) - the cap this enforces + +## Related + +- [TCP acceptor](/quest/m2/one-port/tcp-demux.md) - boxes the accepted stream, so it must keep the socket handle these buffer sizes need diff --git a/quest/m2/relay-io-uring-package.md b/quest/m2/relay-io-uring-package.md index f296184bf05..008aeea6fce 100644 --- a/quest/m2/relay-io-uring-package.md +++ b/quest/m2/relay-io-uring-package.md @@ -18,6 +18,7 @@ ships, not the default. served, the `[quic]` tuning honored, and closes delivered. Offering a flag that silently serves less than the default runtime would be worse than not offering it. Performance work is not a prerequisite. + Decided 2026-10-08: that parity is the Required list below. - Enable the feature only on Linux targets. Confirm the zigbuild glibc 2.34 build still links and that nothing new is needed at runtime. - A kernel without the io_uring features the workers need must make @@ -35,3 +36,6 @@ Public API: none. Wire: none. - [moq-transport on io_uring](/quest/m1/uring-ietf.md) - a packaged relay must not drop protocols when the ring is on +- [Dropped session close](/quest/m1/uring-drop-close.md) - closes are delivered when a session is dropped on the ring +- [Listener deadlines](/quest/m1/listener-deadlines.md) - the io_uring workers apply `listen.timeout` like the default runtime +- [One port on the io_uring workers](/quest/m2/uring-demux.md) - a one-port config is served on the ring too diff --git a/quest/m2/rs2ts-ietf-params.md b/quest/m2/rs2ts-ietf-params.md index cd985e99a05..173a32012bb 100644 --- a/quest/m2/rs2ts-ietf-params.md +++ b/quest/m2/rs2ts-ietf-params.md @@ -13,10 +13,17 @@ The VarInt codec removed Encode/Decode on primitives, but `ietf/parameters.rs` still implements its own `Param` trait on them, which rs2ts can only translate with dictionary passing. Replace the impls with methods on the concrete `Decoder`/`Encoder` (or on the parameter kinds), keeping the draft-14..16 varint cast and the draft-17+ forms byte for -byte. Benchmark IETF message encode and decode before and after with -`--bench codec`. +byte. Keep the per-draft parameter lists and the unknown and misplaced +parameter rules that [Parameters per draft](/quest/m0/ietf-params-per-draft.md) +([#5028](https://github.com/moq-dev/moq/pull/5028)) adds; this is a +refactor, not a behavior change. Benchmark IETF message encode and decode +before and after with `--bench codec`. Public API: none (`ietf` parameters are crate-private). Wire: none. Decided in the 2026-09-30 audit: deferred to m2 with generated IETF, its only consumer, until generated lite passes its go/no-go. + +## Related + +- [Parameters per draft](/quest/m0/ietf-params-per-draft.md) - the per-draft behavior this keeps byte for byte diff --git a/quest/m2/rtsp-import.md b/quest/m2/rtsp-import.md index cacf1f02fa5..237c904354b 100644 --- a/quest/m2/rtsp-import.md +++ b/quest/m2/rtsp-import.md @@ -86,8 +86,6 @@ Public API: the `moq-rtsp` crate and the `moq import rtsp` subcommand. Wire: none. Both are additive, so it is backported to `release` once it lands on main. -The moq.pro guide link below resolves once moq.pro#2210 merges. - ## Required - [Shared import clock](/quest/m1/shared-clock.md) - two sessions importing into one caller broadcast share one timeline From e15d2042e6e90efb19e3d75047218a4484e605ac Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 00:13:12 -0700 Subject: [PATCH 07/10] quest: apply audit fixes (group 7) Co-Authored-By: Claude Opus 5.5 --- quest/m1/drop-loud.md | 39 ++++++++++++++++ quest/m2/starvation-frames.md | 6 +++ quest/m2/teleop/README.md | 25 +++++----- quest/m2/teleop/arbitration.md | 3 ++ quest/m2/teleop/robot.md | 6 ++- quest/m2/ts-eac3.md | 6 +-- quest/m2/ts-hitless.md | 5 +- quest/m2/uring-demux.md | 16 ++++--- quest/m2/uring-tcp/README.md | 12 +++-- quest/m2/uring-tcp/relay.md | 9 ++-- quest/m2/video-codec-coverage.md | 5 +- quest/m2/watch-data-sync.md | 4 ++ quest/m2/watch-decode-gate.md | 15 ++++-- quest/m3/archive-paced-replay.md | 2 +- quest/m3/captions-cea.md | 4 ++ quest/m3/closure-counters.md | 35 +++++++------- quest/m3/cpp-conan.md | 5 +- quest/m3/cut-through/README.md | 29 ++++++------ quest/m3/cut-through/bench.md | 14 +++--- quest/m3/emsg.md | 1 + quest/m3/flv-script.md | 4 ++ quest/m3/id3.md | 4 ++ quest/m3/interop-runner-approval.md | 27 ++++++++--- quest/m3/ladder/controller.md | 2 +- quest/m3/p2p/README.md | 31 ++++++------- quest/m3/p2p/cost-scopes.md | 2 + quest/m3/p2p/harness.md | 15 +++--- quest/m3/p2p/peer-grant.md | 1 + quest/m3/p2p/signal.md | 8 ++-- quest/m3/p2p/transport.md | 9 ++-- quest/m3/p2p/watch.md | 2 +- quest/m3/p2p/webrtc.md | 6 +-- quest/m3/quic-gcc.md | 71 +++++++++++------------------ quest/m3/routing-cost-domains.md | 10 ++-- quest/m3/stats-encoder-feedback.md | 19 ++++---- quest/m3/teleop-mavlink.md | 10 ++++ quest/m3/teleop-proof.md | 17 +++++-- quest/m3/video-embedded.md | 30 ++++++------ quest/m3/video-hardware-access.md | 23 +++++++--- quest/m3/video-hardware.md | 11 ++--- quest/m4/safari-webtransport.md | 11 ++++- 41 files changed, 337 insertions(+), 217 deletions(-) create mode 100644 quest/m1/drop-loud.md diff --git a/quest/m1/drop-loud.md b/quest/m1/drop-loud.md new file mode 100644 index 00000000000..b3aa50b42a1 --- /dev/null +++ b/quest/m1/drop-loud.md @@ -0,0 +1,39 @@ +# [S] Fail loud on dropped timed metadata + +## Goal + +Import stops dropping timed metadata silently. FLV script tags (RTMP and FLV +import) and fMP4 `emsg` boxes are counted and reported when discarded, so an +operator can tell that a source carried metadata MoQ did not deliver. Real +carriage stays with the m3 timed-metadata quests. + +## Plan + +Today `rs/moq-mux/src/container/flv/import.rs` matches `TAG_SCRIPT => {}`, +and the fMP4 importer's box loop (`rs/moq-mux/src/container/fmp4/import.rs`) +sends `emsg` to the catch-all arm that skips unknown atoms, both without a +log line. + +Decided 2026-10-08, from the quest audit: a small m1 quest, since the +carriage quests are parked in m3 with no consumer and the silent drop +violates fail-loud in the meantime. + +Recommendation: count and warn rather than refuse. Every RTMP publisher sends +`onMetaData`, so refusing a script tag would break every RTMP ingest. Keep a +per-importer count by kind (script tag, `emsg`), warn the first time each kind +drops on a broadcast with the count readable afterwards, and leave the debug +line for genuinely unknown tags. If a refusal fits a narrower case better +(for example an `emsg` scheme an application declared it needs), say so in +the PR. + +Test: an FLV clip with `onMetaData` and an fMP4 fragment with an `emsg` box +each import, warn once, and report a count of what was dropped. + +Public API: possibly an accessor for the counts. Wire: none. + +## Related + +- [fMP4 emsg](/quest/m3/emsg.md) - carries the boxes this counts +- [FLV script tags](/quest/m3/flv-script.md) - carries the tags this counts +- [ID3 catalog section](/quest/m3/id3.md) - typed carriage for one `emsg` payload +- [CEA-608/708 extraction](/quest/m3/captions-cea.md) - the other timed-metadata carrier, kept in the SEI rather than dropped diff --git a/quest/m2/starvation-frames.md b/quest/m2/starvation-frames.md index 60e7638f5c5..7c18b843c1e 100644 --- a/quest/m2/starvation-frames.md +++ b/quest/m2/starvation-frames.md @@ -45,6 +45,10 @@ Decided in the 2026-09-30 audit: moved to m2. The group-granularity sampler from the parent quest answers the m1 question, and this waits on the m2 ACK hook. +Decided 2026-10-08: the group-granularity sampler is the egress lag histogram +from the QoS line, which so far exists only on its line branch, so that quest +is Required. + Tests: the frontier tracking frame ends under a peer that acknowledges in bursts, with interval samples landing one bucket lower than group-granularity tracking of the same run; a reset mid-group attributing only the @@ -56,3 +60,5 @@ unsupported. - [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the hook this samples through +- [Egress lag histogram](/quest/m1/qos/lag-histogram.md) - the + group-granularity sampler and starvation histogram this refines diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index adf18b252d3..cd652b644a6 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -13,8 +13,13 @@ partner shows up. Decided in the 2026-09-30 audit: the ROS 2 bridge was deleted, cross-track correlation folded into [robot](/quest/m2/teleop/robot.md), V4L2-M2M encoding folded into [CLI packaging](/quest/m1/cli-packaging.md), and the MAVLink -bridge, SITL proof, and browser package moved to m3. Kyber is a competitor -with proprietary framing, not a transport we replace. +bridge and SITL proof moved to m3. Kyber is a competitor with proprietary +framing, not a transport we replace. + +Decided 2026-10-08: the robot primitive and operator arbitration are parked in +m3 until a teleoperation consumer needs them, so the line's m2 work is the +use-case docs. The browser package was deleted; its shared schema folds into +the [SITL proof](/quest/m3/teleop-proof.md). ## Plan @@ -84,17 +89,17 @@ stating plainly because it is what a builder is comparing against. ## Required -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - a `moq-robot` - crate carrying the track shapes and discovery every teleoperated machine - needs; gates the rest -- [Operator arbitration](/quest/m2/teleop/arbitration.md) - exactly one - controller commands a vehicle at a time, with explicit handoff and a stated - authorization boundary - [Teleoperation use-case docs](/quest/m2/teleop/docs.md) - `doc/concept/use-case/` gains a teleoperation page, with a runnable non-media example beside it ## Related +- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - a `moq-robot` + crate carrying the track shapes and discovery every teleoperated machine + needs, parked in m3 +- [Operator arbitration](/quest/m2/teleop/arbitration.md) - exactly one + controller commands a vehicle at a time, with explicit handoff and a stated + authorization boundary, parked in m3 - [e2ee](/quest/m1/e2ee/README.md) - the answer for a protected control link - [Media stats](/quest/m1/stats/schema.md) - publisher-reported stats on a catalog-announced track (moq#2734); teleop's latency instrumentation @@ -107,7 +112,3 @@ stating plainly because it is what a builder is comparing against. parked until a real ArduPilot user or partner - [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot SITL flown from a browser, parked with the bridge -- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - - `@moq/robot` mirroring the Rust crate, parked with the bridge -- [Text availability](/quest/m3/text-schema.md) - a text track publishes its - own availability index instead of copying the media timeline diff --git a/quest/m2/teleop/arbitration.md b/quest/m2/teleop/arbitration.md index a00331745a6..1badd9e38ff 100644 --- a/quest/m2/teleop/arbitration.md +++ b/quest/m2/teleop/arbitration.md @@ -8,6 +8,9 @@ assumed. ## Plan +Decided 2026-10-08: parked in m3 with [robot](/quest/m2/teleop/robot.md), +which it builds on. + `moq-boy` merges every viewer's input, which is right for crowd control and wrong for a vehicle. Arbitration is the part of a teleoperation stack that cannot be lifted from it: one controller is active, the others are read-only, diff --git a/quest/m2/teleop/robot.md b/quest/m2/teleop/robot.md index 0b0d06b1056..83ab507c65e 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m2/teleop/robot.md @@ -8,6 +8,10 @@ the gate for the rest of the questline. ## Plan +Decided 2026-10-08: parked in m3. No teleoperation consumer needs the crate +yet; OneTooMany's telemetry need is [data sync](/quest/m2/watch-data-sync.md), +not this primitive. + ### Direction The operator publishes and the robot subscribes. The robot serves its own @@ -52,7 +56,7 @@ The framing is where the guarantee lives, not the subscription flags: on it would not be reliable, which is why the reliable class is a single group instead. - What makes the lossy class lossy on the wire is the publisher's - `Info::max_age`: `evict_expired` aborts an aged-out group with `Error::Old` + `Info::max_age`: `evict_expired_scan` aborts an aged-out group with `Error::Old` (`rs/moq-net/src/model/track.rs`), and an abort resets the QUIC stream, so stale bytes stop being retransmitted. - A subscriber cannot weaken either class. `clamp_combined` diff --git a/quest/m2/ts-eac3.md b/quest/m2/ts-eac3.md index fc46effa888..d7ee41f0b77 100644 --- a/quest/m2/ts-eac3.md +++ b/quest/m2/ts-eac3.md @@ -10,15 +10,15 @@ the fixed-delay export (#4645). ## Plan -Found in #4645: E-AC-3 carried as DVB private data still goes out unsplit, +Found in the fixed-delay export review: E-AC-3 carried as DVB private data still goes out unsplit, with no buffer model, so a multi-frame PES can overflow B. -- Split it the way #4645 splits DVB AC-3, but per access unit: an +- Split it the way `rs/moq-mux/src/container/ts/export.rs` splits DVB AC-3, but per access unit: an independent sync frame plus the dependent substreams that follow it share one presentation interval (ETSI TS 102 366 Annex E), so they go out in one PES on one decode time. Read sizes from each sync frame's `frmsiz`, and drop a frame shorter than its header says. -- The buffer is the DVB one, not ATSC's: #4645's 12,896 B is A/52 Annex G's +- The buffer is the DVB one, not ATSC's: the export's 12,896 B is A/52 Annex G's for `stream_type` 0x87, and DVB AC-3 uses 5,696 B. Take the E-AC-3 value from ETSI TS 101 154, cite the clause, and add it to the schedule's per-PID admission and to the `tstd` model in `compliance.py`, which diff --git a/quest/m2/ts-hitless.md b/quest/m2/ts-hitless.md index a055a89fc30..1b578656bd0 100644 --- a/quest/m2/ts-hitless.md +++ b/quest/m2/ts-hitless.md @@ -24,8 +24,9 @@ requirement, so this waits until the T-STD line settles. moves to its own PID, because a discontinuity flag on the PCR PID would declare a time-base break. Loss is still detected within a group. - Once anchored identically, both legs must make the same skip decision and - lay out the same slots. t0ms's `two_legs_render_a_skip_the_same_way` stays - ignored in #4645 until this lands. With the audio late, it also showed a + lay out the same slots. t0ms's `two_legs_render_a_skip_the_same_way` + (`rs/moq-mux/src/container/ts/export_timing_test.rs`) stays ignored until + this lands. With the audio late, it also showed a PES header byte that differs at the skip; find and fix that. - Test with mocked time: - two legs, joined a second apart, give byte-identical output including diff --git a/quest/m2/uring-demux.md b/quest/m2/uring-demux.md index 9c878a3b549..541158d5e4d 100644 --- a/quest/m2/uring-demux.md +++ b/quest/m2/uring-demux.md @@ -4,8 +4,7 @@ `moq-uring`'s workers host the one-port demux, so a relay on the ring serves everything the tokio backend does on its one UDP port: QUIC on the worker, -and STUN, WebRTC media, and SRT reaching their tokio stacks from the same -socket. +and WebRTC media and SRT reaching their tokio stacks from the same socket. ## Plan @@ -18,12 +17,17 @@ one-port. The uring rollout is a performance change and the caps are a customer feature, and moq.pro already ranks one-port above its uring rollout. +Decided 2026-10-08: the UDP demux shrinks to QUIC plus the WebRTC hook, and +the public STUN responder moves to the m3 P2P line, so the ring carries no +STUN responder class either. An ICE Binding request is WebRTC traffic and +follows that class. + Each worker's endpoint receives a batch and feeds every segment straight to the QUIC endpoint. The classifier and flow table from the [UDP demux](/quest/m2/one-port/udp-demux.md), split there into a runtime-agnostic piece, run first on each segment; only QUIC continues into the endpoint. The worker is thread-per-core and `!Send`, while the consumers -of the other classes (`moq-rtc`, `moq-srt`, the STUN responder) run on +of the other classes (`moq-rtc`, `moq-srt`) run on tokio, so non-QUIC datagrams cross to them on a `Send` channel, and their replies come back through a remote-send path into the owning worker's ring, which is what a fed `moq-rtc` takes as its `Transmit` @@ -35,9 +39,9 @@ Keep the cross-thread hop off the QUIC path: a QUIC datagram never leaves its worker. Bound the channel per class with a drop counter, as the tokio demux does. -Tests: the existing uring relay integration test gains a STUN Binding round -trip and a WebRTC-class datagram echoed back through the remote-send path, -both on the QUIC port with a QUIC session active. QUIC-bit greasing is +Tests: the existing uring relay integration test gains a WebRTC-class +datagram echoed back through the remote-send path, on the QUIC port with a +QUIC session active. QUIC-bit greasing is already off on the ring, from shard steering. ## Required diff --git a/quest/m2/uring-tcp/README.md b/quest/m2/uring-tcp/README.md index 831e86655f7..0129dc27e3b 100644 --- a/quest/m2/uring-tcp/README.md +++ b/quest/m2/uring-tcp/README.md @@ -18,11 +18,10 @@ supervision. This line moves the media path, not the control plane. The three quests below ship together as one capability, in order. The prerequisite that shapes the middle quest: **qmux sessions arrive through -the axum router**. `web.rs` routes `/` and `/{*path}` to -`websocket::serve_ws` (rs/moq-relay/src/web.rs:343-344). The gate is -moq-relay's own `websocket` feature (rs/moq-relay/Cargo.toml:43, which is -what turns on `axum/ws`) plus the runtime `resolved_ws()` check -(web.rs:342), so a WebSocket session is an HTTP upgrade before it is a media +the axum router**. `rs/moq-relay/src/web.rs` routes `/` and `/{*path}` to +`websocket::serve_ws`. The gate is moq-relay's own `websocket` feature +(which turns on `axum/ws`) plus the runtime `resolved_ws()` check, so a +WebSocket session is an HTTP upgrade before it is a media session. There is no moving qmux onto the ring without also running the HTTP server that upgrades it there. That is not a reason to rewrite axum: hyper is runtime-agnostic, so implementing `hyper::rt::{Read, Write, Executor}` over @@ -38,6 +37,9 @@ Decided in the 2026-09-30 audit: moved to m2. The WebSocket hot path by moving clients to QUIC, and no fleet demand asks for ring TCP. +Decided 2026-10-08: moved to m3. No fleet demand asks for ring TCP; the +ablation stays the gate for the rest of the line. + ## Required - [Ablation](/quest/m2/uring-tcp/ablation.md) - measure ring TCP against tokio diff --git a/quest/m2/uring-tcp/relay.md b/quest/m2/uring-tcp/relay.md index cfce78c5203..de194840027 100644 --- a/quest/m2/uring-tcp/relay.md +++ b/quest/m2/uring-tcp/relay.md @@ -8,14 +8,13 @@ then pinned to one thread for its whole life, exactly like a QUIC one. ## Plan -`uring::Workers::bind` ignores `listen`'s `tcp`/`unix` listeners and points -the operator at a separate `init_streams` tokio server -(rs/moq-relay/src/uring.rs:116-120); the only thing it refuses is -`tls.generate` (:126-128). Replace the silent skip with real support: each +`uring::Workers::bind` (`rs/moq-relay/src/uring.rs`) ignores `listen`'s +`tcp`/`unix` listeners and points the operator at a separate `init_streams` +tokio server; the only thing it refuses is `tls.generate`. Replace the silent skip with real support: each worker binds its own listener in the reuseport group and runs the router from [stream](/quest/m2/uring-tcp/stream.md) on it. -The split of work stays what `uring.rs` already documents (:10-15): the worker +The split of work stays what the `uring.rs` module docs already describe: the worker owns everything transport-shaped, while authentication and session supervision run on the shared tokio runtime that owns the HTTP client, the timers, and the origins. A qmux session handle is `Send + Sync` however its diff --git a/quest/m2/video-codec-coverage.md b/quest/m2/video-codec-coverage.md index 63731394773..b558c2287a9 100644 --- a/quest/m2/video-codec-coverage.md +++ b/quest/m2/video-codec-coverage.md @@ -3,8 +3,7 @@ ## Goal Identify which missing decoder/backend coverage serves actual consumers after -the existing platform and NVIDIA work, without adding mandatory build costs or -blocking 0.1. +the existing platform and NVIDIA work, without adding mandatory build costs. ## Plan @@ -28,6 +27,8 @@ Use the settled Frame/output/codec extension points; no parallel surface API. Public API and wire: no changes during this study. +Decided 2026-10-08: moved to m3. No consumer has asked for a missing codec. + ## Related - [NVIDIA formats](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - 10-bit HEVC scope; AV1 encode moved to [NVENC AV1](/quest/m3/nvenc-av1.md) diff --git a/quest/m2/watch-data-sync.md b/quest/m2/watch-data-sync.md index c9c5339883e..a29b61193b4 100644 --- a/quest/m2/watch-data-sync.md +++ b/quest/m2/watch-data-sync.md @@ -24,7 +24,11 @@ releases it. frontend holds KLV and MAVLink telemetry back to the video playhead with its own sync code, which this replaces. In m2 rather than m1 because they aren't blocked. +- Decided 2026-10-08: the A/V clock and the watch worker land first, since + they change what `Sync` waits on and where it runs. ## Required - [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - the reader releases each value by the timestamp its consumer returns +- [A/V clock](/quest/m1/av-clock.md) - the playhead the reader releases against +- [Watch worker](/quest/m1/watch-worker.md) - moves `Sync` into a worker, where the reader registers diff --git a/quest/m2/watch-decode-gate.md b/quest/m2/watch-decode-gate.md index e5369a10782..a8b2b769d8f 100644 --- a/quest/m2/watch-decode-gate.md +++ b/quest/m2/watch-decode-gate.md @@ -8,20 +8,25 @@ frames within the decoder's latency of presentation are decoded, so a long ## Plan -Today the video decoder's output callback (`js/watch/src/video/decoder.ts`, -around line 380) awaits `sync.wait` before presenting and closing each frame, +Today the video decoder's output callback (`js/watch/src/video/decoder.ts`) +awaits `sync.wait` before presenting and closing each frame, so every buffered frame is held decoded. `Sync.received` caps this at delay + buffer, so it only bites with a large `buffer`, where it can starve the hardware decoder's frame pool (2026-10-07 audit). Decided (2026-10-07): wait before decode, like the audio `ring.wait`. Feed a chunk to the decoder only once its presentation time is within the decoder's -measured output latency. Re-check against the watch worker plan, which moves -`Sync` off the main thread. +measured output latency. + +Decided 2026-10-08: the watch worker lands first. It moves decode and `Sync` +into a worker and rewrites the same `sync.wait`, so this builds on its shape. Public API: none. Wire: none. -## Related +## Required - [Watch worker](/quest/m1/watch-worker.md) - moves decode and `Sync` into a worker + +## Related + - [A/V clock](/quest/m1/av-clock.md) - changes what `Sync` waits on diff --git a/quest/m3/archive-paced-replay.md b/quest/m3/archive-paced-replay.md index 5f30e4c8d59..845037ef644 100644 --- a/quest/m3/archive-paced-replay.md +++ b/quest/m3/archive-paced-replay.md @@ -11,7 +11,7 @@ who joins late joins mid-replay. ## Plan - Today `moq_archive::Reader` publishes only the timeline track live and serves - media groups on FETCH through `track::Dynamic`, so a subscriber sees none. + media groups on FETCH through `broadcast::Dynamic`, so a subscriber sees none. - One clock per import, not per subscriber. It starts at the earliest recorded timestamp across the selected tracks and every track paces against it, so tracks stay in sync and every viewer sees the same moment. diff --git a/quest/m3/captions-cea.md b/quest/m3/captions-cea.md index 7a4df8ed096..805191b7bb9 100644 --- a/quest/m3/captions-cea.md +++ b/quest/m3/captions-cea.md @@ -28,3 +28,7 @@ Parse at import from the inline SEI. The separation study kept H.264 and HEVC SEI in the video access unit, so this parser walks that access unit. There is no sidecar and no strip step. Leave the SEI in place after the cues are published, so a decoder that reads captions from the bitstream still can. + +## Related + +- [Fail loud on dropped timed metadata](/quest/m1/drop-loud.md) - counts the FLV and emsg metadata import drops today; captions are kept in the SEI, not dropped diff --git a/quest/m3/closure-counters.md b/quest/m3/closure-counters.md index 7039797360c..1682c1b5fa0 100644 --- a/quest/m3/closure-counters.md +++ b/quest/m3/closure-counters.md @@ -1,16 +1,14 @@ -# [S] Keep aggregate closure counters monotonic +# [XS] Document aggregate closure counters on rejoin ## Goal -`moq_stats::aggregate` has one stated, tested rule for whether a same-lifetime -rejoin within the grace may regress the `*_ended` counters that -`Traffic::retire` advanced on departure, documented beside the existing -restart contract in `rs/moq-stats/src/aggregate.rs`. +`moq_stats::aggregate` documents, and one test pins, what a same-lifetime +rejoin within the grace does to the `*_ended` counters that `Traffic`'s +`Mergeable::retire` advanced on departure, beside the existing restart +contract in `rs/moq-stats/src/aggregate.rs`. ## Plan -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer. - Decided by [#4874](https://github.com/moq-dev/moq/pull/4874) (recorded in the 2026-10-06 audit): the restart and after-grace contract. A node returning within `Config::grace` with lower counters regresses the merged counter, the @@ -18,16 +16,17 @@ same fresh-segment rule a single node's restart follows; after the grace its contribution folds into one retired total. `return_within_grace_resumes_counters` and `return_after_grace_counts_twice` pin it. -Still open: `Traffic::retire` raises `announces_ended`, `broadcasts_ended`, -and `subscriptions_ended` to their `*_started` on departure, so the next raw -frame from the same node, rejoining within the grace with its boot-lifetime +`retire` raises `announces_ended`, `broadcasts_ended`, and +`subscriptions_ended` to their `*_started` on departure, so the next raw frame +from the same node, rejoining within the grace with its boot-lifetime counters intact, can show a lower `*_ended` value. The stickiness fix ([moq#3625](https://github.com/moq-dev/moq/pull/3625)) review raised it as a -P2. Two directions were discussed: - -- Retire on departure (current), accepting an `*_ended` regression on rejoin. -- Keep the retired values as a floor until the node's own counters pass - them, which suppresses a still-live node's closures after a transient - reader failure. - -Pick one, test it, and document it as part of the consumer-facing contract. +P2. + +Decided 2026-10-08: keep the current behavior (retire on departure, accept an +`*_ended` regression on rejoin), since it follows the same fresh-segment rule +as a restart and no consumer has asked for anything else. Rejected: keeping +the retired values as a floor until the node's own counters pass them, which +suppresses a still-live node's closures after a transient reader failure. +Document it in the consumer-facing contract and add one test of a rejoin +within the grace. diff --git a/quest/m3/cpp-conan.md b/quest/m3/cpp-conan.md index 9d7048dc7b3..9881b8fe78f 100644 --- a/quest/m3/cpp-conan.md +++ b/quest/m3/cpp-conan.md @@ -9,8 +9,9 @@ Windows, macOS, and Linux. ## Plan -In m3 until a Conan consumer asks; vcpkg and the release tarball cover -C++ consumers first. +In m3 until a Conan consumer asks; the release tarball covers C++ consumers +first. The vcpkg registry, which this reuses, is parked in m3 too (decided +2026-10-08), so it lands before this does. - A `moq-cpp` recipe, named after the package, on a moq-dev remote (Artifactory or a GitHub-hosted `conan` index) that packages the prebuilt diff --git a/quest/m3/cut-through/README.md b/quest/m3/cut-through/README.md index 8310ae487d5..fb238f52594 100644 --- a/quest/m3/cut-through/README.md +++ b/quest/m3/cut-through/README.md @@ -8,9 +8,10 @@ lost packet reaches the next hop at its own output offset while the hole is still being recovered, so a loss on one hop no longer delays everything behind it on the next. -The line first measures whether this is worth it, then builds it only if the -measurement says so. A measured no-go deletes the build quests; the loss-delay -metric and the bench stay either way. +The line measures whether this is worth it. Only the loss-delay metric and +the bench are quests today; on a go, the build quests (offset writes in +`moq-quic`, frame ranges, the transport trait, relay cut-through) are +re-planned from git history against the bench's numbers. Non-goals: end consumers (players, `moq-cli`) keep ordered reads, since a decoder needs whole frames. No MoQ wire change; QUIC already allows a sender to @@ -20,13 +21,17 @@ send stream offsets in any order. Decided 2026-10-02: the line moved from m2 to m3. It is a speculative optimization with no consumer asking for it, so it parks until one does and -is deleted if it goes stale. The QUIC primitives land in `moq-quic` after -[the hard fork](/quest/m1/quic/fork/README.md) rather than in moq-dev/noq. +is deleted if it goes stale. The QUIC primitives land in `moq-quic`, the +[hard fork](/quest/m1/quic/fork/README.md)'s stack. + +Decided 2026-10-08: the four build quests were deleted. They churned with +every frame-model and transport change while waiting on a verdict nobody had +measured, so they are re-planned from git history if the bench says go. The +design decisions below stay as the starting point for that re-plan. Decided 2026-09-30: -- Measure first, and plan the build now so the verdict only decides go or - no-go, not the design. The build quests require the [bench](/quest/m3/cut-through/bench.md). +- Measure first; the [bench](/quest/m3/cut-through/bench.md) gates any build. - The gain is roughly the time the relay would spend bursting the held bytes downstream after the hole fills: small when the egress hop has headroom, larger for a big I-frame on a tight hop. The bench sweeps exactly that. @@ -35,7 +40,7 @@ Decided 2026-09-30: earlier header values (lite's timestamp delta, IETF's object id delta). A hole inside a payload blocks nothing, since the frame sizes locate both the input and the output bytes. Passing a hole into later frames needs several - in-flight frames per group; the relay quest prototypes both scopes and keeps + in-flight frames per group; the build prototypes both scopes and keeps the one the bench justifies. - The opportunity is measured on the real two-hop path, not against a direct connection: the gain exists only with a relay in the middle. @@ -59,7 +64,7 @@ Public API: additive `transport::poll` methods in moq-net; the loss-delay counte `moq-stats` ingress rows. Wire: none for MoQ; the counter is a `moq-stats` field. -End to end: once [the relay quest](/quest/m3/cut-through/relay.md) lands, re-run the +End to end: once a relay build lands, re-run the bench on the same sweep and record before and after in this README before closing the line. No new doc page: nothing user-facing changes beyond the stats field, which its quest documents inline. @@ -68,13 +73,9 @@ stats field, which its quest documents inline. - [Loss delay](/quest/m3/cut-through/loss-delay.md) - relays report, per broadcast, the ingress bytes a loss held back by at least one RTT - [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) - 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 -- [Unordered qmux](/quest/m3/p2p/unordered.md) - the same head-of-line problem on the data channel transport - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - orders streams; offset writes order ranges within one - [QoS](/quest/m1/qos/README.md) - the loss-delay counter follows its per-broadcast ingress row conventions +- [Frame slots are cached for free](/quest/m1/frame-slot-charge.md) - changes how the cache charges the in-flight frames a cut-through build would hold diff --git a/quest/m3/cut-through/bench.md b/quest/m3/cut-through/bench.md index bdbe9dc11fb..196d8e25557 100644 --- a/quest/m3/cut-through/bench.md +++ b/quest/m3/cut-through/bench.md @@ -29,12 +29,11 @@ partly measure its own assumptions. in later frames whose headers were known while the hole was open, and bytes behind a lost header. Only the first two are forwardable; the last blocks with or without cut-through and is reported but excluded from the opportunity. The - first split shows what [multiple in-flight frames](/quest/m3/cut-through/frames.md) - add beyond the current frame. Report the drain estimate as an upper bound, and + first split shows what multiple in-flight frames per group would add beyond + the current frame. Report the drain estimate as an upper bound, and include both a payload-loss and a header-loss case to validate the split. -- Take publisher and subscriber counts as parameters, so - [relay cut-through](/quest/m3/cut-through/relay.md) reuses the rig for its - fan-out sweep. +- Take publisher and subscriber counts as parameters, so a relay build + reuses the rig for its fan-out sweep. - Record the loss-delay counter from the same runs, if [Loss delay](/quest/m3/cut-through/loss-delay.md) has landed, so production numbers can be read against the lab. @@ -42,5 +41,6 @@ partly measure its own assumptions. into the nightly workflow. Write the numbers and the verdict into this line's README. The maintainer makes -the go or no-go call from them; no threshold is set in advance. On a no-go, -delete the build quests and keep the bench. +the go or no-go call from them; no threshold is set in advance. On a go, +re-plan the build quests from git history (decided 2026-10-08); either way +the bench stays. diff --git a/quest/m3/emsg.md b/quest/m3/emsg.md index 867d5a7d179..2041fe65d4b 100644 --- a/quest/m3/emsg.md +++ b/quest/m3/emsg.md @@ -57,6 +57,7 @@ byte-identical. ## Related +- [Fail loud on dropped timed metadata](/quest/m1/drop-loud.md) - counts and warns on what import drops until this carriage lands - [ID3 catalog section](/quest/m3/id3.md) - gives one payload type carried here a typed contract - [FLV script tags](/quest/m3/flv-script.md) - likewise diff --git a/quest/m3/flv-script.md b/quest/m3/flv-script.md index e8c24c87591..15a7e254721 100644 --- a/quest/m3/flv-script.md +++ b/quest/m3/flv-script.md @@ -31,3 +31,7 @@ media tag, and a byte-identical round trip. ## Required - [fMP4 emsg](/quest/m3/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first + +## Related + +- [Fail loud on dropped timed metadata](/quest/m1/drop-loud.md) - counts and warns on what import drops until this carriage lands diff --git a/quest/m3/id3.md b/quest/m3/id3.md index 3524a574b8e..e821ab6e212 100644 --- a/quest/m3/id3.md +++ b/quest/m3/id3.md @@ -40,3 +40,7 @@ generic. ## Required - [fMP4 emsg](/quest/m3/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first + +## Related + +- [Fail loud on dropped timed metadata](/quest/m1/drop-loud.md) - counts and warns on what import drops until this carriage lands diff --git a/quest/m3/interop-runner-approval.md b/quest/m3/interop-runner-approval.md index 3a674b73909..0296364f325 100644 --- a/quest/m3/interop-runner-approval.md +++ b/quest/m3/interop-runner-approval.md @@ -1,10 +1,23 @@ -# [XS] The maintainer approves posting to moq-interop-runner +# [XS] The interop runner withdraws publications before disconnecting ## Goal -Condition: the maintainer approves changing moq-interop-runner, which lives -outside this repository, so [Interop graceful -close](/quest/m3/interop-graceful-close.md) can post there. Check: ask the -maintainer, or look for the approval on the runner's repository. Delete this -quest once it is given, and move the graceful-close quest to the milestone -its priority belongs in. +Condition: the maintainer approves changing moq-interop-runner +(englishm/moq-interop-runner, outside this repository), and a released +moq-tokio and `@moq/net` carry the session `close()` that withdraws this +session's announcements before disconnecting. Then post the one-line change: +a completed publish in the runner calls `close()` instead of aborting, so a +subsequent run can publish the same namespace without an already-published +error. + +Check: ask the maintainer, or look for the approval on the runner's +repository, and read the moq-tokio and `@moq/net` changelogs for a release +with the withdrawing `close()`. Delete this quest once the change is posted. + +## Plan + +The runner found this in [#4209](https://github.com/moq-dev/moq/pull/4209). +Exercise successive runs against the same relay before posting. + +Decided 2026-10-08: the graceful-close quest folds in here as one condition +quest, since the runner change is one line once both conditions hold. diff --git a/quest/m3/ladder/controller.md b/quest/m3/ladder/controller.md index e5dbf442875..117a4e2f243 100644 --- a/quest/m3/ladder/controller.md +++ b/quest/m3/ladder/controller.md @@ -73,6 +73,6 @@ priority where the subscriber's order wins, and a custom ladder order. ## Related -- [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - feeds viewer stalls into this controller as an input for `moq transcode --echo` +- [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - viewer stalls for `moq import`; its `moq transcode --echo` leg, split out if revived, feeds this controller - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - supplies the fair subscription buckets beneath this rendition policy diff --git a/quest/m3/p2p/README.md b/quest/m3/p2p/README.md index c3f71aaa6bd..bef8d1f291e 100644 --- a/quest/m3/p2p/README.md +++ b/quest/m3/p2p/README.md @@ -45,10 +45,12 @@ a peer that dies, drains, or was never reachable leaves the relay route as the best remaining one and the subscription moves back. That is the whole fallback story; nothing TURN-shaped is built. -A relay that also answers STUN on its QUIC port -([one port](/quest/m2/one-port/README.md)) is the lowest-RTT STUN server a -client can name, but this line takes ICE servers from the application and -works with any. +A relay that also answers STUN on its QUIC port is the lowest-RTT STUN +server a client can name, but this line takes ICE servers from the +application and works with any. Decided 2026-10-08: the public STUN +responder moved out of the [one-port](/quest/m2/one-port/README.md) UDP +demux into this line, since P2P is its only consumer; plan it as a child +once the harness shows the relay's STUN beats the application's servers. ### Policy is the application's @@ -77,22 +79,16 @@ message-based, so `max_record_size` defaults to 16 KiB and never exceeds the negotiated `maxMessageSize` (256 KiB in Chrome). The cost is head-of-line blocking: one lost chunk stalls every stream until -SCTP retransmits it. qmux frames already carry stream offsets, so the -follow-up is a qmux transport parameter that permits reordering plus receiver -reassembly. [qmux on the QUIC core](/quest/m2/quic-qmux.md) provides that -reassembly for the Rust qmux only, so [unordered qmux](/quest/m3/p2p/unordered.md) -covers native pairs, and a pair with a browser stays ordered (decided -2026-10-06). Both sides advertise that capability in the roster before the -channel is created so it can run `ordered: false`; a loss then stalls only -the stream it hit. `RTCDataChannel.ordered` cannot change after the -channel exists, so the first qmux record is too late to choose. The -[harness](/quest/m3/p2p/harness.md) supplies the numbers that decide when -that follow-up is worth it. +SCTP retransmits it. Decided 2026-10-08: the channel is always ordered, and +unordered qmux was dropped. Receiver reassembly would exist only in the Rust +qmux, so it could cover native pairs alone, and a native pair already +prefers iroh, whose QUIC streams are independent. The +[harness](/quest/m3/p2p/harness.md) reports the stall so the cost stays +visible. Channel-per-stream is not planned. moq opens a stream per group, so it churns against Chrome's 1024-id cap and its close-event id reclaim, needs DCEP per -channel, and has no reset code without a side channel. Unordered qmux gives -the same independence without fighting the browser. +channel, and has no reset code without a side channel. ### Routes and migration @@ -135,7 +131,6 @@ WASM build, so the browser side stays TypeScript. - [Direct peers win](/quest/m3/p2p/cost-scopes.md) - a direct link wins only when the peer is the origin or a routing node, by link costs the node sets itself - [Watch opts in](/quest/m3/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route - [Harness](/quest/m3/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision -- [Unordered qmux](/quest/m3/p2p/unordered.md) - between native peers, qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream ## Related diff --git a/quest/m3/p2p/cost-scopes.md b/quest/m3/p2p/cost-scopes.md index 66263ad53ed..e0967c3eef3 100644 --- a/quest/m3/p2p/cost-scopes.md +++ b/quest/m3/p2p/cost-scopes.md @@ -43,3 +43,5 @@ layer. ## Required - [Routes and announces](/quest/m1/cluster-routing/routes.md) - the origin node ids and metrics this compares +- [Signaling and policy](/quest/m3/p2p/signal.md) - `Peers`, which gains the cost knobs +- [moq-cli joins](/quest/m3/p2p/cli.md) - `moq-cli --p2p`, which mirrors them diff --git a/quest/m3/p2p/harness.md b/quest/m3/p2p/harness.md index eb6512cb3e8..778bc0aa425 100644 --- a/quest/m3/p2p/harness.md +++ b/quest/m3/p2p/harness.md @@ -10,18 +10,21 @@ quotes. ## Plan -Shaped like the `test/wasm` driver: a local relay, `moq-bench` publishing -synthetic frames of known size and rate through it, and `moq-cli --p2p` as the -native hop. The NAT rows run the peers behind a network-namespace NAT with a +A Playwright driver with a local relay, `moq-bench` publishing synthetic +frames of known size and rate through it, and `moq-cli --p2p` as the native +hop. It stands alone rather than reusing `test/wasm`, which +[rs2ts](/quest/m1/rs2ts/remove-wasm.md) removes. The NAT rows run the peers behind a network-namespace NAT with a local STUN server, so a reflexive pair is exercised without leaving the host. Matrix: - browser to native: the same `moq-cli` hop over WebTransport and over the qmux channel; -- browser to browser: a publishing tab to a watcher tab directly, and a - watcher tab re-serving to a second watcher, against the same pairs through - the relay. +- browser to browser: a publishing tab to a watcher tab directly, and the + same publisher to two watcher tabs directly, against the same pairs through + the relay. A watcher tab never re-serves (decided 2026-10-01), so there is + no tab-transit row, and native-to-native pairs use iroh, so there is no + native data channel row either. Metrics: sustained throughput ceiling, per-frame latency p50 and p99 from the timestamp `moq-bench` stamps into each keyframe (same host, so one clock), diff --git a/quest/m3/p2p/peer-grant.md b/quest/m3/p2p/peer-grant.md index 45326b270db..d6551c9ab0e 100644 --- a/quest/m3/p2p/peer-grant.md +++ b/quest/m3/p2p/peer-grant.md @@ -61,4 +61,5 @@ Additive. ## Required +- [Routes and announces](/quest/m1/cluster-routing/routes.md) - the route-layer node id a grant binds - [In-band auth](/quest/m1/auth/README.md) - relay tokens reach `main` with this line, so the relay owns AUTH and knows the session's paths diff --git a/quest/m3/p2p/signal.md b/quest/m3/p2p/signal.md index 3fe0896ab52..530c7b47351 100644 --- a/quest/m3/p2p/signal.md +++ b/quest/m3/p2p/signal.md @@ -23,14 +23,11 @@ once per tab by the origin rather than once per session. lite-07 drops the hop list, so no hop chain carries it. Roster: each peer publishes `` with an `info.json` snapshot track: -the moq ALPNs it accepts, `webrtc: true`, whether it can run qmux unordered, -the presenter public key that +the moq ALPNs it accepts, `webrtc: true`, the presenter public key that [peer grants](/quest/m3/p2p/peer-grant.md) bind, the application's `meta`, and for native peers an optional `webtransport: { url, fingerprint }` and `iroh` endpoint id. The schema is shared with -[moq-cli](/quest/m3/p2p/cli.md). Unordered is advertised here so the dialer -can set `RTCDataChannel.ordered` at create time; see -[unordered qmux](/quest/m3/p2p/unordered.md). +[moq-cli](/quest/m3/p2p/cli.md). Pairing is sparse: broadcasts exist only for pairs some `select` chose, so the cost is the dialed pairs, not the square of the roster. Whoever selects a @@ -80,5 +77,6 @@ there is no equal-scope shortcut. ## Required +- [Routes](/quest/m1/cluster-routing/routes.md) - the ROUTE_START node id the roster keys on - [Data channel transport](/quest/m3/p2p/transport.md) - [Peer grants](/quest/m3/p2p/peer-grant.md) - the node-bound, asymmetrically signed credential a direct session presents; HS256 keys issue none diff --git a/quest/m3/p2p/transport.md b/quest/m3/p2p/transport.md index 1952e12a602..edf8cbd14cc 100644 --- a/quest/m3/p2p/transport.md +++ b/quest/m3/p2p/transport.md @@ -23,12 +23,9 @@ duplicated. The readable enqueues one `Uint8Array` per message with derives `desiredSize` from `bufferedAmount` against `bufferedAmountLowThreshold`. `max_record_size` defaults to 16 KiB and is clamped to the negotiated `maxMessageSize`; a record that would exceed it is -split at a frame boundary, never chunked mid-frame. The channel is created -with `ordered: true` and no retransmit limit unless signaling already -agreed unordered; `ordered` is a constructor option so -[unordered qmux](/quest/m3/p2p/unordered.md) flips it without a second -transport. The flip is decided from the roster before `createDataChannel`, -never from the first qmux record. +split at a frame boundary, never chunked mid-frame. The channel is always +created with `ordered: true` and no retransmit limit, with no option to +change it (decided 2026-10-08, when unordered qmux was dropped). Tests: framing, the record-size clamp, and backpressure run under `bun test` against an in-memory channel pair; the real thing runs under the Playwright diff --git a/quest/m3/p2p/watch.md b/quest/m3/p2p/watch.md index 29b9e906ff4..33aae05af8f 100644 --- a/quest/m3/p2p/watch.md +++ b/quest/m3/p2p/watch.md @@ -9,7 +9,7 @@ the peer goes away, with no visible interruption. ## Plan -`hang-watch` and `hang-publish` gain a `p2p` attribute that constructs +`moq-watch` and `moq-publish` gain a `p2p` attribute that constructs `Peers` on the shared connection's origin with the demo's ICE servers and a `max` from the page; `demo/web` exposes the toggle. The route pick is the origin's, under the rule from [Direct peers win](/quest/m3/p2p/cost-scopes.md): diff --git a/quest/m3/p2p/webrtc.md b/quest/m3/p2p/webrtc.md index d9ee06b05c8..b3e7fb943df 100644 --- a/quest/m3/p2p/webrtc.md +++ b/quest/m3/p2p/webrtc.md @@ -31,9 +31,7 @@ Transport: implement `qmux::transport::{Transport, Writer, Reader}` over one reliable ordered str0m channel, the way `ws::Upgraded` does, and feed `qmux::Session` through `transport::Session` like `websocket.rs`. One record per message, `max_record_size` 16 KiB by default, clamped to the negotiated -message size. `ordered` is a config knob for -[unordered qmux](/quest/m3/p2p/unordered.md), set from the roster before -the channel is created, never from the first qmux record. +message size. The channel is always ordered, with no knob. Tests: an in-process str0m pair over loopback runs moq-net's session tests; a second pair puts a fake STUN server between them and asserts the reflexive @@ -43,4 +41,4 @@ candidate is offered and selected. Browser interop is the harness's job. - [Data channel transport](/quest/m3/p2p/transport.md) - the browser side of the same binding - [moq-cli joins](/quest/m3/p2p/cli.md) - the first consumer -- [One port](/quest/m2/one-port/README.md) - the relay-side STUN answer this client can be pointed at +- [P2P](/quest/m3/p2p/README.md) - owns the relay-side public STUN responder this client could be pointed at, moved out of the one-port demux diff --git a/quest/m3/quic-gcc.md b/quest/m3/quic-gcc.md index a1dfea3718c..2d8da9d47f0 100644 --- a/quest/m3/quic-gcc.md +++ b/quest/m3/quic-gcc.md @@ -1,60 +1,43 @@ -# [XL] QUIC GCC egress experiment +# [M] QUIC receive-timestamps spike ## Goal -Record a measured verdict on WebRTC-style delay-based congestion control for -subscriber-facing media egress against noq's production -controller, driven by the QUIC receive-timestamps extension -(draft-smith-quic-receive-ts): the peer reports when each acknowledged packet -arrived, so the sender sees per-packet one-way delay variation the way -WebRTC's transport-wide congestion control feedback does. Ship it only if it reduces queueing delay and rate variation -without collapsing throughput. A written abandonment is a successful outcome. +A measured, written verdict on the QUIC receive-timestamps extension +(draft-smith-quic-receive-ts) between native `moq-quic` peers: how much more +accurate its per-packet one-way delay is than the half-RTT estimate the +[deadline quest](/quest/m2/quic-deadline.md) starts with, and what its ACK +overhead costs on relay egress. A written abandonment is a successful +outcome. ## Plan -### Receive timestamps - -- Implement the extension in the fork: the transport parameter, the ACK - frame variant with timestamp ranges, and an `on_ack` extension on - `Controller` that hands each acknowledged packet its receive instant. Both - ends are ours; browsers never see it. -- Compare the forward delay it measures against the half-RTT estimate the - [deadline quest](/quest/m2/quic-deadline.md) starts with, on the impaired - path profile with asymmetric delay. Report how often the half-RTT estimate - would have kept a hopeless retransmission or reset a deliverable one. +Decided 2026-10-08: shrunk from a full GCC egress experiment to this spike. +GCC had no consumer, and receive timestamps are native-only (browsers never +negotiate the extension), so it could never reach browser egress, which was +the experiment's point. The deadline quest is the one consumer that wants the +measurement. A delay-based controller built on the timestamps is re-planned +as its own quest only if this spike says they are cheap and accurate. + +- Implement the extension in `moq-quic`: the transport parameter, the ACK + frame variant with timestamp ranges, and a way for `congestion::Controller` + (or a test hook) to see each acknowledged packet's receive instant. Both + ends are ours. +- Compare the forward delay it measures against the half-RTT estimate on the + impaired path profile with asymmetric delay. Report how often the half-RTT + estimate would have kept a hopeless retransmission or reset a deliverable + one. - Measure the ACK overhead the timestamps add on a fanout-shaped relay egress, with and without the ACK-frequency extension reducing ACK rate. -A delay-based controller without per-packet arrival times is a different, -weaker experiment. - -### GCC - -Implement the candidate in the fork as a `congestion::Controller`, driven by -those per-packet receive timestamps; the sender-side inter-arrival filter is -what makes it GCC rather than another RTT-based controller. If it ships, it joins MoQ's backend-neutral congestion -family as `CongestionControl::RealTime`, beside `Loss` (Cubic) and `Delay` -(BBR3); MoQ owns which algorithm each name means, and the config never -exposes algorithm names. Egress only: relay ingest keeps BBR3. - Use the moq-bench media profiles under reproducible netem delay, loss, and -bottleneck rates. Decide on p95 queueing delay, delivered-rate variation, -goodput, and starvation against a competing low-rate interactive MoQ stream. -Anything measured on real relay hardware needs a dedicated real-NIC rig rather -than loopback. - -State the experiment's boundary beside the result: netem cannot establish -behavior against production cross traffic or real wifi and cellular loss. - -Receive timestamps are native-only: browsers never negotiate the extension, -so GCC can only target native peers or relay-to-relay sessions, not browser -egress. Decided 2026-09-30: the receive-timestamps spike folds in here, and -neither waits on a native consumer. +bottleneck rates. State the boundary beside the result: netem cannot +establish behavior against production cross traffic or real wifi and +cellular loss. ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork +- [Hard fork](/quest/m1/quic/fork/README.md) - the extension lands in `moq-quic` ## Related -- [noq#818](https://github.com/n0-computer/noq/issues/818) - the GCC proposal to n0; matheus23 asked for a non-breaking `Controller` trait +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - the forward-delay estimate this measures against diff --git a/quest/m3/routing-cost-domains.md b/quest/m3/routing-cost-domains.md index 3fb3978141c..4a554edf408 100644 --- a/quest/m3/routing-cost-domains.md +++ b/quest/m3/routing-cost-domains.md @@ -9,12 +9,16 @@ one operator's network is cluster-routing's. This includes whether a boundary may fold a large customer cluster's nodes into one advertised node, and how that keeps loop safety. Produce a reviewed design and scoped implementation quests, not a protocol -implementation. Cloudflare, moq.pro, and self-hosted relays can retain their -own business policy; no RTT/loss-driven repricing or automatic performance -failover is authorized by this work. +implementation. Each operator, such as moq.pro or a self-hosted relay, +retains its own business policy; no RTT/loss-driven repricing or automatic +performance failover is authorized by this work. ## Plan +Decided 2026-10-08: parked and speculative. It needs a second operator +running lite-07 cluster routing to have a boundary at all; delete it if none +appears. + Costs reflect SKU, directional egress economics, provider affinity, and marginal transfer savings. A hosting provider is not necessarily a policy domain: moq.pro can coordinate one model across its OVH and Linode nodes. Domain diff --git a/quest/m3/stats-encoder-feedback.md b/quest/m3/stats-encoder-feedback.md index 5c359423ce6..4ca6583f9cd 100644 --- a/quest/m3/stats-encoder-feedback.md +++ b/quest/m3/stats-encoder-feedback.md @@ -13,6 +13,13 @@ it already follows. Keyframe requests stay out. Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer; the media stats it reads land first in m1. +Decided 2026-10-08: parked, and the transcode leg is out. The +[ladder controller](/quest/m3/ladder/controller.md) owns every +`moq-transcode` rung's target, so `moq transcode --echo` feeds the folded +stall signal to that controller rather than to `rate::Control`; split it +into its own quest requiring the controller if this is revived. This quest +covers the encode producers and `moq import --echo`, which need no ladder. + - `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer options, beside `bandwidth`) gains `echo: Option`. - The handle is built from an `origin::Consumer` and the echo path, @@ -45,14 +52,8 @@ reads land first in m1. (`Options::bandwidth` in `rs/moq-audio/src/encode/producer.rs` reserves only). It follows this signal only once the grant quest lands; until then the loop drives video. -- `moq import --echo ` and `moq transcode --echo ` set the - catalog's `echo` section and wire the handle. The - [ladder controller](/quest/m3/ladder/controller.md) owns every - `moq-transcode` rung's target (decided in the 2026-10-06 audit), so for - `transcode` the folded stall signal is a controller input beside the - bandwidth estimate, read per rung from its own renditions, and never drives - a rung's `rate::Control` directly. Rejected: dropping `moq transcode --echo` - from this quest. +- `moq import --echo ` sets the catalog's `echo` section and wires the + handle. - Test: the CLI publishes to a relay, and two `moq play --echo` viewers report under the echo path, one of them throttled through the impairment profile. The target bitrate drops within two intervals of the throttled @@ -83,13 +84,13 @@ Open, to settle before starting (moved from the ## Required -- [Ladder controller](/quest/m3/ladder/controller.md) - owns the rung targets that viewer stalls feed into - [Schema](/quest/m1/stats/schema.md) - the `echo` section and feedback snapshot - [Rust reporters](/quest/m1/stats/rust.md) - the viewers that report and the CLI it wires ## Related +- [Ladder controller](/quest/m3/ladder/controller.md) - owns the rung targets a split-out transcode leg would feed - [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the audio rate follow this signal would feed - [Ladder](/quest/m3/ladder/README.md) - the transcode ladder, which today diff --git a/quest/m3/teleop-mavlink.md b/quest/m3/teleop-mavlink.md index f428f233ac5..7496745757d 100644 --- a/quest/m3/teleop-mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -10,6 +10,9 @@ and MAVProxy connect unchanged. Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). +Decided 2026-10-08: the lossy class is a snapshot track per key with a +bounded key set, since one snapshot track carries only one latest value. + ### Shape A library crate reached through `moq-cli`, the way `moq-srt` and `moq-rtmp` @@ -56,6 +59,13 @@ delivers latest-value: under msgid 0; keying on msgid alone lets them overwrite each other. Decide explicitly what to do about instances distinguished only inside a payload, which the msgid-only rule cannot see. +- **One snapshot track per key.** A `moq_flate::snapshot` track holds one + latest value, so per-key latest-value means a track per + `(sysid, compid, msgid)`, named from the key and advertised in the catalog + as it appears. That state grows with whatever the flight-controller link + emits, so bound it: cap the number of keys (or derive the set from the + config table) and fail loud past the cap rather than creating tracks + without limit. Not `moq_json::snapshot`: a MAVLink frame is not JSON, and its default batches up to `MAX_DELTA_FRAMES` merge patches into one ordered group, so an earlier diff --git a/quest/m3/teleop-proof.md b/quest/m3/teleop-proof.md index 82a903937da..552f5b9bcb3 100644 --- a/quest/m3/teleop-proof.md +++ b/quest/m3/teleop-proof.md @@ -13,17 +13,28 @@ Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). The browser client subscribes video and telemetry and publishes control, the shape Blue Robotics' Cockpit proves is viable. It is the demo and the end-to-end proof of the primitive, not a bid to out-feature QGroundControl: -real users reach the same link through `moq export mavlink`. +real users reach the same link through the `moq-mavlink` gateway. SITL is the right proof surface precisely because it removes the camera, which otherwise dominates the latency budget and would make the demo a measurement of somebody's webcam. +The ground station's catalog and delivery-class shapes come from a zod +schema mirroring the `moq-robot` types, written once and extending the root +schema through the same seam `js/hang/src/catalog/root.ts` uses (there is no +`@moq/mux`). Decided 2026-10-08: no separate `@moq/robot` package until a +second browser consumer needs it; the schema folds in here. A browser +observer cannot degrade the operator's classes (the publisher's +`Info::max_age` bounds the window), so the schema is for reuse, not safety. + Standing SITL up in CI is separate work with its own build dependencies. Reproducibility by hand is the bar here; automate it later if it proves worth the maintenance. ## Required -- [MAVLink bridge](/quest/m3/teleop-mavlink.md) -- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) - the gateway the vehicle side runs + +## Related + +- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - the Rust types the zod schema mirrors diff --git a/quest/m3/video-embedded.md b/quest/m3/video-embedded.md index c362078006a..d97688dd0a7 100644 --- a/quest/m3/video-embedded.md +++ b/quest/m3/video-embedded.md @@ -1,22 +1,26 @@ -# [L] Embedded video path +# [S] Embedded video path ## Goal -`moq-video` presents on Raspberry Pi and similar embedded hardware. Encoding -and decoding there is the V4L2 M2M backends' job already; presenting is not -possible today, because the renderer's only zero-copy import is Vulkan and -those devices have no usable Vulkan driver. +`moq-video` presents on a Raspberry Pi 4 or 5, verified on the device. +Encoding and decoding there is the V4L2 M2M backends' job already; this +checks whether the renderer's existing paths present those frames, and +records what breaks. ## Plan -**EGL/GLES import** in the renderer. The devices with a V4L2 codec are the ones -without a usable Vulkan driver, so the existing DMA-BUF import cannot reach -them. Same shape as the Vulkan path: alias the buffer, keep the per-path -fallback and three-strike disable, fall back to I420 when import fails. +Decided 2026-10-08: verify first. The Pi 4 and 5 ship Mesa's v3dv Vulkan +driver, so the premise that embedded devices have no usable Vulkan driver is +doubtful. Run the renderer's DMA-BUF Vulkan import against V4L2 M2M decoder +output, and the I420 CPU fallback, and record the device, OS image, Mesa +version, and which path presented. -Hardware-gated end to end. It needs a real device to validate, and the usual -dlopen-and-degrade rule applies: a build without the device present must -degrade rather than fail to start. +If the Vulkan import cannot take the decoder's buffers (a missing extension +or modifier) on a device a consumer needs, plan EGL/GLES import as its own +quest: same shape as the Vulkan path (alias the buffer, keep the per-path +fallback and three-strike disable, fall back to I420 when import fails), and +the usual dlopen-and-degrade rule, so a build without the device present +degrades rather than fails to start. Two items from the same wave are deliberately not here. X11 MIT-SHM capture is optional, since portal and PipeWire cover modern desktops. A pre-encoded @@ -27,4 +31,4 @@ libcamera source composes with what already exists, because ## Required -- [An embedded video device is on hand](/quest/m3/embedded-device.md) - the device to validate on +- [Video validation hardware is on hand](/quest/m3/video-hardware-access.md) - the Pi to validate on diff --git a/quest/m3/video-hardware-access.md b/quest/m3/video-hardware-access.md index 3d6971a03e6..942dd8e6d2a 100644 --- a/quest/m3/video-hardware-access.md +++ b/quest/m3/video-hardware-access.md @@ -2,11 +2,11 @@ ## Goal -Someone with the hardware can run the video validation: an Intel GPU -exposing the VAAPI low-power entrypoint, a Windows -machine with MJPEG and YUY2 cameras, a live camera per platform, a KDE/Wayland -desktop with an Intel or AMD GPU, a sandbox that can show the camera portal -dialog, and a Raspberry Pi whose CSI camera appears as a PipeWire node. +Someone with the hardware can run the video validation: a Windows machine +with MJPEG and YUY2 cameras, a live camera per platform, a KDE/Wayland desktop +with an Intel or AMD GPU, a sandbox that can show the camera portal dialog, +and a Raspberry Pi 4 or 5 whose CSI camera appears as a PipeWire node, which +also validates the [embedded video path](/quest/m3/video-embedded.md). This quest tracks a condition outside the repository. When it holds, delete this quest and every `Required` entry that links it. @@ -18,8 +18,17 @@ Check by asking the maintainer which machines are available. As of Lake iGPU (iHD 26.1.2, `renderD128`) and an AMD RX 9070 (RADV, Mesa 26.0.8, `renderD129`), so it has a second render node; that check moved to [VA-API external images](/quest/m2/vaapi-vulkan-import.md). The -[multi-vendor GPU quests](/quest/m2/gpu-release.md) test on it. Whether the -iGPU exposes the low-power entrypoint is unchecked. +[multi-vendor GPU quests](/quest/m2/gpu-release.md) test on it. + +Checked 2026-10-08 on that desktop: `vainfo` lists only `VAEntrypointEncSlice` +on the iGPU (H.264, HEVC, HEVC Main10, AV1), no `EncSliceLP`, so the +low-power-only fallback is unreachable there and is no longer a validation +item. The desktop runs GNOME, not KDE, and has no camera (`/dev/video*` is +empty). + +Decided 2026-10-08: the embedded-device condition folds in here, since a Pi +4 or 5 serves both the PipeWire camera pass and the embedded video check. +Record the device, OS image, and driver when one is on hand. The validation can start with whatever subset is available; split the rest out of [Video hardware validation](/quest/m3/video-hardware.md) when that diff --git a/quest/m3/video-hardware.md b/quest/m3/video-hardware.md index 58134bb2830..aa5ed2785fc 100644 --- a/quest/m3/video-hardware.md +++ b/quest/m3/video-hardware.md @@ -13,12 +13,11 @@ the KDE DMA-BUF capture and PipeWire camera validations fold in here, and the V4L2 `VIDIOC_EXPBUF` source is dropped with the export itself (see [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md)). -- **VAAPI low-power entrypoint.** H.264 encode, DMA-BUF input, and VPP - resize ran on Intel Meteor Lake with iHD (moq-vaapi 0.1.0). Still unrun: - the low-power encode entrypoint, which that device does not expose. A - render node other than the first moved to - [VA-API external images](/quest/m2/vaapi-vulkan-import.md) (2026-10-06 audit), - whose two-node test host has one. +Decided 2026-10-08: the VAAPI low-power entrypoint check is dropped. Neither +Meteor Lake nor the Arrow Lake test host exposes `EncSliceLP`, so no machine +on hand reaches that fallback. A render node other than the first is checked +by [VA-API external images](/quest/m2/vaapi-vulkan-import.md). + - **Windows Media Foundation capture**: on-demand open and close, so the camera LED is off when nobody is watching, and NV12 delivery from MJPEG and YUY2 cameras. diff --git a/quest/m4/safari-webtransport.md b/quest/m4/safari-webtransport.md index 4d0cc76fb94..c18b681ae1d 100644 --- a/quest/m4/safari-webtransport.md +++ b/quest/m4/safari-webtransport.md @@ -20,11 +20,20 @@ this. Safari for macOS and on Chrome, Firefox and Edge for iOS, with desktop Chrome and Firefox as controls. - Update `doc/lib/js/index.md`. +- The gate needs the Safari version, and the iOS or iPadOS WebKit version + for the iOS browsers, out of the user-agent check. If + [JS bundle trims](/quest/m1/js-bundle-trims.md) has replaced bowser in the + same file by then, its check exposes that version rather than a yes/no + WebKit flag (decided 2026-10-08). ## Required -- [Safari ships the WebKit 319818 fix](/quest/m4/webkit-319818.md) - the release to gate on +- [Safari ships the WebKit 319818 fix](/quest/m3/webkit-319818.md) - the release to gate on ## Closes - [#2388](https://github.com/moq-dev/moq/issues/2388) - close this issue when the quest finishes + +## Related + +- [JS bundle trims](/quest/m1/js-bundle-trims.md) - replaces bowser in the same `browser.ts` user-agent check From 1a58ab4cc14996d702dbb4c3430df9fb236fc4e7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 08:13:52 -0700 Subject: [PATCH 08/10] quest: delete, merge, move, and re-rank quests from the 2026-10-08 audit Deletes done and not-worth-it quests, folds duplicates, retires m4 into m3, moves quests between milestones by priority, splits js-session-parity and listener-deadlines, and fixes every rank inversion the audit found. Co-Authored-By: Claude Opus 5.5 --- quest/README.md | 12 +- quest/m0/README.md | 34 ++---- quest/m0/broadcast-epoch/README.md | 2 +- quest/m0/broadcast-epoch/dynamic-epoch.md | 2 +- quest/m0/idle-fronts.md | 6 +- quest/m0/ietf-first-object-zero.md | 32 ----- quest/m0/prefix-route-fronts.md | 22 ---- quest/m1/README.md | 54 ++++----- .../{m0 => m1}/audio-jitter-target/README.md | 2 +- quest/{m0 => m1}/audio-jitter-target/watch.md | 0 quest/m1/audio-quality-native.md | 4 +- quest/m1/auth/request-token.md | 4 +- quest/m1/av-clock.md | 4 +- quest/m1/binding-surface.md | 2 +- quest/m1/cache-max-age.md | 4 +- quest/m1/capture-default.md | 43 ------- quest/m1/catalog-early-demand.md | 29 ----- quest/m1/ci-runner-stalls.md | 24 ---- .../broadcast-epoch => m1}/claim-epochs.md | 2 +- quest/m1/cluster-routing/README.md | 6 +- quest/m1/color-model.md | 4 +- quest/m1/cpp/README.md | 4 +- .../{flv-export-delay.md => export-delay.md} | 0 quest/m1/ffi-frame-duration-default.md | 29 ----- quest/{m0 => m1}/held-group-wakes.md | 0 quest/m1/ietf-cold-largest.md | 61 ---------- quest/m1/ietf-deviations-doc.md | 26 ---- quest/m1/ietf-headless-subgroup.md | 21 ---- quest/m1/iroh-keep-alive.md | 17 +++ quest/m1/js-pending-tail.md | 24 ++++ quest/m1/js-probe-lifetime.md | 30 ----- quest/m1/js-session-parity.md | 16 ++- quest/{m0 => m1}/largest-regression.md | 2 +- quest/m1/listener-deadlines-http.md | 31 +++++ quest/m1/listener-deadlines.md | 48 +++----- quest/m1/lite07-finalize.md | 2 +- quest/m1/mkv-export-delay.md | 24 ---- quest/m1/mkv-lacing.md | 2 +- quest/m1/nvenc-keyframe-flag.md | 24 ---- quest/m1/obs-moq-video/rate-control.md | 2 +- quest/m1/obs-moq-video/vpx-obs.md | 2 +- quest/m1/papercuts-js.md | 2 +- quest/m1/performance-profiles.md | 48 -------- quest/m1/qos/lag-splice.md | 48 -------- quest/m1/quic/README.md | 4 +- quest/m1/subscribe-live-time.md | 60 ---------- quest/m1/ts-passthrough.md | 2 +- quest/m1/watch-audio-time-stretch.md | 4 +- ...ipewire-dma-bufs-safely-into-the-vulkan.md | 2 +- ...bandwidth-grant-in-moq-audio-instead-of.md | 0 ...ve-sq-indirection-and-per-enter-ring-fd.md | 0 quest/m2/README.md | 43 +++---- quest/m2/c-backend-copy.md | 14 --- quest/m2/cache-shard.md | 69 ----------- quest/{m1 => m2}/capture-alsa-link.md | 6 +- quest/{m1 => m2}/cli-packaging.md | 4 +- quest/{m1 => m2}/cpal-alsa-runtime.md | 10 +- quest/{m1 => m2}/kt-jvm-exit.md | 0 .../cluster-routing => m2}/link-quality.md | 0 quest/m2/one-port/README.md | 2 +- quest/{m1 => m2}/pipeline-fetch-info.md | 0 quest/m2/quic-bbr-loss-parity.md | 5 +- quest/m2/quic-ecn-measure.md | 4 +- quest/m2/quic-keep-alive.md | 4 +- quest/m2/relay-io-uring-package.md | 4 +- quest/m2/signed-priority.md | 58 --------- quest/m2/stats-delta.md | 113 ------------------ quest/m2/teleop/README.md | 14 +-- quest/m2/uring-demux.md | 2 +- quest/{m1 => m2}/uring-drop-close.md | 0 quest/{m1 => m2}/uring-ietf.md | 2 +- quest/m2/uring-open-contract.md | 28 ----- ...evc-and-av1-support-in-the-nvidia-codec.md | 2 +- ...-the-webtransport-stream-header-at-open.md | 0 ...fixed-file-slots-for-worker-udp-sockets.md | 0 quest/m3/README.md | 41 ++++--- quest/m3/af-xdp.md | 28 ----- quest/{m2 => m3}/color-catalog.md | 0 quest/m3/cpp-conan.md | 2 +- quest/{m2 => m3}/cpp-vcpkg.md | 0 quest/m3/cut-through/frames.md | 46 ------- quest/m3/cut-through/quic.md | 32 ----- quest/m3/cut-through/relay.md | 56 --------- quest/m3/cut-through/transport.md | 36 ------ quest/m3/embedded-device.md | 13 -- quest/{m2 => m3}/ietf-cluster-peers.md | 0 quest/m3/interop-graceful-close.md | 20 ---- quest/m3/ladder/README.md | 2 +- quest/m3/moq-relay-subcommand.md | 42 ------- quest/{m2 => m3}/msfts-convergence.md | 0 quest/m3/nvenc-av1.md | 2 +- quest/m3/p2p/unordered.md | 63 ---------- quest/{m2 => m3}/pipewire-camera-planes.md | 0 quest/{m2 => m3}/quic-careful-resume.md | 0 quest/{m2 => m3}/quic-ecn.md | 0 quest/{m4 => m3}/safari-webtransport.md | 0 quest/m3/stats-encoder-feedback.md | 2 +- .../teleop-arbitration.md} | 4 +- quest/m3/teleop-browser-package.md | 28 ----- quest/m3/teleop-mavlink.md | 6 +- quest/m3/teleop-proof.md | 2 +- .../teleop/robot.md => m3/teleop-robot.md} | 2 +- quest/m3/text-schema.md | 31 ----- quest/{m2 => m3}/uring-tcp/README.md | 6 +- quest/{m2 => m3}/uring-tcp/ablation.md | 0 quest/{m2 => m3}/uring-tcp/relay.md | 4 +- quest/{m2 => m3}/uring-tcp/stream.md | 2 +- quest/{m2 => m3}/video-codec-coverage.md | 2 +- quest/m3/video-hardware.md | 4 +- quest/{m4 => m3}/webkit-319818.md | 0 quest/m4/README.md | 16 --- 111 files changed, 270 insertions(+), 1433 deletions(-) delete mode 100644 quest/m0/ietf-first-object-zero.md delete mode 100644 quest/m0/prefix-route-fronts.md rename quest/{m0 => m1}/audio-jitter-target/README.md (97%) rename quest/{m0 => m1}/audio-jitter-target/watch.md (100%) delete mode 100644 quest/m1/capture-default.md delete mode 100644 quest/m1/catalog-early-demand.md delete mode 100644 quest/m1/ci-runner-stalls.md rename quest/{m0/broadcast-epoch => m1}/claim-epochs.md (98%) rename quest/m1/{flv-export-delay.md => export-delay.md} (100%) delete mode 100644 quest/m1/ffi-frame-duration-default.md rename quest/{m0 => m1}/held-group-wakes.md (100%) delete mode 100644 quest/m1/ietf-cold-largest.md delete mode 100644 quest/m1/ietf-deviations-doc.md delete mode 100644 quest/m1/ietf-headless-subgroup.md create mode 100644 quest/m1/iroh-keep-alive.md create mode 100644 quest/m1/js-pending-tail.md delete mode 100644 quest/m1/js-probe-lifetime.md rename quest/{m0 => m1}/largest-regression.md (96%) create mode 100644 quest/m1/listener-deadlines-http.md delete mode 100644 quest/m1/mkv-export-delay.md delete mode 100644 quest/m1/nvenc-keyframe-flag.md delete mode 100644 quest/m1/performance-profiles.md delete mode 100644 quest/m1/qos/lag-splice.md delete mode 100644 quest/m1/subscribe-live-time.md rename quest/{m1 => m2}/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md (100%) rename quest/{m1/perf => m2}/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md (100%) delete mode 100644 quest/m2/c-backend-copy.md delete mode 100644 quest/m2/cache-shard.md rename quest/{m1 => m2}/capture-alsa-link.md (92%) rename quest/{m1 => m2}/cli-packaging.md (96%) rename quest/{m1 => m2}/cpal-alsa-runtime.md (90%) rename quest/{m1 => m2}/kt-jvm-exit.md (100%) rename quest/{m1/cluster-routing => m2}/link-quality.md (100%) rename quest/{m1 => m2}/pipeline-fetch-info.md (100%) delete mode 100644 quest/m2/signed-priority.md delete mode 100644 quest/m2/stats-delta.md rename quest/{m1 => m2}/uring-drop-close.md (100%) rename quest/{m1 => m2}/uring-ietf.md (96%) delete mode 100644 quest/m2/uring-open-contract.md rename quest/{m2 => m3}/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md (96%) rename quest/{m2 => m3}/3129-moq-uring-write-the-webtransport-stream-header-at-open.md (100%) rename quest/{m2 => m3}/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md (100%) delete mode 100644 quest/m3/af-xdp.md rename quest/{m2 => m3}/color-catalog.md (100%) rename quest/{m2 => m3}/cpp-vcpkg.md (100%) delete mode 100644 quest/m3/cut-through/frames.md delete mode 100644 quest/m3/cut-through/quic.md delete mode 100644 quest/m3/cut-through/relay.md delete mode 100644 quest/m3/cut-through/transport.md delete mode 100644 quest/m3/embedded-device.md rename quest/{m2 => m3}/ietf-cluster-peers.md (100%) delete mode 100644 quest/m3/interop-graceful-close.md delete mode 100644 quest/m3/moq-relay-subcommand.md rename quest/{m2 => m3}/msfts-convergence.md (100%) delete mode 100644 quest/m3/p2p/unordered.md rename quest/{m2 => m3}/pipewire-camera-planes.md (100%) rename quest/{m2 => m3}/quic-careful-resume.md (100%) rename quest/{m2 => m3}/quic-ecn.md (100%) rename quest/{m4 => m3}/safari-webtransport.md (100%) rename quest/{m2/teleop/arbitration.md => m3/teleop-arbitration.md} (93%) delete mode 100644 quest/m3/teleop-browser-package.md rename quest/{m2/teleop/robot.md => m3/teleop-robot.md} (98%) delete mode 100644 quest/m3/text-schema.md rename quest/{m2 => m3}/uring-tcp/README.md (91%) rename quest/{m2 => m3}/uring-tcp/ablation.md (100%) rename quest/{m2 => m3}/uring-tcp/relay.md (92%) rename quest/{m2 => m3}/uring-tcp/stream.md (96%) rename quest/{m2 => m3}/video-codec-coverage.md (96%) rename quest/{m4 => m3}/webkit-319818.md (100%) delete mode 100644 quest/m4/README.md diff --git a/quest/README.md b/quest/README.md index f11fef2994f..a086f101fc0 100644 --- a/quest/README.md +++ b/quest/README.md @@ -8,10 +8,11 @@ grouped into milestones ordered by priority. ## Plan m0 is everything in flight now: relay hardening and the IETF interop -fixes ahead of Seattle, wildcard routing, broadcast epochs, and audio playout (the jitter target). m1 is the next wave across reliability, features, performance, and +fixes ahead of Seattle, and broadcast epochs. m1 is the next wave across reliability, features, performance, and planning. m2 holds later features, design studies, and experiments. m3 is -gated on the outside world (hardware, a partner, a consumer, or a provider's -offer) or is speculative work with no named consumer yet. m4 waits on an upstream release. +gated on the outside world (hardware, a partner, a consumer, a provider's +offer, or an upstream release) or is speculative work with no named consumer +yet. A quest waiting on the outside world, in any milestone, requires a small quest beside it that names the condition. That condition quest stays ready, so @@ -20,8 +21,7 @@ move the blocked quest to the milestone its priority belongs in. ## Required -- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and the IETF interop fixes for Seattle, wildcard routing, broadcast epochs, and audio playout +- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and the IETF interop fixes for Seattle, and broadcast epochs - [m1: next wave](/quest/m1/README.md) - reliability, capabilities, performance, and the planning that settles their contracts - [m2: later work](/quest/m2/README.md) - deferred features, design studies, and experiments -- [m3: deferred](/quest/m3/README.md) - gated on the outside world (hardware, a partner, a consumer, or a provider's offer), or speculative with no named consumer -- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release, re-checked periodically +- [m3: deferred](/quest/m3/README.md) - gated on the outside world (hardware, a partner, a consumer, a provider's offer, or an upstream release), or speculative with no named consumer diff --git a/quest/m0/README.md b/quest/m0/README.md index a19f547afcf..bab041a4d58 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -2,14 +2,12 @@ ## Goal -The work in flight now, in three independent tracks. Relay hardening: legal +The work in flight now, in two independent tracks. Relay hardening: legal moq-transport input never fails a session ahead of Seattle interop on 2026-10-12, every resource a peer can make the relay hold is bounded by what it sent or by a budget, and no peer input panics the process. Identity: nothing treats who published a route as what it carries; a path and the epoch on its route are the only content identity, and every first-party publisher that can restart mints a fresh epoch, so #4741 stalls nobody. -Audio playout: the target is a measured estimate of arrival timing in both -languages, and a browser regression fails a nightly run. ## Plan @@ -18,8 +16,9 @@ done. moq.pro pins this repository's `release` line, so the release gate below also keeps #4741 from reaching it early. The Pronto GPU integration lives in moq.pro. -The DoS hardening from an external review on 2026-09-29, verified against `main`, stays in m0 -as security work. Its quests describe fixes, not exploits. +Relay hardening left in m0 is idle fronts: per-session request caps landed +in #4820, and the rest of the 2026-09-29 DoS review moved to m1 with +relay session limits. Routing: Wildcard landed in #4403, so a service claims the prefix it could serve instead of enumerating broadcasts. Serving the relay's ingested-only @@ -33,9 +32,9 @@ Interop: Fastly's moq-relay-interop report (run of 2026-09-23, build 7ee2b02) was triaged against `main` on 2026-10-07. Its SETUP, UNSUBSCRIBE and error-code items were already fixed. Fastly's reruns that day found that a relay moves End of Track's Location and refuses imquic's End of -Group status. The seven fixes below LOCATION_FILTER come from them and go -ahead of Seattle. The cold-relay Largest and the deviations it flagged are -in m1. +Group status. The fixes below LOCATION_FILTER come from them and go ahead +of Seattle. The cold-relay Largest stays compliant with INVALID_RANGE +(decided 2026-10-08), and the deviations doc landed in #5022. Identity: the [broadcast epoch](/quest/m0/broadcast-epoch/README.md) line gates the next release (decided 2026-10-03: @@ -43,30 +42,23 @@ gates the next release (decided 2026-10-03: viewers). #4741 can merge to main, but no release ships until first-party publishers mint epochs. -Audio playout: the jitter target replaces the round-trip guess. The browser -audio quality harness in `test/audio-quality/` has landed; it grades playout -nightly and records the traces it replays. Its native lane is a standalone m1 -quest, since nothing here waits on it. The [A/V clock](/quest/m1/av-clock.md) -moved to m1 in the 2026-09-30 audit: it waits on the whole jitter line and is -a published `@moq/watch` break. +Audio playout: the jitter target is default in both languages (#4162); the +[line](/quest/m1/audio-jitter-target/README.md) moved to m1 in the +2026-10-08 audit, since only a manual browser proof and a native trace replay +remain and no release waits on them. ## Required -- [Held group wakes](/quest/m0/held-group-wakes.md) - a group held across a route switch is woken when its successor's first timestamp or abort makes it stale, not at the next unrelated append - [Draft-22 LOCATION_FILTER](/quest/m0/ietf-location-filter-22.md) - moqt-22 LOCATION_FILTER carries its type instead of a Length in Rust and JS, so a draft-22 peer reads our Next Object correctly - [moq-transport parameters per draft](/quest/m0/ietf-params-per-draft.md) - every control message accepts exactly the parameters its draft allows, so moqx's draft-16 SUBSCRIBE_NAMESPACE with FORWARD stops failing - [No empty d14 prefix](/quest/m0/ietf-d14-root-prefix.md) - draft-14 never sends SUBSCRIBE_NAMESPACE with an empty prefix, and the docs say to scope a d14 link to moxygen -- [End of Track Location](/quest/m0/ietf-end-of-track-location.md) - a relay forwards END_OF_TRACK at its upstream's Location, on the last group's stream, instead of re-sending it at the next group's object 0 +- [Capped stream END_OF_GROUP](/quest/m0/ietf-end-of-track-location.md) - a stream capped by the subscription's end Location never claims END_OF_GROUP; moving End of Track's Location is deferred - [End of Group status](/quest/m0/ietf-end-of-group-status.md) - an End of Group status on a stream whose header already marks the group's end is accepted, so imquic's last object per group arrives -- [Subgroup at object 0](/quest/m0/ietf-first-object-zero.md) - a draft-18 subgroup with FIRST_OBJECT clear that starts at object 0 is read whole -- [Prefix route fronts](/quest/m0/prefix-route-fronts.md) - a prefix route cannot be made to mint one front per requested path - [TRACK stream demand](/quest/m0/track-stream-demand.md) - a lite-05+ subscribe shows the publisher one `used` edge, not a flap between TRACK and SUBSCRIBE - [Idle fronts](/quest/m0/idle-fronts.md) - a front nobody has read for the linger ends with its per-path state, so a standing claim stops accumulating fronts and sources -- [Upstream position regression](/quest/m0/largest-regression.md) - a relay copy that sees upstream's largest group go backwards ends instead of serving the old instance's cache -- [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 +- [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines - [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 ## Related diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 404ca5a451a..ecf7b4555c0 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -54,7 +54,7 @@ Decided: explicit `Restart` announce event tells players to follow, through [Restart](/quest/m0/broadcast-epoch/restart.md). When the newest goes and an older one is still live, the older one wins again as a new broadcast. -- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md), where a +- [Claim-served epochs](/quest/m1/claim-epochs.md), where a lite-07 claim's answer carries the served broadcast's own epoch, no longer gates this line (decided 2026-10-08): it is a lite-07 opt-in, so it moved to m1. diff --git a/quest/m0/broadcast-epoch/dynamic-epoch.md b/quest/m0/broadcast-epoch/dynamic-epoch.md index be5ef04730f..67706244d06 100644 --- a/quest/m0/broadcast-epoch/dynamic-epoch.md +++ b/quest/m0/broadcast-epoch/dynamic-epoch.md @@ -16,7 +16,7 @@ since two epochs may carry the same content; a handler that wants fresh content under the new epoch closes its old broadcast itself. Non-goals: the epoch a claim-served answer carries -([Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md)), and +([Claim-served epochs](/quest/m1/claim-epochs.md)), and same-epoch repricing, which keeps every handle and stays an `Update`. ## Plan diff --git a/quest/m0/idle-fronts.md b/quest/m0/idle-fronts.md index 4d39c8aa338..363854d7604 100644 --- a/quest/m0/idle-fronts.md +++ b/quest/m0/idle-fronts.md @@ -74,7 +74,7 @@ Decisions (2026-10-07): Document that in `doc/concept/moq-lite.md` Resume: such a worker keeps its group sequence going, across its own source restarting too (mirroring an upstream sequence that goes back to 0 isn't enough), or gives each output its own epoch once - [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) lands. + [Claim-served epochs](/quest/m1/claim-epochs.md) lands. Without that, a viewer returning within the linger gets the old instance's cached latest group and then nothing until the new instance's sequence passes it. @@ -93,8 +93,8 @@ Public API: none expected. Wire: none. ## Related - [Restart](/quest/m0/broadcast-epoch/restart.md) - a request joins a front only while its route still wins, the routing half of the same report -- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - on lite-07, a worker's restarted output is a new instance and never spliced -- [Upstream position regression](/quest/m0/largest-regression.md) - fails loud on the stale splice where the answer shows it +- [Claim-served epochs](/quest/m1/claim-epochs.md) - on lite-07, a worker's restarted output is a new instance and never spliced +- [Upstream position regression](/quest/m1/largest-regression.md) - fails loud on the stale splice where the answer shows it - [Front parking](/quest/m1/origin-front-parks.md) - a front waiting for coverage must survive this; the filtered-front leak moved here from it - [Route wakes](/quest/m1/route-wakes.md) - indexes fronts per route, so an ended front must drop its entries - [Front deadline index](/quest/m1/front-deadline-index.md) - indexes a front's per-track linger deadlines in the same `front.rs`; it rebases onto this diff --git a/quest/m0/ietf-first-object-zero.md b/quest/m0/ietf-first-object-zero.md deleted file mode 100644 index 701c72f4980..00000000000 --- a/quest/m0/ietf-first-object-zero.md +++ /dev/null @@ -1,32 +0,0 @@ -# [XS] A subgroup starting at object 0 is whole - -## Goal - -A draft-18+ subgroup stream with FIRST_OBJECT clear whose first Object ID -is 0 is read as a whole group, in `rs/moq-net`, instead of being dropped as -"a group with no head". A clear bit with any other first ID is still dropped -as it is today. - -## Plan - -Triaged from Fastly's moq-relay-interop report (2026-09-23 run, item 7) on -2026-10-07. d18 ยง2.2 says the original publisher MUST set FIRST_OBJECT when -it opens a subgroup, and a relay MUST keep it set, so the probe that left it -clear was the one out of spec. The first Object ID is absolute whatever -the bit says (ยง11.4.2), and object IDs in our model start at 0, so ID 0 is -the head either way. - -Decided 2026-10-07: accept it anyway, to be lenient toward publishers that -are out of spec. Rejected: keeping the drop and documenting it. - -Where it lives: `rs/moq-net/src/ietf/subscriber.rs` (around line 2611) -drops the stream before reading any object. `next_object_id` already -refuses a first ID other than the group's start (0 for a whole group), so -check whether letting a clear-bit stream through to it is enough before -adding a second peek. Check whether `js/net` drops these streams at all; it -has no matching check today. - -Test: a d18 stream with FIRST_OBJECT clear and first ID 0 delivers its -group; one with first ID 3 is still dropped. - -Public API: none. Wire: none. diff --git a/quest/m0/prefix-route-fronts.md b/quest/m0/prefix-route-fronts.md deleted file mode 100644 index 9f9433eb6f0..00000000000 --- a/quest/m0/prefix-route-fronts.md +++ /dev/null @@ -1,22 +0,0 @@ -# [S] Prefix routes mint bounded fronts - -## Goal - -A peer requesting arbitrary paths under a prefix route cannot make an origin -mint one front, driver task, and upstream request per distinct path. The -number of fronts a prefix route can create is bounded, and a request past the -bound is refused rather than queued. - -## Plan - -Found while landing shared fronts (#4922, merged): viewers share one front -per path, but an optimistic resolve under a prefix route still mints a front -for every distinct requested path while the route stands. That cost is per path, -not per viewer, so a single session can amplify it by naming paths. - -- Decide the bound (per route, per session, or both) and what a refusal looks - like on each wire version; reuse the refusal shapes - that request caps (#4820) settled. -- Cover it with a test that requests many distinct covered paths and checks - the front count stays bounded, and extend the origin benchmark with a - distinct-path axis. diff --git a/quest/m1/README.md b/quest/m1/README.md index 5dacd47d8b6..7025bfa565a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -25,9 +25,16 @@ a timestamp requires its JSON pilot. The hard fork follows, ahead of perf, and t of the QUIC line follows the fork. Every blocker ranks above the work it blocks. The quests that gated m0 lines moved under them. +The 2026-10-08 audit moved claim epochs, held group wakes, upstream position +regression, and the audio jitter target line here from m0; moved uring, +capture-chain, and first-FETCH pipelining work to m2; and deleted quests that +were done or not worth their cost. + ## Required - [One max_age meaning](/quest/m1/cache-max-age.md) - a superseded group goes stale on wall clock since its successor arrived or on media time, whichever is first, in Rust and js/net; fixes the untimed failover stall +- [Held group wakes](/quest/m1/held-group-wakes.md) - a group held across a route switch wakes when its successor's first timestamp or abort makes it stale; cache-max-age's wall-clock budget rides the same wake +- [Upstream position regression](/quest/m1/largest-regression.md) - a relay copy that sees upstream's largest group go backwards on moq-transport or epochless lite-07 fails loud instead of serving the old instance's cache - [Untimed decisions](/quest/m1/untimed-decisions.md) - the maintainer decides whether moq-archive keeps refusing untimed tracks, and whether a malformed FETCH object ends its track - [Untimed by default in Rust](/quest/m1/rust-untimed-default.md) - an undeclared Rust timescale means untimed, and shared-clock publishers declare milliseconds - [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - CMAF decoders time samples from the moq-lite frame timestamp, using `tfdt` only within the fragment @@ -37,54 +44,41 @@ blocks. The quests that gated m0 lines moved under them. - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net - [Hard fork](/quest/m1/quic/fork/README.md) - quinn hard-forked in-tree as `moq-quic`, ranked ahead of perf; the rest of the QUIC line follows it -- [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost +- [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` -- [moq-transport deviations](/quest/m1/ietf-deviations-doc.md) - `standard.md` lists the deviations Fastly's interop report flagged (one publisher per path, dropped object properties, OK before an old lite source answers) with their reasons - [Flat questlines](/quest/m1/quest-flat-lines.md) - moq pins the current quest CLI, lands its questline branches on main, and retires them - [moq-bot may push workflow changes](/quest/m1/bot-workflows-permission.md) - condition: the maintainer grants moq-bot's GitHub App the `workflows` permission, so back-merges carrying workflow changes go through - [main merges through a squash queue](/quest/m1/merge-queue-settings.md) - condition: once `release` carries the new back-merge script, the maintainer enables the squash merge queue and moq-bot's pull_request bypass together - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [fMP4 init from the catalog](/quest/m1/fmp4-catalog-init.md) - fMP4 export writes avc3/hev1 entries from the catalog, so an Annex-B H.264 or H.265 init no longer waits for the first keyframe - [Bump web-transport-iroh for the capsule close](/quest/m1/iroh-capsule-bump.md) - condition: moq-dev/web-transport#419 ships in a release, then moq's iroh HTTP/3 client reports a peer's close capsule -- [Early video demand](/quest/m1/catalog-early-demand.md) - a regression guards demand before the first keyframe after the detector removal - [Hang changelog](/quest/m1/hang-changelog-04.md) - the hang draft lists under -03 only what -03 published - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement +- [lite-07 Live flag](/quest/m1/lite-live.md) - a separate `Live` field on lite-07 SUBSCRIBE, so merged floors never starve a subscriber; late lower groups build on it - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges in either order and replaces FETCH; relays fill misses by range, including over moq-transport -- [Cold relay Largest](/quest/m1/ietf-cold-largest.md) - a relay reports the larger of its upstream's Largest and the largest object it received, even with nothing cached, so a d14-19 joining FETCH through it gets the current group's head -- [Live media time](/quest/m1/subscribe-live-time.md) - re-scoped against `set_live`: a lite-07 SUBSCRIBE_OK carries the publisher's current media time only if a reader still needs it - [Cross-relay bursts re-run](/quest/m1/cross-relay-bursts.md) - condition: the #4349 reporter re-runs their A/B/C comparison against current cdn.moq.pro -- [Cross-relay FETCH over moq-transport](/quest/m1/ietf-peer-fetch-old.md) - a moq-transport peer link serves held groups instead of refusing them as old, and the drill covers it +- [Cross-relay FETCH on any peer link](/quest/m1/ietf-peer-fetch-old.md) - a lite or moq-transport peer link serves held groups instead of refusing them as old, and the drill covers both - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time -- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it -- [lite-07 Live flag](/quest/m1/lite-live.md) - a separate `Live` field on lite-07 SUBSCRIBE, so merged floors never starve a subscriber; late lower groups build on it - [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does - [Flate stream budget](/quest/m1/flate-stream-budget.md) - a flate stream refuses an oversized append without ending, sharing one DEFLATE bound with json - [JS track takeover](/quest/m1/js-track-takeover.md) - JS `createTrack` answers a queued request and continues its sequences, as Rust does -- [JS query lifetime](/quest/m1/js-probe-lifetime.md) - a pending JS track-info query ends with its last requester, so broadcast demand drops - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets - [Dogfood hosted worklets](/quest/m1/dogfood-assets.md) - moq.dev and the moq.pro dashboard host the worklets and call `assets()` after the release +- [Media audio-tone check](/quest/m1/media-audio-tone.md) - the media lane's audio-tone check passes under load, fixed at its cause - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [moq-uring tests under load](/quest/m1/uring-tests-under-load.md) - uring tests pass while parallel checks share locked memory -- [Dropped uring session closes](/quest/m1/uring-drop-close.md) - a moq-uring session dropped without close() closes its connection -- [Media audio-tone check](/quest/m1/media-audio-tone.md) - the media lane's audio-tone check passes under load, fixed at its cause -- [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs - [Browser interop cells](/quest/m1/interop-browser-timeouts.md) - `go -> js` and `python -> js` pass, fixed at the cause rather than by a longer timeout - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives -- [cpal loads libasound at runtime](/quest/m1/cpal-alsa-runtime.md) - condition: a cpal release whose Linux build carries no load-time libasound requirement -- [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound -- [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away -- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [moq.sh deploys from CI](/quest/m1/moq-sh-deploy.md) - the first `release` run of the moq.sh workflow deploys with the Workers Editor token - [Plan: untimed verbatim PES](/quest/m1/plan-ts-pes-untimed.md) - decide how a verbatim TS track carries a PES that has no PTS, then write the implementation quest - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()` - [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - @moq/json and @moq/flate consumers return each value's timestamp, with snapshot `next()` and `latest()` - [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are -- [Pipelined first FETCH](/quest/m1/pipeline-fetch-info.md) - a fetch-only reader's first FETCH goes out with the track-info request, on lite and moq-transport -- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - our FETCH_OK carries the track properties SUBSCRIBE_OK does, as draft 16+ requires - [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - a relay fetches from an IETF upstream without subscribing, finished tracks included, with End of Track always reported +- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - our FETCH_OK carries the track properties SUBSCRIBE_OK does, as draft 16+ requires - [IETF object gaps](/quest/m1/ietf-object-gaps.md) - a gapped object ID is refused loudly like a subgroup in Rust and JS, and an overflowing one closes the session in Rust - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface @@ -94,22 +88,23 @@ blocks. The quests that gated m0 lines moved under them. - [Export linger](/quest/m1/export-ts-linger.md) - `moq export ts --linger` fails on an export error while the broadcast is live, and lingers once it closes or is replaced - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish +- [Claim epochs](/quest/m1/claim-epochs.md) - a lite-07 claim's answer carries its broadcast's epoch, so a worker restarting an output under an unchanged claim route is a new source; moved from m0 on 2026-10-08 since lite-07 is opt-in +- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a release tarball, and adopted by the OBS plugin - [OBS publishes under epochs](/quest/m1/obs-epoch.md) - each OBS Start Streaming is a fresh epoch, through the generated C++ - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [The final libmoq release is the stub](/quest/m1/libmoq-final-release.md) - the release that lets `rs/libmoq` go - [Retire the libmoq stub](/quest/m1/libmoq-retire.md) - the published `libmoq` crate stops after its final release points users at `moq-c` +- [VideoToolbox presets](/quest/m1/videotoolbox-presets.md) - VideoToolbox honors Balanced and Quality instead of always reporting LowLatency - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders - [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers - [HE-AAC catalog output](/quest/m1/he-aac-catalog-output.md) - HE-AAC catalog entries name the output rate and layout, not the LC core - [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - macOS and iOS encode AAC-LC -- [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) - the binding audio encoder takes the codec's own frame by default, so `aac()` needs no explicit 0 - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table - [A self-hosted NVIDIA runner is registered](/quest/m1/gpu-runner.md) - the maintainer registers the host that runs the NVIDIA tests - [GPU CI](/quest/m1/gpu-ci.md) - NVIDIA tests run nightly on a self-hosted GPU runner, and `just rs nvidia` runs them locally instead of skipping -- [NVENC keyframe flag](/quest/m1/nvenc-keyframe-flag.md) - NVENC flags keyframes from its reported picture type instead of scanning the bitstream - [Rendition preference](/quest/m1/rendition-preference.md) - automatic selection by ``, `Video::ranked`, and WHEP keeps the highest `preference` that decodes, so a compatibility transcode is only picked when nothing preferred decodes - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name - [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding @@ -121,10 +116,8 @@ blocks. The quests that gated m0 lines moved under them. - [Drain handshakes](/quest/m1/drain-handshakes.md) - a drain GOAWAYs and waits for sessions still in their handshake instead of exiting under them - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over without dropping a group - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants -- [IETF on the ring](/quest/m1/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol - [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) - packet bookkeeping scales with completed entries instead of scanning the flight on every ACK - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - retained evidence, repeated paired runs, and uncertainty for performance claims -- [Relay profiling](/quest/m1/performance-profiles.md) - reproducible CPU and allocation captures under the existing workloads - [Perf](/quest/m1/perf/README.md) - eliminate measured hot-path costs across moq-uring, kio, and the moq-net model - [#2924](/quest/m1/2924-moq-relay-tls-rotation-is-not-atomic-across-thread-per.md) - every listener on both runtimes shares one reloadable served identity, so rotation is atomic and generate works with workers - [Benchmark regressions in CI](/quest/m1/bench-ci.md) - PRs get a non-blocking comparison of the Criterion benches they affect, and a nightly trend on main alerts on regressions @@ -132,13 +125,16 @@ blocks. The quests that gated m0 lines moved under them. - [Relay session bench](/quest/m1/bench-relay.md) - the same scenario through moq-relay's own connection handling - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - measure JS transport, container, decode, and render costs in an identified browser - [Generated @moq/net](/quest/m1/rs2ts/README.md) - the browser runs moq-net as TypeScript generated from the Rust source, retiring js/net's hand-written protocol and model code +- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain - [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [Plan: watch worker](/quest/m1/plan-watch-worker.md) - prototype an invisible page worker against app-spawned workers, and land the jank harness that decides - [Watch worker](/quest/m1/watch-worker.md) - watch playback runs in a worker onto an OffscreenCanvas, so main-thread jank never stalls video or audio - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - with the default pool, relay memory plateaus at the expiry window on every version - [Frame slot charge](/quest/m1/frame-slot-charge.md) - a group's frame slots past the first four count against the cache pool, including capacity a released group keeps - [Front deadlines](/quest/m1/front-deadline-index.md) - a front's per-event cost stops growing with its track count: an expiry index and per-track wakes, proven by a churn benchmark -- [Listener deadlines](/quest/m1/listener-deadlines.md) - io_uring, HTTP/2, and the internal listener bound slow handshakes and headers, and iroh honors `quic.keep_alive` +- [io_uring handshake deadline](/quest/m1/listener-deadlines.md) - the io_uring workers apply `listen.timeout` to the handshake +- [HTTP listener deadlines](/quest/m1/listener-deadlines-http.md) - the HTTPS and internal listeners drop a connection with no request in flight for `listen.timeout` +- [iroh keep-alive](/quest/m1/iroh-keep-alive.md) - the iroh backend honors `quic.keep_alive` - [Rust papercuts](/quest/m1/papercuts-rs.md) - HTTP refusals are counted, a `u64::MAX` resume is unbounded, GOING_AWAY falls forward, and GRO stride 0 cannot panic - [JS papercuts](/quest/m1/papercuts-js.md) - IETF status 0 keeps the subgroup open, a muted rendition change settles, and bad element attributes warn - [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move @@ -149,11 +145,11 @@ blocks. The quests that gated m0 lines moved under them. - [qmux no-wait opens](/quest/m1/qmux-no-wait.md) - @moq/qmux rejects an over-limit create when waitUntilAvailable is false, like Chrome - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt - [#933](/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md) - the catalog rotation follows the live camera's orientation -- [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent - [Native audio quality](/quest/m1/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device - [Caption import](/quest/m1/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped - [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption or subtitle track survives conversion to a hang catalog +- [Fail loud on dropped timed metadata](/quest/m1/drop-loud.md) - FLV script tags and fMP4 emsg boxes are counted and warned about instead of silently dropped, until real carriage lands - [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 @@ -163,8 +159,7 @@ blocks. The quests that gated m0 lines moved under them. - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor - [TS passthrough](/quest/m1/ts-passthrough.md) - `--passthrough` carries the multiplex as whole packets, listed in an `m2ts` catalog section, and writes it back byte-identical (less late drops) on a fixed delay -- [FLV export delay](/quest/m1/flv-export-delay.md) - FLV interleaves through the shared jitter buffer -- [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared jitter buffer +- [FLV and MKV export delay](/quest/m1/export-delay.md) - FLV and MKV interleave through the shared jitter buffer on a fixed delay, breaking the CLI once - [MKV lacing](/quest/m1/mkv-lacing.md) - laced MKV blocks import as one timed frame each, refused without DefaultDuration - [Release profile](/quest/m1/release-profile.md) - every release build gets fat LTO, one codegen unit, and stripping from the workspace profile instead of three script exports - [Size report](/quest/m1/size-report.md) - a nightly job reports every shipped artifact's size, native and JS, and alerts when one grows @@ -173,13 +168,12 @@ blocks. The quests that gated m0 lines moved under them. - [Go mirror delivery](/quest/m1/go-mirror-delivery.md) - the Go binding's staticlibs stop growing git history by ~210 MiB per release - [Relay iroh opt-in](/quest/m1/relay-iroh-opt-in.md) - moq-relay drops iroh from its defaults and shipped builds, while moq-cli keeps it for P2P - [Dart on iOS](/quest/m1/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can -- [Kotlin JVM exit](/quest/m1/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 - [Dart publish](/quest/m1/dart-publish.md) - a `moq-dart-v*` tag publishes `moq` to pub.dev unattended, as `moq_ffi`'s tags already do - [Dart codec parity](/quest/m1/dart-codecs.md) - Dart is the one binding that cannot originate media - [`moq --listen` drain and stats](/quest/m1/cli-serve.md) - a listening CLI session, already admitted through the relay's auth, is counted and drained like a relay's - [#709](/quest/m1/709-automatic-letsencrypt-support.md) - the relay provisions and renews its own ACME certificate through rustls-acme over TLS-ALPN-01, persisted on disk - [Draft 14-16 updates](/quest/m1/ietf-legacy-updates.md) - Rust and JS apply and answer moq-transport 14-16 request updates without ending or leaking the request -- [JS session parity](/quest/m1/js-session-parity.md) - @moq/net gets moq-net's per-session caps, pending-tail hold, and resolved epochs -- [Headless subgroup in Rust](/quest/m1/ietf-headless-subgroup.md) - a draft 14-17 subgroup starting mid-group is dropped, not fatal, as in JS +- [JS session caps](/quest/m1/js-session-parity.md) - @moq/net enforces moq-net's per-session announce and subscription caps +- [JS pending tail](/quest/m1/js-pending-tail.md) - a JS reader holds for a track's pending tail like Rust, once #4225 lands - [In-band CMAF follow-ups](/quest/m1/cmaf-inline-followups.md) - MSF, h264/h265 export, and gst caps handle avc3/hev1 CMAF - [Datagram replay bound](/quest/m1/datagram-replay-bound.md) - a new Rust datagram subscriber starts within its max delay of the newest datagram, not at a minutes-old buffer diff --git a/quest/m0/audio-jitter-target/README.md b/quest/m1/audio-jitter-target/README.md similarity index 97% rename from quest/m0/audio-jitter-target/README.md rename to quest/m1/audio-jitter-target/README.md index b66b61753d6..b054dc3552a 100644 --- a/quest/m0/audio-jitter-target/README.md +++ b/quest/m1/audio-jitter-target/README.md @@ -36,7 +36,7 @@ the native decode path too, asserting the same target series the browser's ## Required -- [Watch](/quest/m0/audio-jitter-target/watch.md) - the browser's measured target, proven on Chrome and Safari against the public relay +- [Watch](/quest/m1/audio-jitter-target/watch.md) - the browser's measured target, proven on Chrome and Safari against the public relay ## Closes diff --git a/quest/m0/audio-jitter-target/watch.md b/quest/m1/audio-jitter-target/watch.md similarity index 100% rename from quest/m0/audio-jitter-target/watch.md rename to quest/m1/audio-jitter-target/watch.md diff --git a/quest/m1/audio-quality-native.md b/quest/m1/audio-quality-native.md index d45f65276be..978f6afb8f9 100644 --- a/quest/m1/audio-quality-native.md +++ b/quest/m1/audio-quality-native.md @@ -36,7 +36,7 @@ from whichever platform a user happened to be on. Nothing here is a second estimator, and this lane does not compare the two runtimes' target series: the [Audio jitter -target](/quest/m0/audio-jitter-target/README.md) line replays its recorded +target](/quest/m1/audio-jitter-target/README.md) line replays its recorded trace through the native decode path and asserts the browser's target series (2026-10-06 audit). This lane relies on that result; a disagreement there is a finding against that line and never a reason to widen a budget. It grades @@ -50,4 +50,4 @@ it grades is done on the jitter target line. ## Related -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - its native trace replay is the estimator comparison this lane relies on +- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - its native trace replay is the estimator comparison this lane relies on diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index 6d4b3c4e6a8..19f30aa2d1d 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -18,7 +18,9 @@ request token authorizing its own request (the fallback after the session grant, refresh by REQUEST_UPDATE, and a per-request relay lease on `moq_auth::Client`) is deferred until a moq-transport peer needs it; re-plan it then from [#4675](https://github.com/moq-dev/moq/pull/4675), which built -it. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) +it. #4675 is too large to review as one change, so it splits: the +decode-and-close part lands first as this quest, and the grant and lease work +parks on its branch. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) nor a lease. - Decode with the SETUP option's structure and rules diff --git a/quest/m1/av-clock.md b/quest/m1/av-clock.md index fc85b3842b8..48f7dcad5c0 100644 --- a/quest/m1/av-clock.md +++ b/quest/m1/av-clock.md @@ -27,7 +27,7 @@ spread, and one is nominated as the clock source. `SyncInput` and a third track joins without another pair of inputs; `Sync.register` already keeps one jitter entry per track and grows into the handles. The measured target per track comes from the [Audio jitter -target](/quest/m0/audio-jitter-target/README.md) line: each decoder registers +target](/quest/m1/audio-jitter-target/README.md) line: each decoder registers its own target through `Sync.register`, and `probe` stays in `SyncInput` unread so that line lands on `main`. This quest folds the registrations into the handles and drops `probe`. `SyncInput` is a published `@moq/watch` shape, so @@ -61,7 +61,7 @@ Recommendations for the implementation: ## Required -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the estimator this sits on, and the per-track targets this shape carries +- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the estimator this sits on, and the per-track targets this shape carries ## Related diff --git a/quest/m1/binding-surface.md b/quest/m1/binding-surface.md index 4b94d60d919..4ddf22f0fcb 100644 --- a/quest/m1/binding-surface.md +++ b/quest/m1/binding-surface.md @@ -29,4 +29,4 @@ decoder rather than to `BroadcastConsumer.decode_audio`, which Codecs removes. ## Related - [FFI shape](/quest/m1/ffi-shape/README.md) - reshapes the binding namespaces -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - landed the native decode delay API this exposes +- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - landed the native decode delay API this exposes diff --git a/quest/m1/cache-max-age.md b/quest/m1/cache-max-age.md index aba966b8f4a..7c8f22eaf3c 100644 --- a/quest/m1/cache-max-age.md +++ b/quest/m1/cache-max-age.md @@ -51,7 +51,7 @@ Decided (2026-10-06, maintainer): superseded group. Arm a wake at successor arrival + budget on those reader paths, re-armed when the successor changes. Decided 2026-10-08: one wake mechanism. The deadline rides the held group's `expiry::Wakes` entry from - [Held group wakes](/quest/m0/held-group-wakes.md), not a wake of its own; + [Held group wakes](/quest/m1/held-group-wakes.md), not a wake of its own; whichever lands second adds its trigger to that entry. - The swept benchmark measures cost and picks between evaluating the wall term on a timer and evaluating it lazily on access, for retention only. It @@ -122,7 +122,7 @@ encoding change; Max Age semantics in the lite draft change. ## Related -- [Held group wakes](/quest/m0/held-group-wakes.md) - the `Wakes` entry this quest's wall-clock deadline rides on +- [Held group wakes](/quest/m1/held-group-wakes.md) - the `Wakes` entry this quest's wall-clock deadline rides on - [lite-07 Live flag](/quest/m1/lite-live.md) - its untimed `Live` start (the latest group) follows this rule instead: replay what is not stale - [JS track handover](/quest/m1/js-group-handover.md) - mirrors the failover rule in JS - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - relay memory past the expiry window, in the same cache diff --git a/quest/m1/capture-default.md b/quest/m1/capture-default.md deleted file mode 100644 index a651dc5c3b5..00000000000 --- a/quest/m1/capture-default.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Capture is a default feature - -## Goal - -`capture` is on by default in moq-video and moq-audio, so the pre-merge -`just check` compiles and tests device capture like any other default code, -and the separate capture CI gate goes away. The flag stays so a minimal build -can opt out. Workspace consumers that set `default-features = false` (the -relay, the language bindings) keep building without it. - -## Plan - -Decided in planning (09-29), after capture-control (#4545) found that -pre-merge `just check` never ran moq-video's `capture` tests. `sh/rs/select.sh` -now runs `just rs capture-test` when moq-video or moq-audio changes, so this -is gate cleanup, not a coverage fix (reframed 2026-10-07): one default build -replaces the special branch. - -- **Default-on, keep the flag.** Removing the flag was rejected: consumers - that don't want device stacks would pay for them. -- moq-video's `capture` already costs nothing to build on any platform. Its - Cargo comment says it stays off only "until every distribution ships it", a - packaging concern this reverses. -- moq-audio's `capture` links libasound when it builds on Linux, which is why - it depends on [ALSA link](/quest/m1/capture-alsa-link.md). Once libasound - loads at runtime, the default costs no system library. -- Delete the special capture gate (`rs capture`, `capture-test`, and the - capture branch in `sh/rs/select.sh`) once default - `just check` covers it. Keep the platform jobs (`just rs macos`, - `just rs windows`). -- Update the Cargo feature comments and `doc/` wherever capture is described - as opt-in. moq-cli's `capture` feature stays: the root manifest pins - moq-video and moq-audio to `default-features = false` for every workspace - consumer, and [Ship capture and playback](/quest/m1/cli-packaging.md) makes - it default-on and droppable. - -Verify: `just check` on a moq-video or moq-audio change runs the capture -tests, and a `default-features = false` consumer (for example -`cargo tree -p moq-ffi -e features`) pulls no capture dependency. - -## Required - -- [ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture can't be on by default while it links libasound at build time diff --git a/quest/m1/catalog-early-demand.md b/quest/m1/catalog-early-demand.md deleted file mode 100644 index 5e724c5d2a6..00000000000 --- a/quest/m1/catalog-early-demand.md +++ /dev/null @@ -1,29 +0,0 @@ -# [XS] Guard video demand before the first keyframe - -## Goal - -A regression test proves that demand on a video track before its first -keyframe does not end the import or modify an unpublished rendition. -It guards the importer failure reported in #4945. - -## Plan - -The enabled-flag change in [#4915](https://github.com/moq-dev/moq/pull/4915) -removes `publish_stalled` and the importer detector hooks that called -`track.modify()` before a configuration was published. The catalog now -publishes a resolved configuration through `track.set()`; it has no -mutation driven by early demand. The relay half of the report is fixed by -[#4942](https://github.com/moq-dev/moq/pull/4942)'s publisher epochs. - -The source fixes are present; the before-first-keyframe regression from -the imported issue remains to be added. Exercise a video importer with -track demand before it resolves its configuration, then deliver its first -keyframe and require the import to continue. Use mocked time if needed, -and keep the test in the existing moq-mux Check/Test suite. Do not restore -the removed detector or add an availability mechanism. - -Public API: none. Wire: none. - -## Closes - -- [#4945](https://github.com/moq-dev/moq/issues/4945) - early video demand does not end a replacement import with "rendition is not published" diff --git a/quest/m1/ci-runner-stalls.md b/quest/m1/ci-runner-stalls.md deleted file mode 100644 index 6d3aea5d20c..00000000000 --- a/quest/m1/ci-runner-stalls.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] Interop freezes on CI runners are attributed - -## Goal - -The 0.4 to 0.8 s freezes where both interop tracks stop at once on CI are -attributed to the runner, the relay, or the player, with evidence from the -nightly traces. A cause in our code is fixed at its source; a runner stall is -documented, and the interop checks tell it apart from a playback bug instead -of failing on it as one. - -## Plan - -Found in [#4529](https://github.com/moq-dev/moq/pull/4529) while chasing the -cold-start tone check: some CI traces show both tracks freezing together, -which that fix shortens but cannot remove. #4529 added the player's `delay` to -the interop trace, so a week of nightlies after it lands shows the freezes -without the delay-flush noise that hid them. - -Collect the failing and passing nightly interop traces for that week, line up -each freeze against relay and player timestamps, and look for what the -runner was doing (CPU steal, GC, disk). Decided with the maintainer: diagnose -first from real nightlies rather than assume a runner stall. - -Public API: none. Wire: none. diff --git a/quest/m0/broadcast-epoch/claim-epochs.md b/quest/m1/claim-epochs.md similarity index 98% rename from quest/m0/broadcast-epoch/claim-epochs.md rename to quest/m1/claim-epochs.md index aef6101a5ac..cc06976247e 100644 --- a/quest/m0/broadcast-epoch/claim-epochs.md +++ b/quest/m1/claim-epochs.md @@ -95,5 +95,5 @@ it. Wire: lite-07 TRACK_INFO gains `Epoch`. ## Related - [Idle fronts](/quest/m0/idle-fronts.md) - ends an unread front and its per-path state after the linger on every version -- [Upstream position regression](/quest/m0/largest-regression.md) - catches the same restart from the answer's largest position on lite-07 and moq-transport; lite-05 and 06 stay uncovered +- [Upstream position regression](/quest/m1/largest-regression.md) - catches the same restart from the answer's largest position on lite-07 and moq-transport; lite-05 and 06 stay uncovered - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - waits on this wire change diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 636673fb67d..1355f844ed0 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -75,7 +75,7 @@ vector the 2026-09-30 cache-tiers audit kept: origin's per-prefix cost rides ANNOUNCE untouched (`transcode/**` at 10 and `transcode/foobar` at 1 from one node). Static configured costs stay the default (the CDN); a radio link may measure its - own ([Link quality](/quest/m1/cluster-routing/link-quality.md)). + own ([Link quality](/quest/m2/link-quality.md)). - **Topology now, wire later.** moq.pro's edge and core migration runs on today's lite-06 path vector with upstream links; the route layer lands in lite-07 (the current wip version) afterwards with no re-layout, once @@ -90,7 +90,7 @@ One route cost lands on its own (`--hop` was replaced by `--epoch` in #4969). De 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. -Decided 2026-10-08: [Link quality](/quest/m1/cluster-routing/link-quality.md) +Decided 2026-10-08: [Link quality](/quest/m2/link-quality.md) is Related, not Required, and moves to m2; measured cost is opt-in and the line ships on static costs. @@ -140,7 +140,7 @@ Once every child has landed: ## Related -- [Link quality](/quest/m1/cluster-routing/link-quality.md) - a radio link's cost follows its measured quality without flapping routes; not a blocker, since static costs are the default +- [Link quality](/quest/m2/link-quality.md) - a radio link's cost follows its measured quality without flapping routes; not a blocker, since static costs are the default - [P2P](/quest/m3/p2p/README.md) - browser and native peers that become routing nodes over this layer - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static cost - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - the importer half of a redundant pair under one explicit epoch diff --git a/quest/m1/color-model.md b/quest/m1/color-model.md index 77edcb0ffd7..a6a9f868e94 100644 --- a/quest/m1/color-model.md +++ b/quest/m1/color-model.md @@ -16,10 +16,10 @@ requested color: convert correctly or refuse. Preserve color information through CUDA, D3D, and Android paths and test the signaled VUI against pixels. Decided in the 2026-09-30 audit: split from the catalog colour model, which -moved to [Catalog colour](/quest/m2/color-catalog.md) because no renderer +moved to [Catalog colour](/quest/m3/color-catalog.md) because no renderer consumes colour from the catalog today. Encoder correctness stays in m1 because a mislabelled stream is wrong for every consumer. ## Related -- [Catalog colour](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties +- [Catalog colour](/quest/m3/color-catalog.md) - the catalog describes a rendition's colour and HDR properties diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index 65dda4ecacf..2327e124557 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -44,7 +44,7 @@ on a future under `__cpp_impl_coroutine`, `std::expected` under Distribution is a release tarball with a CMake package config and pkg-config file (mirroring `moq-c.yml`), so consumers never need a Rust toolchain or the bindgen fork. Decided in the 2026-09-30 audit: this line promises the tarball -only. A [vcpkg registry](/quest/m2/cpp-vcpkg.md) and a +only. A [vcpkg registry](/quest/m3/cpp-vcpkg.md) and a [Conan remote](/quest/m3/cpp-conan.md) fetch the same tarball later and stay deferred. @@ -80,6 +80,6 @@ too. What remains is landing [#4079](https://github.com/moq-dev/moq/pull/4079). ## Related -- [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests +- [vcpkg registry](/quest/m3/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests - [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the prebuilt package to Conan - [Unreal prototype](/quest/m3/unreal.md) - a UE5 module consumes the package with exceptions disabled diff --git a/quest/m1/flv-export-delay.md b/quest/m1/export-delay.md similarity index 100% rename from quest/m1/flv-export-delay.md rename to quest/m1/export-delay.md diff --git a/quest/m1/ffi-frame-duration-default.md b/quest/m1/ffi-frame-duration-default.md deleted file mode 100644 index 05d17afa52e..00000000000 --- a/quest/m1/ffi-frame-duration-default.md +++ /dev/null @@ -1,29 +0,0 @@ -# [XS] FFI audio encoder takes the codec's own frame by default - -## Goal - -`MoqAudioEncoderOutput::frame_duration_us` defaults to 0, the -codec's own frame, so `MoqAudioCodec::aac()` works without an explicit 0 in -every binding. Opus still encodes 20 ms frames by default. - -## Plan - -- Decided in [#4183](https://github.com/moq-dev/moq/pull/4183): the uniffi - default moves from 20000 to 0. Changing a published binding default is a - break. Split from AudioToolbox encode on 2026-09-30. -- `rs/moq-ffi/src/audio.rs` already treats 0 as the codec's frame; the - `default_frame_duration_matches_moq_audio` test that pins 20000 to - moq-audio's default goes away with the literal. -- Update the wrappers and docs that restate 20000: the Python test asserting - the default, `py/moq-rs/README.md`, and `doc/lib/{py,swift,kt,go,dart}`. - libmoq already reads 0 as the default. - -Decided in the 2026-10-05 audit: this lands after -[Codecs](/quest/m1/ffi-shape/codec.md), which moves the same audio encoder -surface, so callers take the default change on the reshaped type. - -Public API: breaking default in moq-ffi and every binding. Wire: none. - -## Required - -- [Codecs](/quest/m1/ffi-shape/codec.md) - reshapes the audio encoder output this default lives on diff --git a/quest/m0/held-group-wakes.md b/quest/m1/held-group-wakes.md similarity index 100% rename from quest/m0/held-group-wakes.md rename to quest/m1/held-group-wakes.md diff --git a/quest/m1/ietf-cold-largest.md b/quest/m1/ietf-cold-largest.md deleted file mode 100644 index 0b84d0bca42..00000000000 --- a/quest/m1/ietf-cold-largest.md +++ /dev/null @@ -1,61 +0,0 @@ -# [M] A cold relay reports its upstream's Largest - -## Goal - -On drafts 14 to 19, a relay's SUBSCRIBE_OK reports the larger of its -upstream's Largest Location and the largest object it has received for the -track, including when it has cached nothing yet. A relative joining FETCH -(start 0) through a cold relay then gets the head of the current group, -filled upstream if needed, instead of INVALID_RANGE. - -## Plan - -Triaged from Fastly's moq-relay-interop report (2026-09-23 run, item 14) -on 2026-10-07. The report's DOES_NOT_EXIST was fixed by #4253: the empty -join is INVALID_RANGE now, which the draft requires when no Largest was sent. -What remains is that the Largest is lost. d18 ยง10.2.11 and d19 ยง10.2.16 -say "A relay MUST set LARGEST_OBJECT to the largest of" the upstream's -LARGEST_OBJECT and the largest object received upstream, whatever the -cache holds; d14 to d17 state no rule, so follow the same one there. - -- The publisher's SUBSCRIBE_OK carries `live_edge(&cache).largest` - (`rs/moq-net/src/ietf/publisher.rs`, around lines 664 and 717), which is - `None` until a group is cached, so `(Filter::NextObject, None)` becomes - `Joined::Empty`. -- The subscriber passes its upstream's Largest only to - `track.start_at(largest.group)` and its held subscription state - (`rs/moq-net/src/ietf/subscriber.rs`, around line 2013), and does not - record the object. `live_floor` (`model/track.rs`) is a cache-validity - group floor, not the upstream's Largest. -- The latest group is protected from eviction while the track has a - producer, but `live_edge` falls back through the cache when the newest - group has no object yet. An empty newer group demotes the last - object-bearing group, which can then expire, losing its Location. - -Decided 2026-10-07: carry the upstream's Largest into the model, and keep a -high-watermark of the largest object received that expiry does not lower, -so the publisher reports the maximum of the two. Serve the joining FETCH -through the existing one-group upstream fill. Rejected: leaving -INVALID_RANGE, which is compliant but loses late joiners' first group head. -This reports state learned from the upstream; nothing waits on a peer. The -same Largest goes out in every response this relay sends that carries one: -SUBSCRIBE_OK and the track-update REQUEST_OK. Inbound PUBLISH is refused -today (`run_publish_stream`), so it is out of scope. - -Scrutinize the model change: keep any new track state crate-private unless a -consumer needs it. - -Test: through a cold relay, a d16 subscriber with a relative joining FETCH -(start 0) receives the current group from object 0, and its SUBSCRIBE_OK -carries the upstream's Largest. On d18 and d19, a relay whose cached -objects are behind the upstream's Largest reports the upstream's, and one -whose cache is ahead reports its own. Regression for the high-watermark: -create an empty newer group, expire the older object-bearing group it -demoted, and SUBSCRIBE_OK still reports that group's received Location. - -Public API: none expected. Wire: none new. - -## Related - -- [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - the same upstream fill path, for multi-group ranges -- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - the other FETCH gap at a relay diff --git a/quest/m1/ietf-deviations-doc.md b/quest/m1/ietf-deviations-doc.md deleted file mode 100644 index 91e1eaf0f00..00000000000 --- a/quest/m1/ietf-deviations-doc.md +++ /dev/null @@ -1,26 +0,0 @@ -# [XS] Document the relay's moq-transport deviations - -## Goal - -`doc/concept/standard.md` lists, under moq-transport, the deliberate -deviations that Fastly's moq-relay-interop report flagged, each with its -reason and draft section, so the next interop run has something to point at: - -- One publisher per broadcast path: a SUBSCRIBE goes to one route, not to - every matching publisher (d16 ยง8.4), because a path names one content. -- Unknown object properties are dropped, not forwarded (d18 ยง2.5), because - the model carries only payload and timestamp. -- A source with no track stream (lite-01 to 04) behind the relay gets - SUBSCRIBE_OK before the source answers, so a missing track ends as - PUBLISH_DONE, not REQUEST_ERROR. - -## Plan - -Triaged on 2026-10-07. Decided then: these are the product's model (see -[A gapped IETF object ID](/quest/m1/ietf-object-gaps.md) and the AGENTS.md -rule that a name always means the same content), so they are documented, -not changed. Check the wording against `doc/concept/moq-lite.md`, which -already explains what moq-lite leaves out, and link to it rather than -repeat it. - -Public API: none. Wire: none. diff --git a/quest/m1/ietf-headless-subgroup.md b/quest/m1/ietf-headless-subgroup.md deleted file mode 100644 index 591a561b2c7..00000000000 --- a/quest/m1/ietf-headless-subgroup.md +++ /dev/null @@ -1,21 +0,0 @@ -# [S] Rust drops a headless draft 14-17 subgroup - -## Goal - -A Rust moq-net subscriber on moq-transport drafts 14 to 17 that receives a -subgroup stream starting mid-group (a non-zero first object ID, since those -drafts have no FIRST_OBJECT bit) drops that stream and keeps the -subscription, as `@moq/net` does since #5019, instead of failing the group. - -## Plan - -First check whether Rust has the bug: a test that opens a subgroup at object -2 on d14 and d16 and expects the subscription to stay up for the next group. -If it fails, apply #5019's rule: on a draft without the bit, a non-zero first -delta takes the same drop path as a cleared FIRST_OBJECT bit on d18. A gap -after an object was delivered still fails that group. If it passes, delete -this quest. - -## Related - -- [Gapped IETF object IDs](/quest/m1/ietf-object-gaps.md) - a headless d14-17 subgroup is a quiet drop; only a gap after a delivered object is refused loudly diff --git a/quest/m1/iroh-keep-alive.md b/quest/m1/iroh-keep-alive.md new file mode 100644 index 00000000000..7aa7f4b6eba --- /dev/null +++ b/quest/m1/iroh-keep-alive.md @@ -0,0 +1,17 @@ +# [XS] iroh honors quic.keep_alive + +## Goal + +The iroh backend sends keep-alives at `quic.keep_alive`, like the QUIC +backend, and the docs stop saying iroh has no knob. + +## Plan + +Set `keep_alive_interval` from `quic.keep_alive` in `rs/moq-tokio/src/iroh.rs` +(the locked iroh 1.2 already has +`QuicTransportConfigBuilder::keep_alive_interval`, so no bump), and fix the +docs that say iroh has no knob (`rs/moq-tokio/src/quic.rs`, +`rs/moq-tokio/src/iroh.rs`, `doc/bin/relay/config.md`). Split from +[io_uring handshake deadline](/quest/m1/listener-deadlines.md) on 2026-10-08. + +Public API: none. Wire: none. diff --git a/quest/m1/js-pending-tail.md b/quest/m1/js-pending-tail.md new file mode 100644 index 00000000000..195259477ee --- /dev/null +++ b/quest/m1/js-pending-tail.md @@ -0,0 +1,24 @@ +# [S] JS readers hold for a track's pending tail + +## Goal + +A `@moq/net` reader of a received track waits for missing groups below a +declared end until the tail settles, as Rust readers do once #4225 lands, +instead of ending at the end with groups missing (`doc/lib/js/net.md`). + +## Plan + +Mirror the Rust hold from [Track tail interop](/quest/m1/track-tail-interop.md) +(#4225) once it merges, and test it against the Rust behavior with mocked +time. Split from [JS session parity](/quest/m1/js-session-parity.md) on +2026-10-08 so the caps work stays ready. + +Public API: none. Wire: none. + +## Required + +- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust hold this mirrors + +## Related + +- [JS session parity](/quest/m1/js-session-parity.md) - per-session caps, the other half diff --git a/quest/m1/js-probe-lifetime.md b/quest/m1/js-probe-lifetime.md deleted file mode 100644 index b0c5ff0bf77..00000000000 --- a/quest/m1/js-probe-lifetime.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] A JS track-info query ends with its last requester - -## Goal - -In `@moq/net`, a pending track-info query counts as broadcast demand only -while someone still wants the answer. When the requester's TRACK stream is -reset or its session closes before the publisher answers, the query ends and -`Broadcast.Demand` drops, as in Rust. - -## Plan - -Found in the review of #4956. Decided 2026-10-07: mirror Rust, where the -query is a consumer of the track state that counts toward demand and drops -with the serve (`TrackInfoServe`, `rs/moq-net/src/lite/publisher.rs`). - -- `resolveTrackInfo` (`js/net/src/broadcast.ts`) takes an `AbortSignal` and - pins demand only while a requester holds the query. -- The lite publisher (`runTrackInfo`, `runFetch`, and `#resolveTrackInfo` in - `js/net/src/lite/publisher.ts`) watches the TRACK or FETCH stream for a - reset and releases its hold; the shared per-front query ends with its last - holder. -- Fold in the review nit: `removeTrack` on a name cached only by a - `consume()` subscription is outside its documented contract; document or - refuse it. - -Test: a requester (TRACK or FETCH) that disconnects before the answer drops -broadcast demand, and a second requester keeps it pinned until it leaves too. - -Public API: none (`resolveTrackInfo` is internal, reached through `Wire`). -Wire: none. diff --git a/quest/m1/js-session-parity.md b/quest/m1/js-session-parity.md index 85586afcffa..43f342b4949 100644 --- a/quest/m1/js-session-parity.md +++ b/quest/m1/js-session-parity.md @@ -1,9 +1,9 @@ -# [M] @moq/net session parity with moq-net +# [S] @moq/net per-session caps match moq-net ## Goal -Two Rust moq-net session behaviors hold in `@moq/net` too, so a JS peer or -relay behaves like a Rust one. +Rust moq-net's per-session caps hold in `@moq/net` too, so a JS peer or +relay refuses past them like a Rust one. ## Plan @@ -11,12 +11,9 @@ relay behaves like a Rust one. subscription caps to JS with the same defaults (100,000 and 10,000) and close the session with TOO_MANY_REQUESTS (0x7) past them, as Rust does. JS's own request-ID window is [JS request window](/quest/m1/js-request-window.md). -- Pending tail (#4225, still open): once Rust readers of a received track - wait for missing groups below a declared end until the tail settles, mirror - the hold. JS readers still end at the end with groups missing - (`doc/lib/js/net.md`). - -Test each against the Rust behavior, with mocked time. +Test against the Rust behavior, with mocked time. The pending-tail hold +split out to [JS pending tail](/quest/m1/js-pending-tail.md) on 2026-10-08, +since it waits on #4225 and the caps do not. Decided 2026-10-08: the resolved-epoch check is done for JS (`broadcast.Consumer.epoch` mirrors `broadcast::Info::epoch`), and the @@ -24,4 +21,5 @@ bindings' epoch surface is [Bindings](/quest/m0/broadcast-epoch/bindings.md)'s. ## Related +- [JS pending tail](/quest/m1/js-pending-tail.md) - the other half of session parity, behind #4225 - [JS request window](/quest/m1/js-request-window.md) - JS grants request IDs as requests close, the other half of JS request limits diff --git a/quest/m0/largest-regression.md b/quest/m1/largest-regression.md similarity index 96% rename from quest/m0/largest-regression.md rename to quest/m1/largest-regression.md index ef2cfbcfdc2..78f0bb4ed5d 100644 --- a/quest/m0/largest-regression.md +++ b/quest/m1/largest-regression.md @@ -60,5 +60,5 @@ Public API: none. Wire: none. ## Related -- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - prevents the splice on lite-07 by naming the instance +- [Claim-served epochs](/quest/m1/claim-epochs.md) - prevents the splice on lite-07 by naming the instance - [Coalesce dynamic tracks](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - keeps sequences going when a dynamic track's producer is replaced within one broadcast diff --git a/quest/m1/listener-deadlines-http.md b/quest/m1/listener-deadlines-http.md new file mode 100644 index 00000000000..7d7e73f29a5 --- /dev/null +++ b/quest/m1/listener-deadlines-http.md @@ -0,0 +1,31 @@ +# [M] HTTP listeners drop a connection with no request in flight + +## Goal + +The HTTPS listener's HTTP/2 path and the `[internal]` listener drop a +connection with no complete request in flight for `listen.timeout`, covering +slow headers and an idle keep-alive, even one that ACKs every PING. + +## Plan + +- `axum_server` builds hyper with no timer, and #4612's + `header_read_timeout` is HTTP/1 only. hyper's HTTP/2 PING keep-alive + (`http2().timer(..)`, `keep_alive_interval`, `keep_alive_timeout`) only + detects a dead peer: a client that ACKs every PING and never finishes a + request stays up. So the bound is a per-connection idle deadline: the + connection closes once it has had no complete request in flight for + `listen.timeout`, which covers both a trickled HEADERS block and an idle + keep-alive. hyper has no such knob, so it lives in the relay's serve path + (`rs/moq-relay/src/listener.rs` and `web.rs`, e.g. an in-flight counter in + the per-connection service driving that connection's graceful shutdown). +- Set the PING keep-alive too, for dead peers. Apply both to the HTTPS + listener and the `[internal]` listener, which also gets the HTTP/1 header + timer. +- Tests on a paused clock: an HTTP/2 client that ACKs PINGs but never sends a + request, or trickles one request's headers, is dropped at the deadline + while one with a request in flight is not. + +Split from [io_uring handshake deadline](/quest/m1/listener-deadlines.md) on +2026-10-08. + +Public API: none beyond existing settings. Wire: none. diff --git a/quest/m1/listener-deadlines.md b/quest/m1/listener-deadlines.md index 60f3c718abe..25c598729ff 100644 --- a/quest/m1/listener-deadlines.md +++ b/quest/m1/listener-deadlines.md @@ -1,41 +1,29 @@ -# [L] Every listener bounds its handshake and headers +# [S] io_uring workers bound the handshake ## Goal -Every relay listener bounds slow peers the way the default runtime does -after the handshake deadline (moq-dev/moq#4612): the io_uring -workers apply `listen.timeout`, the HTTPS listener's HTTP/2 path and the -`[internal]` listener drop a connection with no complete request in flight -for `listen.timeout` (covering slow headers and an idle keep-alive, even one -that ACKs every PING), and the iroh backend honors `quic.keep_alive`. +The io_uring workers bound a slow handshake the way the default runtime does +after the handshake deadline (moq-dev/moq#4612), by applying +`listen.timeout`. ## Plan -- io_uring (`rs/moq-relay/src/uring.rs` `serve_connection`): bound the +- `rs/moq-relay/src/uring.rs` `serve_connection`: bound the WebTransport `Request::accept`, `respond`, and `accept_request_lite` by one deadline from `listen::Config::resolved_timeout()`, on the worker's own timer (`rs/moq-uring/src/timer.rs`), closing with the timeout code. Delete - the "There is no timeout here" note in `rs/moq-uring/src/quic/web.rs`. -- HTTP: `axum_server` builds hyper with no timer, and #4612's - `header_read_timeout` is HTTP/1 only. hyper's HTTP/2 PING keep-alive - (`http2().timer(..)`, `keep_alive_interval`, `keep_alive_timeout`) only - detects a dead peer: a client that ACKs every PING and never finishes a - request stays up. So the bound is a per-connection idle deadline: the - connection closes once it has had no complete request in flight for - `listen.timeout`, which covers both a trickled HEADERS block and an idle - keep-alive. hyper has no such knob, so it lives in the relay's serve path - (`rs/moq-relay/src/listener.rs` and `web.rs`, e.g. an in-flight counter in - the per-connection service driving that connection's graceful shutdown). - Set the PING keep-alive too, for dead peers. Apply both to the HTTPS - listener and the `[internal]` listener, which also gets the HTTP/1 header - timer. -- iroh (`rs/moq-tokio/src/iroh.rs`): set `keep_alive_interval` from - `quic.keep_alive` (the locked iroh 1.2 already has it), and fix the docs - that say iroh has no knob (`quic.rs`, `iroh.rs`, and - `doc/bin/relay/config.md`). -- Tests on a paused clock where the runtime allows: a stalled io_uring - handshake closes at the deadline, and an HTTP/2 client that ACKs PINGs but - never sends a request, or trickles one request's headers, is dropped at the - deadline while one with a request in flight is not. + the "There is no timeout here" note in `rs/moq-uring/src/quic/web.rs`, and + the matching caveat in `doc/bin/relay/config.md`. +- Test on the worker's timer: a stalled handshake closes at the deadline. + +Split on 2026-10-08: the HTTP/2 idle deadline is +[HTTP listener deadlines](/quest/m1/listener-deadlines-http.md) and the iroh +keep-alive is [iroh keep-alive](/quest/m1/iroh-keep-alive.md); each lands on +its own. Public API: none beyond existing settings. Wire: none. + +## Related + +- [HTTP listener deadlines](/quest/m1/listener-deadlines-http.md) - the HTTPS and internal listeners' half +- [iroh keep-alive](/quest/m1/iroh-keep-alive.md) - the iroh backend's half diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index df8dc10f7f4..417909d5cf5 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -80,7 +80,7 @@ is published; older versions are unchanged. - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Untimed lite-07](/quest/m1/lite-untimed.md) - an untimed track crosses the wire untimed - [One route cost](/quest/m1/route-cost.md) - ANNOUNCE carries one cost -- [Claim-served epochs](/quest/m0/broadcast-epoch/claim-epochs.md) - TRACK_INFO carries the epoch of the instance that answered +- [Claim-served epochs](/quest/m1/claim-epochs.md) - TRACK_INFO carries the epoch of the instance that answered ## Related diff --git a/quest/m1/mkv-export-delay.md b/quest/m1/mkv-export-delay.md deleted file mode 100644 index c8382691f98..00000000000 --- a/quest/m1/mkv-export-delay.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] MKV export releases frames on a fixed delay - -## Goal - -`moq export mkv --delay ` interleaves tracks through the shared -jitter buffer, so its tag order is a function of the media, not -of arrival, as the TS export's is. - -## Plan - -Today `pick_next_track` (`rs/moq-mux/src/container/mkv/export.rs`) takes the -smallest *pending* timestamp, so which track goes first depends on which frame -has arrived. Replace it with the jitter buffer the TS export uses -(`rs/moq-mux/src/jitter.rs`), with the same `--delay` flag and the same -late-frame drop. Update `doc/bin/cli.md`. - -Decided in the 2026-10-06 audit: `--delay` replaces the staleness flag, as it -replaced `--max-age` on TS, so one knob sets both the release delay and the -sources' staleness budget. [#4917](https://github.com/moq-dev/moq/pull/4917) -renames that flag to `--max-delay` first; this quest then replaces -`--max-delay` with `--delay`. Rejected: excluding mkv from the #4917 rename. - -Public API: breaking, the exporter's staleness setting becomes the delay -setting. Wire: none. diff --git a/quest/m1/mkv-lacing.md b/quest/m1/mkv-lacing.md index 3fc4da89743..358dea93956 100644 --- a/quest/m1/mkv-lacing.md +++ b/quest/m1/mkv-lacing.md @@ -25,4 +25,4 @@ Public API: none. Wire: none. ## Related -- [Export delay](/quest/m1/flv-export-delay.md) - the export side of the same container +- [Export delay](/quest/m1/export-delay.md) - the export side of the same container diff --git a/quest/m1/nvenc-keyframe-flag.md b/quest/m1/nvenc-keyframe-flag.md deleted file mode 100644 index a377f53eac2..00000000000 --- a/quest/m1/nvenc-keyframe-flag.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] NVENC reports its own keyframes - -## Goal - -The `moq-video` NVENC backend sets `Encoded::keyframe` from the picture type -NVENC reports for the output. It stops re-deriving the flag by scanning the -Annex-B slice type. - -## Plan - -- moq-nvenc already reads `pictureType` when it locks the output bitstream, - but `Submission::finish` returns only the bytes. Expose the picture type, or - a keyframe bool, on that result. It is a published crate, so weigh the - shape against the other fields a caller may want later, such as the output - timestamp. -- NVENC's IDR and I picture types are not the same thing. The flag should - mean what the moq-mux importer treats as a group start (an H.264 IDR, an - H.265 IRAP), so check both codecs on hardware. -- The NVIDIA tests skip under the Nix shell unless the driver libraries are on - the loader path; see [GPU CI](/quest/m1/gpu-ci.md). - -## Related - -- [#4295](https://github.com/moq-dev/moq/pull/4295) - added the flag, with NVENC on the bitstream fallback diff --git a/quest/m1/obs-moq-video/rate-control.md b/quest/m1/obs-moq-video/rate-control.md index 6aa7433d8bc..4946be7ada7 100644 --- a/quest/m1/obs-moq-video/rate-control.md +++ b/quest/m1/obs-moq-video/rate-control.md @@ -28,4 +28,4 @@ whether a second binding wants it. Verify against a shaped uplink and with ## Related -- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the shared rate policy audio adopts; OBS audio still reserves only +- [Audio follows the grant](/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the shared rate policy audio adopts; OBS audio still reserves only diff --git a/quest/m1/obs-moq-video/vpx-obs.md b/quest/m1/obs-moq-video/vpx-obs.md index 9502e37aaf3..065a281dc87 100644 --- a/quest/m1/obs-moq-video/vpx-obs.md +++ b/quest/m1/obs-moq-video/vpx-obs.md @@ -16,4 +16,4 @@ The OBS MoQ source plays VP8 and VP9 (8-bit 4:2:0) on every platform it ships fo ## Related -- [Codec coverage](/quest/m2/video-codec-coverage.md) - hardware VP8/VP9 decode belongs to that review +- [Codec coverage](/quest/m3/video-codec-coverage.md) - hardware VP8/VP9 decode belongs to that review diff --git a/quest/m1/papercuts-js.md b/quest/m1/papercuts-js.md index 111cf5fcb1c..56a8e2cfbf4 100644 --- a/quest/m1/papercuts-js.md +++ b/quest/m1/papercuts-js.md @@ -39,4 +39,4 @@ Public API: none. Wire: none. - [End of Group status](/quest/m0/ietf-end-of-group-status.md) - the same `Frame.decode` status branch, landing first - [Rust papercuts](/quest/m1/papercuts-rs.md) - the Rust half of the same audit -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - owns the audio ring and its backpressure +- [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - owns the audio ring and its backpressure diff --git a/quest/m1/performance-profiles.md b/quest/m1/performance-profiles.md deleted file mode 100644 index b9817b837bb..00000000000 --- a/quest/m1/performance-profiles.md +++ /dev/null @@ -1,48 +0,0 @@ -# [M] Reproducible relay CPU and allocation profiles - -## Goal - -One local recipe captures a symbolized relay profile under an existing workload, -with enough metadata to reproduce it and distinguish relay cost from load-generator -cost. Profiling is opt-in and has no production overhead when disabled. - -## Plan - -`bench/run.sh` already owns the builds, relay PID, workload, and host -samples, but has no profiler integration. Reuse that lifecycle instead -of adding a second launcher. `Cargo.toml` already has a `profiling` profile and -`rs/moq-tokio/src/jemalloc.rs` already supports on-demand heap dumps. - -- Add a focused `just` recipe selecting workload, duration, and capture mode through - one configuration. Reuse locked builds and the existing profiling Cargo profile; - record frame-pointer flags, features, compiler, OS/kernel, CPU, runtime, affinity, - allocator, exact revision, dirty diff, and resolved workload alongside the result. -- Capture the relay process and all its workers, excluding the load generator. - Start sampling after readiness and mark the measurement window. Keep an - uninstrumented control run to quantify profiler overhead. -- Support symbolized CPU stacks on Linux with perf and on macOS with a maintained - profiler such as samply. Probe tool/platform permissions and report unsupported - captures clearly. Do not silently substitute wall-clock timing for CPU samples. -- Reuse jemalloc's supported build/configuration and signal listener for heap - snapshots before load, at steady state, and after teardown. Include allocation - churn as well as retained bytes; snapshots alone cannot establish allocation rate. - Never send a profiling signal before verifying the listener is active. -- Retain raw captures, symbols or binary identity, commands, logs, and a locally - viewable report in a caller-selected artifact directory. On cancellation or a - failed capture, stop owned profiler/load/relay children and preserve diagnostics. -- Validate on one supported Linux host and macOS. A smoke capture must contain - resolved MoQ frames, the intended PID/window, and nonempty samples. Exercise an - unavailable profiler and an interrupted run without leaving children behind. - -Tool references: [samply](https://github.com/mstange/samply) and the existing -[jemalloc controls](https://jemalloc.net/jemalloc.3.html) are starting points; -verify current supported versions and pin any newly installed tools. - -## Required - -- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - reuse its workload lifecycle and artifact metadata - -## Related - -- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - repeatable results and artifact metadata -- [Release profile](/quest/m1/release-profile.md) - also changes `[profile.profiling]`; land one, then rebase the other diff --git a/quest/m1/qos/lag-splice.md b/quest/m1/qos/lag-splice.md deleted file mode 100644 index f7c4f583a2c..00000000000 --- a/quest/m1/qos/lag-splice.md +++ /dev/null @@ -1,48 +0,0 @@ -# [S] Lag across a splice - -## Goal - -A spliced subscription's `lag` histogram stays exact across a route switch: -every byte the viewer could read is weighed once, and nothing a retired -segment produces afterwards is weighed at all, however early in its life the -segment was replaced. - -## Plan - -Decided in the 2026-10-05 audit: this quest, planned in draft -[#4381](https://github.com/moq-dev/moq/pull/4381) against the QoS line branch, -lands as a quest on `main` now that questlines are flat, and the QoS line -([#4133](https://github.com/moq-dev/moq/pull/4133)) is held until it is -fixed. The sampler exists only on the line branch, so the fix PR targets -`quest/m1/qos/README` (or lands with #4133). - -[#4298](https://github.com/moq-dev/moq/pull/4298) added the per-broadcast -viewer lag sampler (`FrontierInner::sample` in `rs/moq-net/src/stats.rs`) and -had a spliced subscription watch each segment's track -(`rs/moq-net/src/model/resume.rs`). Two Codex findings on its last round -merged unanswered, and the maintainer ruled in the 09-28 merged-PR audit that -both block the line: - -- **Pending weight is lost when the replacement has no frame yet** - ([r4113824520](https://github.com/moq-dev/moq/pull/4298#discussion_r4113824520)). - `sample` takes `state.unsampled` before it knows a source supplies `newest` - and `first`. When a capped segment folded bytes into `unsampled` and the - replacement has not produced, the `?` returns and those bytes are gone. - Keep the weight until a sample can record it, or keep the retired source's - edge alongside its weight. Still present on the line branch on 2026-10-05. -- **A segment replaced before its first frame is never unwatched** - ([r4113824522](https://github.com/moq-dev/moq/pull/4298#discussion_r4113824522)). - `unwatch` runs only when an existing segment's `end` changes. A segment - the producer replaces outright is marked `pruned` and dropped through - `retired()` without it, so if its route keeps publishing, those - unreachable bytes keep weighing this viewer's lag. Unwatch on every path - that retires or replaces a segment, not just on a cap. - -Extend the existing splice lag test (`lag_weighs_every_segment`) or add -siblings so each case fails without its fix. Rejected: two quests, since -both sit in the same splice accounting path and would conflict. - -Final lag sample (#4451) changed the same sampler; keep any weight this -quest defers in its drop-time sample. - -Public API: none. Wire: none, only the histogram's values change. diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 324ee903c5b..804fcf49782 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -72,8 +72,8 @@ The BBR app-limited fixes land in `moq-quic` without waiting for the switch. - [Scope track priority](/quest/m1/track-priority-scope.md) - the per-broadcast fairness policy on cluster sessions - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic -- [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement -- [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate +- [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement +- [Careful resume on reconnect](/quest/m3/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer - [GCC egress experiment](/quest/m3/quic-gcc.md) - a receive-timestamps measurement spike, the first step toward WebRTC-style delay control diff --git a/quest/m1/subscribe-live-time.md b/quest/m1/subscribe-live-time.md deleted file mode 100644 index 6ab4b4c854f..00000000000 --- a/quest/m1/subscribe-live-time.md +++ /dev/null @@ -1,60 +0,0 @@ -# [L] SUBSCRIBE_OK carries the live media time - -## Goal - -When a route answers a lite-07 subscription, the subscriber learns the -publisher's current media time, extrapolated to now rather than the newest -frame's timestamp, so every reader's budget judges a cache against the real -live edge, even across a gap. - -Since [#4741](https://github.com/moq-dev/moq/pull/4741) the track model -already reads lite-07 SUBSCRIBE_OK's largest position: `set_live` -(`rs/moq-net/src/model/track.rs`, called from `lite/subscriber.rs`) marks a -copy's cache current up to it, and when the feed went on past a gap after -everything cached, readers skip the unjudgeable cache. That covers the -idle-cache case that motivated this quest. - -Decided in the 2026-10-05 audit: re-scope against `set_live` before -starting. What `set_live` does not give is a media time: a budget still judges -a group by where its successor starts, so on a live track past a gap an old -group's reach stays open until the next group arrives. Name the reader that -needs the extrapolated live media time beyond that; if none remains, delete -this quest instead. - -## Plan - -Decided in planning (2026-10-03): - -- **Estimator: least-delayed reference.** Each track keeps - `offset = min(wall โˆ’ pts)` over a recent sliding window of the frames written - to it (the least-delayed frame sets the reference, the window follows clock - drift), and reports `now โˆ’ offset` in the track's timescale. Reason: the - newest frame's timestamp is stale on a sparse track and carries that frame's - delivery jitter. -- **Lives in moq-net track state**, fed by every frame a `track::Producer` - writes, so origin publishers and relays share one implementation and any - SUBSCRIBE_OK reads it. js/net gets the same in its track state. -- **Each hop estimates on its own.** A relay reports its own estimate from the - `(pts, arrival)` pairs it received, never the upstream's value, so the delay - every hop adds shows up honestly. -- **Optional on the wire.** An untimed track (see - [Untimed lite-07](/quest/m1/lite-untimed.md)) has no media time, so the field - is absent, as its frame timestamps are. An untimed track never reports one, - 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::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 - intended, and only the publisher's estimate uses the least-delayed reference. -- No new docs page: the lite draft and the max delay paragraph in - `doc/concept/moq-lite.md` are updated inline. - -## Related - -- [Shared clock](/quest/m1/shared-clock.md) - the hang catalog's `{wall, timescale}` anchor sits a layer up; this stays media-agnostic diff --git a/quest/m1/ts-passthrough.md b/quest/m1/ts-passthrough.md index e5954f087af..a31f521b4ea 100644 --- a/quest/m1/ts-passthrough.md +++ b/quest/m1/ts-passthrough.md @@ -129,4 +129,4 @@ hang catalog gains an `m2ts` root section; additive. ## Related - [TS hitless](/quest/m2/ts-hitless.md) - the demultiplexed lane's 2022-7 legs and the `--sync` anchor -- [MSFTS convergence](/quest/m2/msfts-convergence.md) - the ES-level side of the same mapping +- [MSFTS convergence](/quest/m3/msfts-convergence.md) - the ES-level side of the same mapping diff --git a/quest/m1/watch-audio-time-stretch.md b/quest/m1/watch-audio-time-stretch.md index a27b24b5588..1a930e5f702 100644 --- a/quest/m1/watch-audio-time-stretch.md +++ b/quest/m1/watch-audio-time-stretch.md @@ -10,7 +10,7 @@ burst sizes. Boundaries: no packet loss concealment; an underrun still renders a ramped gap. The target estimator and the ring's slack and re-stall are the -[audio jitter target](/quest/m0/audio-jitter-target/README.md) line (#3517 +[audio jitter target](/quest/m1/audio-jitter-target/README.md) line (#3517 was closed in favor of it); the clock the stretch converges toward is [A/V clock](/quest/m1/av-clock.md). @@ -29,5 +29,5 @@ was closed in favor of it); the clock the stretch converges toward is ## Required -- [Watch](/quest/m0/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward +- [Watch](/quest/m1/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward - [A/V clock](/quest/m1/av-clock.md) - the clock the stretch converges toward diff --git a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md index d479c5efcac..baaac5cc5ad 100644 --- a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md +++ b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md @@ -40,4 +40,4 @@ Refs #2481, #1837. ## Related -- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate memory blocks from a camera, the capture offer rather than this import +- [Capture multi-plane PipeWire cameras](/quest/m3/pipewire-camera-planes.md) - separate memory blocks from a camera, the capture offer rather than this import diff --git a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md b/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md similarity index 100% rename from quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md rename to quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md diff --git a/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md b/quest/m2/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md similarity index 100% rename from quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md rename to quest/m2/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 4219fd054d7..78324dc88c9 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -10,8 +10,8 @@ Nothing here blocks a release. Promote a quest into [m1](/quest/m1/README.md) when it joins the next wave, including planning work whose decisions are worth settling now; deferral does not abandon a feature. A study may end with a measured no-go. Work gated on hardware, a -partner, a consumer, or a provider, or with no named consumer yet, waits in [m3](/quest/m3/README.md); work -waiting on an upstream release waits in [m4](/quest/m4/README.md). +partner, a consumer, a provider, or an upstream release, or with no named +consumer yet, waits in [m3](/quest/m3/README.md). ## Required @@ -24,7 +24,6 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [One port on the io_uring workers](/quest/m2/uring-demux.md) - `moq-uring`'s workers host the UDP demux, so a ring relay keeps STUN, WebRTC, and SRT on its QUIC port - [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio -- [Stream sessions](/quest/m2/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most - [Hitless TS legs](/quest/m2/ts-hitless.md) - two `--sync` export legs emit packet-identical TS for ST 2022-7 - [DVB E-AC-3](/quest/m2/ts-eac3.md) - E-AC-3 private data is split per sync frame and buffer-modelled in TS export - [T-STD controls](/quest/m2/tstd-controls.md) - the harness gains an MB-overflow control and an AAC broadcast reference @@ -34,14 +33,14 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback - [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback - [Windows GPU input](/quest/m2/obs-windows.md) - import or blit OBS D3D11 textures with explicit synchronization -- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the session shape it translates +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the moq-transport session is driven by bytes and tick(now), so it can translate - [IETF parameters](/quest/m2/rs2ts-ietf-params.md) - the IETF codec drops its `Param` trait on primitives, so it translates like lite - [Generated IETF](/quest/m2/rs2ts-ietf.md) - @moq/net's moq-transport session is generated too - [Per-stream deadlines](/quest/m2/quic-deadline.md) - hopeless retransmits become resets, and a tail loss probe fires early while there is still time - [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - qmux is a first-class crate in the fork over the shared stream state machine -- [Align BBR loss handling with draft-06](/quest/m2/quic-bbr-loss-parity.md) - losses use their own sample and undo re-enters ProbeUp through Refill +- [Align BBR loss handling with draft-06](/quest/m2/quic-bbr-loss-parity.md) - losses use their own sample and the draft-05 links go, keeping the spurious-loss undo that already re-enters ProbeUp through Refill - [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - a written verdict on marking versus dropping, and whether Linode and OVH keep marks - [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - `moq-quic` reports @@ -52,71 +51,65 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the acknowledged frontier moves at every frame boundary through `poll_acked`, with a delivery-delay histogram for jitter +- [#3199](/quest/m2/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup, if a profile shows the win - [#3200](/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT -- [#3202](/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: use fixed-file slots for worker UDP sockets -- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation -- [#3129](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring: write the WebTransport stream header at open time, so finish() never owes one -- [Cache shard](/quest/m2/cache-shard.md) - stop hammering one process-global cache line from every worker - [Send depth](/quest/m2/send-depth.md) - moq-net futures prove Send at the default recursion limit, so downstream crates see no nightly lint - [Refusal reasons](/quest/m2/refusal-reasons.md) - refused-session metrics tell an expired token from an invalid one, and count gateway admissions -- [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then moq-mux containers, the hang catalog, and moq-auth -- [Signed priority](/quest/m2/signed-priority.md) - every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it +- [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then moq-mux containers - [mTLS on tls://](/quest/m2/tls-listener-mtls.md) - a `tls://` listener can identify a cluster peer by its client certificate +- [Link quality](/quest/m2/link-quality.md) - a radio link's cost follows its measured quality without flapping routes, once a consumer names a radio mesh - [One transport adapter](/quest/m2/transport-adapter-dedup.md) - the poll transport adapter exists once, and the 64 KiB cap in moq-net's default `poll_read_buf` (not in the adapter) has a test - [Catalog track identity](/quest/m2/catalog-tracks.md) - a changed track configuration becomes a new track name or epoch, never a mutated definition -- [Catalog colour model](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties once a renderer consumes them - [Archive S3 wire proof](/quest/m2/archive-s3.md) - the archive proof also runs through the S3 client against an in-process S3-compatible server - [Archive recovery listing](/quest/m2/archive-recovery-listing.md) - a resumed DVR lists what changed since its checkpoint, not every stored group - [DASH rendition URLs](/quest/m2/dash-rendition-uri.md) - DASH init and segment URLs percent-encode the rendition name, so a name with a slash resolves to its own rendition +- [IETF on the ring](/quest/m2/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol +- [Dropped uring session closes](/quest/m2/uring-drop-close.md) - a moq-uring session dropped without close() closes its connection - [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - Linux relay packages ship io_uring once the ring is on par with tokio - [iOS capture](/quest/m2/mobile-capture-ios.md) - Rust captures the camera and screen on iOS - [Android capture](/quest/m2/mobile-capture-android.md) - Rust captures through NDK/JNI on Android, reusing the existing codecs - [Mobile completion](/quest/m2/mobile-completion.md) - verify the selected native/mobile path before closing #700 - [Opus implementation](/quest/m2/audio-opus-backend.md) - compare Opus codec quality, CPU, build cost, and the loss recovery each backend offers -- [Latency ledger](/quest/m2/latency-ledger.md) - a session reports where its end-to-end audio delay went, stage by stage +- [Latency ledger](/quest/m2/latency-ledger.md) - a viewer reports its share of playback delay stage by stage: jitter buffer, decode, render, and device - [JS LOC duration marker](/quest/m2/js-loc-duration-marker.md) - `@moq/loc`'s producer ends each video group with the empty duration frame, as moq-mux does - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer - [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers - [MediaCodec encode](/quest/m2/audio-encode-mediacodec.md) - Android encodes AAC-LC -- [Video codec coverage](/quest/m2/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps -- [#2147](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - moq-video: 10-bit HEVC in the NVIDIA codec path; AV1 is m3 +- [#2848](/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [NVENC buffer pool](/quest/m2/nvenc-pool.md) - NVENC reuses input and output buffers instead of allocating per frame, if a benchmark shows it wins - [Direct3D11 render import](/quest/m2/render-d3d11.md) - Windows presents without downloading every frame to system memory - [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - video with periodic intra refresh publishes, imports, and tunes in cleanly with one group per sweep and a catalog `warmup` -- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane - [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - moq-video: validate PipeWire DMA-BUFs into the Vulkan renderer on hardware -- [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests -- [Binary delta stats](/quest/m2/stats-delta.md) - an on-demand varint delta flavor of every stats track, if relay encode CPU still matters after the JSON fixes - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation - [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into registered buffers with no copy, once a profile says where - [BBR media study](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference, and where our BBR differs from Google's - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [Viewer up-switch](/quest/m2/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up -- [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement -- [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer -- [Socket close](/quest/m2/noq-socket-close.md) - `moq-quic` releases an endpoint's socket on close, so moq-tokio drops its wrapper +- [Socket close](/quest/m2/noq-socket-close.md) - moq-tokio's QUIC endpoint releases its socket on close, so it drops its wrapper - [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the media harness measures a Firefox or WebKit player over the fallback and names what each engine lacks - [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - the WGC display and window backend verified on real Windows hardware - [Windows capture parity](/quest/m2/capture-windows.md) - system audio and a settled app-capture policy - [Linux capture parity](/quest/m2/capture-linux.md) - Wayland window/system-audio capture with explicit display-selection and app-capture limits +- [cpal loads libasound at runtime](/quest/m2/cpal-alsa-runtime.md) - condition: a cpal release whose Linux build carries no load-time libasound requirement +- [Audio capture without ALSA link](/quest/m2/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound, and capture becomes a default feature +- [Ship capture and playback](/quest/m2/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [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` -- [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 - [One external GPU image for every encoder](/quest/m2/gpu-surface.md) - a vendor-neutral `Surface::Vulkan` that `Kind::Auto` routes to whichever backend imports it on its device; NVENC imports internally - [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - H.264 and H.265 from an external Vulkan image on RADV, hand-rolled on ash, proven on an RX 9070 - [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - an explicit-sync DMA-BUF reaches Intel's encoder, proven on Arrow Lake -- [A release carries multi-vendor GPU input](/quest/m2/gpu-release.md) - `release` ships all three so a pinned consumer drops its vendor code - [GPU capacity and health](/quest/m2/gpu-health.md) - moq-video reports each device's sessions, memory, utilization, and health on NVIDIA, AMD, and Intel alike +- [A release carries multi-vendor GPU input](/quest/m2/gpu-release.md) - `release` ships all three so a pinned consumer drops its vendor code +- [Pipelined first FETCH](/quest/m2/pipeline-fetch-info.md) - a fetch-only reader's first FETCH goes out with the track-info request, on lite and moq-transport, if the first-fetch latency is measured to matter - [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) - malformed draft-18 and draft-21 control input closes the session with the draft's code, or PROTOCOL_VIOLATION where a code is a real burden and the fallback is recorded in `doc/concept/standard.md`, in moq-net and js/net - [moq-transport request codes](/quest/m2/ietf-request-codes.md) - Range Filters (INVALID_FILTER), reserved namespaces, and RENDEZVOUS_TIMEOUT get the draft's answer, or a recorded fallback code, and the deliberate deviations are documented - [Native enabled](/quest/m2/native-enabled.md) - native players and the ffi/C paths never select a disabled rendition +- [Kotlin JVM exit](/quest/m2/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 - [JS audio ranking](/quest/m2/js-audio-ranked.md) - @moq/hang and HLS rank audio renditions like Rust - [ts::Export catalog stream](/quest/m2/ts-export-catalog.md) - TS export takes (source, catalog) like the other exporters -- [C backend copy](/quest/m2/c-backend-copy.md) - one payload copy out of the C backend, benchmarked - [Load-balancer refusals](/quest/m2/listener-lb-refusals.md) - refuse ignored or conflicting QUIC load-balancer settings diff --git a/quest/m2/c-backend-copy.md b/quest/m2/c-backend-copy.md deleted file mode 100644 index 3eafc0324f6..00000000000 --- a/quest/m2/c-backend-copy.md +++ /dev/null @@ -1,14 +0,0 @@ -# [S] One payload copy out of the C backend - -## Goal - -A frame payload crossing moq-ffi's C backend (uniffi-bindgen-cpp fork, -#5007) is copied once, not twice, measured by a benchmark that lands with -the change. - -## Plan - -Find both copies (FFI buffer conversion and the C struct fill), remove one, -and add a benchmark over payload sizes so a regression shows up. Whether to -offer the C backend upstream (LiveKit, NordSecurity) is the maintainer's call -and out of scope. diff --git a/quest/m2/cache-shard.md b/quest/m2/cache-shard.md deleted file mode 100644 index 7de26319e62..00000000000 --- a/quest/m2/cache-shard.md +++ /dev/null @@ -1,69 +0,0 @@ -# [M] Batch the cache pool counters - -## Goal - -The relay creates one `cache::Pool` (rs/moq-net/src/model/cache.rs) for the -whole process, and every frame written or read on every worker does relaxed -`fetch_add`s on the same cache line (`Inner::used`, cache.rs:146, and -`Inner::access_sum`/`access_count`, :156-157, for the evictable population). -At fanout this is the top cross-core contention point in the model layer. -Make per-frame accounting land on per-owner state and hit the shared line -only at a coarse cadence. - -## Plan - -Two pieces of the original survey are settled; one is not. - -Settled, and not to be retried as specified: **sharding the counters**. -16-way sharding of the process-wide counters was implemented and measured, -then abandoned. Repeated runs were mixed, and one regressed the fanout -benchmark by 15.6% at 64 readers and 10.5% at 512. It also wanted delayed -accounting, explicit overshoot bounds, and more reconciliation for no -consistent win. Sharding a counter that is already only relaxed -`fetch_add`s trades one cheap contended line for several lines plus a -read-side fold, and the fold is what showed up. - -Settled: **one clock read per frame write**. The write path samples -`model::clock::now()` once, in `Charge::touch` -> `Pool::stamp` -(cache.rs:736, :326), and threads that tick into `Track::settle` -> -`expiry_due` (:510, :565). Keep it that way: the clock is no coarser, nothing -is delayed, and eviction and staleness bounds are untouched. - -Open, and the real content of this quest: **batching the counters -themselves**. The precedent is in the same file, where `cache::Track` -accumulates `written` per track and drains into eviction debt only at a -256 KiB threshold or the expiry-scan tick, and the pool's module docs argue -for lock-free distributed reclamation with convergence rather than -exactness. - -- Extend that accumulator so `used` moves in batched deltas: per-owner - counters that flush to the global on a byte threshold, keeping the global - a converging approximation the governor already tolerates. -- Same for `access_sum`/`access_count`. The access average only steers - eviction, so per-owner accumulation with periodic reconciliation is - enough. -- Eviction correctness bounds the design: staleness must never let the pool - exceed its ceiling by more than the sum of unflushed deltas, and that - bound must be stated and tested. - -This is the half sharding was standing in front of, and it is not the same -idea: batching reduces how *often* the shared line is touched, where -sharding kept the frequency and spread the address. Measure it on its own -before concluding anything from the sharding result. - -Acceptance: cross-core traffic on the pool line (perf stat cycles or c2c -where available), relay CPU and RSS at the fanout shape via -`just bench BASE` on Linux, plus `track_parallel_write` in -`rs/moq-net/benches/track.rs` (:186) for the writer-side shape. Eviction -behavior covered by the existing cache tests plus new ones for the staleness -bound. - -Decided in the 2026-09-30 audit: moved to m2 because the contention is -unmeasured on noq. Measured since (#5031, 2026-10-07): the lock wait sits on -kio channel mutexes, not the pool line, so this stays parked until a profile -shows the pool line hot. - -## Related - -- [kio channel contention](/quest/m1/perf/kio-channel-contention.md) - where the measured cross-worker wait actually is -- [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - the remaining clock reads one layer down; a pool epoch driven by its per-turn timestamp is the way to drop the last per-frame read, and the model should drink from that cup rather than grow a second clock diff --git a/quest/m1/capture-alsa-link.md b/quest/m2/capture-alsa-link.md similarity index 92% rename from quest/m1/capture-alsa-link.md rename to quest/m2/capture-alsa-link.md index df6fed45ccd..bf40a90c4d1 100644 --- a/quest/m1/capture-alsa-link.md +++ b/quest/m2/capture-alsa-link.md @@ -20,7 +20,7 @@ still links and starts driverless. `capture` and `playback` pull cpal with ALSA always linked; the host flags alone no longer activate it. cpal cannot load ALSA at runtime in-tree (no release offers it, and the in-tree routes are hacks), so this waits on -[the cpal release](/quest/m1/cpal-alsa-runtime.md). Once it ships, bump cpal, +[the cpal release](/quest/m2/cpal-alsa-runtime.md). Once it ships, bump cpal, enable whatever it needs, and update the moq-audio and moq-cli feature comments that call libasound a build-time link. @@ -41,8 +41,8 @@ covers it. Keep the platform jobs. Update the Cargo feature comments and ## Required -- [cpal loads libasound at runtime](/quest/m1/cpal-alsa-runtime.md) - condition: a cpal release whose Linux build carries no load-time libasound requirement +- [cpal loads libasound at runtime](/quest/m2/cpal-alsa-runtime.md) - condition: a cpal release whose Linux build carries no load-time libasound requirement ## Related -- [Ship capture and playback](/quest/m1/cli-packaging.md) - the shippable capture milestone this work supports +- [Ship capture and playback](/quest/m2/cli-packaging.md) - the shippable capture milestone this work supports diff --git a/quest/m1/cli-packaging.md b/quest/m2/cli-packaging.md similarity index 96% rename from quest/m1/cli-packaging.md rename to quest/m2/cli-packaging.md index b2eb2253b01..9037ab4a5a4 100644 --- a/quest/m1/cli-packaging.md +++ b/quest/m2/cli-packaging.md @@ -46,7 +46,7 @@ encodes through rkmpp in a vendor kernel, not V4L2, so it stays on the `pipewire` stays off in shipped builds (decided 2026-10-06): it needs libpipewire-0.3 to load, the same load-time requirement -[ALSA](/quest/m1/capture-alsa-link.md) removes. +[ALSA](/quest/m2/capture-alsa-link.md) removes. Decided in the 2026-09-30 audit: the v4l2 encode quest folded in here, since its remaining work was one release feature flag and a doc note. @@ -57,4 +57,4 @@ making it default-on does not depend on the library defaults. ## Required -- [Audio capture without runtime system libraries](/quest/m1/capture-alsa-link.md) - the microphone path must start without system audio libraries before every distribution can ship it +- [Audio capture without runtime system libraries](/quest/m2/capture-alsa-link.md) - the microphone path must start without system audio libraries before every distribution can ship it diff --git a/quest/m1/cpal-alsa-runtime.md b/quest/m2/cpal-alsa-runtime.md similarity index 90% rename from quest/m1/cpal-alsa-runtime.md rename to quest/m2/cpal-alsa-runtime.md index e10a4f40525..256db13f380 100644 --- a/quest/m1/cpal-alsa-runtime.md +++ b/quest/m2/cpal-alsa-runtime.md @@ -12,7 +12,7 @@ runtime loading, `--features capture`; with an optional host, cpal's ALSA host off and `pulseaudio` on) and confirm `readelf -d` lists no `libasound.so.2` under `NEEDED`. A clean `readelf` is not enough on its own: the binary must also start, list devices, and play on a host without -libasound, as [capture-alsa-link](/quest/m1/capture-alsa-link.md) verifies. +libasound, as [capture-alsa-link](/quest/m2/capture-alsa-link.md) verifies. Advance it by proposing the change upstream (RustAudio/cpal, and diwic/alsa-sys if the loading lives there). Posting there needs maintainer @@ -20,8 +20,8 @@ approval, which is pending: on 2026-10-06 the maintainer chose not to post yet. Once the release is out, delete this quest. Decided 2026-10-08: the capture chain (this quest, -[capture-alsa-link](/quest/m1/capture-alsa-link.md), and -[Ship capture and playback](/quest/m1/cli-packaging.md)) moves to m2 and parks +[capture-alsa-link](/quest/m2/capture-alsa-link.md), and +[Ship capture and playback](/quest/m2/cli-packaging.md)) moves to m2 and parks until cpal ships runtime ALSA loading. Nothing is posted upstream and no fork is taken meanwhile. @@ -34,7 +34,7 @@ pkg-config and offers no runtime-loading mode. No upstream issue or PR asks for either. Two upstream shapes, either of which unblocks -[Audio capture without runtime system libraries](/quest/m1/capture-alsa-link.md): +[Audio capture without runtime system libraries](/quest/m2/capture-alsa-link.md): - **Runtime loading.** An `alsa-sys` feature that resolves the `snd_*` symbols through dlopen (bindgen can emit such a wrapper), forwarded by @@ -62,4 +62,4 @@ calls a symbol the shim misses. ## Related -- [Ship capture and playback](/quest/m1/cli-packaging.md) - needs the microphone path to start without libasound +- [Ship capture and playback](/quest/m2/cli-packaging.md) - needs the microphone path to start without libasound diff --git a/quest/m1/kt-jvm-exit.md b/quest/m2/kt-jvm-exit.md similarity index 100% rename from quest/m1/kt-jvm-exit.md rename to quest/m2/kt-jvm-exit.md diff --git a/quest/m1/cluster-routing/link-quality.md b/quest/m2/link-quality.md similarity index 100% rename from quest/m1/cluster-routing/link-quality.md rename to quest/m2/link-quality.md diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index b1b652bd93f..e6f50cd19e7 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -98,4 +98,4 @@ pre-accepted streams can stand behind. - [P2P](/quest/m3/p2p/README.md) - the only consumer of a public STUN responder, which it plans when it needs one - [One port on the io_uring workers](/quest/m2/uring-demux.md) - the io_uring workers host the UDP demux -- [Stream sessions](/quest/m2/uring-tcp/README.md) - the io_uring workers that would host the TCP acceptor later +- [Stream sessions](/quest/m3/uring-tcp/README.md) - the io_uring workers that would host the TCP acceptor later diff --git a/quest/m1/pipeline-fetch-info.md b/quest/m2/pipeline-fetch-info.md similarity index 100% rename from quest/m1/pipeline-fetch-info.md rename to quest/m2/pipeline-fetch-info.md diff --git a/quest/m2/quic-bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md index dd821b65f1e..667888395a9 100644 --- a/quest/m2/quic-bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -39,4 +39,7 @@ traffic yet. ## Required - [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 -- [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 + +- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`; not a blocker, since this is a local `rs/moq-quic` fix (decided for the m1 BBR quests in fork/input-validation) diff --git a/quest/m2/quic-ecn-measure.md b/quest/m2/quic-ecn-measure.md index 335a9e68723..cb789685baf 100644 --- a/quest/m2/quic-ecn-measure.md +++ b/quest/m2/quic-ecn-measure.md @@ -6,7 +6,7 @@ A written verdict on classic ECN between relays: whether a marking bottleneck reduces the rate before its queue overflows instead of after, with the numbers, and whether Linode's and OVH's networks preserve ECT(0) and CE between relays. No code lands; the verdict is recorded in -[L4S on the backbone](/quest/m2/quic-ecn.md), which acts on it. +[L4S on the backbone](/quest/m3/quic-ecn.md), which acts on it. ## Plan @@ -38,7 +38,7 @@ from 1.3.1 is a defective baseline, not evidence that classic ECN cannot help. the marking response is only a lab result. Decided in the 2026-09-30 audit: moved to m2 with its only consumer, -[L4S on the backbone](/quest/m2/quic-ecn.md). +[L4S on the backbone](/quest/m3/quic-ecn.md). Decided in the 2026-10-06 audit: no longer waits on the hard fork. No code lands here, and the pinned moq-noq-proto 2.0.1 already carries the classic diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index e417872fe42..5aa7c4db25b 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -23,7 +23,7 @@ and its probe land before the peer's timer. Pick how the config expresses "derived" (an `Option`, or a sentinel) by what reads clearest in the `[quic]` section and CLI; document it in `doc/bin/relay/config.md`. -iroh stays on upstream noq. [Listener deadlines](/quest/m1/listener-deadlines.md) +iroh stays on upstream noq. [iroh keep-alive](/quest/m1/iroh-keep-alive.md) wires `quic.keep_alive` into iroh's `keep_alive_interval`; with no explicit value, iroh gets the same derivation from its idle timeout. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, a fixed 5 s ping and 30 s @@ -39,5 +39,5 @@ default; an explicit value wins; `0s` disables. ## Related -- [Listener deadlines](/quest/m1/listener-deadlines.md) - wires the same setting into iroh's fixed interval +- [iroh keep-alive](/quest/m1/iroh-keep-alive.md) - wires the same setting into iroh's fixed interval - [noq#810](https://github.com/n0-computer/noq/issues/810) - the deadline-driven proposal to n0; flub and matheus23 asked to keep a cap for NAT bindings, which the override covers diff --git a/quest/m2/relay-io-uring-package.md b/quest/m2/relay-io-uring-package.md index 008aeea6fce..ae5b666f90a 100644 --- a/quest/m2/relay-io-uring-package.md +++ b/quest/m2/relay-io-uring-package.md @@ -34,8 +34,8 @@ Public API: none. Wire: none. ## Required -- [moq-transport on io_uring](/quest/m1/uring-ietf.md) - a packaged relay +- [moq-transport on io_uring](/quest/m2/uring-ietf.md) - a packaged relay must not drop protocols when the ring is on -- [Dropped session close](/quest/m1/uring-drop-close.md) - closes are delivered when a session is dropped on the ring +- [Dropped session close](/quest/m2/uring-drop-close.md) - closes are delivered when a session is dropped on the ring - [Listener deadlines](/quest/m1/listener-deadlines.md) - the io_uring workers apply `listen.timeout` like the default runtime - [One port on the io_uring workers](/quest/m2/uring-demux.md) - a one-port config is served on the ring too diff --git a/quest/m2/signed-priority.md b/quest/m2/signed-priority.md deleted file mode 100644 index 37f3b539ac9..00000000000 --- a/quest/m2/signed-priority.md +++ /dev/null @@ -1,58 +0,0 @@ -# [L] Signed priority - -## Goal - -Every priority in the API is an `i8`, higher first, with 0 as the unset -midpoint: `track::Info`, `Subscription`, and `group::Fetch` in Rust, their -JS counterparts, moq-ffi, moq-c, and every wrapper. Nobody has to know that -127 is the middle of a `u8`, the default the moxygen line ships. The wire -stays a byte. - -## Plan - -Decided with the maintainer: - -- moq-lite carries `p + 128` (flip the top bit). The mapping is one-to-one - and keeps order, so a given byte means what it means today; only the API - number changes. The default becomes byte 128. -- IETF carries `127 - p`. Both mappings are one-to-one over the whole `i8` - range, with no saturation. An unset priority goes out as IETF 127, not the - draft's usual 128, and an absent IETF priority decodes to 0, the unset - default. Pin both ends in tests. -- Invariant, kept from the default-priority change (#4273): one urgency on - both wires, so the IETF byte is always `255 -` the lite byte. Mapping IETF - as `128 - p` to hit the draft's 128 would break it, which is why the - default is one step off the draft there. -- hang's built-in priorities move above 0, so hang media outranks a track that - never set one. Something like catalog 40, text 30, audio 20, video 10; the - spacing is the implementer's call. Rust and JS keep matching values. -- A zeroed moq-c `moq_track_info` then means the default, which retires the - need for a `priority_present` flag. - -Changing published `u8` fields to `i8` is an API break in every language. Look for anything that does arithmetic on priority -(the lite send queue, JS send-order packing, the bandwidth allocator, the -relay's max-of-subscribers) and keep its ordering, not just its type. - -moq-archive's `Info::priority` follows. Its version-1 `.info` stores the -`u8`, so existing recordings must keep their meaning: store the moq-lite byte -(`p + 128`) or bump the format version, never reinterpret silently. -`doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md` -(IETF 128 maps to 127) move to the new range and mapping. - -Report the wire impact in the PR: none in format, but the default byte moves -again, from 127 to 128 on moq-lite and from 128 to 127 on IETF. - -Decided in the 2026-09-30 audit: moved to m2. - -Decided in the 2026-10-05 audit: the moxygen default change -(`DEFAULT_PRIORITY = 127`, #4273) already shipped in moq-net v0.3.9 on -2026-10-03, so the old gate (ship in the same release so the default byte -moves once) can no longer be met and is dropped. Accept the second default -move, and add an upgrade note to the release's upgrade page saying the -default byte moves again and why. Rejected: a mapping that keeps today's -bytes (lite byte = p + 127), and deleting the quest. - -## Related - -- [Scope track priority](/quest/m1/track-priority-scope.md) - which streams a priority competes with, not its type -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - reworks the same priority arithmetic in the transport diff --git a/quest/m2/stats-delta.md b/quest/m2/stats-delta.md deleted file mode 100644 index 26f279bb98c..00000000000 --- a/quest/m2/stats-delta.md +++ /dev/null @@ -1,113 +0,0 @@ -# [M] Binary delta stats flavor - -## Goal - -A consumer can request a binary delta flavor of every stats track (name TBD, -for example `publisher.bin.z`, `subscriber.bin.z`, `sessions.bin.z`, per -tier) that a relay encodes and a reader decodes several times cheaper than -`.json.z`, in fewer bytes. The relay serves it only on request, so an -unrequested flavor costs nothing, and `moq_stats::Consumer`, the aggregate, -and a dependency-free JS decoder read it into the same frame types as JSON. -The JSON tracks stay unchanged on the wire. - -Not here: replacing or deprecating `.json` / `.json.z`, a relay config switch, -or moving the demo dashboard off JSON. - -## Plan - -**Gate first.** Bandwidth is small in absolute terms (about 0.8 Mbps per -stats subscriber in the worst scenario below), so bytes alone do not justify -a new format. The motivation is relay encode CPU at 10k+ broadcasts and -aggregator fan-in. #4019 already cut `.json.z` decode allocations about 42x -(time 2.5-4x) by dropping per-key path tracking; `rs/moq-stats/benches/decode.rs` -measures it. `rs/moq-stats/benches/producer_tick.rs` profiles the encode side: -a full rewrite at 10k held paths is about 22 ms per tick for one tier and -91 ms for four. Proceed only if CPU still matters after that profile has fixed -or ruled out the moq-json snapshot encoder's cost. Re-run the benchmark against that baseline; if JSON is -close enough, abandon this quest with the numbers. - -**Evidence.** A prototype benchmark on top of #3955's commit `d86496be2` -simulated relay traffic from how `moq_net::stats` counts and how -`moq_stats::produce` emits (live-or-changed rows, pruned a drain after they -close), through the same group policy for every format and checked against -ground truth every tick. Only the traffic tracks were modelled, not -`sessions`. Bytes per tick, mean over 600 ticks: - -| format | steady 1k | churn (conference) | large 10k x3 tiers | idle cams 2k | -|---|---:|---:|---:|---:| -| `.json.z` today | 14735 | 55211 | 101472 | 888 | -| `.fb.z` full snapshot (#3955) | 73653 | 87048 | 616416 | 20906 | -| stable-slot FlatBuffers XOR | 8105 | 18798 | 57464 | 1040 | -| protobuf merge patch, absolute values | 10670 | 53294 | 97011 | 834 | -| custom varint delta | 3754 | 9494 | 25616 | 364 | - -At 10k broadcasts x 3 tiers, per tick: `.json.z` encodes in 98 ms and -decodes in 76 ms with 1M decode allocations (before #4019); a typed -`.json.z` merge patch (same wire, not landed) cut decode to 5.7 ms and 445 -allocations; the varint delta encodes in 10 ms and decodes in 0.8 ms with 12 -and 167 allocations. Against the best JSON decode, the remaining wins are -encode CPU (7-13x), bytes (2.4-5.8x), and a smaller decode margin (3-9x). - -What the numbers taught, so the design does not relearn it: - -- A full snapshot per frame fails once it outgrows DEFLATE's 32 KiB window; - that is what sank `.fb.z`. -- Absolute cumulative counters do not compress: each is 5-6 near-random - bytes. Varint deltas of monotonic counters are 1-3 bytes. -- Naive XOR against the previous frame keyframes on 95-99% of frames because - any row join or leave shifts the layout. - -**Format sketch** (the prototype's; adjust as the implementation learns): - -- Each group is one DEFLATE window, rolled by the same policy as - `moq_json::snapshot` (frame count, growth against the first frame, the - cache bound). The first frame of a group is a keyframe: every row's path - and absolute values. -- A delta frame carries new paths inline (ids assigned implicitly, continuing - the group's dictionary), then each changed row as `(id gap varint, - changed-field bitmask, one varint delta per set bit)`, then the removed ids - as gaps. Ids ascend within each list, so gaps are small. -- A counter that goes backwards is a remove plus a re-add under a new id, - which keeps every delta unsigned and matches the existing "a decrease starts - a fresh segment" rule. -- An unchanged tick writes no frame. - -Design points left open for the implementer: - -- Extensibility: if every field is a varint, a reader can skip mask bits it - does not know, so fields append without breaking old readers. Decide that - or refuse unknown bits loudly, and say which. -- Gauges: none today. Media stats, with their latency and bitrate gauges, - ride hang tracks rather than a moq-stats extension, so this flavor encodes - relay frames only. -- Measure `sessions` (`Presence`) too; the benchmark skipped it. -- Sweep the aggregate over node publishers x entries per node, for both - flavors; the benchmark above only varied one relay's stream, so it cannot - show the fan-in cost the gate cites. - -**Serving.** Like `.fb.z` was planned: a flavor suffix accepted by -`requested_track_shape` and the track-name helpers for every name that takes -`.json.z`, created only when requested rather than with the plain/compressed -pair. Weigh replacing `compressed: bool` in the helpers with a flavor enum, -which is a published API break. - -**Readers.** `Consumer` and the aggregate read either flavor into -`TrafficFrame` / `SessionsFrame`. The JS decoder is about 120 lines and -dependency-free apart from inflate (`@moq/flate`); read varints through -`BigInt` or split 32-bit halves, since counters exceed 2^53. It belongs with -the demo dashboard's relay-stats reader. Share fixtures between Rust and JS so the two stay wire -identical, and keep the benchmark in-tree, wired into CI at least nightly. - -**Docs and spec.** No IETF draft covers stats today. Write the format into -the stats format page ([doc/concept/stats.md](/doc/concept/stats.md)) -and the stats section of `doc/bin/relay/config.md`, plus the moq-stats crate -docs. Whether stats needs its own `draft-lcurley-moq-stats.md` is the -maintainer's call; ask before writing one. - -Public API impact: additive on moq-stats unless the helpers change. Wire -impact: new on-demand tracks; existing tracks unchanged. - -## Related - -- [Stats format page](/doc/concept/stats.md) - where the new flavor is documented -- [Compressed tracks](/quest/m2/flate.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index cd652b644a6..ae18545e744 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -11,8 +11,8 @@ protocol and flight integration, parked in m3 until a real ArduPilot user or partner shows up. Decided in the 2026-09-30 audit: the ROS 2 bridge was deleted, cross-track -correlation folded into [robot](/quest/m2/teleop/robot.md), V4L2-M2M encoding -folded into [CLI packaging](/quest/m1/cli-packaging.md), and the MAVLink +correlation folded into [robot](/quest/m3/teleop-robot.md), V4L2-M2M encoding +folded into [CLI packaging](/quest/m2/cli-packaging.md), and the MAVLink bridge and SITL proof moved to m3. Kyber is a competitor with proprietary framing, not a transport we replace. @@ -36,7 +36,7 @@ operator arbitration, and the latency instrumentation from scratch. The hang catalog is no longer a gap: it advertises data tracks in its `json` and `binary` sections beside video and audio. The other missing piece, `moq-video`'s V4L2-M2M encoder in a released `moq-cli`, is tracked by -[CLI packaging](/quest/m1/cli-packaging.md). +[CLI packaging](/quest/m2/cli-packaging.md). ### Two delivery classes, one session @@ -56,7 +56,7 @@ for QUIC reliable streams as for DDS best-effort: correct and useless. The split is a framing decision, not a subscription flag, and `moq-json` and `moq-flate` already implement both halves as their snapshot and stream modes. What that -means for the primitive is in [robot](/quest/m2/teleop/robot.md), and what it +means for the primitive is in [robot](/quest/m3/teleop-robot.md), and what it means for a protocol multiplexing many message rates onto one link is in [mavlink](/quest/m3/teleop-mavlink.md). @@ -94,10 +94,10 @@ stating plainly because it is what a builder is comparing against. ## Related -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - a `moq-robot` +- [Robot teleoperation primitive](/quest/m3/teleop-robot.md) - a `moq-robot` crate carrying the track shapes and discovery every teleoperated machine needs, parked in m3 -- [Operator arbitration](/quest/m2/teleop/arbitration.md) - exactly one +- [Operator arbitration](/quest/m3/teleop-arbitration.md) - exactly one controller commands a vehicle at a time, with explicit handoff and a stated authorization boundary, parked in m3 - [e2ee](/quest/m1/e2ee/README.md) - the answer for a protected control link @@ -106,7 +106,7 @@ stating plainly because it is what a builder is comparing against. extends those types rather than adding a second stats surface - [Video hardware validation](/quest/m3/video-hardware.md) - the VAAPI run that covers Intel ground robots and NUC companions -- [CLI packaging](/quest/m1/cli-packaging.md) - ships the V4L2-M2M encoder the +- [CLI packaging](/quest/m2/cli-packaging.md) - ships the V4L2-M2M encoder the boards that fly need - [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway, parked until a real ArduPilot user or partner diff --git a/quest/m2/uring-demux.md b/quest/m2/uring-demux.md index 541158d5e4d..2cd45103597 100644 --- a/quest/m2/uring-demux.md +++ b/quest/m2/uring-demux.md @@ -51,4 +51,4 @@ already off on the ring, from shard steering. ## Related -- [Stream sessions](/quest/m2/uring-tcp/README.md) - the TCP half of moving the relay onto the ring +- [Stream sessions](/quest/m3/uring-tcp/README.md) - the TCP half of moving the relay onto the ring diff --git a/quest/m1/uring-drop-close.md b/quest/m2/uring-drop-close.md similarity index 100% rename from quest/m1/uring-drop-close.md rename to quest/m2/uring-drop-close.md diff --git a/quest/m1/uring-ietf.md b/quest/m2/uring-ietf.md similarity index 96% rename from quest/m1/uring-ietf.md rename to quest/m2/uring-ietf.md index 474f69b0ca5..a42d8a58618 100644 --- a/quest/m1/uring-ietf.md +++ b/quest/m2/uring-ietf.md @@ -33,5 +33,5 @@ that fleet deploy, which is m2 work. ## Related -- [Stream sessions](/quest/m2/uring-tcp/README.md) - the other protocol gap +- [Stream sessions](/quest/m3/uring-tcp/README.md) - the other protocol gap on the ring, WebSocket and HTTP diff --git a/quest/m2/uring-open-contract.md b/quest/m2/uring-open-contract.md deleted file mode 100644 index 39e37fa4c5e..00000000000 --- a/quest/m2/uring-open-contract.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] Plan concurrent WebTransport stream opening - -## Goal - -Settle ownership, cancellation, and backpressure for writing a WebTransport -stream header before returning the stream, so the implementation can proceed -without inventing concurrent-open semantics. - -## Plan - -Inspect the shared Session state and the upstream poll-open trait. Determine -how independent concurrent openers retain ownership across Pending and -cancellation, and whether an open-before-read caller can deadlock when the -header needs flow-control credit. A queue alone is not a chosen contract. - -Present the viable ownership choices and a recommendation to the maintainer. -Update the implementation quest with the selected state transitions, resource -bounds, cancellation behavior, and regression cases for concurrent openers, -credit starvation, dropped futures, and finish/drop. This quest ships the plan; -it does not close #3129 or implement an unsettled public contract. - -Decided in the 2026-09-30 audit: moved to m2 with #3129, which it plans. -io_uring ships in no package, and #3129 fixes an API wart no in-tree caller -hits. - -## Related - -- [Write headers at open](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - implementation after the contract is settled diff --git a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md b/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md similarity index 96% rename from quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md rename to quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md index c7bcd3fd255..8692fb7048d 100644 --- a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md +++ b/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md @@ -39,4 +39,4 @@ codec signaling, with cross-language fixtures for any metadata change. - [GPU CI](/quest/m1/gpu-ci.md) - the RTX 3070 Ti host that verifies Main10 - [NVENC AV1](/quest/m3/nvenc-av1.md) - the AV1 half of #2147, hardware-gated -- [Codec coverage study](/quest/m2/video-codec-coverage.md) - measure optional software and other native backends separately +- [Codec coverage study](/quest/m3/video-codec-coverage.md) - measure optional software and other native backends separately diff --git a/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md b/quest/m3/3129-moq-uring-write-the-webtransport-stream-header-at-open.md similarity index 100% rename from quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md rename to quest/m3/3129-moq-uring-write-the-webtransport-stream-header-at-open.md diff --git a/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md b/quest/m3/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md similarity index 100% rename from quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md rename to quest/m3/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md diff --git a/quest/m3/README.md b/quest/m3/README.md index 84a88a312c7..a9f48084298 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -4,8 +4,8 @@ Work that waits on something besides priority: either a first step outside this repository (hardware nobody on the team has, a partner or customer who -asks for it, or a hosting provider's offer), or a speculative feature or study -with no named consumer yet. +asks for it, a hosting provider's offer, or an upstream release), or a +speculative feature or study with no named consumer yet. ## Plan @@ -14,34 +14,43 @@ root [questline](/quest/README.md) describes. A speculative feature or study with no consumer needs no condition quest: it parks here rather than in m2 until a consumer appears, and is deleted when it goes stale; git history keeps it. Decided in the 2026-10-05 audit: both kinds live here, and the m2 quests -deferred for having no named consumer moved here. +deferred for having no named consumer moved here. The 2026-10-08 audit folded +m4's upstream waits in here and moved m2 work with no consumer. ## Required -- [Video validation hardware is on hand](/quest/m3/video-hardware-access.md) - the machines the validation runs on +- [Video validation hardware is on hand](/quest/m3/video-hardware-access.md) - the machines the validation runs on, including a Raspberry Pi 4/5 for embedded presenting - [Video hardware validation](/quest/m3/video-hardware.md) - run the encode, capture, and zero-copy paths that were never run on real machines, including PipeWire on KDE, the camera portal, and a Pi - [An Ada NVIDIA GPU is available](/quest/m3/ada-gpu.md) - the hardware AV1 NVENC is verified on - [NVENC AV1](/quest/m3/nvenc-av1.md) - AV1 encode through NVENC, once an Ada-generation GPU is available -- [An embedded video device is on hand](/quest/m3/embedded-device.md) - the device EGL import is validated on -- [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi +- [Catalog colour model](/quest/m3/color-catalog.md) - the catalog describes a rendition's colour and HDR properties once a renderer consumes them +- [#2147](/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - NVIDIA Main10 encode, once a 10-bit source exists in the pipeline +- [Embedded video](/quest/m3/video-embedded.md) - verify a Pi 4/5 presents through the existing Vulkan and CPU paths, adding EGL import only if that fails +- [Multi-plane PipeWire cameras](/quest/m3/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane capture, if the hardware pass finds one +- [Video codec coverage](/quest/m3/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps once a consumer asks - [A physical-NIC peer for the zero-copy sweep](/quest/m3/zero-copy-peer.md) - the rig the zero-copy sweep runs on - [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first - [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends -- [QUIC GCC](/quest/m3/quic-gcc.md) - receive timestamps in ACKs and a measured verdict on delay-based congestion control for media egress, shipping as `RealTime` -- [Cut-through](/quest/m3/cut-through/README.md) - a relay forwards bytes behind a QUIC stream hole before the retransmission fills it, if a lossy-hop bench says it is worth it -- [AF_XDP UDP path](/quest/m3/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK +- [Stream sessions on the ring](/quest/m3/uring-tcp/README.md) - WebSocket and HTTP on the io_uring workers, gated on the ablation; no fleet asks for ring TCP yet +- [#3202](/quest/m3/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: fixed-file slots for worker UDP sockets, if the ablation measures a win +- [#3129](/quest/m3/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring writes the WebTransport stream header at open and settles the open contract, once a caller hits it +- [QUIC receive timestamps](/quest/m3/quic-gcc.md) - a spike measuring receive timestamps in ACKs on native and relay-to-relay egress; delay-based control only if it justifies one +- [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement, if the ECN measurement says marks survive +- [Careful resume on reconnect](/quest/m3/quic-careful-resume.md) - a Rust redial starts at the previous connection's rate +- [Cut-through](/quest/m3/cut-through/README.md) - a lossy-hop bench decides whether a relay should forward bytes behind a QUIC stream hole; the build is re-planned if it says go - [Unreal prototype](/quest/m3/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture +- [vcpkg registry](/quest/m3/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests, once a consumer asks - [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the same tarball to `conan install` - [Linux OBS GPU input](/quest/m3/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination - [Routing cost domains](/quest/m3/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs +- [moq-transport cluster peers](/quest/m3/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, once a moq-transport relay operator asks - [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment that makes the exemption dead code - [Drop the hidden cluster exemption](/quest/m3/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire +- [Robot teleoperation primitive](/quest/m3/teleop-robot.md) - a `moq-robot` crate for video down and control up, once a robotics consumer appears +- [Operator arbitration](/quest/m3/teleop-arbitration.md) - one operator holds control at a time - [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway replacing the VPN plus two unmanaged UDP flows, with QGroundControl and friends unchanged -- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - `@moq/robot` - mirrors the Rust crate, so browser clients consume the catalog and delivery - classes - [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot SITL and a synthetic camera flown from a browser ground station, reproducible in five minutes @@ -50,14 +59,14 @@ deferred for having no named consumer moved here. - [fMP4 emsg](/quest/m3/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - [ID3 catalog section](/quest/m3/id3.md) - timed ID3 as a first-class container-neutral catalog section - [FLV script tags](/quest/m3/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import +- [MSFTS convergence](/quest/m3/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where they differ, once an MSFTS implementer engages - [#2279](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [CEA-608/708](/quest/m3/captions-cea.md) - captions carried inside video SEI become a real text rendition at import - [Browser archive](/quest/m3/archive-browser.md) - the same contract for browser-published broadcasts - [Paced replay](/quest/m3/archive-paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it -- [`moq relay`](/quest/m3/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder reads its viewers' feedback and adapts its bitrate -- [Text availability](/quest/m3/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline - [Closure counters](/quest/m3/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw -- [The maintainer approves posting to moq-interop-runner](/quest/m3/interop-runner-approval.md) - condition: the runner change may be posted -- [Interop graceful close](/quest/m3/interop-graceful-close.md) - successful runner publications withdraw before disconnecting +- [Interop runner withdraws before disconnecting](/quest/m3/interop-runner-approval.md) - condition: the maintainer approves posting and a released moq-tokio and @moq/net carry close() withdrawals +- [Safari ships the WebKit 319818 fix](/quest/m3/webkit-319818.md) - the Safari release the gate admits +- [Safari WebTransport](/quest/m3/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed diff --git a/quest/m3/af-xdp.md b/quest/m3/af-xdp.md deleted file mode 100644 index 9ae34da3b0a..00000000000 --- a/quest/m3/af-xdp.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] AF_XDP UDP path - -## Goal - -A measured verdict on an AF_XDP socket as the io_uring worker's UDP path on -the hosts the fleet runs today. virtio-net supports AF_XDP in copy mode on any -Linode or OVH instance and zero-copy where the driver allows; if it lifts the -per-worker packet ceiling or cuts CPU per Gbps materially against the -io_uring path, full kernel bypass becomes a concrete question; if not, it is -closed until hardware changes. - -## Plan - -- A prototype `moq-uring` UDP path over an `AF_XDP` socket with a minimal - XDP program steering the relay's port to the worker's queue, UDP and IP - headers built in userspace, GSO replaced by the ring's batch. Keep it - behind a feature; nothing ships. -- Measure packets per second, CPU per Gbps, and p99 latency on one virtio - host in copy mode, on the chat and fanout shapes, against the io_uring path - with the zero-copy quests' best settings. - -Decided in the 2026-09-30 audit: moved to m3. The relay packages don't ship -io_uring yet, so a bypass that competes with it has no deployment to -improve. - -## Required - -- [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - the io_uring path this is compared against ships first diff --git a/quest/m2/color-catalog.md b/quest/m3/color-catalog.md similarity index 100% rename from quest/m2/color-catalog.md rename to quest/m3/color-catalog.md diff --git a/quest/m3/cpp-conan.md b/quest/m3/cpp-conan.md index 9881b8fe78f..6c5acea7d9f 100644 --- a/quest/m3/cpp-conan.md +++ b/quest/m3/cpp-conan.md @@ -26,4 +26,4 @@ first. The vcpkg registry, which this reuses, is parked in m3 too (decided ## Required -- [vcpkg registry](/quest/m2/cpp-vcpkg.md) - the release manifest and bump automation this reuses +- [vcpkg registry](/quest/m3/cpp-vcpkg.md) - the release manifest and bump automation this reuses diff --git a/quest/m2/cpp-vcpkg.md b/quest/m3/cpp-vcpkg.md similarity index 100% rename from quest/m2/cpp-vcpkg.md rename to quest/m3/cpp-vcpkg.md diff --git a/quest/m3/cut-through/frames.md b/quest/m3/cut-through/frames.md deleted file mode 100644 index e821806578d..00000000000 --- a/quest/m3/cut-through/frames.md +++ /dev/null @@ -1,46 +0,0 @@ -# [L] Frames fill out of order - -## Goal - -A `moq-net` frame accepts payload ranges at any offset, a group can hold several -in-flight frames at once, and a reader can consume each range as soon as it -lands. Existing in-order readers and writers behave exactly as before. - -## Plan - -Decided 2026-09-30: - -- `frame::Producer` gains an offset write and `frame::Consumer` gains a read - that yields `(offset, Bytes)` ranges in arrival order. Both are - `pub(crate)`: the only users are the lite and IETF sessions in the same crate. -- A frame written out of order keeps the received chunks by offset instead of - copying into a pre-allocated buffer, so its memory tracks bytes received and - the per-session pre-allocation `Budget` (`model/frame.rs`) does not apply. - Each in-flight frame keeps the existing charge-by-bytes-written cache - accounting (`charge_partial` in `model/group.rs`), per frame. The - in-order readers (`poll_read_chunk`, `poll_read_all`) still see contiguous - bytes up to the first hole, and `finish` still requires every byte. -- Overlapping or out-of-bounds ranges are errors. -- A group holds several in-flight frames, not only the one `partial` in - `GroupState` (`model/group.rs`), and `create_frame_owned` stops rejecting a - second open frame. Frames are still created in order: frame N+1 exists only - once N's header, and so its size, is known, because that is what locates - N+1's header. The group consumer still yields frames in order. Decided - 2026-09-30 after review of #4616, so a hole in frame N does not hold back - N+1's bytes. -- The open-time `would_overflow` check assumes one frame in flight, so it - counts only the new frame's declared size. With several open frames it must - also count the unwritten remainder of every other in-flight frame, or - concurrent declarations could jointly exceed `MAX_CACHE_BYTES`. -- Today's single sequential writer (`model/frame.rs`, the one `written` - watermark and its safety comments) is the invariant being changed; keep the - ordered fast path, including the whole-frame zero-copy install, unchanged. - -Extend `rs/moq-net/benches/group.rs` so the ordered path shows no regression, -and test that a frame filled in shuffled ranges reads back identical through -both readers, and that frame N+1's ranges reach a range reader while N still -has a hole. - -## Required - -- [Bench](/quest/m3/cut-through/bench.md) - a go verdict diff --git a/quest/m3/cut-through/quic.md b/quest/m3/cut-through/quic.md deleted file mode 100644 index 9dc6c1009ff..00000000000 --- a/quest/m3/cut-through/quic.md +++ /dev/null @@ -1,32 +0,0 @@ -# [L] Offset writes in moq-quic - -## Goal - -A send stream in `moq-quic` accepts a write at an offset past unwritten -bytes, sends it right away, and fills the gap when those bytes are written -later. - -## Plan - -Decided 2026-09-30: no write-ahead limit beyond QUIC's own flow control. - -- An offset write reserves the gap and queues the range. Stream and connection - credit is charged up to the highest written offset, as it already is on the - receiver's side. -- Within a stream, lower offsets are sent first once they are written, and - retransmits keep the existing stream priority path. -- `finish` waits until every range below the final size is written; a write - that overlaps an existing range is an error. -- The append-only `write` and `write_chunks` stay as they are; the offset write - is a new method, since a writer that never skips pays nothing. -- Tests in `moq-quic`'s simulated pair: an out-of-order writer delivers the - same bytes as an ordered one, flow control blocks at the highest offset, FIN - waits for the gap, and a reset with a gap outstanding is clean. - -The change lands in-tree with its consumer, per the -[QUIC line's rules](/quest/m1/quic/README.md); no fork release or pin bump. - -## Required - -- [Hard fork](/quest/m1/quic/fork/README.md) - `moq-quic` exists and MoQ runs on it -- [Bench](/quest/m3/cut-through/bench.md) - a go verdict diff --git a/quest/m3/cut-through/relay.md b/quest/m3/cut-through/relay.md deleted file mode 100644 index f0ddee7649c..00000000000 --- a/quest/m3/cut-through/relay.md +++ /dev/null @@ -1,56 +0,0 @@ -# [L] Relay cut-through for group streams - -## Goal - -The lite and IETF sessions read incoming group streams out of order and write -each payload range to every subscriber's stream at its output offset, so bytes -behind an ingress hole reach the next hop before the hole is filled. On the -[bench](/quest/m3/cut-through/bench.md), cut-through shrinks the post-hole -drain time on the same two-hop path. - -## Plan - -Decided 2026-09-30: always on when the ingress and egress streams both support -it, no config knob; otherwise today's ordered path. - -- Ingest: read the stream header in order, then switch to unordered reads. - `Reader` may already hold bytes past the header in its buffer, so hand that - suffix over with its absolute stream offset rather than dropping or - re-basing it; test a transport chunk that carries both the header and the - first payload bytes. - Frame headers are parsed from the contiguous prefix; once a header is known, - its frame's payload ranges go into the frame with the - [offset write](/quest/m3/cut-through/frames.md) wherever they land. A hole - covering the next header blocks later frames, because that header's position - depends on it. Lite: `FrameIngest` in `lite/subscriber.rs`; IETF: - `GroupIngest` in `ietf/subscriber.rs`. `Reader::poll_read_frame` in - `coding/reader.rs` is the ordered path they share today. -- Egress: each subscriber's output offset for a payload range is its stream - prefix plus every earlier frame's encoded header and size, plus this frame's - header, plus the range offset. That is known once every earlier input header - has been parsed, including across a lite and IETF translation, since output - header lengths depend on values (timestamp and object id deltas). Write the - header, then the ranges with the - [offset write](/quest/m3/cut-through/transport.md). Lite: `GroupServe` in - `lite/publisher.rs`; IETF: `GroupServe` in `ietf/publisher.rs`. -- The fetch paths stay ordered. -- Tests over the mock transport with shuffled chunk delivery: every subscriber - version receives byte-identical streams to the ordered path, and a - header-covering hole holds later frames. - -Prototype both scopes on the bench: cut-through within the current frame only, -and across in-flight frames, where N+1's payload passes N's hole once N's -header is parsed. Keep the one the numbers justify and delete the other; a -regression test asserts N+1 is forwarded before N's hole fills when the -multi-frame scope ships. - -Sweep the bench over publisher and subscriber counts as well as the network -axes. Range bookkeeping, wakeups, and offset writes run per served -subscriber, so total CPU grows with the subscribers a range reaches; the cost -per served subscriber, and the cost from table entries a range does not touch, -must stay flat against the ordered path. Re-run it and record the result in the line's README. - -## Required - -- [Frame ranges](/quest/m3/cut-through/frames.md) - the model primitive -- [Transport trait](/quest/m3/cut-through/transport.md) - the I/O primitive diff --git a/quest/m3/cut-through/transport.md b/quest/m3/cut-through/transport.md deleted file mode 100644 index 48625bc3826..00000000000 --- a/quest/m3/cut-through/transport.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] Unordered reads and offset writes in moq-net's transport traits - -## Goal - -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 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 - report unsupported in the return type (as - [poll_acked](/quest/m2/quic-ack-hook.md) does, since a default cannot build - `Self::Error`), and the caller falls back to ordered I/O. -- 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 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. The WASM, qmux, and iroh adapters keep the - defaults. - -## Required - -- [Offset writes in moq-quic](/quest/m3/cut-through/quic.md) - the send-side primitive this exposes diff --git a/quest/m3/embedded-device.md b/quest/m3/embedded-device.md deleted file mode 100644 index 8e30e309992..00000000000 --- a/quest/m3/embedded-device.md +++ /dev/null @@ -1,13 +0,0 @@ -# [XS] An embedded video device is on hand - -## Goal - -Someone has a Raspberry Pi or similar V4L2 M2M device without a usable -Vulkan driver, and can validate the renderer's EGL import on it. - -This quest tracks a condition outside the repository. When it holds, delete -this quest and every `Required` entry that links it. - -## Plan - -Record the device, OS image, and driver when it exists. diff --git a/quest/m2/ietf-cluster-peers.md b/quest/m3/ietf-cluster-peers.md similarity index 100% rename from quest/m2/ietf-cluster-peers.md rename to quest/m3/ietf-cluster-peers.md diff --git a/quest/m3/interop-graceful-close.md b/quest/m3/interop-graceful-close.md deleted file mode 100644 index ee8e9645aee..00000000000 --- a/quest/m3/interop-graceful-close.md +++ /dev/null @@ -1,20 +0,0 @@ -# [S] Interop runner withdraws publications before disconnecting - -## Goal - -A completed publish in moq-interop-runner gracefully closes its session so a -subsequent run can publish the same namespace without an already-published error. - -## Plan - -The runner found this in [#4209](https://github.com/moq-dev/moq/pull/4209). -Replace successful publication's immediate abort with the graceful close API -once the runner uses a moq-net revision that withdraws namespaces on close. -Exercise successive runs against the same relay. - -The caller lives outside this repository. Obtain maintainer approval before -posting to its repository; that approval has not been given. - -## Required - -- [The maintainer approves posting to moq-interop-runner](/quest/m3/interop-runner-approval.md) - the outstanding approval this waits on diff --git a/quest/m3/ladder/README.md b/quest/m3/ladder/README.md index 479f0d3b0ed..e05a80ab841 100644 --- a/quest/m3/ladder/README.md +++ b/quest/m3/ladder/README.md @@ -88,4 +88,4 @@ encoders on every target change. ## Related -- [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the other sender that reserves but never follows its grant +- [#2848](/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the other sender that reserves but never follows its grant diff --git a/quest/m3/moq-relay-subcommand.md b/quest/m3/moq-relay-subcommand.md deleted file mode 100644 index 27c97dc5660..00000000000 --- a/quest/m3/moq-relay-subcommand.md +++ /dev/null @@ -1,42 +0,0 @@ -# [S] Relay verb - -## Goal - -`moq relay` runs the relay with exactly the flags, environment, and TOML -`moq-relay` accepts, and `moq-relay` stays published as its own minimal -binary: someone who only wants a relay does not download the capture, encode, -decode, and render stack. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer, and [`moq --listen` -drain and stats](/quest/m1/cli-serve.md) no longer waits on it. - -`moq-relay` is lib+bin (`rs/moq-relay/Cargo.toml`), with a 15-line -`main.rs` that installs the aws-lc-rs provider, optionally jemalloc, and calls -`Relay::load(Config::load()?).await?.run()`. - -- moq-cli gains a default-on `relay` feature depending on the moq-relay - library and a `Command::Relay(moq_relay::Config)` verb, answered before any - transport binds like `token` and `completion`, with `MoqSide::reject` - covering it. The relay's own features (`iroh`, `cluster-lan`, backends, - `websocket`) forward from the CLI's features of the same name. -- `Config::load` parses argv, reads the TOML `file` names, and merges the - layers in one step (`rs/moq-relay/src/config.rs`, `parse_and_merge`), so a - nested `Config` would carry only the flags and ignore its TOML. Split the - file read and precedence merge into a step that takes an already-parsed - `Config`, used by both `Config::load` and the verb, and test the same TOML - invocation through both binaries. -- Move the provider install out of both mains into `Relay::load`, so an - embedder and the two binaries share one startup. jemalloc stays a - binary-level global allocator. -- `moq relay --help` renders the relay's whole tree under the verb; check the - spec dumps both binaries produce agree. -- Docs: `doc/bin/relay/` names both spellings once, `doc/bin/cli.md` gains the - verb, and the demo recipes keep using `moq-relay`. -- Test: `rs/moq-relay/tests/released_cli.rs` drives the binary; add a case - that runs the same smoke through `moq relay`. - -## Related - -- [`moq --listen` drain and stats](/quest/m1/cli-serve.md) - the CLI's listener is admitted through the same `serve` diff --git a/quest/m2/msfts-convergence.md b/quest/m3/msfts-convergence.md similarity index 100% rename from quest/m2/msfts-convergence.md rename to quest/m3/msfts-convergence.md diff --git a/quest/m3/nvenc-av1.md b/quest/m3/nvenc-av1.md index 7af1ec9ac7b..1b03b2ec0b8 100644 --- a/quest/m3/nvenc-av1.md +++ b/quest/m3/nvenc-av1.md @@ -27,5 +27,5 @@ Public API: additive. Wire: existing AV1 codec signaling. ## Related -- [Main10](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - the other half of #2147 +- [Main10](/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - the other half of #2147 - [GPU CI](/quest/m1/gpu-ci.md) - the current runner lacks AV1 NVENC diff --git a/quest/m3/p2p/unordered.md b/quest/m3/p2p/unordered.md deleted file mode 100644 index 696f6bac43d..00000000000 --- a/quest/m3/p2p/unordered.md +++ /dev/null @@ -1,63 +0,0 @@ -# [M] Unordered qmux - -## Goal - -qmux tolerates reordered records when both sides agree to it, so the data -channel runs `ordered: false` and a lost SCTP chunk stalls only the stream -whose frame it carried. Native pairs only: both endpoints must run the Rust -qmux core, and a pair with a browser stays ordered. The native transports -flip one option; the WebSocket and TCP bindings are untouched. - -## Plan - -Decided in the 2026-10-06 audit: native pairs only. Receiver reassembly comes -from [qmux on the QUIC core](/quest/m2/quic-qmux.md), which ports only the -Rust qmux; the TypeScript `@moq/qmux` keeps its own in-order state machine, -and building offset reassembly there was rejected. So only an endpoint on -the Rust core advertises `unordered`, and a browser never does. - -qmux frames already carry stream offsets; the draft's in-order STREAM -requirement exists so a receiver can deliver without reassembly. Add a -transport parameter, `unordered`, that both sides must send for the relaxed -rule to apply, and receiver-side reassembly by offset for STREAM frames when -it does. That reassembly is QUIC's own receive buffer once qmux runs on the -QUIC core, so this quest is the parameter plus the binding flip; do not -build a second reassembly buffer. One -record is one SCTP message, so the unordered writer emits frames for only -one stream per record; mixing streams in a record would stall both on one -lost chunk and is forbidden when unordered is on. - -Frames that QUIC itself handles out of order (MAX_DATA, MAX_STREAM_DATA, -RESET_STREAM by final size) need nothing. Params-first setup still holds -because the transport parameters travel in the first record and the receiver -holds later records until it has them. - -`RTCDataChannel.ordered` is fixed at `createDataChannel`. The qmux -parameter arrives in the first record on that already-created channel, so -neither binding can learn unordered from the handshake and then flip the -channel. Advertise the capability in the roster `info.json` -(`unordered: true`) before any channel exists, the same place ALPNs live. -The dialer creates the channel with `ordered: false` only when both roster -entries say so, and both sides then send the parameter; otherwise the -channel stays ordered and the parameter is not sent. A channel created -unordered whose peer omits the parameter, or a parameter on an ordered -channel, aborts the session. Do not open a second channel, and do not -learn the mode from the first record. Native iroh and QUIC have no -constructor constraint; the parameter alone is enough there. - -Draft: a new extension draft (for example `draft-lcurley-qmux-unordered.md`) -defines the parameter and the relaxed rule, decided in the 2026-10-05 audit; -no `draft-lcurley-qmux.md` exists, QMux itself is the WG's -I-D.ietf-quic-qmux, and the WebSocket binding draft is the wrong home. The -data channel row in `draft-lcurley-moq-lite.md` says which mode it runs. -`just drafts check` passes. - -Measure with the [harness](/quest/m3/p2p/harness.md) before and after: stall -duration after an induced loss is the number this quest exists to move, and -throughput must not regress. - -## Required - -- [qmux on the QUIC core](/quest/m2/quic-qmux.md) - the Rust qmux whose QUIC receive buffer reassembles by offset -- [Harness](/quest/m3/p2p/harness.md) - the loss row this quest is measured against -- [Signaling and policy](/quest/m3/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists diff --git a/quest/m2/pipewire-camera-planes.md b/quest/m3/pipewire-camera-planes.md similarity index 100% rename from quest/m2/pipewire-camera-planes.md rename to quest/m3/pipewire-camera-planes.md diff --git a/quest/m2/quic-careful-resume.md b/quest/m3/quic-careful-resume.md similarity index 100% rename from quest/m2/quic-careful-resume.md rename to quest/m3/quic-careful-resume.md diff --git a/quest/m2/quic-ecn.md b/quest/m3/quic-ecn.md similarity index 100% rename from quest/m2/quic-ecn.md rename to quest/m3/quic-ecn.md diff --git a/quest/m4/safari-webtransport.md b/quest/m3/safari-webtransport.md similarity index 100% rename from quest/m4/safari-webtransport.md rename to quest/m3/safari-webtransport.md diff --git a/quest/m3/stats-encoder-feedback.md b/quest/m3/stats-encoder-feedback.md index 4ca6583f9cd..34932e0970e 100644 --- a/quest/m3/stats-encoder-feedback.md +++ b/quest/m3/stats-encoder-feedback.md @@ -91,7 +91,7 @@ Open, to settle before starting (moved from the ## Related - [Ladder controller](/quest/m3/ladder/controller.md) - owns the rung targets a split-out transcode leg would feed -- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - +- [Audio follows the grant](/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the audio rate follow this signal would feed - [Ladder](/quest/m3/ladder/README.md) - the transcode ladder, which today encodes every rung at a fixed rate with no bandwidth input diff --git a/quest/m2/teleop/arbitration.md b/quest/m3/teleop-arbitration.md similarity index 93% rename from quest/m2/teleop/arbitration.md rename to quest/m3/teleop-arbitration.md index 1badd9e38ff..4edb2fac288 100644 --- a/quest/m2/teleop/arbitration.md +++ b/quest/m3/teleop-arbitration.md @@ -8,7 +8,7 @@ assumed. ## Plan -Decided 2026-10-08: parked in m3 with [robot](/quest/m2/teleop/robot.md), +Decided 2026-10-08: parked in m3 with [robot](/quest/m3/teleop-robot.md), which it builds on. `moq-boy` merges every viewer's input, which is right for crowd control and @@ -42,4 +42,4 @@ not attempt. ## Required -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) +- [Robot teleoperation primitive](/quest/m3/teleop-robot.md) diff --git a/quest/m3/teleop-browser-package.md b/quest/m3/teleop-browser-package.md deleted file mode 100644 index c954013824b..00000000000 --- a/quest/m3/teleop-browser-package.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Browser teleoperation package - -## Goal - -`@moq/robot` mirrors the Rust crate, so a browser client consumes the catalog -and delivery classes rather than reimplementing them. - -## Plan - -Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). - -Follow the existing split: `net`, `hang`, `json` and `auth` each have a Rust -crate and a TypeScript package, with zod schemas mirroring the Rust types. -There is no `@moq/mux`, so the catalog extension goes through the same seam -`js/hang/src/catalog/root.ts` uses to extend the root schema. - -A browser observer cannot degrade the operator's classes (`clamp_combined` -bounds the window at the publisher, and `Subscription::max_delay` already -defaults to `Duration::ZERO`), so this package exists for reuse, not for safety: the -catalog schema, the snapshot and append-log shapes, and the instrumentation are -the same on both sides and should be written once. - -Port `js/moq-boy` onto it alongside the Rust port, for the same reason: it is -the only existing consumer and the only available falsification test. - -## Required - -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) diff --git a/quest/m3/teleop-mavlink.md b/quest/m3/teleop-mavlink.md index 7496745757d..bcf46bcffb0 100644 --- a/quest/m3/teleop-mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -74,7 +74,7 @@ up to `MAX_DELTA_FRAMES` merge patches into one ordered group, so an earlier The reliable class is the append-log shape (the binary `stream` mode): commands, ACKs, mission, parameter and file transfer are stop-and-wait exchanges carried in one ordered group. Note the scope in -[robot](/quest/m2/teleop/robot.md): that is gap-free for a live reader, not +[robot](/quest/m3/teleop-robot.md): that is gap-free for a live reader, not recoverable after a lag or a reconnect, so these MAVLink services keep relying on their own retransmission across a link drop. @@ -88,8 +88,8 @@ small, real contribution and its own future quest. ## Required -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) -- [Operator arbitration](/quest/m2/teleop/arbitration.md) +- [Robot teleoperation primitive](/quest/m3/teleop-robot.md) +- [Operator arbitration](/quest/m3/teleop-arbitration.md) ## Related diff --git a/quest/m3/teleop-proof.md b/quest/m3/teleop-proof.md index 552f5b9bcb3..053d2292aa4 100644 --- a/quest/m3/teleop-proof.md +++ b/quest/m3/teleop-proof.md @@ -37,4 +37,4 @@ the maintenance. ## Related -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) - the Rust types the zod schema mirrors +- [Robot teleoperation primitive](/quest/m3/teleop-robot.md) - the Rust types the zod schema mirrors diff --git a/quest/m2/teleop/robot.md b/quest/m3/teleop-robot.md similarity index 98% rename from quest/m2/teleop/robot.md rename to quest/m3/teleop-robot.md index 83ab507c65e..00211fedec6 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m3/teleop-robot.md @@ -116,5 +116,5 @@ control then it is the wrong abstraction. ## Related -- [arbitration](/quest/m2/teleop/arbitration.md) - which controller is obeyed +- [arbitration](/quest/m3/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/m3/text-schema.md b/quest/m3/text-schema.md deleted file mode 100644 index a84a5fe11b1..00000000000 --- a/quest/m3/text-schema.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] Text availability index - -## Goal - -A text track says what it actually covers. An independently hosted -transcription publishes its own local availability index instead of copying -the audio or video timeline it transcribes. - -## Plan - -Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer. - -The `text` catalog section already carries the rest of the contract: relative -`broadcast` references so a transcription can live in its own broadcast, cue -timing on the shared media clock, and `jitter` for the publisher's flush -delay. What it has no answer for is coverage. - -A transcription contribution is not continuous and does not start when the -media does. It may join late, drop out, or cover only part of what it listens -to, so a consumer that reads the source's timeline learns nothing about which -spans actually have text. Copying that timeline would be worse than useless: -it would advertise coverage the transcriber never produced. - -Give the text rendition its own availability index over the spans it has -published, on the same media clock as its cues, so a consumer can tell "no -speech here" from "no transcription here". Keep it local to the text track: -composing transcription contributions onto broadcasts stays downstream in -moq.pro. - -Per cross-package sync, mirror the schema in `js/hang` and update -`drafts/draft-lcurley-moq-hang.md` in the same PR. diff --git a/quest/m2/uring-tcp/README.md b/quest/m3/uring-tcp/README.md similarity index 91% rename from quest/m2/uring-tcp/README.md rename to quest/m3/uring-tcp/README.md index 0129dc27e3b..063060f3b57 100644 --- a/quest/m2/uring-tcp/README.md +++ b/quest/m3/uring-tcp/README.md @@ -42,9 +42,9 @@ ablation stays the gate for the rest of the line. ## Required -- [Ablation](/quest/m2/uring-tcp/ablation.md) - measure ring TCP against tokio +- [Ablation](/quest/m3/uring-tcp/ablation.md) - measure ring TCP against tokio TCP under the qmux workload before committing to the port -- [Stream](/quest/m2/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and +- [Stream](/quest/m3/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and the `hyper::rt` adapters that let axum run on it -- [Relay](/quest/m2/uring-tcp/relay.md) - serve the relay's WebSocket and +- [Relay](/quest/m3/uring-tcp/relay.md) - serve the relay's WebSocket and stream listeners from the io_uring workers diff --git a/quest/m2/uring-tcp/ablation.md b/quest/m3/uring-tcp/ablation.md similarity index 100% rename from quest/m2/uring-tcp/ablation.md rename to quest/m3/uring-tcp/ablation.md diff --git a/quest/m2/uring-tcp/relay.md b/quest/m3/uring-tcp/relay.md similarity index 92% rename from quest/m2/uring-tcp/relay.md rename to quest/m3/uring-tcp/relay.md index de194840027..ebb4506edf5 100644 --- a/quest/m2/uring-tcp/relay.md +++ b/quest/m3/uring-tcp/relay.md @@ -12,7 +12,7 @@ then pinned to one thread for its whole life, exactly like a QUIC one. `tcp`/`unix` listeners and points the operator at a separate `init_streams` tokio server; the only thing it refuses is `tls.generate`. Replace the silent skip with real support: each worker binds its own listener in the reuseport group and runs the router from -[stream](/quest/m2/uring-tcp/stream.md) on it. +[stream](/quest/m3/uring-tcp/stream.md) on it. The split of work stays what the `uring.rs` module docs already describe: the worker owns everything transport-shaped, while authentication and session @@ -28,5 +28,5 @@ worker. ## Required -- [Stream](/quest/m2/uring-tcp/stream.md) - the module and adapters this +- [Stream](/quest/m3/uring-tcp/stream.md) - the module and adapters this serves from diff --git a/quest/m2/uring-tcp/stream.md b/quest/m3/uring-tcp/stream.md similarity index 96% rename from quest/m2/uring-tcp/stream.md rename to quest/m3/uring-tcp/stream.md index c0ce1630d23..a25ade8c012 100644 --- a/quest/m2/uring-tcp/stream.md +++ b/quest/m3/uring-tcp/stream.md @@ -32,4 +32,4 @@ existing suite does. ## Required -- [Ring TCP ablation](/quest/m2/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts +- [Ring TCP ablation](/quest/m3/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts diff --git a/quest/m2/video-codec-coverage.md b/quest/m3/video-codec-coverage.md similarity index 96% rename from quest/m2/video-codec-coverage.md rename to quest/m3/video-codec-coverage.md index b558c2287a9..fc43c75caf8 100644 --- a/quest/m2/video-codec-coverage.md +++ b/quest/m3/video-codec-coverage.md @@ -31,6 +31,6 @@ Decided 2026-10-08: moved to m3. No consumer has asked for a missing codec. ## Related -- [NVIDIA formats](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - 10-bit HEVC scope; AV1 encode moved to [NVENC AV1](/quest/m3/nvenc-av1.md) +- [NVIDIA formats](/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - 10-bit HEVC scope; AV1 encode moved to [NVENC AV1](/quest/m3/nvenc-av1.md) - [VAAPI](/quest/m2/video-vaapi.md) - existing Linux codec expansion - [VP8/VP9 in OBS](/quest/m1/obs-moq-video/vpx-obs.md) - the software decoder reaching the OBS source diff --git a/quest/m3/video-hardware.md b/quest/m3/video-hardware.md index aa5ed2785fc..f9ccafc464f 100644 --- a/quest/m3/video-hardware.md +++ b/quest/m3/video-hardware.md @@ -53,7 +53,7 @@ arrived, and whether the producer used one memory block or one per plane. No new capture API, and no libcamera source. A separate-plane producer belongs to -[multi-plane cameras](/quest/m2/pipewire-camera-planes.md); if that is why a +[multi-plane cameras](/quest/m3/pipewire-camera-planes.md); if that is why a Pi produces nothing, write it down and stop. `doc/lib/rs/moq-video.md` says both paths are reachable; correct that sentence if one cannot capture. @@ -75,5 +75,5 @@ is not a bug any amount of review finds. ## Related - [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the DMA-BUF import validation this capture feeds -- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the Pi pass finds them +- [Capture multi-plane PipeWire cameras](/quest/m3/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the Pi pass finds them - [Embedded video path](/quest/m3/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m4/webkit-319818.md b/quest/m3/webkit-319818.md similarity index 100% rename from quest/m4/webkit-319818.md rename to quest/m3/webkit-319818.md diff --git a/quest/m4/README.md b/quest/m4/README.md deleted file mode 100644 index 96567c2f3bc..00000000000 --- a/quest/m4/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# m4: upstream - -## Goal - -Work waiting on an upstream release or external dependency to ship, kept here -so it is not forgotten. - -## Plan - -Each quest's gate is a condition quest beside it, as the root -[questline](/quest/README.md) describes. - -## Required - -- [Safari ships the WebKit 319818 fix](/quest/m4/webkit-319818.md) - the Safari release the gate admits -- [Safari WebTransport](/quest/m4/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed From e4d7fc040d52eff2e24adcd50a56be2fdae86b29 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 08:23:30 -0700 Subject: [PATCH 09/10] quest: address review on the audit PR Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/moqsrc.md | 13 +++++++++---- quest/m0/broadcast-epoch/ts-restart.md | 9 ++++++--- quest/m1/drop-loud.md | 11 ++++++++--- quest/m2/one-port/tcp-demux.md | 11 +++++++---- 4 files changed, 30 insertions(+), 14 deletions(-) diff --git a/quest/m0/broadcast-epoch/moqsrc.md b/quest/m0/broadcast-epoch/moqsrc.md index 0d2c9be381d..171615d03ad 100644 --- a/quest/m0/broadcast-epoch/moqsrc.md +++ b/quest/m0/broadcast-epoch/moqsrc.md @@ -27,9 +27,13 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered than the path itself. `moqsrc` switches on a `Restart` of the route its path resolves through; the re-request re-resolves upstream, and if it lands on the same source the run still restarts on the same pads. -- **Errors keep today's handling.** A replacement no longer ends the old - subscriptions, so a catalog error posts the session error and a track error - logs and ends that pad, as today. The earlier rule treating `Unroutable` as +- **Errors keep today's handling, except source loss.** A replacement no + longer ends the old subscriptions, so a malformed catalog or track posts + the session error or ends that pad, as today. Losing the source (the + publisher's session closing, or the route going away) is not fatal: it + enters the held state below even when it arrives before the announce + `End`, since `catalog.next()` and session completion + (`rs/moq-gst/src/source/imp.rs`) see it first today. The earlier rule treating `Unroutable` as a switch in flight is dropped: it could not tell a switch from a dead route and could hang. - **Cutover.** Cancel the old pumps as soon as the `Restart` is seen, without @@ -52,7 +56,8 @@ Decided in planning (2026-10-06, after #4955 found that no quest covered and START are not coalesced into a `Restart`, and a withdrawn source. A track that ends or loses its source hands its pad back without EOS, since tracks, the catalog, and `End` arrive on different streams in either order; - the next `Start` resumes on the same pads. A rendition the catalog retired + the next `Start` resumes on the same pads. The regression covers both + orders: source loss before `End`, and `End` before source loss. A rendition the catalog retired still drains to EOS. No timer and no property: announcements already say when the source is back, and a timer cannot tell a slow restart from a dead source. diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md index f809dd58bab..3525b3a3512 100644 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ b/quest/m0/broadcast-epoch/ts-restart.md @@ -38,9 +38,12 @@ Decided (maintainer, 2026-09-30): program and `Program::All`. Decided 2026-10-08: when the operator gave `--epoch`, a flagged rewind is -fatal like an unsignalled one, so the supervisor restarts the process and -both hosts of a redundant pair keep the operator's epoch. A fresh epoch per -rewind would split the pair. +fatal like an unsignalled one, since minting a fresh epoch per rewind would +split a redundant pair. Restarting under the same epoch is not safe either: +the new run restarts group numbering, and a matching epoch lets viewers and +caches resume the old content under the same names. So the error says the +operator's supervisor must restart both hosts under a new shared epoch, and +`doc/bin/cli.md`'s redundant-pair example says the same. Tests: a fixture with a flagged rewind publishes two broadcasts, the second starting at the rewound PTS; the same rewind unflagged still errors; one SRT diff --git a/quest/m1/drop-loud.md b/quest/m1/drop-loud.md index b3aa50b42a1..5ad6996d718 100644 --- a/quest/m1/drop-loud.md +++ b/quest/m1/drop-loud.md @@ -12,7 +12,11 @@ carriage stays with the m3 timed-metadata quests. Today `rs/moq-mux/src/container/flv/import.rs` matches `TAG_SCRIPT => {}`, and the fMP4 importer's box loop (`rs/moq-mux/src/container/fmp4/import.rs`) sends `emsg` to the catch-all arm that skips unknown atoms, both without a -log line. +log line. RTMP metadata never reaches the FLV importer: the publish side +discards `ServerSessionEvent::StreamMetadataChanged` +(`rs/moq-rtmp/src/server.rs`) and the pull side discards +`ClientSessionEvent::StreamMetadataReceived` (`rs/moq-rtmp/src/dial.rs`), so +those two arms are counted too. Decided 2026-10-08, from the quest audit: a small m1 quest, since the carriage quests are parked in m3 with no consumer and the silent drop @@ -26,8 +30,9 @@ line for genuinely unknown tags. If a refusal fits a narrower case better (for example an `emsg` scheme an application declared it needs), say so in the PR. -Test: an FLV clip with `onMetaData` and an fMP4 fragment with an `emsg` box -each import, warn once, and report a count of what was dropped. +Test: an FLV clip with `onMetaData`, an fMP4 fragment with an `emsg` box, and +an RTMP publish and pull carrying metadata each import, warn once, and report +a count of what was dropped. Public API: possibly an accessor for the counts. Wire: none. diff --git a/quest/m2/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md index 2047fa74973..083930bc2c2 100644 --- a/quest/m2/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -32,16 +32,19 @@ stream alike. Reuse the handshake bound `listen.timeout` already sets The TLS arm also carries `tls://` qmux, served today by its own `listen.tcp` listener with TLS. It negotiates a moq ALPN in the TLS handshake, so split -the decrypted arm on ALPN: a moq ALPN goes to the qmux server, and HTTP -ALPNs (or none) go to the router. +the decrypted arm on ALPN: a moq ALPN goes to the qmux server and an HTTP +ALPN to the router. A connection with no ALPN keeps the decrypted-byte +sniff, since RTMPS clients negotiate none (`moq-rtmp` documents an empty +ALPN list): `0x03` is RTMP, anything else is HTTP. Keep the accepted `TcpStream`'s handle reachable after it is boxed: the relay already captures socket stats at accept for qmux (`SocketStats` in `web.rs`), and [WebSocket bitrate caps](/quest/m2/rate-websocket.md) set socket buffer sizes on the same socket. -Tests: an HTTP request, a WebSocket upgrade, a raw RTMP C0, and an RTMPS C0 -against one listener each land in the right arm. +Tests: an HTTP request, a WebSocket upgrade, a raw RTMP C0, an RTMPS C0 with +no ALPN, and a `tls://` qmux client against one listener each land in the +right arm. ## Related From 2e42af05f2c8d98c828a066787f357e1451d1971 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 09:00:36 -0700 Subject: [PATCH 10/10] quest: drop the in-process TS restart; a rewind stays fatal Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 1 - quest/m0/broadcast-epoch/ts-restart.md | 62 -------------------------- quest/m1/ts-passthrough.md | 20 +++------ 3 files changed, 5 insertions(+), 78 deletions(-) delete mode 100644 quest/m0/broadcast-epoch/ts-restart.md diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index ecf7b4555c0..7a1c727a206 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -97,7 +97,6 @@ then. MoQ Pro's VOD `storage.json` moves from the same seed to its own epoch. - [Restart](/quest/m0/broadcast-epoch/restart.md) - a replaced broadcast reaches announce consumers as an explicit Restart, subscriptions stay sticky, and new requests never join a replaced route's front - [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch - [Publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) - `@moq/publish` never reuses catalog group numbers under one name and epoch after a re-announce -- [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch - [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and let a publisher announce one - [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) - moqsrc switches to the new broadcast on a `Restart`, keeping its pads by rendition name - [Stats totals and prefix tracks](/quest/m0/broadcast-epoch/stats-split.md) - the same release retires the per-path stats maps for totals and on-demand prefix tracks (decided 2026-10-05) diff --git a/quest/m0/broadcast-epoch/ts-restart.md b/quest/m0/broadcast-epoch/ts-restart.md deleted file mode 100644 index 3525b3a3512..00000000000 --- a/quest/m0/broadcast-epoch/ts-restart.md +++ /dev/null @@ -1,62 +0,0 @@ -# [M] A signalled TS restart continues as a new epoch - -## Goal - -When a TS feed rewinds its time base and signals it -(`discontinuity_indicator` on the PCR PID, ISO/IEC 13818-1 2.4.3.5), -`moq import ts` and `moq-srt` finish the current broadcast cleanly and publish -the rest of the same input as a new broadcast under a fresh epoch, in the same -process and connection. This covers an encoder restart or source switch behind -a gateway that keeps its connection up, and a looping playout server, none of -which makes a new connection for the ingest gateways -to turn into an epoch. An unsignalled rewind stays fatal, as #4543 decided. - -## Plan - -Since #4543, every rewind ends the import with `TimestampRewind` from -`Producer::write`; the importer already reads the flag in `timebase_break`, -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. 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 - `import.restart(broadcast)`. The importer carries over only the PAT/PMT - layout and the bytes it has not consumed, so there is no wait for the next - PSI repetition; tracks, groups, and timestamps start fresh. `ts::Programs` - does this per program. Returning unconsumed bytes to a fresh `Import` was - rejected for the PSI wait, and letting the importer publish its own - broadcast was rejected for coupling moq-mux to origin publishing. -- A flag with the next PCR behind the last one is a restart; a flag with a - forward jump stays a break marker. The 33-bit wrap is modular, not a rewind. -- Callers: `moq import ts` (`rs/moq-cli`) and `moq-srt`'s `Publisher`, single - program and `Program::All`. - -Decided 2026-10-08: when the operator gave `--epoch`, a flagged rewind is -fatal like an unsignalled one, since minting a fresh epoch per rewind would -split a redundant pair. Restarting under the same epoch is not safe either: -the new run restarts group numbering, and a matching epoch lets viewers and -caches resume the old content under the same names. So the error says the -operator's supervisor must restart both hosts under a new shared epoch, and -`doc/bin/cli.md`'s redundant-pair example says the same. - -Tests: a fixture with a flagged rewind publishes two broadcasts, the second -starting at the rewound PTS; the same rewind unflagged still errors; one SRT -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 -- [#5003](https://github.com/moq-dev/moq/pull/5003) - `import ts --passthrough`, which waits on this quest's `decode` change diff --git a/quest/m1/ts-passthrough.md b/quest/m1/ts-passthrough.md index a31f521b4ea..ab0856c0d13 100644 --- a/quest/m1/ts-passthrough.md +++ b/quest/m1/ts-passthrough.md @@ -42,16 +42,10 @@ Decided (2026-10-01), from a discussion with t0ms: inside a group. A source that never sets the random-access indicator falls back to a group every N PCRs (N to be fixed in the PR, with a group spanning at most 1 s of PCR time). Pacing stays on the PCR PID throughout. -- A flagged PCR discontinuity that rewinds is a restart, as - [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) decides for the - demultiplexed lane: the passthrough broadcast finishes cleanly and the rest - of the input continues as a new broadcast at the same path under a fresh - epoch, so object timestamps never go backwards within one broadcast. A - flagged forward jump starts a group, and an unflagged rewind is fatal - (decided 2026-10-07 in the final-head audit of #4670, which had a backward - flag start a group in place). When the operator pinned the epoch with - `--epoch`, a flagged rewind is fatal instead, as TS restart decides - (2026-10-08), so both hosts of a redundant pair keep the operator's epoch. +- Any PCR rewind, flagged or not, is fatal, as on the demultiplexed lane: an + importer never restarts a broadcast in-process (decided 2026-10-08; a + supervisor that wants to continue publishes a new broadcast under a new + epoch). A flagged forward jump starts a group. - `randomAccess` is true only while the PAT lists a single program with at most one video PID, and every group has started at a `random_access_indicator`. The first group that starts without one (a @@ -112,7 +106,7 @@ A dropped object is counted, and the rest still go out on time. Rerun the #4613 netem rig (10% loss, 120 s) against it. Lands in two PRs (decided 2026-10-08): #5003 is the import half and the -`m2ts` catalog section, and waits on TS restart; the export half follows on +`m2ts` catalog section, refusing any PCR rewind; the export half follows on the fixed-delay release stage. This quest finishes with the export. Update `doc/bin/cli.md` for both flags, `doc/concept` for the section, and @@ -122,10 +116,6 @@ shapes. Public API: new import and export modes; nothing existing breaks. Wire: the hang catalog gains an `m2ts` root section; additive. -## Required - -- [TS restart](/quest/m0/broadcast-epoch/ts-restart.md) - the restart-under-a-new-epoch path a backward PCR discontinuity reuses - ## Related - [TS hitless](/quest/m2/ts-hitless.md) - the demultiplexed lane's 2022-7 legs and the `--sync` anchor