From 436de29dcdef89191fa613c13e138ff9672dd5e4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 4 Sep 2026 21:39:27 -0700 Subject: [PATCH 1/4] docs(quest): import the open issues that had no quest, and gate the dev merge Triages the 43 open issues the 2026-08 grooming left without a quest. Seven become quests (five m0 bugs, the m1 gap-discontinuity contract, and #3124 as a Closes on noq-parity), 24 join a new merge-dev gate quest that closes them when dev lands, and the rest are dispositioned in the PR. Two design decisions settled on the way: a discontinuity is a hole in the delivered group sequence rather than an empty group (the empty group is shed under a zero budget on dev, #3291), and in the legacy and LOC containers a video group ends with an empty frame that closes its last frame's duration while audio writes no empty frames at all (m2 duration-marker). The IETF error-code quest absorbs #3001; the #3049 quest is deleted because #3066 already moved the duplicate-hop check into Hops::push. Co-Authored-By: Claude Fable 5.1 --- ...pler-frames-keep-their-source-timestamp.md | 42 ++++++++++ ...oc-observing-the-catalog-from-moq-watch.md | 32 ++++++++ ...q-package-a-package-imports-is-declared.md | 33 ++++++++ ...published-on-one-session-keeps-resuming.md | 50 ++++++++++++ quest/m0/README.md | 5 ++ quest/m0/ietf-error-codes.md | 70 +++++++++++++++++ ...ts-send-moq-lite-error-codes-so-routine.md | 33 -------- ...outbound-hop-path-construction-is-never.md | 76 ------------------- ...60-moq-net-ban-hop-id-0-from-hop-chains.md | 9 +-- quest/m1/README.md | 4 +- quest/m1/gap-discontinuity.md | 70 +++++++++++++++++ quest/m1/group-overflow-abort.md | 4 +- quest/m1/js-net-stream-error-codes.md | 4 +- quest/m1/merge-dev.md | 58 ++++++++++++++ quest/m1/monotonic-timeline.md | 13 ++-- quest/m2/README.md | 1 + quest/m2/duration-marker.md | 56 ++++++++++++++ quest/m2/quic/noq-parity.md | 4 + 18 files changed, 438 insertions(+), 126 deletions(-) create mode 100644 quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md create mode 100644 quest/m0/3360-doc-observing-the-catalog-from-moq-watch.md create mode 100644 quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md create mode 100644 quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md create mode 100644 quest/m0/ietf-error-codes.md delete mode 100644 quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md delete mode 100644 quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md create mode 100644 quest/m1/gap-discontinuity.md create mode 100644 quest/m1/merge-dev.md create mode 100644 quest/m2/duration-marker.md diff --git a/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md b/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md new file mode 100644 index 00000000000..b83d516478b --- /dev/null +++ b/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md @@ -0,0 +1,42 @@ +# [S] moq-audio: held resampler frames keep their source timestamp + +## Goal + +`decode::Consumer` stamps resampled output where its first sample came from, +in every phase, instead of subtracting held-frame counts from the newest +packet's timestamp. A forward gap can no longer place audio up to a packet +away from where it belongs, and `Frame::activity`, keyed by the same stamp, +labels the right span. + +## Plan + +`starts_at` in `rs/moq-audio/src/decode/consumer.rs` rewinds the current +packet's `decoded_at` by `pending` input frames and `skipped` startup frames; +`Resampler` in `rs/moq-audio/src/resample.rs` exposes only counts +(`pending_frames`, `skipped`), never where the held samples came from. #3386 +mitigated the reported case on both branches: `Consumer::read` detects an +undeclared hole before decoding (`discontinuous(next, mux_frame.timestamp)`), +drains the resampler through `gap()`, and stamps the tail from the pre-gap +`tail`. Two holes remain: the gap check is skipped once `self.end` is set (the +terminal phase), and a jump inside `discontinuous()`'s slack still rewinds +across silently. + +- The resampler records the source timestamp of the oldest held input frame, + fed alongside the samples, and `starts_at` reads it; the `skipped` startup + frames rewind from that. +- Delete the derived subtraction; `pending_frames` stays for the drain + accounting. +- Regression: a 10 ms packet at 0 leaves 10 ms held, the next packet lands at + 1 s, and the output is stamped from 0 rather than near 990 ms, in the + terminal phase too, with the activity span labelled from the held packet. + Cover a jump inside the slack. +- [Duration marker](/quest/m2/duration-marker.md) removes the audio end marker + and the terminal phase; whichever lands second simplifies the other. + +## Closes + +- [#3326](https://github.com/moq-dev/moq/issues/3326) - close this issue when the quest finishes + +## Related + +- [Duration marker](/quest/m2/duration-marker.md) - removes the terminal phase this quest has to cover diff --git a/quest/m0/3360-doc-observing-the-catalog-from-moq-watch.md b/quest/m0/3360-doc-observing-the-catalog-from-moq-watch.md new file mode 100644 index 00000000000..7f9a8a3c8eb --- /dev/null +++ b/quest/m0/3360-doc-observing-the-catalog-from-moq-watch.md @@ -0,0 +1,32 @@ +# [XS] doc: observing the catalog from moq-watch + +## Goal + +A `` user can find, in the published docs and the element's JSDoc, +how to observe the live catalog and how to read a custom catalog section from +it. + +## Plan + +Not a bug: `MoqWatch.broadcast` is assigned in the constructor. What moved in +0.4.0 (#2242, #2335) is the `Broadcast` class's signals into `in` and `out` +groups, so the catalog is `broadcast.out.catalog`, a read-only +`Signal`, observed with +`moqWatch.signals.run((effect) => effect.get(moqWatch.broadcast.out.catalog))`. +The element's `catalog` accessor peeks it (and sets the manual-mode input); +`observedAttributes` carries `catalog-format` (`hang`, `msf`, `hangz`, +`manual`) and no `catalog`. A custom section rides the loose catalog schema +and is read off the same root object. + +- `doc/`: the watch element page gains an "Observing the catalog" section with + the `signals.run` snippet and a custom-section example, and the hang concept + page's custom-tracks section links to it. +- JSDoc on `MoqWatch.broadcast`, `MoqWatch.catalog`, and + `Broadcast.out.catalog` says how to observe; the `.d.ts` is what consumers + read. +- No API change. A reactive accessor on the element is a separate decision if + the docs prove insufficient. + +## Closes + +- [#3360](https://github.com/moq-dev/moq/issues/3360) - close this issue when the quest finishes diff --git a/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md b/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md new file mode 100644 index 00000000000..9169937b948 --- /dev/null +++ b/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md @@ -0,0 +1,33 @@ +# [XS] js: every @moq package a package imports is a declared dependency + +## Goal + +No published `@moq/*` package imports another `@moq/*` package it does not +declare, and a check keeps it that way. `@moq/watch` on Firefox 140 ESR either +plays or fails with a mechanism named in #3361. + +## Plan + +`js/watch/src/broadcast.ts` imports `@moq/json` (`new +Json.Snapshot.Consumer(...)` in `#runCatalog`), but `js/watch/package.json` +does not declare it. `js/watch/vite.config.ts` externalizes every `@moq/*` +import, so the published bundle resolves it only through hoisting from +`@moq/hang`. A consumer whose resolver stubs it gets `Json.Snapshot` undefined +and exactly the reported `can't access property "Consumer", (void 0) is +undefined` inside an effect. The import predates 0.3.2, so it is not the +whole story: the only Firefox-relevant change between 0.3.2 and 0.5.2 is the +bowser user-agent gate (#2943, a new CJS runtime dependency in js/net), and +Firefox 140 takes the WebSocket path either way. + +- Declare `@moq/json` in js/watch with the workspace range, and audit the other + packages the same way. +- Add a check under `js/`, run by `just js check`, that every bare `@moq/*` + specifier under a package's `src/` appears in that package's dependencies + or peer dependencies. It fails on the current tree; fix what it finds. +- Reproduce on Firefox 140 ESR against `just relay` and `just pub bbb` with a + source map. If the undeclared dependency was the mechanism, close; otherwise + record the real stack in the issue and rescope. + +## Closes + +- [#3361](https://github.com/moq-dev/moq/issues/3361) - close this issue when the quest finishes diff --git a/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md b/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md new file mode 100644 index 00000000000..353be1b767b --- /dev/null +++ b/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md @@ -0,0 +1,50 @@ +# [S] js/watch: a broadcast republished under its name on one session keeps resuming + +## Goal + +A watcher of a broadcast that its publisher drops and republishes under the +same name on the same session re-consumes every generation, not just the +first. The reported shape is an `invisible` `` toggling `muted`: +with no media left the element unpublishes, and each unmute publishes again. + +## Plan + +Reported on `@moq/watch` 0.3.2 (#3363); nobody has retested 0.5.3, and three +fixes since target this path: #2617 (`announcedBroadcast`, lite restarts +resolved by publisher identity), #2976 (keep a republished broadcast when its +predecessor closes), #3368 (a refused duplicate namespace does not strand the +first). + +Mechanism on main: `js/publish/src/element.ts` derives `hasMedia` from the +audio and video sources, and `Microphone` stops its track when `muted`, so an +`invisible` publisher with `muted` set has no media and `#publishEnabled` goes +false; `js/publish/src/broadcast.ts` `Broadcast.#run` closes the +`Moq.Broadcast.Producer` (the broadcast is unannounced), and unmute creates a +fresh producer and calls `connection.publish(name, broadcast)` again. The +watcher's `js/watch/src/broadcast.ts` `#runBroadcast` delegates to +`conn.announcedBroadcast(name)`, and `js/net/src/announced.ts` keeps a live +handle across a redundant re-announce (`current.closed.peek() === undefined` +continues). If the retraction is coalesced away or lands late, the watcher +holds the dead generation and the wire resets its tracks: play, then close, +until a fresh session (a publisher reload) forces an unambiguous retraction. +dev's `#runBroadcast` builds on `Moq.Origin.Table` and `Announce.Broadcast` +instead, but the publisher chain and the audio source are the same. + +- Regression first: a js/net test that publishes, unpublishes, and republishes + one path on one session three times, and asserts the announced-broadcast + handle re-consumes each generation and the audio track yields frames after + each. Run it on main (0.5.3) and dev. +- If it fails, key the re-announce on a generation identity so an announce + that follows a retraction always swaps the handle. If it passes, keep the + test and close. +- Manual check per the issue: `just relay`, an `invisible muted` + `` toggling `muted`, a `` on the same name. + +## Closes + +- [#3363](https://github.com/moq-dev/moq/issues/3363) - close this issue when the quest finishes + +## Related + +- [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - the publisher side of a same-path replacement +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - sequences across replacements diff --git a/quest/m0/README.md b/quest/m0/README.md index 54cf3a74f66..bd659e57c17 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -17,7 +17,12 @@ regression test per Root Cause First. - [#2405](/quest/m0/2405-js-net-connect-logs-on-every-connection-at-the-wrong.md) - js/net: connect logs print the JWT in the relay URL - [Adapter namespace map](/quest/m0/rs-adapter-namespace-map.md) - moq-net: a duplicate PUBLISH_NAMESPACE on draft-14/15 strands the first request, and the map never shrinks +- [IETF error codes](/quest/m0/ietf-error-codes.md) - every code on a moq-transport wire is a registered value for the negotiated draft, requests and stream resets alike - [#3080](/quest/m0/3080-fix-watch-audio-ring-truncate-can-race-the-worklet-reader.md) - watch: an audio ring truncate can race the worklet reader for one quantum +- [#3363](/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md) - js/watch: a broadcast republished under its name on one session keeps resuming +- [#3361](/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md) - js: every @moq package a package imports is a declared dependency - [#2833](/quest/m0/2833-moq-export-ts-a-rewound-timeline-stalls-the-si-table.md) - moq export ts: a rewound timeline stalls SI tables, PCR, and pacing until the media clock catches up +- [#3326](/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md) - moq-audio: held resampler frames keep their source timestamp - [#2799](/quest/m0/2799-moq-video-capture-negotiates-twice-so-a-window-resize.md) - moq-transcode: the ladder follows a source resolution change instead of keeping the one it started with - [Group charge](/quest/m0/group-charge.md) - charge real per-group cost so MOQ_CACHE_CAPACITY bounds real memory +- [#3360](/quest/m0/3360-doc-observing-the-catalog-from-moq-watch.md) - doc: observing the catalog and custom sections from moq-watch diff --git a/quest/m0/ietf-error-codes.md b/quest/m0/ietf-error-codes.md new file mode 100644 index 00000000000..3627ffe2edd --- /dev/null +++ b/quest/m0/ietf-error-codes.md @@ -0,0 +1,70 @@ +# [M] IETF error codes come from the draft registry + +## Goal + +Every error code moq-net and js/net put on a moq-transport wire is a +registered value for the negotiated draft, in both directions: the +SUBSCRIBE_ERROR, FETCH_ERROR, and REQUEST_ERROR payloads, and the RESET_STREAM +and STOP_SENDING codes on data and request streams. A relay built on these +crates passes the interop runner's subscribe-error and subscribe-before-announce +cases without the peer's compatibility branch, and a routine cancellation is +read as CANCELLED rather than INTERNAL_ERROR. + +Boundaries: moq-lite's own code spaces are untouched, and js/net's inability to +carry a code on a locally raised stream error stays with +[JS stream codes](/quest/m1/js-net-stream-error-codes.md), which is about the +moq-lite space and the abstraction, not the registry. + +## Plan + +What the tree does today, identically on main and dev: + +- `rs/moq-net/src/ietf/publisher.rs` `run_subscribe` rejects with the literal + `404` at three sites and `run_fetch_stream` with `500`; + `rs/moq-net/src/ietf/subscriber.rs` `write_error` uses `400`. + `reject_subscribe`, `reject_fetch`, and `write_error` take a bare `u64`, and + `ietf::SubscribeError`, `ietf::FetchError`, and `ietf::RequestError` carry a + bare `error_code`. The only named IETF code type is `TrackStatusCode` + (`rs/moq-net/src/ietf/track.rs`), for a different registry, plus a + function-local `NOT_SUPPORTED: u64 = 0x3` in the subscriber. +- `js/net/src/ietf/publisher.ts` `runSubscribe` writes `errorCode: 404` on both + the draft-14 `SubscribeError` and the draft-15+ `RequestError` branch; + `js/net/src/ietf/subscriber.ts` uses `400` and `409`; `errorCode` is a plain + number everywhere. +- Stream resets on an IETF session send `Error::to_code()`, the moq-lite space + where `Cancel` is `0`; draft-19 section 3.3.4 assigns `0x0` to INTERNAL_ERROR + and `0x1` to CANCELLED. `Error::from_transport` maps only `0` back to + `Cancel`, so both directions have to move together. #2993 fixed one site + (`cancel_subscribe`, a named `STREAM_CANCELLED`). +- `Version::Draft14` through `Draft20` are all negotiated, straddling the + draft-19 consolidation into REQUEST_ERROR, so the values are per version. + +The work: + +- One named code type per registry (request errors, stream errors), with + `Encode` and `Decode` in the `TrackStatusCode` style, that + maps `Error` variants to the registered value for the negotiated draft and + back. An incoming code with no named value decodes to the remote/opaque + variant, never to a named one. Cite the draft section each value comes from + in the type's docs. +- Use it at every construction site above, in Rust and JS, and in + `Reader::abort` / `Writer::abort` on IETF sessions. Delete the literals and + the function-local constant. `Error::NotFound`'s IETF wire value comes from + the same mapping. +- Tests: encode/decode round-trips per version; a subscribe for a missing + broadcast rejects with the not-found value of each draft; a cancelled + subscription resets with CANCELLED and a moq-net peer reads it back as + `Cancel`; the two interop runner cases pass without their COMPAT branch. + +The reporter of #3359 offered a PR and asked whether to prefer a version-aware +enum over a flat one: version-aware, per the above. + +## Closes + +- [#3359](https://github.com/moq-dev/moq/issues/3359) - close this issue when the quest finishes +- [#3001](https://github.com/moq-dev/moq/issues/3001) - close this issue when the quest finishes + +## Related + +- [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - the moq-lite half for js/net +- [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - the same codes crossing the FFI diff --git a/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md b/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md deleted file mode 100644 index 2cab7ac4a66..00000000000 --- a/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] IETF stream resets send moq-lite error codes, so routine events read as INTERNAL_ERROR - -## Goal - -Implement and verify the behavior tracked in [#3001](https://github.com/moq-dev/moq/issues/3001) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -Split out of #2993, where the cancellation path was fixed narrowly and the general case deliberately was not. - -`Error::to_code()` encodes the moq-lite space, where `Cancel` is `0`. On the moq-transport wire, draft-19 section 3.3.4 assigns `0x0` to `INTERNAL_ERROR` and `0x1` to `CANCELLED`. Every IETF stream reset that goes through `Reader::abort`/`Writer::abort` therefore sends a code from the wrong registry. - -The most visible case is `ietf/session.rs`, where a failed `run_uni_group` does `reader.abort(&err)`. A group arriving for an alias the subscriber retired by its own cancellation is an expected late object, and it stops the stream with `0` -- the publisher reads a routine event as an internal failure on our side. - -\#2993 fixed exactly one site (`cancel_subscribe`, via a named `STREAM_CANCELLED` and a raw-code `Reader::stop`) because it could be shown safe there: the publisher treats its request stream reader closing as `Ok(())` and never inspects the code. - -The general fix is not a matter of passing `1` at each remaining site, which is why it was not folded in: - -- `Error::from_transport` maps only `0` back to `Cancel`. Changing outgoing codes without it makes two moq-net IETF peers disagree, so a routine cancellation surfaces as `Remote(1)` and can move an expected event into error paths. -- Both directions have to change together, and the mapping is shared with moq-lite, whose code space is unrelated. - -So this wants a per-protocol code mapping (outgoing and incoming) rather than a scattering of literals. The js/net counterpart is #2999: there the abstraction cannot express a code at all. - -## Closes - -- [#3001](https://github.com/moq-dev/moq/issues/3001) - close this issue when the quest finishes diff --git a/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md b/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md deleted file mode 100644 index 2a9606552b1..00000000000 --- a/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md +++ /dev/null @@ -1,76 +0,0 @@ -# [M] moq-net: outbound HOP_PATH construction is never validated - -## Goal - -A hop chain is validated where it is emitted, not only where it is parsed, so -moq-net cannot construct an advertisement that a conforming receiver must -close the session over. - -Every outbound path enforces the rule once: the entries exactly fill `Length`, -the list is non-empty, and no non-zero Hop ID appears twice. Publisher route -selection skips a route that cannot be legally advertised instead of emitting -it, and the moq-lite ingress cannot introduce a duplicate that later reaches an -IETF cluster peer. - -Boundaries: a route that is invalid to advertise may still be fine to serve -locally, so it is dropped from advertisement rather than from the origin. The -per-path ingress guards added by [#3042](https://github.com/moq-dev/moq/issues/3042) -stay working; this replaces the need for the next route source to remember the -rule again. - -## Plan - -Use the public issue's scope and implementation notes below as the starting -plan. Reconcile paths and assumptions with the current tree before -implementation. - -### Issue context - -`HopPath::validate` runs only on decode, so nothing stops us building and -sending an outbound HOP_PATH that a conforming receiver must reject. - -`ietf::cluster::HopPath::validate` rejects an empty list and a repeated -non-zero Hop ID, but it is only called from `param_decode`. `Advert::forward` -appends our own Hop ID and wraps the result without revalidating, and the -encode path does not check either. A `broadcast::Route` whose `hops` already -carry a duplicate therefore goes out as-is. - -That matters because `draft-lcurley-moq-cluster` requires the receiver to treat -it as fatal: "A receiver MUST close the session with a PROTOCOL_VIOLATION if -the entries do not exactly fill `Length`, if the list is empty, or if a -non-zero Hop ID appears twice." So a malformed chain we construct does not -degrade our own routing, it closes the downstream session. - -Routes reach the model from more than one place, and only the IETF decode path -is checked: - -- The moq-lite ingress builds hop chains itself. `OriginList` caps length but - does not reject duplicates, so a lite chain may legally carry one and, once - shared through the origin, be forwarded to an IETF cluster peer. -- `broadcast::Route` is public with a public `hops` field, so any in-process - producer can attach one. - -[#3042](https://github.com/moq-dev/moq/issues/3042) closed the two reachable -cases it introduced, both at ingress: `ietf::Subscriber::route` discards a chain -already carrying the identity assigned to the peer, and `lite::Subscriber`'s two -responder-append sites do the same. Those are per-path guards. The general gap -is that validity is enforced where a chain is parsed rather than where one is -emitted. - -### Design notes - -Validate in the outbound constructor (`Advert::forward`, or the encode path) and -have publisher route selection skip a route that cannot be legally advertised. -Making the invalid state unrepresentable is preferable to a check callers must -remember: a constructor that can only produce a valid chain means the next route -source gets the rule for free. - -Found by Codex during adversarial review of #3042. - -## Closes - -- [#3049](https://github.com/moq-dev/moq/issues/3049) - close this issue when the quest finishes - -## Related - -- [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - bans Hop ID 0 from chains outright, and builds on this diff --git a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md b/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md index 6d0358df51c..4f9a950be3c 100644 --- a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md +++ b/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md @@ -52,12 +52,9 @@ The section's honest summary today, `Declaring 0 therefore trades loop detection Every `== Origin::UNKNOWN` / `!= Origin::UNKNOWN` test that exists to ask "does this chain entry name anybody" is gone, across `lite/subscriber.rs`, `ietf/{subscriber,publisher,cluster}.rs`, and `model/{origin,broadcast}.rs`. The marker survives only where it means "this field is absent". Any survivor in the first category means 0 is still special somewhere and the change is incomplete. -Targets `dev`: it changes published `moq-net` API alongside -[#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md), and lands on top of it. - -## Required - -- [#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md) - validates hop chains where they are emitted; this quest lands on top of it +Targets `dev`: it changes published `moq-net` API. The outbound validation it +builds on landed in #3066, where `Hops::push` enforces the duplicate rule +wherever a chain is built. ## Closes diff --git a/quest/m1/README.md b/quest/m1/README.md index 55f9f481fc9..80f88b7bd38 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -29,6 +29,7 @@ with the current dev tree before starting. - [#2853](/quest/m1/2853-quiche-with-a-pinned-source-port-can-dial-only-a-broken.md) - quiche with a pinned source port can dial only a broken IPv4 address - [#2624](/quest/m1/2624-moq-native-goaway-redirect-guard-classifies-hosts-by-name.md) - moq-native: GOAWAY redirect guard classifies hosts by name, not by resolved address - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - Retention should reclaim idle open groups now that expiry is timestamp-only +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - a hole in the delivered group sequence is the discontinuity; no marker has to arrive - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - a track's timestamps never fall below its live edge; publishers declare a discontinuity and continue forward, consumers stop detecting rewinds - [Group overflow](/quest/m1/group-overflow-abort.md) - an oversized open group aborts for every reader instead of shedding its head - [#2895](/quest/m1/2895-add-an-atomic-readiness-gate-for-origin-broadcasts.md) - Add an atomic readiness gate for Origin broadcasts @@ -46,7 +47,6 @@ with the current dev tree before starting. - [Plan: binding rate control](/quest/m1/plan-binding-rate-control.md) - settle how a non-Rust publisher follows the send estimate before wiring five bindings - [#2709](/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md) - js/net mirrors the send-side bandwidth allocator so each publisher encodes against its own share - [#3000](/quest/m1/3000-track-teardown-on-poll-unused-is-not-atomic-against-a.md) - Track teardown on poll_unused is not atomic against a consumer reattaching -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - IETF stream resets send moq-lite error codes, so routine events read as INTERNAL_ERROR - [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - js/net: a locally raised group error reaches the wire as INTERNAL_ERROR - [#3002](/quest/m1/3002-no-test-drives-a-late-group-through-the-ietf-dispatch-loop.md) - No test drives a late group through the IETF dispatch loop - [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - Preserve structured protocol error codes across FFI and C bindings @@ -64,6 +64,6 @@ with the current dev tree before starting. - [#3208](/quest/m1/3208-make-2-5-ms-opus-frame-durations-work-across-bindings.md) - Make 2.5 ms Opus frame durations work across bindings - [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq: C ABI catch-up with the moq-ffi surface - [Plan: route cold cost](/quest/m1/plan-route-cold-cost.md) - settle how a route's cold cost crosses the bindings without being rewritten on the way back -- [#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md) - moq-net: validate a hop chain where it is emitted, not only where it is parsed - [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - moq-net: ban Hop ID 0 from hop chains - [#2248](/quest/m1/2248-moq-mux-rebase-fmp4-export-timestamps-for-late-subscribers.md) - moq-mux: rebase fMP4 export timestamps for late subscribers +- [Merge dev](/quest/m1/merge-dev.md) - dev lands on main with a closing keyword for every issue it fixed diff --git a/quest/m1/gap-discontinuity.md b/quest/m1/gap-discontinuity.md new file mode 100644 index 00000000000..29c8cd74a3d --- /dev/null +++ b/quest/m1/gap-discontinuity.md @@ -0,0 +1,70 @@ +# [M] A gap in the group sequence is a discontinuity + +## Goal + +A consumer resets codec state and its timeline whenever the group sequence it +delivers has a hole, whatever made it: the publisher skipped a sequence to +declare a break, the relay or the subscriber's budget shed a group, or a group +was lost. No signal that has to arrive carries the reset, because moq-lite is +lossy and any marker group can be shed before the container layer sees it. +An empty group stops meaning anything. + +## Plan + +Today `drafts/draft-lcurley-moq-hang.md` says an empty group declares a +discontinuity between codec epochs, and both container consumers key on it: +`rs/moq-mux/src/container/consumer.rs` waits for a zero-frame group's FIN in +`GroupBuffer::poll_empty` and bumps the counter in `mark_discontinuities` +(on the latency-skip path too); `js/hang/src/container/consumer.ts` does the +same through `Group.empty` and `#markDiscontinuity`. The one producer is +`rs/moq-mux/src/container/producer.rs` `Producer::discontinuity()`, which +appends and immediately finishes an empty group; its callers are the +h264, h265, and opus importers, `rs/moq-video`'s idle capture path +(`capture_stopped`), `rs/moq-audio`'s deferred `pending_discontinuity`, and +moq-boy. js/publish never emits one. On dev, `TrackState::is_stale` in +`rs/moq-net/src/model/track.rs` sheds a finished empty group under a zero +budget, since its reach is its successor's start, so a live-edge subscriber +never sees the marker and the reset is lost end to end (#3291). + +- Draft: replace the empty-group sentence with the gap rule. A publisher + declares a discontinuity by skipping at least one group sequence. A consumer + MUST reset codec state, reapplying startup delay and pre-skip, before + decoding the first group after any gap in the sequence it delivers, + declared or not. An empty group is permitted and carries no meaning. +- Consumers, both languages: `discontinuity()` bumps when the delivered + sequence advances by more than one, and the empty-group state machine + (`poll_empty`, `Group.empty`, the FIN wait) goes. The max-age skip path + already resets through the same counter. `rs/moq-audio`'s undeclared-hole + handling from #3386 (`gap()`) becomes the declared path as well. +- Cost to check: a video decoder reset on every shed group. Measure a + WebCodecs reset plus configure, and a VideoToolbox or openh264 reset, on the + keyframe that follows a skip. If it is material, make the container-level + reset a timeline reset and let the decoder decide whether the keyframe needs + a flush. +- Gap gate: the mux consumer cannot tell a skipped sequence from a late group + (#3258, `max_ts - next_start >= max_age`), so a declared skip resumes only + when the gate trips or the timestamp jump already exceeds the budget. Decide + by measurement whether `Producer::discontinuity()` keeps writing an empty + group purely as a walk-now hint, harmless when shed, or stops; record the + resume latency either way. +- Producers: `Producer::discontinuity()` skips a sequence, and every caller + above follows; the importers re-estimate as today. +- Tests: the transport-level regression for #3291 (a zero-budget subscriber, + an idle publisher, a resume: the reset happens); the mux tests + `empty_group_declares_a_discontinuity`, + `latency_skip_preserves_empty_group_discontinuity`, and + `empty_group_advances`, with their js equivalents, rewritten for the gap + rule; a shed group resets; an empty group does nothing. + +Branch from dev, where `is_stale` and the current consumers live. + +## Closes + +- [#3291](https://github.com/moq-dev/moq/issues/3291) - close this issue when the quest finishes + +## Related + +- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - requires this: a declared discontinuity is what a forward-only timeline continues from +- [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - the watch decoder reset that fires on the counter +- [Duration marker](/quest/m2/duration-marker.md) - the empty frame that closes a group's last frame, a different signal +- [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - the retention half of timestamp-only expiry diff --git a/quest/m1/group-overflow-abort.md b/quest/m1/group-overflow-abort.md index 368a4234909..1b4b7fbacac 100644 --- a/quest/m1/group-overflow-abort.md +++ b/quest/m1/group-overflow-abort.md @@ -56,7 +56,7 @@ evicted prefix. still holds. - **The IETF wire keeps its own mapping.** Sending the new code on the moq-transport wire belongs to - [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md), + [IETF error codes](/quest/m0/ietf-error-codes.md), which is fixing the whole registry confusion rather than one variant. ### What actually gets deleted @@ -128,4 +128,4 @@ already claims its top end "intentionally reaches the raised - [Group charge](/quest/m0/group-charge.md) - pool-level budget accounting, unaffected by this change - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - also turns "open group hit a limit" into an abort, so the two must not collide on the error variant - [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - without it a JS publisher sends this new code to the wire as Internal -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - the moq-transport half of the code mapping +- [IETF error codes](/quest/m0/ietf-error-codes.md) - the moq-transport half of the code mapping diff --git a/quest/m1/js-net-stream-error-codes.md b/quest/m1/js-net-stream-error-codes.md index e55c63a1438..f781fb17a8a 100644 --- a/quest/m1/js-net-stream-error-codes.md +++ b/quest/m1/js-net-stream-error-codes.md @@ -42,7 +42,7 @@ disagree about what a code means. Scope is the moq-lite code space, matching what Rust sends today. The moq-transport registry is a separate confusion tracked by -[#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md), +[IETF error codes](/quest/m0/ietf-error-codes.md), which is fixing both directions there; do not fold the two together. Land it with a test that a JS publisher's reset arrives at a peer as the right @@ -55,5 +55,5 @@ code, and drop the `js/json` workaround once the class check is redundant. ## Related - [Group overflow](/quest/m1/group-overflow-abort.md) - adds a new stream code that a JS publisher cannot currently send -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - the moq-transport half +- [IETF error codes](/quest/m0/ietf-error-codes.md) - the moq-transport half - [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - the same structured-code loss across FFI and C diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md new file mode 100644 index 00000000000..6eb681739c1 --- /dev/null +++ b/quest/m1/merge-dev.md @@ -0,0 +1,58 @@ +# [L] Merge dev into main + +## Goal + +`main` carries everything on `dev`: the thread-per-core runtime, the net model +and allocator work, the announce handle and its bindings, the archive line, and +every fix that only dev has. The merge PR closes each issue dev fixed with a +closing keyword, and the release that follows is the one moq.pro adopts. + +## Plan + +As of 2026-09-05 dev is 243 commits ahead of main and main 16 ahead of dev. +Merge main into dev first and resolve there, then open the merge PR from dev +with the list below as closing keywords. Run `just check-all`, `just test all`, +`just test smoke-full`, and `just bench origin/main` on the merged tree. The +breaking-change targeting rules in CONTRIBUTING.md govern the release that +follows, and [Dart announce](/quest/m1/dart-announce.md) unblocks when this +lands. + +## Required + +- [Archive](/quest/m1/archive/README.md) - moq.pro needs archive-backed recording on the release dev produces +- [Announce handle](/quest/m1/announce-handle.md) - the origin surface the merge ships +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding on that surface +- [JS announce](/quest/m1/js-announce.md) - js/net on that surface +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - so the lost-reset regression does not ship + +## Closes + +- [#3173](https://github.com/moq-dev/moq/issues/3173) - moq-uring: worker drop cancels staged receives (8acbeb306) +- [#3107](https://github.com/moq-dev/moq/issues/3107) - moq-relay: the io_uring listener serves its certificate fingerprint (#3116) +- [#3112](https://github.com/moq-dev/moq/issues/3112) - moq-relay: the io_uring listener authenticates mTLS peers (#3116) +- [#3160](https://github.com/moq-dev/moq/issues/3160) - moq-tokio: a rustls backend without a crypto provider is a compile error (#3210) +- [#3119](https://github.com/moq-dev/moq/issues/3119) - moq-uring: UDP pools grow when a socket starves (#3133) +- [#3111](https://github.com/moq-dev/moq/issues/3111) - moq-uring: an unmappable HTTP/3 code lands in `Error::Http3` (#3110) +- [#2627](https://github.com/moq-dev/moq/issues/2627) - js: a detached element's connection lingers for a real window (#2705) +- [#2628](https://github.com/moq-dev/moq/issues/2628) - js: one connection per relay URL (#2705) +- [#2532](https://github.com/moq-dev/moq/issues/2532) - js/publish: files are demuxed and decoded, not captured (#2541) +- [#2609](https://github.com/moq-dev/moq/issues/2609) - moq-ffi: sessions reconnect automatically (#2618) +- [#2807](https://github.com/moq-dev/moq/issues/2807) - js/net: a group pop and its frame-range snapshot are one step (#2820) +- [#2808](https://github.com/moq-dev/moq/issues/2808) - js/net: the bounds snapshot is atomic with the pop (#2820) +- [#2892](https://github.com/moq-dev/moq/issues/2892) - js/net: the subscriber latency budget is enforced (#2926) +- [#2517](https://github.com/moq-dev/moq/issues/2517) - net: subscriptions resume across routes sharing a first hop (#3312) +- [#2934](https://github.com/moq-dev/moq/issues/2934) - moq export ts: SI is emitted when the snapshot changes, repeats are floored (#2971) +- [#3049](https://github.com/moq-dev/moq/issues/3049) - moq-net: `Hops::push` enforces the loop-free chain wherever one is built (#3066) +- [#1238](https://github.com/moq-dev/moq/issues/1238) - js: standalone components default to enabled (#2872) +- [#3260](https://github.com/moq-dev/moq/issues/3260) - stream consumers detect a rolled log without waiting for the group to end (#3282) +- [#3174](https://github.com/moq-dev/moq/issues/3174) - js/publish: the gain target is set before the first frame (#2541) +- [#3171](https://github.com/moq-dev/moq/issues/3171) - js/publish: fanout queue limits are validated (7bb180fdc) +- [#3172](https://github.com/moq-dev/moq/issues/3172) - js/net: Reload stops after a terminal failure (#3177) +- [#2401](https://github.com/moq-dev/moq/issues/2401) - the route linger is gone; overlapping routes resume instead (#2704, #3312) +- [#2217](https://github.com/moq-dev/moq/issues/2217) - moq-ffi: the announce handle carries the lifecycle (announce-handle, #3190) +- [#980](https://github.com/moq-dev/moq/issues/980) - dual-stack binding on main; happy eyeballs in `moq-tokio::resolve` (#2749) +- [#2153](https://github.com/moq-dev/moq/issues/2153) - go: the wrapper caught up on main; hops landed on dev (#2168) + +## Related + +- [Dart announce](/quest/m1/dart-announce.md) - waits on this merge, so it cannot be required here diff --git a/quest/m1/monotonic-timeline.md b/quest/m1/monotonic-timeline.md index fcce20b0292..3596acd003d 100644 --- a/quest/m1/monotonic-timeline.md +++ b/quest/m1/monotonic-timeline.md @@ -4,8 +4,8 @@ A track's timestamps never fall below the live edge its earlier groups reached. A publisher that has to reset (a flush, a seek, a source restart) -declares an empty-group discontinuity and continues forward from where it -was; it can no longer rewind. Inside a group timestamps still reorder freely, +declares a discontinuity by leaving a gap in the group sequence and +continues forward from where it was; it can no longer rewind. Inside a group timestamps still reorder freely, since B-frames present before the frames that precede them in decode order, and open-GOP leading pictures still qualify because they sit above the previous group's reach. @@ -19,9 +19,10 @@ Today both container consumers (`Rewind` in `rs/moq-mux/src/container/consumer.rs` and in `js/hang/src/container/consumer.ts`) classify a newer group whose timestamps land before the live edge as a rewind, drop the reneged buffer, and bump the -same counter a declared discontinuity bumps. The hang draft says an empty -group declares a discontinuity "whether the resumed timestamps move backward -or forward". That machinery is what goes. +same counter a declared discontinuity bumps. The hang draft says a declared +discontinuity applies "whether the resumed timestamps move backward or +forward". That machinery is what goes; how a publisher declares one is +[Gap discontinuity](/quest/m1/gap-discontinuity.md). - **Publisher side, in both container producers.** The track producer refuses a frame whose timestamp is below the live edge established by the groups @@ -61,10 +62,12 @@ state. ## Required +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - settles how a publisher declares the discontinuity this rule continues from - [moq#3375](https://github.com/moq-dev/moq/pull/3375) has merged, so the TS export reset it adds is keyed on the discontinuity counter before this quest trims it ## Related +- [Duration marker](/quest/m2/duration-marker.md) - the empty frame that closes a group, which is not a discontinuity - [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - the watch decoder reset that keeps mattering for declared discontinuities - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink's generation model after EOS, the same publisher - [#2833](/quest/m0/2833-moq-export-ts-a-rewound-timeline-stalls-the-si-table.md) - the TS export fix this trims once it lands diff --git a/quest/m2/README.md b/quest/m2/README.md index 1a266389d04..82785b8ba28 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -35,6 +35,7 @@ can act on. Each still carries its own plan and regression test. - [SEI](/quest/m2/sei/README.md) - H.26x SEI moves into its own track, readable without subscribing to video - [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution with scoped access - [Timeline wall](/quest/m2/timeline-wall.md) - every built-in publisher anchors its timeline to wall time; the anchor is data, never a sync source +- [Duration marker](/quest/m2/duration-marker.md) - a video group ends with an empty frame that closes its last frame's duration; audio never writes one - [#2278](/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: a timeline consumer exposes the wall anchor, and the library never syncs playback on it - [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues ride a per-rendition sidecar a player can act on - [Caption import](/quest/m2/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped diff --git a/quest/m2/duration-marker.md b/quest/m2/duration-marker.md new file mode 100644 index 00000000000..3e657fbf1f5 --- /dev/null +++ b/quest/m2/duration-marker.md @@ -0,0 +1,56 @@ +# [M] Empty frames close the previous frame's duration + +## Goal + +In the legacy (hang) and LOC containers, every video group ends with an empty +frame stamped at the exclusive end of its last frame, so a group's last frame +has a duration without peeking at the next group. Audio writes no empty +frames: its durations are codec-defined, and the end-of-track marker and its +terminal-packet rule go. CMAF is untouched, since it carries sample durations. +An empty frame is never submitted to a decoder and never means the track +ended. + +## Plan + +Today only `rs/moq-audio`'s `publish_terminal` writes an empty frame, as the +first frame of a final group followed by the encoder's flush packets, and the +draft's legacy section defines it as the end marker: consumers discard decoded +samples at or after it (the decode consumer's terminal phase in +`rs/moq-audio/src/decode/consumer.rs`, `js/watch/src/audio/terminal.ts`). +`rs/moq-mux/src/container/consumer.rs` latches `end` sticky from any empty +payload and `js/hang/src/container/consumer.ts` returns it positionally. The +last frame of every group is otherwise timed by a guess: +`rs/moq-mux/src/container/fmp4/fragmenter.rs` times a group's trailing frame +by the catalog cadence because a group boundary is never a duration, +`rs/moq-hls`'s rendition export accumulates whole segments to see each frame's +successor, and the timeline recorder's `end(pts)` gets a bound only when a +caller passes `cut(Some(end))`. + +- Draft: the legacy and LOC sections say an empty frame is the exclusive end + of the frame before it, a video group ends with one, audio has none, and a + consumer skips it. Remove the end-marker and terminal-packet paragraph. +- Producers: the `rs/moq-mux` container `Producer` writes the marker at `cut` + and `finish` for video tracks, at the caller's bound or the last timestamp + plus its estimated duration; the js/hang container producer does the same; + `publish_terminal` stops writing it and its flush packets become ordinary + frames, so a few ms of encoder padding play at the end unless the consumer + trims by the codec delay. +- Consumers: the mux consumer records a per-group boundary that feeds + `max_end`, the last frame's `duration`, and the timeline recorder, instead + of a sticky `end`; the audio terminal phase goes; js/hang and js/watch + follow. The fragmenter and the HLS export use the boundary for the trailing + sample. +- Compatibility: released video consumers already skip empty frames, since + only the audio decoder reads `end()`, so a new publisher is safe against an + old player, and a new consumer still skips an audio marker from an old + publisher. This lands on main. +- Tests: a group's last frame carries the marker's duration through fmp4 + export and HLS; an audio track end has no marker and plays out; an old-style + audio marker is skipped; CMAF is unchanged. + +## Related + +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - the reset signal, which this marker is not +- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - the forward-only rule the boundary sits under +- [Timeline](/quest/m1/archive/timeline.md) - the archive index that wants honest final durations +- [#3326](/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md) - covers the terminal phase this quest removes diff --git a/quest/m2/quic/noq-parity.md b/quest/m2/quic/noq-parity.md index 153b9bd7d89..79ef2fe4792 100644 --- a/quest/m2/quic/noq-parity.md +++ b/quest/m2/quic/noq-parity.md @@ -40,3 +40,7 @@ backend docs and feature matrix in the same PR. parity cannot be claimed without it - [Release the fork stack](/quest/m2/quic/release.md) - the relay must pin released noq sources before quiche goes + +## Closes + +- [#3124](https://github.com/moq-dev/moq/issues/3124) - the parity report is the matched runtime-versus-QUIC-stack measurement the issue asked for From 60c5530ed876016b6ed3b3b60cc776132d71ba52 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 4 Sep 2026 21:58:00 -0700 Subject: [PATCH 2/4] docs(quest): apply the review findings on the issue import The gap rule resets only when the boundary cannot prove continuity, so legal non-sequential group ids keep playing; the IETF error-code quest covers the draft-14 publish-error path; the noq parity report runs noq on both runtimes as the matched control #3124 asked for. Co-Authored-By: Claude Fable 5.1 --- quest/m0/ietf-error-codes.md | 6 +++++- quest/m1/README.md | 2 +- quest/m1/gap-discontinuity.md | 36 ++++++++++++++++++++++++----------- quest/m2/quic/noq-parity.md | 9 ++++++--- 4 files changed, 37 insertions(+), 16 deletions(-) diff --git a/quest/m0/ietf-error-codes.md b/quest/m0/ietf-error-codes.md index 3627ffe2edd..f90385afa66 100644 --- a/quest/m0/ietf-error-codes.md +++ b/quest/m0/ietf-error-codes.md @@ -31,6 +31,9 @@ What the tree does today, identically on main and dev: the draft-14 `SubscribeError` and the draft-15+ `RequestError` branch; `js/net/src/ietf/subscriber.ts` uses `400` and `409`; `errorCode` is a plain number everywhere. +- `js/net/src/ietf/subscriber.ts` `runPublish` writes a draft-14 `PublishError` + with the function-local `NOT_SUPPORTED` and a `RequestError` on later + drafts; the Rust subscriber's publish handling is the same shape. - Stream resets on an IETF session send `Error::to_code()`, the moq-lite space where `Cancel` is `0`; draft-19 section 3.3.4 assigns `0x0` to INTERNAL_ERROR and `0x1` to CANCELLED. `Error::from_transport` maps only `0` back to @@ -51,7 +54,8 @@ The work: `Reader::abort` / `Writer::abort` on IETF sessions. Delete the literals and the function-local constant. `Error::NotFound`'s IETF wire value comes from the same mapping. -- Tests: encode/decode round-trips per version; a subscribe for a missing +- Tests: encode/decode round-trips per version; a draft-14 PublishError and a + draft-15+ RequestError round-trip for the publish path; a subscribe for a missing broadcast rejects with the not-found value of each draft; a cancelled subscription resets with CANCELLED and a moq-net peer reads it back as `Cancel`; the two interop runner cases pass without their COMPAT branch. diff --git a/quest/m1/README.md b/quest/m1/README.md index 3670ccbc5b9..478c6d98638 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -29,7 +29,7 @@ with the current dev tree before starting. - [#2853](/quest/m1/2853-quiche-with-a-pinned-source-port-can-dial-only-a-broken.md) - quiche with a pinned source port can dial only a broken IPv4 address - [#2624](/quest/m1/2624-moq-native-goaway-redirect-guard-classifies-hosts-by-name.md) - moq-native: GOAWAY redirect guard classifies hosts by name, not by resolved address - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - Retention should reclaim idle open groups now that expiry is timestamp-only -- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - a hole in the delivered group sequence is the discontinuity; no marker has to arrive +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - a hole in the delivered group sequence is the discontinuity unless the boundary proves continuity; no marker has to arrive - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - a track's timestamps never fall below its live edge; publishers declare a discontinuity and continue forward, consumers stop detecting rewinds - [Group overflow](/quest/m1/group-overflow-abort.md) - an oversized open group aborts for every reader instead of shedding its head - [#2895](/quest/m1/2895-add-an-atomic-readiness-gate-for-origin-broadcasts.md) - Add an atomic readiness gate for Origin broadcasts diff --git a/quest/m1/gap-discontinuity.md b/quest/m1/gap-discontinuity.md index 29c8cd74a3d..dafcc108f58 100644 --- a/quest/m1/gap-discontinuity.md +++ b/quest/m1/gap-discontinuity.md @@ -1,13 +1,16 @@ -# [M] A gap in the group sequence is a discontinuity +# [M] A gap in the group sequence is a discontinuity unless the boundary proves continuity ## Goal A consumer resets codec state and its timeline whenever the group sequence it -delivers has a hole, whatever made it: the publisher skipped a sequence to -declare a break, the relay or the subscriber's budget shed a group, or a group -was lost. No signal that has to arrive carries the reset, because moq-lite is -lossy and any marker group can be shed before the container layer sees it. -An empty group stops meaning anything. +delivers has a hole it cannot prove harmless, whatever made it: the publisher +skipped a sequence to declare a break, the relay or the subscriber's budget +shed a group, or a group was lost. A hole is harmless only when the previous +group's end equals the next group's first timestamp, which keeps the legal +non-sequential numbering (DTS-derived ids, the HLS importer's packed epoch +bits) playing through. No signal that has to arrive carries the reset, +because moq-lite is lossy and any marker group can be shed before the +container layer sees it. An empty group stops meaning anything. ## Plan @@ -29,10 +32,16 @@ never sees the marker and the reset is lost end to end (#3291). - Draft: replace the empty-group sentence with the gap rule. A publisher declares a discontinuity by skipping at least one group sequence. A consumer MUST reset codec state, reapplying startup delay and pre-skip, before - decoding the first group after any gap in the sequence it delivers, - declared or not. An empty group is permitted and carries no meaning. + decoding the first group after a gap in the sequence it delivers, declared + or not, unless the previous group's end equals the next group's first + timestamp. Video knows its end from the + [duration marker](/quest/m2/duration-marker.md); audio from its + codec-defined frame durations. An empty group is permitted and carries no + meaning. Group sequences stay free to be non-sequential. - Consumers, both languages: `discontinuity()` bumps when the delivered - sequence advances by more than one, and the empty-group state machine + sequence advances by more than one and the boundary is not contiguous + (`ptsContiguous` in the js consumer is the shape, now exact rather than + upper-bound), and the empty-group state machine (`poll_empty`, `Group.empty`, the FIN wait) goes. The max-age skip path already resets through the same counter. `rs/moq-audio`'s undeclared-hole handling from #3386 (`gap()`) becomes the declared path as well. @@ -54,10 +63,16 @@ never sees the marker and the reset is lost end to end (#3291). `empty_group_declares_a_discontinuity`, `latency_skip_preserves_empty_group_discontinuity`, and `empty_group_advances`, with their js equivalents, rewritten for the gap - rule; a shed group resets; an empty group does nothing. + rule; a shed group resets; an empty group does nothing; a non-sequential id + jump with a contiguous boundary (`consumer.nonsequential.test.ts`) does not + reset. Branch from dev, where `is_stale` and the current consumers live. +## Required + +- [Duration marker](/quest/m2/duration-marker.md) - a video group has to know its own end before a boundary can prove continuity + ## Closes - [#3291](https://github.com/moq-dev/moq/issues/3291) - close this issue when the quest finishes @@ -66,5 +81,4 @@ Branch from dev, where `is_stale` and the current consumers live. - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - requires this: a declared discontinuity is what a forward-only timeline continues from - [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - the watch decoder reset that fires on the counter -- [Duration marker](/quest/m2/duration-marker.md) - the empty frame that closes a group's last frame, a different signal - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - the retention half of timestamp-only expiry diff --git a/quest/m2/quic/noq-parity.md b/quest/m2/quic/noq-parity.md index 79ef2fe4792..c594998ac73 100644 --- a/quest/m2/quic/noq-parity.md +++ b/quest/m2/quic/noq-parity.md @@ -16,9 +16,12 @@ Quinn and quiche backends, and the merge recorded matched throughput with a lower RSS. What remains is the gate that lets quiche go. Benchmark chat, media 1:1, media fanout, handshake churn, and idle-connection -memory on `moq-uring` with noq against quiche, on the same worker and crypto -configuration, with `just bench`. Adoption requires no material latency, -capacity, or RSS regression and a written explanation of any CPU tradeoff. +memory with `just bench`, on the same worker and crypto configuration, across +four cells: noq and quiche on `moq-uring`, and noq and quinn on the tokio +workers. noq on both runtimes is the matched control #3124 asked for, since +quiche cannot serve per-core tokio workers; the report states which QUIC +stack each runtime mode ran, so runtime and stack are never confounded again. +Adoption requires no material latency, capacity, or RSS regression and a written explanation of any CPU tradeoff. Run the browser and interop gates on the noq path: `just test wasm`, the TypeScript interop cases, `just test smoke-full`, and connection draining From d34a48246f86c091ff8554a151117601e2219a66 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 4 Sep 2026 22:13:11 -0700 Subject: [PATCH 3/4] docs(quest): gate the LOC duration marker on released consumers, and state why a contiguous boundary needs no reset Co-Authored-By: Claude Fable 5.1 --- quest/m1/gap-discontinuity.md | 5 +++++ quest/m2/README.md | 1 + quest/m2/duration-marker.md | 13 +++++++++---- quest/m2/loc-duration-marker.md | 20 ++++++++++++++++++++ 4 files changed, 35 insertions(+), 4 deletions(-) create mode 100644 quest/m2/loc-duration-marker.md diff --git a/quest/m1/gap-discontinuity.md b/quest/m1/gap-discontinuity.md index dafcc108f58..16656605ca1 100644 --- a/quest/m1/gap-discontinuity.md +++ b/quest/m1/gap-discontinuity.md @@ -38,6 +38,11 @@ never sees the marker and the reset is lost end to end (#3291). [duration marker](/quest/m2/duration-marker.md); audio from its codec-defined frame durations. An empty group is permitted and carries no meaning. Group sequences stay free to be non-sequential. + A contiguous boundary is what every ordinary group boundary already is: + the keyframe that opens the next group resets prediction state and carries + its parameter sets, and a codec config change rides the catalog, so an + encoder replacement on a continuous clock needs nothing more. A publisher + that wants the consumer to re-apply startup delay presents a hole. - Consumers, both languages: `discontinuity()` bumps when the delivered sequence advances by more than one and the boundary is not contiguous (`ptsContiguous` in the js consumer is the shape, now exact rather than diff --git a/quest/m2/README.md b/quest/m2/README.md index 82785b8ba28..22bcbc52989 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -36,6 +36,7 @@ can act on. Each still carries its own plan and regression test. - [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution with scoped access - [Timeline wall](/quest/m2/timeline-wall.md) - every built-in publisher anchors its timeline to wall time; the anchor is data, never a sync source - [Duration marker](/quest/m2/duration-marker.md) - a video group ends with an empty frame that closes its last frame's duration; audio never writes one +- [LOC duration marker](/quest/m2/loc-duration-marker.md) - LOC producers write the marker once released consumers skip it - [#2278](/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: a timeline consumer exposes the wall anchor, and the library never syncs playback on it - [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues ride a per-rendition sidecar a player can act on - [Caption import](/quest/m2/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped diff --git a/quest/m2/duration-marker.md b/quest/m2/duration-marker.md index 3e657fbf1f5..363eaf2a4cb 100644 --- a/quest/m2/duration-marker.md +++ b/quest/m2/duration-marker.md @@ -40,10 +40,14 @@ caller passes `cut(Some(end))`. of a sticky `end`; the audio terminal phase goes; js/hang and js/watch follow. The fragmenter and the HLS export use the boundary for the trailing sample. -- Compatibility: released video consumers already skip empty frames, since - only the audio decoder reads `end()`, so a new publisher is safe against an - old player, and a new consumer still skips an audio marker from an old - publisher. This lands on main. +- Compatibility: released legacy video consumers already skip empty frames, + since only the audio decoder reads `end()`, so a legacy publisher is safe + against an old player, and a new consumer still skips an audio marker from + an old publisher. Released LOC consumers (`rs/moq-mux/src/container/loc`, + `js/loc`) submit an empty payload to the decoder, so this quest lands the + LOC consumer-side skip only; LOC producers start writing the marker in + [LOC duration marker](/quest/m2/loc-duration-marker.md) once skipping + consumers have shipped. This lands on main. - Tests: a group's last frame carries the marker's duration through fmp4 export and HLS; an audio track end has no marker and plays out; an old-style audio marker is skipped; CMAF is unchanged. @@ -54,3 +58,4 @@ caller passes `cut(Some(end))`. - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - the forward-only rule the boundary sits under - [Timeline](/quest/m1/archive/timeline.md) - the archive index that wants honest final durations - [#3326](/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md) - covers the terminal phase this quest removes +- [LOC duration marker](/quest/m2/loc-duration-marker.md) - the LOC producer half, gated on a release diff --git a/quest/m2/loc-duration-marker.md b/quest/m2/loc-duration-marker.md new file mode 100644 index 00000000000..df9b7c7603d --- /dev/null +++ b/quest/m2/loc-duration-marker.md @@ -0,0 +1,20 @@ +# [XS] LOC producers write the duration marker + +## Goal + +LOC video groups end with the empty frame that closes their last frame's +duration, the same contract the legacy container carries, once every released +LOC consumer skips it. + +## Plan + +[Duration marker](/quest/m2/duration-marker.md) lands the consumer-side skip +in `rs/moq-mux/src/container/loc` and `js/loc` but leaves LOC producers alone, +because a released LOC consumer submits an empty payload to the decoder. When +the bullet below clears, have the LOC producers write the marker at `cut` and +`finish` exactly as the legacy producer does, and extend the same tests. + +## Required + +- [Duration marker](/quest/m2/duration-marker.md) - the consumer-side skip and the contract +- A release of `moq-mux` and `@moq/loc` whose consumers skip an empty LOC payload has shipped From f8580e7aff14504856a4fe5a4a6e8d75e300a48a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 4 Sep 2026 22:24:27 -0700 Subject: [PATCH 4/4] docs(quest): keep the rounding tolerance at contiguous boundaries, and narrow the marker goal to what ships Co-Authored-By: Claude Fable 5.1 --- quest/m1/gap-discontinuity.md | 9 ++++++--- quest/m2/duration-marker.md | 7 ++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/quest/m1/gap-discontinuity.md b/quest/m1/gap-discontinuity.md index 16656605ca1..101fd4e364a 100644 --- a/quest/m1/gap-discontinuity.md +++ b/quest/m1/gap-discontinuity.md @@ -6,7 +6,8 @@ A consumer resets codec state and its timeline whenever the group sequence it delivers has a hole it cannot prove harmless, whatever made it: the publisher skipped a sequence to declare a break, the relay or the subscriber's budget shed a group, or a group was lost. A hole is harmless only when the previous -group's end equals the next group's first timestamp, which keeps the legal +group's end meets the next group's first timestamp within the rounding +tolerance the js consumer already uses (`CONTIGUITY_TOLERANCE`), which keeps the legal non-sequential numbering (DTS-derived ids, the HLS importer's packed epoch bits) playing through. No signal that has to arrive carries the reset, because moq-lite is lossy and any marker group can be shed before the @@ -33,8 +34,10 @@ never sees the marker and the reset is lost end to end (#3291). declares a discontinuity by skipping at least one group sequence. A consumer MUST reset codec state, reapplying startup delay and pre-skip, before decoding the first group after a gap in the sequence it delivers, declared - or not, unless the previous group's end equals the next group's first - timestamp. Video knows its end from the + or not, unless the previous group's end meets the next group's first + timestamp within a rounding tolerance of about a microsecond, since a + 1024-sample AAC frame has no integer microsecond duration and independently + rounded stamps differ by one. Video knows its end from the [duration marker](/quest/m2/duration-marker.md); audio from its codec-defined frame durations. An empty group is permitted and carries no meaning. Group sequences stay free to be non-sequential. diff --git a/quest/m2/duration-marker.md b/quest/m2/duration-marker.md index 363eaf2a4cb..69b7efe79e6 100644 --- a/quest/m2/duration-marker.md +++ b/quest/m2/duration-marker.md @@ -2,9 +2,10 @@ ## Goal -In the legacy (hang) and LOC containers, every video group ends with an empty -frame stamped at the exclusive end of its last frame, so a group's last frame -has a duration without peeking at the next group. Audio writes no empty +In the legacy (hang) container every video group ends with an empty frame +stamped at the exclusive end of its last frame, so a group's last frame has a +duration without peeking at the next group, and the LOC consumers are ready +to skip the same marker before LOC producers start writing it. Audio writes no empty frames: its durations are codec-defined, and the end-of-track marker and its terminal-packet rule go. CMAF is untouched, since it carries sample durations. An empty frame is never submitted to a decoder and never means the track