diff --git a/quest/README.md b/quest/README.md index e8dd7936072..884c9a529a0 100644 --- a/quest/README.md +++ b/quest/README.md @@ -7,12 +7,12 @@ grouped into milestones ordered by priority. ## Plan -m0 is everything in flight now: relay hardening and IETF interop ahead of -Seattle, wildcard routing, broadcast epochs, and audio playout (jitter target +m0 is everything in flight now: relay hardening and the last known IETF +interop fix ahead of Seattle, wildcard routing, broadcast epochs, and audio playout (jitter target and quality harness). 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. m4 waits on an upstream release. +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. 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 @@ -21,8 +21,8 @@ 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 IETF interop for Seattle, wildcard routing, broadcast epochs, and audio playout +- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and the last known IETF interop fix for Seattle, wildcard routing, broadcast epochs, and audio playout - [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 +- [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 diff --git a/quest/m0/README.md b/quest/m0/README.md index b61c2e6564a..050683a4e08 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -20,10 +20,12 @@ 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 branch flip ranks first: it is a short cutover that every later PR -targets. Relay hardening: IETF interop leads the rest, since only those -quests block Seattle. IETF stream types came from m1 in the 2026-09-30 audit -because a session ended by legal input is exactly what Seattle would hit. The DoS hardening +The branch flip is done except its #4605 backport to `release`; the +Cloudflare switch waits on the maintainer as a condition quest. Relay +hardening: [REQUEST_OK accepts LARGEST_OBJECT](/quest/m0/ietf-largest-object.md) +leads the rest, since it is the one known case left of legal moq-transport +input closing a session, which Seattle would hit. The 2026-10-05 audit split +it from the m2 validator findings, which block nothing. 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. @@ -48,6 +50,8 @@ a published `@moq/watch` break. ## Required - [Branch flip](/quest/m0/branch-flip.md) - `dev` becomes the default `main` trunk and today's `main` becomes `release`, where publishing runs +- [Cloudflare builds track release](/quest/m0/cloudflare-release.md) - condition: the maintainer points the docs and demo builds at `release` +- [REQUEST_OK accepts LARGEST_OBJECT](/quest/m0/ietf-largest-object.md) - a conformant moq-transport peer's REQUEST_OK no longer closes the session, ahead of Seattle - [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - iroh's upstream noq carries quinn's stream reassembly cap, once n0 releases it - [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines diff --git a/quest/m0/branch-flip.md b/quest/m0/branch-flip.md index df9061dcebb..0d845d32a38 100644 --- a/quest/m0/branch-flip.md +++ b/quest/m0/branch-flip.md @@ -1,4 +1,4 @@ -# [S] Trunk is main, releases ship from release +# [XS] Trunk is main, releases ship from release ## Goal @@ -89,14 +89,19 @@ its ruleset has no linear history, the `release` ruleset exists, and the `dev` ruleset is gone. The first back-merge ran during the rename window and 404ed; its re-run opened #4742. +Done (verified in the 2026-10-05 audit): #4742 landed on `main` as a merge +commit, release-plz #4596 ran on `release`, and the back-merges #4762, #4797, +and #4831 landed on `main`. + Remaining: -- The maintainer points the Cloudflare docs (`moq-doc`) and demo builds' - production branch at `release`. -- Once #4605 merges on `main`, cherry-pick it into `release` as a backport PR. -- Verify: #4742 lands on `main` as a merge commit; release-plz runs on - `release`; a chained publish builds `release` while trunk differs; the - back-merges of two patch publishes on `release`, without a cut between, - both land on `main`. +- #4605 merged on `main` (275af9352, 2026-10-03), but `release` still lacks + its 64 MiB default receive window. Cherry-pick it into `release` as a + backport PR. Public API: none. Wire: none. Contributors see the new branch model. + +## Related + +- [Cloudflare builds track release](/quest/m0/cloudflare-release.md) - the maintainer's dashboard step, waiting on its own condition +- [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - the rest of the cap on `release` diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 9aba1577073..141a6f8ff53 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -52,12 +52,17 @@ Decided: prefix route. Document this rather than promise it works. - Publishers on the default publish path, such as moq-boy and moq-room, inherit the epoch from Origin. moq-stats mints its own through - [Stats epochs](/quest/m1/stats-epoch.md), which also gates the release + [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md), which also gates the release (decided 2026-10-04): a restarted stats node under a reused name stalls its viewers the same way. -- [Retracted demand release](/quest/m1/unannounce-demand-release.md) also +- [Retracted demand release](/quest/m0/broadcast-epoch/unannounce-demand-release.md) also gates the release (decided 2026-10-05): a regression from #4741 on main that `release` lacks. +- Decided in the 2026-10-05 audit: the m1 quests gating this line (stats + epochs, the bounded stats aggregate it requires, and retracted demand + release) moved under it, and the OBS half of GStreamer and OBS moved to m1 + as [OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release + gate no longer waits on m1 work. - Derived output mirrors the epoch it came from (`.pro/transcode//foo.hang/@e`, per the [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so @@ -75,12 +80,13 @@ This README owns: ## Required +- [Retracted demand release](/quest/m0/broadcast-epoch/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 - [Origin](/quest/m0/broadcast-epoch/origin.md) - moq-net publish mints an epoch, consumers follow the newest live one, and bare requests resolve to it on every version - [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names - [Gateways](/quest/m0/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover - [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 inherit the default -- [GStreamer and OBS](/quest/m0/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch -- [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp and NO_CAPACITY are gone -- [Stats epochs](/quest/m1/stats-epoch.md) - moq-stats publishes each node under its own epoch, so a restarted node never stalls its viewers -- [Retracted demand release](/quest/m1/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 +- [GStreamer](/quest/m0/broadcast-epoch/gst.md) - moqsink publishes each run under a fresh epoch +- [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp is gone +- [Bounded stats aggregate](/quest/m0/broadcast-epoch/stats-aggregate-bound.md) - the stats aggregator folds departed nodes into a retired total, so epoch churn stops growing its memory +- [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - moq-stats publishes each node under its own epoch, so a restarted node never stalls its viewers diff --git a/quest/m0/broadcast-epoch/bindings.md b/quest/m0/broadcast-epoch/bindings.md index 5aecc9045c9..4ee0c1b2a7e 100644 --- a/quest/m0/broadcast-epoch/bindings.md +++ b/quest/m0/broadcast-epoch/bindings.md @@ -19,6 +19,11 @@ reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. Decided in the 2026-09-30 audit: libmoq is frozen (renamed `rs/moq-c`), so C and C++ consumers get epochs from moq-ffi. +Decided in the 2026-10-05 audit: this lands before the +[FFI shape](/quest/m1/ffi-shape/README.md) line (#4519), which reshapes the +same wrappers and keeps `epoch()` today. It rebases onto this quest and +adopts the epoch surface and the rename, so the wrappers break once each. + ## Required - [Origin](/quest/m0/broadcast-epoch/origin.md) - the behavior the bindings surface diff --git a/quest/m0/broadcast-epoch/gst-obs.md b/quest/m0/broadcast-epoch/gst-obs.md deleted file mode 100644 index de562614565..00000000000 --- a/quest/m0/broadcast-epoch/gst-obs.md +++ /dev/null @@ -1,20 +0,0 @@ -# [S] GStreamer and OBS publish under epochs - -## Goal - -`moqsink` and the OBS plugin publish each run under a fresh epoch, so a -restarted pipeline or a stop and start in OBS is a clean takeover for viewers. - -## Plan - -`moqsink` takes the origin default per session. When -[#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) -lands, each of its publication generations is a new epoch. OBS gets it -through the generated C++ bindings from moq-ffi (decided in the 2026-09-30 -audit: libmoq gets no new API). Update `doc/bin/gstreamer.md` and -`doc/bin/obs.md` if they show paths. - -## Required - -- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi exposes epochs -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - OBS publishes through the generated C++ diff --git a/quest/m0/broadcast-epoch/gst.md b/quest/m0/broadcast-epoch/gst.md new file mode 100644 index 00000000000..f4ec65fd191 --- /dev/null +++ b/quest/m0/broadcast-epoch/gst.md @@ -0,0 +1,27 @@ +# [S] GStreamer publishes under epochs + +## Goal + +`moqsink` publishes each run under a fresh epoch, so a restarted pipeline is +a clean takeover for viewers. + +## Plan + +`moqsink` takes the origin default per session. When +[#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) +lands, each of its publication generations is a new epoch. Update +`doc/bin/gstreamer.md` if it shows paths. + +Decided in the 2026-10-05 audit: the OBS half moved to +[OBS publishes under epochs](/quest/m1/obs-epoch.md), so the release gate no +longer waits on the C++ line. `moqsink` is Rust on moq-net and needs nothing +from it. moq-c announces through `broadcast::Producer::announce`, so it only +inherits an epoch if Origin mints one there; the OBS quest checks that. + +## Required + +- [Origin](/quest/m0/broadcast-epoch/origin.md) - the publish default moqsink takes + +## Related + +- [OBS publishes under epochs](/quest/m1/obs-epoch.md) - the OBS plugin's half, after the C++ line diff --git a/quest/m0/broadcast-epoch/hop-removal.md b/quest/m0/broadcast-epoch/hop-removal.md index 2f776c535a0..2e98108b4f9 100644 --- a/quest/m0/broadcast-epoch/hop-removal.md +++ b/quest/m0/broadcast-epoch/hop-removal.md @@ -9,7 +9,7 @@ default); a redundant pair passes the same value. A plain publisher declares a random Hop ID per process with no flag, as the bindings and js already do, so a multi-homed publisher still catches its own loops. `--cluster-id` names a node and no longer falls back to `--hop`. Relays stop stamping an unnamed -publisher's hop chain, and NO_CAPACITY is gone: every refusal is terminal. +publisher's hop chain. ## Plan @@ -21,18 +21,17 @@ publisher's hop chain, and NO_CAPACITY is gone: every refusal is terminal. `js/net/src/hop.ts` and its callers in `js/net/src/{lite,ietf}/subscriber.ts`, and their tests, including `rs/moq-net/tests/legacy_reconnect.rs`. Keep the leading 0, so an unnamed chain still ranks anonymous. -- Remove NO_CAPACITY entirely (decided 2026-10-03: the maintainer does not - want a retryable refusal). Every refusal is terminal, and an advertiser - sheds load by withdrawing or re-pricing its route. That covers - `StreamCode.NoCapacity` and its uses in `js/net/src/{error,origin}.ts` and - the reserved-code comments in `rs/moq-net/src/error.rs`. +- NO_CAPACITY's removal (decided 2026-10-03: every refusal is terminal) + lands with the [wildcard](/quest/m0/wildcard/README.md) line, whose branch + already deletes it from js/net, moq-net, and both drafts (found in the + 2026-10-05 audit). Don't redo it here; rebase onto that line if it lands + first. - Drafts: lite-07 and cluster-02 are in progress, so edit their text and changelogs in place. In `drafts/draft-lcurley-moq-lite.md`: the stamping - rule, NO_CAPACITY in Error Codes and Resolution, "the identity it stamps", + rule, "the identity it stamps", and "the first entry identifies the endpoint that originated the route". In `drafts/draft-lcurley-moq-cluster.md`: the unknown-publisher stamping text, - the relay behavior that stamps, NO_CAPACITY and its IANA row, and the - changelog bullets. + the relay behavior that stamps, and the changelog bullets. - CLI: `rs/moq-cli/src/{args,complete,fetch,ls}.rs`. Relays keep `cluster.id` as their node id. - Docs: `doc/bin/cli.md` ("Redundant publishers" uses `--epoch`), the @@ -46,8 +45,8 @@ idle timeout (a failover service that retracts it, or active-active delivery to the relay). Neither is required to land this. Public API: removes `--hop`, `MOQ_HOP`, and `--origin`, adds `--epoch`, and -`--cluster-id` stops reading `--hop`; js/net loses `StreamCode.NoCapacity`. -Wire: relays stop stamping, and lite-07 and cluster-02 lose NO_CAPACITY. +`--cluster-id` stops reading `--hop`. +Wire: relays stop stamping. ## Required diff --git a/quest/m0/broadcast-epoch/origin.md b/quest/m0/broadcast-epoch/origin.md index 0c9bc4f0e2a..9906345af6f 100644 --- a/quest/m0/broadcast-epoch/origin.md +++ b/quest/m0/broadcast-epoch/origin.md @@ -32,9 +32,11 @@ any wire change. exclusion and the per-path fronts from #3312 stay intact. - Benchmark resolution swept over epochs per name and names per origin, so following does not scan the table. -- Open: does a catalog `broadcast` reference by bare name pin the epoch its - catalog came from, or follow the newest? Settle it with - [Catalog track alias](/quest/m1/catalog-track-alias.md). +- Settle here, in this m0 quest, whether a catalog `broadcast` reference by + bare name pins the epoch its catalog came from or follows the newest + (decided in the 2026-10-05 audit: it is not handed to + [Catalog track alias](/quest/m1/catalog-track-alias.md), an m1 quest that + never mentions epochs). Record the answer in the line README. - Update `doc/concept` and `drafts/draft-lcurley-moq-lite.md` wherever they describe resolution or takeover. The rule is a relay behavior, so state it in the draft even though no field changes. diff --git a/quest/m1/stats-aggregate-bound.md b/quest/m0/broadcast-epoch/stats-aggregate-bound.md similarity index 89% rename from quest/m1/stats-aggregate-bound.md rename to quest/m0/broadcast-epoch/stats-aggregate-bound.md index be68b3d6d13..7fe85310c7c 100644 --- a/quest/m1/stats-aggregate-bound.md +++ b/quest/m0/broadcast-epoch/stats-aggregate-bound.md @@ -9,7 +9,7 @@ Today `aggregate::Merged` keeps a sticky traffic node with `Reader::Ended` forever (the `STICKY` unannounce branch in `rs/moq-stats/src/aggregate.rs`). A returning path reuses its entry, but every distinct path ever announced (a scale-out, a renamed node) stays in a long-lived aggregator's `nodes`. This is -a bug on main regardless of [stats epochs](/quest/m1/stats-epoch.md), which +a bug on main regardless of [stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md), which make it worse by giving every restart a distinct path. ## Plan @@ -40,5 +40,5 @@ Public API: none expected beyond a possible grace-window knob on ## Related -- [Stats epochs](/quest/m1/stats-epoch.md) - every restarted node gets a new name, so retired entries churn faster +- [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - every restarted node gets a new name, so retired entries churn faster - [Binary delta stats](/quest/m2/stats-delta.md) - also sweeps the aggregate over node count diff --git a/quest/m1/stats-epoch.md b/quest/m0/broadcast-epoch/stats-epoch.md similarity index 87% rename from quest/m1/stats-epoch.md rename to quest/m0/broadcast-epoch/stats-epoch.md index f549b13b7c6..d9236e330e3 100644 --- a/quest/m1/stats-epoch.md +++ b/quest/m0/broadcast-epoch/stats-epoch.md @@ -17,7 +17,7 @@ broadcast name or the group numbers a relay cached under it. - Decide what an unset node becomes once the epoch follows it (#4739 used `local`). - The aggregator treats a new epoch as a new node: its counters add to the - retired total from the [bounded aggregate](/quest/m1/stats-aggregate-bound.md) + retired total from the [bounded aggregate](/quest/m0/broadcast-epoch/stats-aggregate-bound.md) instead of regressing the merged total. - MoQ Pro wants to share the same epoch with its storage stats, so expose it from `Producer`. @@ -37,4 +37,4 @@ names gain a trailing epoch segment. ## Required -- [Bounded stats aggregate](/quest/m1/stats-aggregate-bound.md) - retired nodes fold into a bounded total, which epochs churn +- [Bounded stats aggregate](/quest/m0/broadcast-epoch/stats-aggregate-bound.md) - retired nodes fold into a bounded total, which epochs churn diff --git a/quest/m1/unannounce-demand-release.md b/quest/m0/broadcast-epoch/unannounce-demand-release.md similarity index 100% rename from quest/m1/unannounce-demand-release.md rename to quest/m0/broadcast-epoch/unannounce-demand-release.md diff --git a/quest/m0/cloudflare-release.md b/quest/m0/cloudflare-release.md new file mode 100644 index 00000000000..f92e298553e --- /dev/null +++ b/quest/m0/cloudflare-release.md @@ -0,0 +1,9 @@ +# [XS] Cloudflare docs and demo builds track release + +## Goal + +Condition: the maintainer points the Cloudflare docs (`moq-doc`) and demo +builds' production branch at `release` in the Cloudflare dashboard, as the +[branch flip](/quest/m0/branch-flip.md) decided on 2026-10-02. Check: the +dashboard's production branch for both projects reads `release`, and the +live docs match `release`, not `main`. Delete this quest once it does. diff --git a/quest/m0/ietf-largest-object.md b/quest/m0/ietf-largest-object.md new file mode 100644 index 00000000000..8516dc73a87 --- /dev/null +++ b/quest/m0/ietf-largest-object.md @@ -0,0 +1,30 @@ +# [S] REQUEST_OK accepts LARGEST_OBJECT + +## Goal + +On moq-transport, a REQUEST_OK or REQUEST_UPDATE_OK carrying LARGEST_OBJECT +(0x09) is accepted in `rs/moq-net` and `js/net`, instead of closing the +session with PROTOCOL_VIOLATION. The draft makes the parameter a MUST when +objects exist, so a conformant peer hits this on its first reply. It lands +before Seattle interop on 2026-10-12. + +## Plan + +Decided in the 2026-10-05 audit: split from [moq-transport request +codes](/quest/m2/ietf-request-codes.md), whose other cases stay in m2, +because a session closed by legal input is exactly what m0's relay hardening +rules out. + +- `RequestOk::decode_msg` (`rs/moq-net/src/ietf/request.rs`) allows only + 0x08 and ACTIVE_COUNT today. Decode 0x09 as a `Location`, which + `ietf/parameters.rs` already handles, and decide whether anything reads it + or it is ignored like EXPIRES. +- Mirror in `js/net/src/ietf`. +- A regression test per language that fails on `main`: a REQUEST_OK with + LARGEST_OBJECT decodes, on each draft that carries it. + +Public API: none. Wire: none new; a legal reply stops closing the session. + +## Related + +- [moq-transport request codes](/quest/m2/ietf-request-codes.md) - the rest of the validator's request-level findings diff --git a/quest/m0/noq-reassembly-cap.md b/quest/m0/noq-reassembly-cap.md index ea3bfb2d0f7..2df3c47cc76 100644 --- a/quest/m0/noq-reassembly-cap.md +++ b/quest/m0/noq-reassembly-cap.md @@ -15,8 +15,10 @@ and released, then bump `noq` / `noq-proto` (directly or through `iroh`) on ## Plan `moq-noq` already carries the cap (2.0.1 on `main`, 1.3.3 on `release`), and -`moq-tokio` defaults the connection receive window to 64 MiB on noq and iroh, -so only this pin remains. +`moq-tokio` on `main` defaults the connection receive window to 64 MiB on noq +and iroh (#4605). `release` lacks that default until the +[branch flip](/quest/m0/branch-flip.md)'s backport of #4605 lands, so the bump +on `release` goes in after it. ## Related diff --git a/quest/m0/shared-fronts.md b/quest/m0/shared-fronts.md index 4ceaf017f10..86aa2af6f95 100644 --- a/quest/m0/shared-fronts.md +++ b/quest/m0/shared-fronts.md @@ -56,4 +56,4 @@ Public API: none. Wire: none. - [Front deadlines](/quest/m1/front-deadline-index.md) - per-front cost per track - [Front parking](/quest/m1/origin-front-parks.md) - also changes what mints a front -- [Wildcard](/quest/m0/wildcard/README.md) - its line rewrites `model/origin.rs` heavily (+401 lines, fronts end on a standing refusal); land after it or rebase onto it +- [Wildcard](/quest/m0/wildcard/README.md) - its line edits `model/origin.rs` resolution, and its [refusal child](/quest/m0/wildcard/refusal-final.md) makes a standing refusal end the front; land after it or rebase onto it diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index b0b410588d6..a8f7b1ad5ec 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -53,7 +53,7 @@ would have to start working (a cold transcoder)" `origin::Producer` gained versioned patterns on the [Auth](/quest/m1/auth/README.md) line, so tokens and filters reuse the same matcher; advertisements stay prefixes. `Cost { warm, cold }` -(`rs/moq-net/src/model/origin.rs:426`) is the route cost since +(`rs/moq-net/src/model/origin.rs:404`) is the route cost since [#2925](https://github.com/moq-dev/moq/pull/2925). [moq#3225](https://github.com/moq-dev/moq/pull/3225) moved a long way toward @@ -135,7 +135,7 @@ path, not with a route identity or a generation field. refused. A prefix wider than the grant is accepted, but it only routes requests for paths the grant covers. Fleet-wide services use the cluster identity; a customer service serves only what its own v1 grant contains. - Until [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) + Until [Advertise-only authorization](/quest/m3/processor/advertise-auth.md) lands, the publish scope stands in for advertising; a credential with its own advertise scope is checked against that instead. - **Claims are visible to subscribers.** A subscriber sees every advertised @@ -165,7 +165,7 @@ path, not with a route identity or a generation field. literal path. A path is one broadcast whoever serves it, so claim workers mirror the source's epoch and group numbers, publish a deterministic catalog, and start at group boundaries - ([Transcoders start at group boundaries](/quest/m1/transcode-group-start.md)). + ([Transcoders start at group boundaries](/quest/m0/wildcard/transcode-group-start.md)). Two workers at one path are then one broadcast, and a relay moving between them does so at a group boundary (decided 2026-10-03: #4741 drops first-hop identity, so routing can no longer tell two workers apart). @@ -217,7 +217,8 @@ distinguish recording generations reads the catalog's archive entry ## Required -- [Transcoders start at group boundaries](/quest/m1/transcode-group-start.md) - two claim workers at one path are one broadcast, so a relay never splices them mid-group +- [Transcoders start at group boundaries](/quest/m0/wildcard/transcode-group-start.md) - two claim workers at one path are one broadcast, so a relay never splices them mid-group +- [A standing refusal ends the front](/quest/m0/wildcard/refusal-final.md) - a refusal from the winning route ends the request instead of re-selecting a sibling or a shorter prefix ## Related diff --git a/quest/m0/wildcard/refusal-final.md b/quest/m0/wildcard/refusal-final.md new file mode 100644 index 00000000000..a0fc4e0fa00 --- /dev/null +++ b/quest/m0/wildcard/refusal-final.md @@ -0,0 +1,40 @@ +# [S] A standing refusal ends the front + +## Goal + +A refusal from the winning route is the answer. The request ends with that +refusal instead of re-selecting a sibling advertiser of the same prefix or +falling through to a shorter one, as the wildcard line, the lite draft, and +the cluster draft already say. A new route, or the refuser's route changing, +is what a client's ordinary resubscribe resolves against. + +## Plan + +Decided in the 2026-10-05 audit: a refusal is final, with no retry. The +maintainer: "otherwise we'll try all other possible options and cause a +cascade of requests". + +- Since #4741, `main` does the opposite. The front's standing-refusal arm + (`Err(Refusal { standing: true, .. })` in `rs/moq-net/src/model/front.rs`) + records the refuser in its `refused` set and pushes `Reselect`, and + `best_route` (`rs/moq-net/src/model/origin.rs`) skips those entries, which + can reach a sibling or a shorter prefix. `js/net/src/origin.ts` keeps the + same `refused` set per slot. Change only that arm, in both languages: it + ends the front with the refusal's typed code instead of re-selecting. +- Keep the `refused` set itself. `source_closed` also fills it, to exclude a + standing route whose source just ended ("asking it again would re-request + the broadcast that just ended"); deleting the set would re-pick that route + in a loop. Per-track refusal (`redispatch`) is already final, so only + front-level route selection changes. +- Keep resume across routes that did not refuse: a route that goes away + mid-track is not a refusal, and any covering route still resumes it. +- Tests in both languages: a refusal from the only advertiser of the longest + prefix ends the request even when a sibling or a catch-all could serve it. + Replace any test that asserts the fall-through; the tests asserting + `refused_routes()` mix both causes and need splitting. + +Public API: none. Wire: none; the relay matches what the drafts specify. + +## Related + +- [Shared fronts](/quest/m0/shared-fronts.md) - also changes what a front holds diff --git a/quest/m1/transcode-group-start.md b/quest/m0/wildcard/transcode-group-start.md similarity index 100% rename from quest/m1/transcode-group-start.md rename to quest/m0/wildcard/transcode-group-start.md 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 e1a1377b0a6..1bc8f4232a0 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 @@ -65,6 +65,10 @@ returns; a grant below the Opus floor disables the rendition, and recovered bandwidth enables it again even after the last viewer unsubscribed; a PCM Producer ignores every grant. +## Required + +- [Enabled flag](/quest/m1/catalog-enabled.md) - defines the `enabled` field a disabled rendition sets + ## Closes - [#2848](https://github.com/moq-dev/moq/issues/2848) - close this issue when the quest finishes diff --git a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md index 0c36f01a0bd..66398904bc0 100644 --- a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md +++ b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md @@ -13,7 +13,12 @@ ahead of the serving loop so every buffered update applies before the next group pop. It keeps only the newest range for the loop, but the decoder runs on its own and calls `apply` for each update, so a peer can turn flow-controlled bytes into unbounded work and heap while the loop is stalled. -First confirm what still grows on the current code, then cap the updates +First confirm what still grows on the current code. The 2026-10-05 audit +found the hole may already be closed: since #2820 `SubscriptionControls` +coalesces to the newest update ("Coalescing bounds memory") and each `apply` +is a single signal set, so per-update heap growth has no obvious source. +Flood SUBSCRIBE_UPDATE during a stalled write and measure; if nothing grows, +close #2850 and delete this quest instead. Otherwise cap the updates decoded between two drains by the loop and fail the session on overflow, matching Rust's refusal of malformed input. Test: a flood during a stalled write fails the session instead of growing. diff --git a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md index 6e60a2d7527..4c2d00c09fd 100644 --- a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md +++ b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md @@ -19,18 +19,20 @@ subscription creates a fresh `track::Request` (`rs/moq-net/src/model/track.rs`), and `Request::new` creates a fresh `TrackState`. Because its `max_sequence` is empty, both `append_group` and `append_datagram` restart at sequence 0. -That conflicts with the relay's logical track. The pump -(`rs/moq-net/src/model/pump.rs`) resumes a replacement from the first frame -the subscriber lacks, so groups from a restarted producer are skipped until -its counter catches up, causing the same playback stall fixed for JavaScript -in #2953. With #4741 this is the general hazard of restarting at 0 under one +That conflicts with the relay's logical track. The pump this was written +against is gone: #4741 resumes route changes by reading the routes' copies +(`rs/moq-net/src/model/front.rs`, `resume.rs`, and `origin.rs`). Re-check +first that a replacement restarting at sequence 0 still stalls under +copy-based resume, the way groups from a restarted producer were skipped +until its counter caught up (the playback stall fixed for JavaScript in +#2953), and rewrite this section against what the code does now. With #4741 this is the general hazard of restarting at 0 under one name, which [broadcast epochs](/quest/m0/broadcast-epoch/README.md) fix for a restarted publisher. This quest covers what an epoch does not: one dynamic track replaced inside a live broadcast. -The pump's route-change tests (`rs/moq-net/tests/route_change.rs`) are the -ones to extend: none replaces a producer through `append_group()`, which would -create group 0 and leave the subscriber stalled. Explicit group or datagram +The route-change tests (`rs/moq-net/tests/route_change.rs`) are the ones to +extend: none replaces a producer through `append_group()`, which would +create group 0 and, if the stall still holds, leave the subscriber stalled. Explicit group or datagram writes can raise the old producer's shared sequence edge further, making the catch-up window longer. diff --git a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md index 14f002dd893..662337a9e65 100644 --- a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md +++ b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md @@ -20,7 +20,7 @@ its own. Do not define a GStreamer-specific catalog shape. Decided in the 2026-09-30 audit: a restart is a new broadcast epoch, not a forward re-anchor on the old clock (per remove-live and -[GStreamer and OBS](/quest/m0/broadcast-epoch/gst-obs.md)), and +[GStreamer](/quest/m0/broadcast-epoch/gst.md)), and [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) handles the sink side. @@ -33,4 +33,5 @@ delayed first buffers, and multiple pads sharing one epoch. ## Related -- [GStreamer and OBS](/quest/m0/broadcast-epoch/gst-obs.md) - a restarted pipeline publishes a new epoch +- [GStreamer](/quest/m0/broadcast-epoch/gst.md) - a restarted pipeline publishes a new epoch +- [Shared import clock](/quest/m1/shared-clock.md) - when a catalog clock becomes final and how a `with_clock` catalog offsets every importer; set this epoch through that API, either `with_clock` or the first anchor, consistent with its rules diff --git a/quest/m1/README.md b/quest/m1/README.md index 6ebb7091a95..bb67091948b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -15,53 +15,64 @@ Give one agent ownership of each shared code area at a time (origin/auth, the JS Reader, audio playback, media containers and archive, bindings, worker transport, benchmark tooling); worktrees isolate commits, not semantics. -A line with no named consumer waits in m2 until one appears. The 2026-09-30 -audit moved P2P, one-port, ladder, processor, timed metadata, -the OBS GPU paths, the IETF half of rs2ts, and the unmeasured io_uring and -QUIC studies there on that rule. +A line with no named consumer waits in m3 until one appears; the 2026-10-05 +audit moved P2P, ladder, processor, and timed metadata there from m2. + +Decided in the 2026-10-05 audit: the clock chain ranks first (import at the +first frame, the HLS first catalog, typed timedness, the untimed models, +CMAF frame timestamp, the shared clock, and the two publish-timestamp +quests), with FFI shape pulled up inside it because publishing never invents +a timestamp requires its JSON pilot. The hard fork follows, ahead of transport-seam and perf, and the rest +of the QUIC line follows the fork. Every blocker ranks above the work it +blocks. The quests that gated m0 lines moved under them. ## Required -- [Retracted demand release](/quest/m1/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 -- [Bounded stats aggregate](/quest/m1/stats-aggregate-bound.md) - the stats aggregator folds departed nodes into a retired total after a grace window, so its memory stops growing with node churn -- [Stats epochs](/quest/m1/stats-epoch.md) - each stats producer publishes under `.../node//@`, so a restarted node never reuses a name +- [Import at the first frame](/quest/m1/import-first-frame.md) - fMP4, MKV, and MPEG-TS imports publish the catalog at their first frame, so a lone importer's root clock never moves +- [HLS first catalog](/quest/m1/hls-first-catalog.md) - moq-hls import's first catalog lists every rendition from the master playlist, not only the first +- [Typed timedness](/quest/m1/typed-timedness.md) - a track is all timed or all untimed, `Info.timescale` is optional, and `Timed` loses its clock parameter, in Rust, JS, and the bindings +- [Untimed model](/quest/m1/untimed-model.md) - an untimed moq-net track reaches every subscriber untimed; no receiver fills in arrival time +- [JS untimed model](/quest/m1/js-untimed-model.md) - the same in @moq/net +- [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 +- [Shared import clock](/quest/m1/shared-clock.md) - an importer joining a clock already in use offsets its PTS instead of moving it, so captures and imports share one timeline +- [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below +- [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 transport-seam and 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 -- [Transcoders start at group boundaries](/quest/m1/transcode-group-start.md) - moq-transcode serves from a group boundary and mirrors its source's sequences, so two instances are interchangeable - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost - [Delete removed cluster flags](/quest/m1/cluster-shims.md) - `mesh` and `linger` leave `cluster::Config` and their flags become unknown - [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` - [Request linger](/quest/m1/request-linger.md) - an upstream FETCH or SUBSCRIBE outlives its last reader by a short linger, so quick re-requests don't churn upstream - [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 - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay -- [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below - [moq-net owns its transport seam](/quest/m1/transport-seam.md) - moq-net names only its own transport traits, so a web-transport-trait or qmux major bump is a patch for it - [moq announced](/quest/m1/cli-announced.md) - `moq ls` becomes a follow-only live view named `moq announced`, with local-only shell completion - [Leave out a role](/quest/m1/cli-no-role.md) - `moq export` and `moq play` accept `--no-video` and `--no-audio`, and sinks that ignore selection refuse it - [fMP4 export tracks](/quest/m1/fmp4-export-tracks.md) - fMP4 export inits from the catalog, keeps early audio, and fails loudly instead of writing a track missing from moov -- [TS export rewind](/quest/m1/ts-export-rewind.md) - TS export keeps its clock through gaps, flags only a resume or a new broadcast, and fails on backwards time - [Delete the live marker](/quest/m1/announce-live-removal.md) - announce streams yield only route events; the `Live` marker and its hold machinery are gone - [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend - [JS dev mode](/quest/m1/js-dev-mode.md) - net and signals stop reading `import.meta.env`, the subscriber tripwire is deleted, and announced requests hold no subscription -- [Enabled flag](/quest/m1/catalog-enabled.md) - one `enabled` rendition flag replaces `stalled` and pausing, and the flapping encoder-lag detector is deleted -- [Audio graph lifetime](/quest/m1/watch-audio-graph.md) - the watch audio graph survives a rendition leaving the catalog, so a publisher mute keeps the tail and the next start - [Audio publish hygiene](/quest/m1/audio-publish-hygiene.md) - JS audio uses the shared container producer, so any stop ends its epoch, and volume ramps over a configurable `fade` +- [Audio graph lifetime](/quest/m1/watch-audio-graph.md) - the watch audio graph survives a rendition leaving the catalog, so a publisher mute keeps the tail and the next start +- [Enabled flag](/quest/m1/catalog-enabled.md) - one `enabled` rendition flag replaces `stalled` and pausing, and the flapping encoder-lag detector is deleted - [DTX timestamps](/quest/m1/opus-dtx-timestamps.md) - Opus DTX keeps the capture timeline, so voice enables it by default again - [LIFO cleanups](/quest/m1/signals-lifo.md) - signals effects clean up last-in, first-out, so nested teardown runs first - [Still screen share](/quest/m1/capture-still-frame.md) - video capture keeps its latest frame and replays it, re-stamped, to late subscribers - [Spent capture budget errors](/quest/m1/capture-exhausted-error.md) - a camera or microphone that runs out of retries sets `out.error` instead of failing silently - [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 - [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 -- [Live media time](/quest/m1/subscribe-live-time.md) - a lite-07 SUBSCRIBE_OK carries the publisher's current media time, so readers judge a cache against the live edge +- [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](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - on lite-07, a relay fetching the head of a group it receives mid-group still delivers that group to new subscribers - [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 - [IETF rejoin keeps the open group](/quest/m1/ietf-rejoin-open-group.md) - on moq-transport-19/22, a reader that rejoins mid-group still receives the open group's later frames -- [JS cache window](/quest/m1/js-prune-cache-window.md) - js/net ages idle groups on a cache window and keeps max_age as media-time staleness, as Rust does - [JSON stream budget](/quest/m1/json-stream-budget.md) - an oversized JSON stream record is refused without ending the log, and a JS subscribe to a gone track answers NotFound - [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 - [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 -- [Shaper step on mock time](/quest/m1/shaper-step-clock.md) - the `moq-shaper` step test asserts on a paused clock, so a loaded runner cannot fail it - [A week of nightly interop after #4529](/quest/m1/interop-week.md) - the nightly traces the stall diagnosis reads - [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 - [Subscriber max-delay](/quest/m1/subscriber-max-delay.md) - subscriber staleness becomes `max_delay`; publisher retention stays `max_age` @@ -73,16 +84,7 @@ QUIC studies there on that rule. - [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 - [Install with moq.sh](/quest/m1/moq-sh.md) - `curl -fsSL https://moq.sh | sh` installs or upgrades the released `moq` on macOS and Linux -- [Import at the first frame](/quest/m1/import-first-frame.md) - fMP4, MKV, and MPEG-TS imports publish the catalog at their first frame, so a lone importer's root clock never moves -- [HLS first catalog](/quest/m1/hls-first-catalog.md) - moq-hls import's first catalog lists every rendition from the master playlist, not only the first -- [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 -- [Shared import clock](/quest/m1/shared-clock.md) - an importer joining a clock already in use offsets its PTS instead of moving it, so captures and imports share one timeline -- [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 -- [Typed timedness](/quest/m1/typed-timedness.md) - a track is all timed or all untimed, `Info.timescale` is optional, and `Timed` loses its clock parameter, in Rust, JS, and the bindings -- [Untimed model](/quest/m1/untimed-model.md) - an untimed moq-net track reaches every subscriber untimed; no receiver fills in arrival time - [Untimed failover](/quest/m1/untimed-failover.md) - a resumed group no route continues is given up even when media time can't judge its drift -- [JS untimed model](/quest/m1/js-untimed-model.md) - the same in @moq/net - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [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()` @@ -94,12 +96,12 @@ QUIC studies there on that rule. - [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) - drafts 14-16 stop sending Timestamp properties they can't give units for - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - no FETCH, replay to a new subscriber, or cache fill ever returns a datagram group -- [#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 -- [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers +- [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [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 - [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 +- [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` @@ -137,28 +139,30 @@ QUIC studies there on that rule. - [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 - [Audio group duration](/quest/m1/audio-group-duration.md) - audio publishers in JS and Rust take a minimum group duration, default one frame - [JS group cancel](/quest/m1/js-group-cancel.md) - a JS Reader stopped after FIN allocates no cancel error - [#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 -- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - retained evidence, repeated paired runs, and uncertainty for performance claims - [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - moq-bench reports per-interval latency percentiles so the ramp leaves the steady state - [Relay session bench](/quest/m1/bench-relay.md) - the same scenario through moq-relay's own connection handling -- [Relay profiling](/quest/m1/performance-profiles.md) - reproducible CPU and allocation captures under the existing workloads - [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 +- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles +- [Video auto creep](/quest/m1/video-auto-creep.md) - a browser video-only broadcast's `"auto"` target stops creeping upward one step at a time - [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 -- [Plan: cache age-out](/quest/m1/cache-wall-eviction.md) - a swept benchmark decides whether the track cache ages groups out on wall time without a write +- [One max_age meaning](/quest/m1/cache-max-age.md) - a swept benchmark decides whether the track cache ages groups out on wall time without a write, then Rust and js/net both implement it - [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` -- [Papercuts](/quest/m1/papercuts.md) - JS refuses to serve a broadcast it did not produce, `just` skips `.scratch/`, and a uring test stops sleeping +- [Papercuts](/quest/m1/papercuts.md) - JS refuses to serve a broadcast it did not produce, and a uring test stops sleeping - [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [Route wakes](/quest/m1/route-wakes.md) - a route change wakes only the fronts it can move, so pool churn stops scaling with served paths -- [Admission bench](/quest/m1/admission-bench.md) - the driver's per-event admission walk is benchmarked over tracks and copies +- [Copy-walk bench](/quest/m1/admission-bench.md) - a front's walk over its copies on a route change is benchmarked over tracks and copies - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence - [JS abandonment](/quest/m1/js-subscribe-abandonment.md) - a viewer returning during IETF subscribe setup keeps its track across microtasks - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt @@ -166,16 +170,15 @@ QUIC studies there on that rule. - [#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 -- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [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, subtitle, or sign-language track survives conversion to a hang catalog +- [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption or subtitle track survives conversion to a hang catalog - [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling +- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay` - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [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 -- [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` - [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 fixed-delay release stage - [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared fixed-delay release stage @@ -190,8 +193,8 @@ QUIC studies there on that rule. - [Rust owns mobile codecs](/quest/m1/mobile-ownership.md) - the settled verdict (Rust codecs, CVPixelBuffer bridge) is written where binding work reads it - [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) - the packages are built and dry-run clean but exist nowhere consumers can install from +- [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 - [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net caps the publisher's subscription controls so a flood cannot grow memory without bound -- [`moq --listen` admission](/quest/m1/cli-serve.md) - a listening CLI session is authenticated, scoped, counted, and drained like a relay's instead of accepting everything +- [`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 diff --git a/quest/m1/admission-bench.md b/quest/m1/admission-bench.md index 288dc13e685..4d8cb614c32 100644 --- a/quest/m1/admission-bench.md +++ b/quest/m1/admission-bench.md @@ -1,23 +1,31 @@ -# [S] Admission walk benchmark +# [S] Front copy-walk benchmark ## Goal -A benchmark sweeps tracks per front against copies per track for the -driver's admission walk, so a per-event cost that grows with the front -shows up as a slope. +A benchmark sweeps tracks per front against copies per track for the walks a +front makes over its copies when its route changes, so a cost that grows with +the front shows up as a slope. ## Plan -On the wildcard line, `run_front` (`rs/moq-net/src/model/origin.rs`) walks -every track and every copy (`io.copies()`) and calls `Provenance::admit` after -each event whenever `front.admit()` returns an origin, even when nothing -changed; Abort and End walk the same way. #4279 left this unbenchmarked -(moq-dev/moq#4607 covered pool resolution). The walk only runs once a -lite-07 reply names an origin, so extend `rs/moq-net/benches/session.rs` over -lite-07 mock sessions. If the slope matters, say so rather than optimizing -here; [Front deadlines](/quest/m1/front-deadline-index.md) owns per-track -wakes. +Decided in the 2026-10-05 audit: re-scoped from the wildcard line's admission +walk, which no longer exists (`Provenance::admit`, `front.admit()`, and +`io.copies()` are on neither `main` nor the line branch), to the copy walk +#4741 put on `main`. The Wildcard blocker is dropped, since this code is on +`main`. -## Required +- Since #4741 a front resumes route changes by reading the routes' copies. + `attach` and `source_closed` call `drain_copies` + (`rs/moq-net/src/model/front.rs`), which walks every track, and the driver + keeps the serving source's copies until End. Nothing benchmarks either. +- Extend `rs/moq-net/benches/origin.rs` (or `session.rs` if a session is + needed to drive it) with a route swap swept over tracks per front and copies + per track. +- If the slope matters, say so rather than optimizing here; + [Front deadlines](/quest/m1/front-deadline-index.md) owns per-track wakes. -- [Wildcard](/quest/m0/wildcard/README.md) - the line the admission walk lives on +Public API: none. Wire: none. + +## Related + +- [Front deadlines](/quest/m1/front-deadline-index.md) - per-track wakes on the same front diff --git a/quest/m1/audio-decode-audiotoolbox.md b/quest/m1/audio-decode-audiotoolbox.md index cda8f73b5cc..69633f6229e 100644 --- a/quest/m1/audio-decode-audiotoolbox.md +++ b/quest/m1/audio-decode-audiotoolbox.md @@ -32,8 +32,9 @@ alongside the `objc2-core-audio-types` the crate already carries. end up where `Layout` says). - iOS: the binding compiles into the moq-ffi iOS slice; runtime proof waits on a device like the rest of the mobile line. -- Docs: `doc/bin/obs.md` drops the HE-AAC and multichannel caveat on macOS, - and the backend table names what this host decodes. +- Docs: `doc/lib/rs/moq-audio.md` drops its caveat that multichannel AAC and + HE-AAC are refused on macOS and iOS, and its backend table names what this + host decodes. ## Related diff --git a/quest/m1/audio-publish-hygiene.md b/quest/m1/audio-publish-hygiene.md index 1c5eddbeeed..8b44ce39392 100644 --- a/quest/m1/audio-publish-hygiene.md +++ b/quest/m1/audio-publish-hygiene.md @@ -36,5 +36,6 @@ with a subscriber attached writes a marker. ## Related +- [Enabled flag](/quest/m1/catalog-enabled.md) - builds its publisher pause on this quest's disable path, after it lands - [Audio group duration](/quest/m1/audio-group-duration.md) - builds on the shared producer - [LIFO cleanups](/quest/m1/signals-lifo.md) - the teardown error from the same capture diff --git a/quest/m1/audio-quality-native.md b/quest/m1/audio-quality-native.md index 76b845c16e8..123dee281e0 100644 --- a/quest/m1/audio-quality-native.md +++ b/quest/m1/audio-quality-native.md @@ -18,7 +18,10 @@ from whichever platform a user happened to be on. it measures anything. Settle which way out: a virtual display and software rendering in CI, or an audio-only mode in `moq play` that never opens a window. The second is worth having on its own, and it is the smaller - dependency to keep working. A real device callback is part of what is being + dependency to keep working. Recorded in the 2026-10-05 audit: + [Leave out a role](/quest/m1/cli-no-role.md) decided that `play --no-video` + shows a blank, closable window and left a headless audio-only path as later + work, so this quest owns that headless path, built on `--no-video`. A real device callback is part of what is being measured, so keep the real backend rather than substituting a fake clock, and accept that the timing noise it adds sets the floor for the native budgets. That floor is worth measuring on its own before the budgets are written. @@ -44,3 +47,7 @@ difference in totals alone proves nothing about the estimator. Standalone in m1 rather than a child of the m0 audio quality harness line (decided in the 2026-09-28 quest audit): nothing in m0 waits on it. The native jitter target it grades is done on the jitter target line. + +## Related + +- [Leave out a role](/quest/m1/cli-no-role.md) - `play --no-video`, which the headless audio-only path builds on diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index 3e4cbe5c22d..abbd24aa17e 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -124,6 +124,6 @@ existing lite-06 ALPN. ## Related -- [Expiring media grants](/quest/m2/processor/grant-lease.md) - a worker's +- [Expiring media grants](/quest/m3/processor/grant-lease.md) - a worker's lease renewal is a new in-band token -- [P2P](/quest/m2/p2p/README.md) - the first consumer of hop-bound peer grants +- [P2P](/quest/m3/p2p/README.md) - the first consumer of hop-bound peer grants diff --git a/quest/m1/auth/peer-grant.md b/quest/m1/auth/peer-grant.md index 0641129a7c1..2861c0d0890 100644 --- a/quest/m1/auth/peer-grant.md +++ b/quest/m1/auth/peer-grant.md @@ -46,7 +46,7 @@ serves only the granted paths. A missing, expired, HMAC-signed, or unproven grant is not a grant. P2P is the first consumer: -[Signaling and policy](/quest/m2/p2p/signal.md) presents the grant in band +[Signaling and policy](/quest/m3/p2p/signal.md) presents the grant in band on each direct session. This quest does not depend on that line. Docs: `doc/bin/relay/auth.md` states that peer grants need an asymmetric @@ -66,5 +66,5 @@ Additive. ## Related -- [Signaling and policy](/quest/m2/p2p/signal.md) - the first consumer -- [Route trust](/quest/m1/cluster-routing/route-trust.md) - extends the grant with the node ids its holder may advertise routes for, a second purpose beside serving paths +- [Signaling and policy](/quest/m3/p2p/signal.md) - the first consumer +- [Route trust](/quest/m3/route-trust.md) - extends the grant with the node ids its holder may advertise routes for, a second purpose beside serving paths diff --git a/quest/m1/auth/token-in-band.md b/quest/m1/auth/token-in-band.md index 574bf9c96c5..b3a5ab2cf5f 100644 --- a/quest/m1/auth/token-in-band.md +++ b/quest/m1/auth/token-in-band.md @@ -23,8 +23,11 @@ AUTH can carry the full grant once the pattern-interest prerequisite lands. `--connect-token` and `MOQ_CONNECT_TOKEN`, the default set for every dial the client makes. A `?jwt=` in the URL stays a member of the union, which is how cluster dial targets keep their per-peer credential, and per-dial - extras use the session's `auth().add()` once connected. moq-ffi - `MoqClient::set_tokens` (mirrored in the wrappers, and reaching the + extras use the session's `auth().add()` once connected. moq-ffi gains a + `tokens` field on the `MoqClientConfig` record that + [FFI shape](/quest/m1/ffi-shape/README.md) (#4697) puts in place of every + `MoqClient` setter, mirroring `moq_tokio::connect::Config`, not a new + `set_tokens` setter (mirrored in the wrappers, and reaching the generated C and C++ bindings and OBS through [C++ through moq-ffi](/quest/m1/cpp/README.md)) and `js/net`'s `connect` options field follow. Decided in the 2026-09-30 audit: no new libmoq API, diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index 5d55cc9b4b0..d79ca556ec1 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -5,15 +5,14 @@ Large BBR flights do not make every ACK scan all outstanding packets. Packet bookkeeping scales with acknowledged, lost, and expired entries while preserving bandwidth samples and congestion behavior. Ship the improvement -through MoQ's published dependency chain without changing public APIs or wire -behavior. +in `moq-quic` without changing public APIs or wire behavior. ## Plan -The fix lives in moq-dev/noq. The baseline is the current releases: the -workspace pins moq-noq 1.3.2 and 2.0.0 is out. In both, `on_end_acks` -(`noq-proto/src/congestion/bbr3/mod.rs:1845`) runs `retain` over all tracked -packets, then scans them again to mark stale entries. Draining a flight with fixed-size ACK batches has quadratic total +The fix lives in `moq-quic`'s BBR3, after [BBR3](/quest/m1/quic/fork/bbr3.md) +re-ports it in the hard fork; moq-dev/noq is frozen. In the BBR3 it ports, +`on_end_acks` (`noq-proto/src/congestion/bbr3/mod.rs`) runs `retain` over all +tracked packets, then scans them again to mark stale entries. Draining a flight with fixed-size ACK batches has quadratic total cleanup work. [Google QUICHE](https://github.com/google/quiche/blob/c961965aa3ee8f2b6f05ebcac794f7854101adcd/quiche/quic/core/congestion_control/bandwidth_sampler.cc#L377) uses packet-number lookup and obsolete-prefix reclamation; use that as a reference without copying a TCP or single-space assumption into QUIC. @@ -45,16 +44,15 @@ Acceptance is the removal of the whole-flight factor from per-ACK work, with measured scaling and bounded retained memory under reordering and loss. Report CPU time and memory across both benchmark axes, including small flights, and explain any remaining logarithmic or amortized cost. Keep the -regressions in fork CI and the benchmark matrix at least nightly. Do not +regressions in CI and the benchmark matrix at least nightly. Do not substitute one hardware-specific millisecond limit for the scaling check. -Land the fix in the fork, offer it upstream or record why not, publish an -immutable fork release, and pin the corrected dependency chain here before -completing this quest. Do not wait for the broader QUIC stack release. Update internal packet-lifetime comments inline; no new user guide -is needed. +Offer the fix upstream to quinn or record why not. Update internal +packet-lifetime comments inline; no new user guide is needed. ## Required +- [BBR3](/quest/m1/quic/fork/bbr3.md) - the `moq-quic` BBR3 this fixes - [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork ## Related diff --git a/quest/m1/bot-workflows-permission.md b/quest/m1/bot-workflows-permission.md new file mode 100644 index 00000000000..0ac1460fb96 --- /dev/null +++ b/quest/m1/bot-workflows-permission.md @@ -0,0 +1,16 @@ +# [XS] moq-bot may push workflow changes + +## Goal + +Condition: the maintainer grants moq-bot's GitHub App the `workflows` +permission, so the Back-merge workflow (`.github/workflows/back-merge.yml`, +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. + +Planned as a follow-up of the 2026-10-05 audit. diff --git a/quest/m1/browser-benchmarks.md b/quest/m1/browser-benchmarks.md index b8ed38d6ef0..5498eeb8f18 100644 --- a/quest/m1/browser-benchmarks.md +++ b/quest/m1/browser-benchmarks.md @@ -8,9 +8,11 @@ microbenchmarks do not exercise. ## Plan -The JS microbenchmarks already exist: the four Bun sweeps in `js/net/bench` -(`broadcasts`, `reader`, `frames`, `track`) run nightly and cover the origin -map, fragmented `Reader` reads, group frame decode, and track retention. This +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, +group frame decode, lite-07 against lite-06 varints, fragmented `Reader` +reads, track retention, and varint coding. This quest is only the real-browser half: conclusions come from an identified browser version on a real WebTransport connection. `test/wasm` validates browser interop but measures nothing. Reuse the existing relay/browser harness @@ -19,7 +21,7 @@ pieces and add a focused recipe with artifacts under the benchmark conventions. - Measure the `js/net/src/stream.ts` path in the browser over WebTransport, with payloads from small audio through large keyframes, recording CPU, wall time, allocation volume, GC pauses, and bytes copied where measurable. Add a - Bun sweep only for a cost the browser run finds and the four miss. + Bun sweep only for a cost the browser run finds and the seven miss. - Cover CMAF encode/decode with fixed audio/video fixtures and multiple samples. Keep fixture generation and relay startup outside timed intervals. - Add publish/watch scenarios measuring delivered/decoded/presented frames, diff --git a/quest/m1/cache-max-age.md b/quest/m1/cache-max-age.md new file mode 100644 index 00000000000..f6ec797255c --- /dev/null +++ b/quest/m1/cache-max-age.md @@ -0,0 +1,64 @@ +# [M] One max_age meaning for both languages' track caches + +## Goal + +`max_age` means the same thing in Rust and js/net. A swept benchmark decides +first whether a track's cache ages groups out without waiting for a write, on +`max(wall, pts)` like other time decisions in moq-net, or stays the one +write-driven exception. Both languages then implement that answer, with the +pool's (Rust) or cache window's (JS) wall-clock idle bound kept separate from +`max_age`. + +## Plan + +Decided in the 2026-10-05 audit: the Rust plan (wall-clock age-out) and the +JS fix (a cache window apart from `maxAge`) merge into this one quest, which +owns `max_age` semantics for both languages. The benchmark decides first; +[#4659](https://github.com/moq-dev/moq/pull/4659), which already moves JS to +media-time `maxAge` with a private 30 s idle window, is reworked to match the +decision or closed after it. Rejected: treating the JS half as settled and +narrowing the benchmark to Rust. + +Settled scope: a track's `max_age` retention, and whether it ages groups out +on a timer instead of only on a write. The pool's idle expiry stays the +separate wall-clock bound. + +- Today Rust's `max_age` is media time and is applied only when the track + writes: a group ages out when a later one starts (`is_stale` and the expiry + scans in `rs/moq-net/src/model/track.rs`). A track that stops writing keeps + groups past `max_age` until the pool's idle expiry (`Pool::gc`, driven by + the origin driver without a write) or byte pressure reclaims them. + `max_age_does_not_drive_wall_eviction` pins that behaviour. +- JS does the opposite on `main`: `#prune` in `js/net/src/track.ts` evicts a + group once it has been idle on the wall clock (`performance.now`) past + `maxAge`, on its own timer, so a congestion stall can age content out of a + JS publisher's cache. `js/net/bench/track.ts` benches the publish cost + against the retained window. +- Prototype the Rust alternative behind a bench-only switch: each track keeps + a deadline for its oldest group on `max(wall elapsed, pts)`, armed on the + timers the origin driver already runs, and evicts on expiry. +- Bench in `rs/moq-net/benches/track.rs`, swept over tracks (1 to 10k) and + cached groups per track (1 to 1k): write-path cost, timer cost per driver + pass, and retained memory for a population of idle tracks. A cost that + grows with the table should show as a slope. +- Weigh the semantics too: `max_age` is media time on purpose, so a congestion + stall cannot age content out (`track::Info::max_age`). A wall term changes + that for a stalled but live publisher. +- Whatever this decides, an untimed group is never media-stale and only the + pool's expiry reclaims it, as decided in + [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md). +- Then implement the decision in both languages: give js/net a cache window + of its own for idle eviction, as Rust's pool has (keep it private), and + apply `max_age` the way the benchmark settled. Test with mocked time that a + stalled track keeps or drops its groups as decided. + [Generated @moq/net](/quest/m1/rs2ts/README.md) will replace the JS model + later; the maintainer chose to fix it by hand first. + +Public API: none unless the JS window becomes configurable. Wire: none. + +## Related + +- [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 +- [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) - untimed groups are never media-stale +- [Generated @moq/net](/quest/m1/rs2ts/README.md) - retires js/net's hand-written model diff --git a/quest/m1/cache-wall-eviction.md b/quest/m1/cache-wall-eviction.md deleted file mode 100644 index 53d42d7a4ca..00000000000 --- a/quest/m1/cache-wall-eviction.md +++ /dev/null @@ -1,49 +0,0 @@ -# [S] Plan: wall-clock age-out in the track cache - -## Goal - -A benchmark decides whether a track's cache ages groups out without waiting -for a write, on `max(wall, pts)` like other time decisions in moq-net, or -stays the one write-driven exception. The result is an implementation quest -or a recorded reason to keep the exception. - -## Plan - -Settled scope: a track's `max_age` retention aging groups out on a timer -instead of only on a write. The pool's idle expiry is out of scope. - -- Today a track's `max_age` is media time and is applied only when the track - writes: a group ages out when a later one starts (`is_stale` and the expiry - scans in `rs/moq-net/src/model/track.rs`). A track that stops writing keeps - groups past `max_age` until the pool's idle expiry (`Pool::gc`, driven by - the origin driver without a write) or byte pressure reclaims them. - `max_age_does_not_drive_wall_eviction` pins that behaviour. -- JS already does the opposite: `#prune` in `js/net/src/track.ts` evicts a - group once it has been idle on the wall clock (`performance.now`) past - `maxAge`, on its own timer, and `js/net/bench/track.ts` benches the publish - cost against the retained window. So `max_age` means different things per - language today. The decision settles both: either Rust gains a wall term or - JS moves to media time, and the loser's tests and docs change with it. -- Prototype the alternative behind a bench-only switch: each track keeps a - deadline for its oldest group on `max(wall elapsed, pts)`, armed on the - timers the origin driver already runs, and evicts on expiry. -- Bench in `rs/moq-net/benches/track.rs`, swept over tracks (1 to 10k) and - cached groups per track (1 to 1k): write-path cost, timer cost per driver - pass, and retained memory for a population of idle tracks. A cost that - grows with the table should show as a slope. -- Weigh the semantics too: `max_age` is media time on purpose, so a congestion - stall cannot age content out (`track::Info::max_age`). A wall term changes - that for a stalled but live publisher. -- Whatever this decides, an untimed group is never media-stale and only the - pool's expiry reclaims it, as decided in - [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md). -- Record the numbers and the decision in the PR, then rewrite this quest into - the implementation or delete it. - -Public API: none from the plan. Wire: none. - -## Related - -- [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 -- [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) - untimed groups are never media-stale diff --git a/quest/m1/captions-msf.md b/quest/m1/captions-msf.md index 5079a87ee4c..8cb2ae850cd 100644 --- a/quest/m1/captions-msf.md +++ b/quest/m1/captions-msf.md @@ -34,4 +34,4 @@ Per cross-package sync, mirror any schema movement in `js/msf`. ## Related - [Caption import](/quest/m1/captions-import.md) - the container half of the - same gap, and the quest that closes the issue + same gap diff --git a/quest/m1/capture-default.md b/quest/m1/capture-default.md index d27fde791eb..123e7271e8f 100644 --- a/quest/m1/capture-default.md +++ b/quest/m1/capture-default.md @@ -25,8 +25,11 @@ pre-merge `just check` never runs moq-video's `capture` tests: 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, moq-cli's `capture` feature (it may - become redundant), and `doc/` wherever capture is described as opt-in. +- 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 diff --git a/quest/m1/catalog-enabled.md b/quest/m1/catalog-enabled.md index c3ec780a4b7..b5a593a7c58 100644 --- a/quest/m1/catalog-enabled.md +++ b/quest/m1/catalog-enabled.md @@ -41,7 +41,7 @@ Decided (2026-10-04): until the grant recovers. A disabled rendition loses its subscribers, and the allocator grants nothing to an undemanded track, so recovery evaluates a hypothetical share against the current estimate instead of waiting for a - grant. The [ladder](/quest/m2/ladder/README.md) and + grant. The [ladder](/quest/m3/ladder/README.md) and [audio grant following](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) adopt that rule; this quest only defines the field. - Everything else that names `stalled` moves to `enabled`: moq-transcode's @@ -58,6 +58,7 @@ nothing; nothing in the tree writes `stalled`. ## Required - [Audio graph lifetime](/quest/m1/watch-audio-graph.md) - the viewer keeps its graph across an absence, which a disable reuses +- [Audio publish hygiene](/quest/m1/audio-publish-hygiene.md) - lands first, so the publisher pause builds on the shared container producer's disable path ## Closes @@ -66,5 +67,5 @@ nothing; nothing in the tree writes `stalled`. ## Related -- [Ladder](/quest/m2/ladder/README.md) - disables a rung its grant cannot sustain +- [Ladder](/quest/m3/ladder/README.md) - disables a rung its grant cannot sustain - [Rendition preference](/quest/m1/rendition-preference.md) - the other per-rendition selection field diff --git a/quest/m1/cli-packaging.md b/quest/m1/cli-packaging.md index 4cb9136bb02..ad9561b529a 100644 --- a/quest/m1/cli-packaging.md +++ b/quest/m1/cli-packaging.md @@ -49,4 +49,5 @@ its remaining work was one release feature flag and a doc note. ## Required +- [Capture by default](/quest/m1/capture-default.md) - also changes moq-cli's `capture` feature; land it first - [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 diff --git a/quest/m1/cli-serve.md b/quest/m1/cli-serve.md index 298cd2a3f67..994b594686d 100644 --- a/quest/m1/cli-serve.md +++ b/quest/m1/cli-serve.md @@ -1,40 +1,41 @@ -# [M] A listening CLI session is admitted like a relay's +# [S] A listening CLI session is counted and drained like a relay's ## Goal A session accepted by `moq import --listen` or `moq export --listen` is -authenticated (JWT, mTLS, or public prefixes), scoped by its grant, counted in -stats, and drained on shutdown, the way a relay admits one. Today -`spawn_server`, `route_server`, and `spawn_serve` (`rs/moq-cli/src/main.rs`) -accept every request with `request.ok()` and attach the process's single -origin in whichever directions the stages use, so a listening CLI is an open -relay. `moq-relay` stays its own minimal binary; this does not make `moq` the -relay. +counted in stats and drained on shutdown, the way a relay's is. Admission +already matches the relay: since #3688 `serve_client` +(`rs/moq-cli/src/main.rs`) admits each session through a `moq_relay::auth` +lease, scopes the origin by its grant, and refuses what the grant does not +allow. What remains is that it then calls `moq_relay::supervise` with +`shutdown::Observer::disabled()` and no stats. `moq-relay` stays its own +minimal binary; this does not make `moq` the relay. ## Plan -- Replace the CLI's three server helpers with the relay's acceptance path, - exposing a small library entry point when the CLI needs it. `MoqSide` nests - `moq_relay::auth::Config` and `stats::Config`, so `--auth-*` and `--stats-*` - read the same on both binaries; `--auth-public '**'` is the open listener, - spelled the same on both. -- The Unix peer-credential gate on `--listen-unix-bind` and the certificate - endpoint for an explicit `--listen` survive, rehomed on the relay's web - server or kept as the CLI's, whichever leaves one copy. +Decided in the 2026-10-05 audit: re-scoped to what remains, after +[Auth client CA](/quest/m1/relay-auth-client-ca.md), which reworks the same +`spawn_server` auth path. + - Drain: on SIGTERM the listener sends GOAWAY and waits `drain_timeout` like - the relay, instead of dropping sessions. + the relay, through a real `shutdown::Observer` instead of the disabled one. + [Drain handshakes](/quest/m1/drain-handshakes.md) moves where the relay + takes that count; hand the observer over the way it settles. +- Stats: `MoqSide` nests `stats::Config` like the relay, so `--stats-*` reads + the same on both binaries, and `supervise` gets it instead of `None`. - Docs: `doc/bin/cli.md` describes listening in the relay's terms and links the relay's auth page rather than restating it. -- Test: an authenticated viewer with a scoped token sees only its root on a - `moq import --listen`; an unscoped one is refused when a key is - configured; the unauthenticated import-to-export smoke keeps passing with - `--auth-public`. +- 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/m2/moq-relay-subcommand.md). `moq-cli` already depends -on `moq-relay`, and the open-relay listener is a security gap that should not -wait on an m2 subcommand. +[`moq relay`](/quest/m3/moq-relay-subcommand.md). + +## Required + +- [Auth client CA](/quest/m1/relay-auth-client-ca.md) - reworks the same `spawn_server` auth path first ## Related -- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the CLI later hosts the whole relay +- [`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 a8c5e0becd1..c5629579139 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -62,8 +62,9 @@ vector the 2026-09-30 cache-tiers audit kept: version; a plain client with one link advertises only itself. Node ids are opaque randoms, so routes reveal no backbone addresses. - **Trust.** Cluster-peer links may advertise any node; a client link's node - ids stay scoped to its session. See - [Route trust](/quest/m1/cluster-routing/route-trust.md). + ids stay scoped to its session. Promoting them is + [Route trust](/quest/m3/route-trust.md), which moved beside P2P in the + 2026-10-05 audit; this line finishes without it. - **Multi-CDN by link preference.** A node may rank its links (moq.pro primary, Cloudflare secondary) ahead of the metric, so metrics from different operators are never compared; a CDN that speaks no ROUTE is just @@ -131,13 +132,13 @@ 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 -- [Route trust](/quest/m1/cluster-routing/route-trust.md) - a peer grant lets a client link advertise the nodes behind it as one identity - [Link quality](/quest/m1/cluster-routing/link-quality.md) - a radio link's cost follows its measured quality without flapping routes ## Related - [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule and pool spread Selection builds on -- [P2P](/quest/m2/p2p/README.md) - browser and native peers that become routing nodes over this layer +- [P2P](/quest/m3/p2p/README.md) - browser and native peers that become routing nodes over this layer +- [Route trust](/quest/m3/route-trust.md) - a peer grant lets a client link advertise the nodes behind it as one identity - [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - redundant publishers share an explicit `@` - [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/routes.md b/quest/m1/cluster-routing/routes.md index 6b5d57fe866..3e656df8ed5 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -70,7 +70,7 @@ Decided 2026-10-01 (see the [line's decisions](/quest/m1/cluster-routing/README. ([Upstream links](/quest/m1/cluster-routing/transit.md)). - A plain client with one link advertises a ROUTE for itself and the ANNOUNCEs it publishes; its node id is scoped to its session (shared - identity across sessions is [Route trust](/quest/m1/cluster-routing/route-trust.md)). + identity across sessions is [Route trust](/quest/m3/route-trust.md)). A relay advertising routes to a client sends them as usual; node ids reveal nothing about the backbone. - Every hop re-selects; SUBSCRIBE names no origin, and the reply names none @@ -107,7 +107,7 @@ refused. Wire: `drafts/draft-lcurley-moq-lite.md` in the same PR, and `js/net` encodes, decodes, and resolves it (JS transit stays in -[P2P](/quest/m2/p2p/README.md)). Public API: the route-change surface on +[P2P](/quest/m3/p2p/README.md)). Public API: the route-change surface on `broadcast::Route` and its bindings will likely change; report it. This may split at start (Rust and draft, then JS), as long as both land in one release. diff --git a/quest/m1/cluster-routing/selection.md b/quest/m1/cluster-routing/selection.md index 42d5cc44978..7cf5d58a6be 100644 --- a/quest/m1/cluster-routing/selection.md +++ b/quest/m1/cluster-routing/selection.md @@ -26,6 +26,14 @@ Decided: per [Wildcard](/quest/m0/wildcard/README.md)'s double-claim rule. So a relay never needs to tell claim output from a redundant pair. +Recorded in the 2026-10-05 audit: part of this is already built. The +wildcard line's `route_order` hash is keyed on the requested path, the HRW +spread below, and #4741 made a concrete path one source with mid-group +resume. Once [Wildcard](/quest/m0/wildcard/README.md) (#4403) lands, cut this +quest down to what remains: terminal refusal (see its +[refusal child](/quest/m0/wildcard/refusal-final.md)), the HRW split test, +the same-path failover test, and upstream-link spread. + Candidate mechanics: - Route selection stays `route_order` over the routes a relay holds: longest diff --git a/quest/m1/cluster-routing/sim.md b/quest/m1/cluster-routing/sim.md index d474d82282f..6ebf7f85352 100644 --- a/quest/m1/cluster-routing/sim.md +++ b/quest/m1/cluster-routing/sim.md @@ -13,9 +13,9 @@ Per scenario (publish, end, link flap, relay loss and restart, uplink loss): 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 rewrites that quest for the split; until it merges the -moq.pro quest still asks the older path-vector question. To check: look for -the report in a merged moq.pro PR. To advance: land #2136, then ask the -maintainer to start the moq.pro quest. Delete this quest once the report is +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. diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index 9a8655c78bc..24bfaa05853 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -64,8 +64,14 @@ Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): - MSVC is covered by the post-merge nightly, not a branch dispatch: branches never dispatch the nightly. +Decided in the 2026-10-05 audit: the [FFI shape](/quest/m1/ffi-shape/README.md) +line (#4519) lands first, and this line ports `cpp/moq`, `cpp/obs`, and the +C++ interop client onto the reshaped moq-ffi, since its branch still calls +APIs FFI shape deleted. + ## Required +- [FFI shape](/quest/m1/ffi-shape/README.md) - lands first; this line ports onto its moq-ffi - [Generator](/quest/m1/cpp/generator.md) - the uniffi 0.32 C++ generator with futures and expected-style errors, pinned and generating `cpp/ffi` in CI - [Package](/quest/m1/cpp/package.md) - the `cpp/moq` wrapper, CMake package, release tarball, interop client, and docs - [Cancel](/quest/m1/cpp/cancel.md) - a cancelled or consumed future reports `valid() == false`, like `std::future`, and a read of it aborts with a message naming the misuse diff --git a/quest/m1/dart-ios.md b/quest/m1/dart-ios.md index 792e552d3c0..707b83b43ff 100644 --- a/quest/m1/dart-ios.md +++ b/quest/m1/dart-ios.md @@ -38,4 +38,4 @@ and drop the three iOS targets from `release-dart-ffi.yml` rather than paying ## Related -- [Dart publish](/quest/m1/dart-publish.md) - requires this verdict, since publishing spreads the iOS claim +- [Dart publish](/quest/m1/dart-publish.md) - the packages are already on pub.dev, and `moq_ffi` is tagged `platform:ios`, so this verdict now corrects a published claim rather than gating one diff --git a/quest/m1/dart-publish.md b/quest/m1/dart-publish.md index f634f082147..38afc6ca99f 100644 --- a/quest/m1/dart-publish.md +++ b/quest/m1/dart-publish.md @@ -1,53 +1,31 @@ -# [S] Dart packages on pub.dev +# [XS] A Dart tag publishes unattended ## Goal -`moq` and `moq_ffi` are installable from pub.dev, and later `moq-ffi-v*` and -`moq-dart-v*` tags publish without hand-holding. +A `moq-dart-v*` tag publishes `moq` to pub.dev with no manual step, as +`moq-ffi-v*` tags already publish `moq_ffi`. ## Plan -The release workflows landed with -[#3215](https://github.com/moq-dev/moq/pull/3215) and pass their dry runs, but -nothing is published: pub.dev requires the first version of a new package to be -uploaded by hand before automated publishing can be configured. So this is -one-time setup rather than code. - -Order matters, and the obvious order is wrong. A published `moq_ffi` resolves -its native assets from the GitHub release for its own version, and that release -only exists once the `moq-ffi-v*` tag has run. Publishing by hand first would -ship a package whose hook downloads from a release that does not exist, and the -later tag would then reach `dart pub publish` on an already-published version, -which pub.dev refuses because versions are immutable. - -So the assets come first: - -- Cut `moq-ffi-v*`. Its build and release jobs attach the per-target libraries - and their checksums. Expect the publish job to fail: the package name is not - claimed yet, which is the whole reason for this quest. -- Upload the staged package by hand to claim `moq_ffi`. The `package` job has - already produced exactly that artifact, so upload it rather than restaging. -- Repeat for `moq` via `moq-dart-v*`, whose only asset is the package itself. -- Configure trusted publishing for each: repository `moq-dev/moq`, tag patterns - `moq-ffi-v{{version}}` and `moq-dart-v{{version}}`. GitHub OIDC then covers - every later release and there is no token to store. -- Cut one more patch of each and confirm both workflows publish unattended. - -`package.sh` replaces the committed `0.0.0-dev` sentinel with the real version -in `pubspec.yaml`, `hook/build.dart`, and `CHANGELOG.md`, so no version is -hand-edited before tagging. Verify the published `moq_ffi` resolves its native -asset from a clean machine with no monorepo checkout, since that download path -is the one CI never exercises. - -The iOS blocker is about not publishing a claim we cannot support: the -first release is the one that reaches strangers, and pub.dev packages generally -cannot be unpublished or deleted. A version may be retracted within seven days, -but retraction does not erase it. - -Decided in the 2026-09-30 audit: publishing also waits on FFI shape, which -relies on Dart being unpublished so its breaking renames are free. - -## Required - -- [Dart on iOS](/quest/m1/dart-ios.md) - the package advertises iOS, which nobody has run -- [FFI shape](/quest/m1/ffi-shape/README.md) - its breaking renames are free only while Dart is unpublished +Found in the 2026-10-05 audit: both packages are on pub.dev. `moq_ffi` has +eight versions (0.4.3 to 0.4.10, published 2026-09-25 to 2026-10-03), so its +tag-driven publish works. `moq` has only 0.1.0 (2026-09-25), the one +`moq-dart-v*` tag so far, so whether its tag publishes unattended through +trusted publishing is still unproven. + +Decided in the 2026-10-05 audit: the quest shrinks to that check. The FFI +shape wait is gone, since Dart is no longer unpublished; FFI shape carries a +Dart upgrade note instead. + +- Confirm trusted publishing is configured for `moq` (repository + `moq-dev/moq`, tag pattern `moq-dart-v{{version}}`). +- Cut the next `moq-dart-v*` patch and confirm the workflow publishes it. +- Verify the published `moq_ffi` resolves its native asset from a clean + machine with no monorepo checkout, since that download path is the one CI + never exercises. + +Public API: none. Wire: none. + +## Related + +- [Dart on iOS](/quest/m1/dart-ios.md) - pub.dev already tags `moq_ffi` for iOS, which nobody has run diff --git a/quest/m1/fetch-ok-properties.md b/quest/m1/fetch-ok-properties.md index cd8b066c16b..164963e5404 100644 --- a/quest/m1/fetch-ok-properties.md +++ b/quest/m1/fetch-ok-properties.md @@ -1,4 +1,4 @@ -# [S] FETCH_OK carries the track's properties +# [M] FETCH_OK carries the track's properties ## Goal @@ -24,15 +24,31 @@ sends an empty block. Extension Headers / Properties associated with a track in FETCH_OK (d16 ยง8.6, d22 ยง7.7). An empty block also misleads the reader: it infers Ascending order and priority 128 where SUBSCRIBE_OK says Descending. -- Honour INCLUDE_PROPERTIES (0x35) on FETCH from draft 20. It defaults to - sending the properties; at 0 the block is present but empty. `fetch.rs` - decodes it on draft 20+ and drops it, so it is not honoured today. +- FETCH preserves object properties, Timestamp included. Decided in the + 2026-10-05 audit (maintainer: "FETCH must send stamped objects? It's not + legal to remove the property."): the standalone FETCH path sending its + objects unstamped because no SUBSCRIBE declared a timescale + (`ietf/publisher.rs`, around line 1346) is a bug to fix here. FETCH_OK declares the track's TIMESCALE, and every + fetched object keeps its Timestamp, so a fetch-only reader is timed exactly + when the track is, as [Typed timedness](/quest/m1/typed-timedness.md) + requires. Rejected: omitting timescale from FETCH_OK and leaving fetch-only + readers untimed. +- Honour INCLUDE_PROPERTIES (0x35) on FETCH from draft 20, once + [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) serves draft-20 FETCH at + all (today our publisher refuses every one). It defaults to sending the + properties; at 0 the block is present but empty. `fetch.rs` decodes it on + draft 20+ and drops it, so it is not honoured today. - Test per draft range: FETCH_OK round-trips the properties SUBSCRIBE_OK would - carry, and INCLUDE_PROPERTIES = 0 empties the block. + carry, a standalone FETCH's objects arrive stamped, and + INCLUDE_PROPERTIES = 0 empties the block. Public API: none. Wire: FETCH_OK gains its properties on drafts that define the block. Interop: run `just test interop --all`. +## Required + +- [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/ffi-frame-duration-default.md b/quest/m1/ffi-frame-duration-default.md index f5295dbb4e4..05d17afa52e 100644 --- a/quest/m1/ffi-frame-duration-default.md +++ b/quest/m1/ffi-frame-duration-default.md @@ -18,4 +18,12 @@ every binding. Opus still encodes 20 ms frames by default. 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/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 06db0e1b2d0..5e1b39ff0d4 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -10,8 +10,18 @@ and verb maps to a Rust one. A docs page shows the layers in each language. ## Plan -Lands after the release, as one binding break in Python, Go, Swift, and -Kotlin (Dart is unpublished). +Lands after the release, as one binding break in Python, Go, Swift, Kotlin, +and Dart. Dart is published now (`moq` 0.1.0 and `moq_ffi` 0.4.x on pub.dev), +so its renames get the same upgrade note as the others. + +Decided in the 2026-10-05 audit: + +- The m0 [Bindings](/quest/m0/broadcast-epoch/bindings.md) quest lands + first. This line rebases onto it and adopts its epoch surface and the + `session.epoch()` rename, rather than renaming again. +- This line lands before [C++ through moq-ffi](/quest/m1/cpp/README.md), + which then ports `cpp/moq`, `cpp/obs`, and the C++ interop client onto the + reshaped moq-ffi, so the C++ breaks once. Settled shape: @@ -34,7 +44,8 @@ Settled shape: namespaces. - `demand()` is the one way to watch subscribers; producers drop their `name`/`is_used`/`used`/`unused` duplicates. -- moq-ffi only. The hand-written moq-c and `cpp/obs` are out of scope: the +- moq-ffi and its generated consumers. The C++ line ports `cpp/obs` after + this lands (above). The hand-written moq-c is out of scope: the [generated C](/quest/m1/c/README.md) and [C++](/quest/m1/cpp/README.md) bindings inherit this shape from moq-ffi, so reshaping the hand-written C ABI would break C users twice. @@ -51,6 +62,7 @@ work no child does: ## Required +- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - lands first; this line adopts its epoch surface and the `session.epoch()` rename - [JSON](/quest/m1/ffi-shape/json.md) - the pilot: json and flate become their own namespaces wrapping a track in every binding and set the per-language pattern - [Net](/quest/m1/ffi-shape/net.md) - client and server take config records, snapshots are records, and the verbs match moq-net - [Media](/quest/m1/ffi-shape/media.md) - catalog, import, and container consume move under `media` diff --git a/quest/m1/gpu-runner.md b/quest/m1/gpu-runner.md index 591b3b7bb8d..e1045304493 100644 --- a/quest/m1/gpu-runner.md +++ b/quest/m1/gpu-runner.md @@ -14,5 +14,4 @@ this quest and every `Required` entry that links it. As of 2026-09-30 `gh api repos/moq-dev/moq/actions/runners` lists none. Register it with the dedicated label and hardening that -[GPU CI](/quest/m1/gpu-ci.md) describes, and share the registration with the -io_uring runner the drain line plans. +[GPU CI](/quest/m1/gpu-ci.md) describes. diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 29fb464e175..3f3fe0b336e 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -25,6 +25,16 @@ fed one encoded stream. Capture is out: two encoders never align. sides of it. - Frame timestamps derive from the input alone too. Importers publish the stream's own timestamps and refuse a rewind, so nothing shifts them. +- The catalog's root `clock` must agree too. Today each importer anchors it + to its own first-frame arrival (`Clock::arrival` in + `rs/moq-mux/src/catalog/producer.rs`), which + [Import at the first frame](/quest/m1/import-first-frame.md) makes the + first published clock, and [Shared import clock](/quest/m1/shared-clock.md) + offsets a joining importer by its arrival time. Decided in the 2026-10-05 + audit: redundant importers derive the wall anchor from the input (its PTS + or PCR) or from the shared epoch, never from arrival, so two catalogs of + one stream are identical. Rejected: narrowing the contract to exclude the + catalog clock. - An importer announces only once it knows its tracks, so it never refuses a track the incumbent serves. - Docs (`doc/bin/cli.md` "Redundant publishers", the `--epoch` doc comment) @@ -47,3 +57,4 @@ issues' 1+1 setup (one relay, two `import ts` sharing one `--epoch`, two ## Related - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a redundant pair shares one epoch +- [Shared import clock](/quest/m1/shared-clock.md) - the clock and offset rules an importer joining an existing clock follows diff --git a/quest/m1/js-data-consumer-timestamps.md b/quest/m1/js-data-consumer-timestamps.md index 7565dd92964..6700a272412 100644 --- a/quest/m1/js-data-consumer-timestamps.md +++ b/quest/m1/js-data-consumer-timestamps.md @@ -15,7 +15,10 @@ beside video and today reads raw frames to recover the timestamps. Decided (2026-10-01): `next()` and the async iterator yield `@moq/net`'s `Timed` (`{ value, at? }`), the type the producers take after [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md). -`at` is the frame's timestamp, absent for an untimed frame. Snapshot +`at` is the frame's timestamp, absent for an untimed frame. Decided +(2026-10-05): timedness is per track, in the shape [Typed +timedness](/quest/m1/typed-timedness.md) mirrors into `@moq/net`; where this +note assumes a per-frame optional timestamp, that shape wins. Snapshot consumers get the same two reads as Rust: `next()` yields every state in order (`@moq/json` stops draining to the latest, `@moq/flate` reads groups in order), and `latest()` skips to the newest state, today's behavior. A reader diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index e029fe6a9db..6ba95f3bc4d 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -1,23 +1,16 @@ -# [L] Serve on-demand groups and IETF FETCH in JavaScript +# [M] Serve IETF FETCH in JavaScript ## Goal -A JavaScript publisher serves requested groups that are no longer in its live -cache, including IETF FETCH from a native subscriber. The capability is -independent of archives and works for arbitrary track payloads. +A JavaScript publisher answers IETF FETCH from a native subscriber, including +groups that are no longer in its live cache, through the on-demand request +surface `@moq/net` gains in [JS ranges](/quest/m1/subscribe-ranges/js.md). ## Plan -Add the producer-side counterpart of `track::Consumer.fetchGroup`, matching -Rust's `track::Dynamic` request ownership and accept/refuse lifecycle. Expose -an owned request handle rather than a storage callback; dropping a request -must refuse it rather than leave the subscriber waiting. Preserve group -sequence, frame boundaries, payload bytes, and track properties. Storage, -retention, and media catalog interpretation remain outside `js/net`. - -Use one logical dynamic track per broadcast/name. Keep cache-miss group -requests distinct from creation of a new live track producer, and cover -concurrent requests and cancellation without creating duplicate live producers. +Decided in the 2026-10-05 audit: the producer-side request surface folded +into [JS ranges](/quest/m1/subscribe-ranges/js.md), so it takes range +requests from the start. This quest keeps only IETF FETCH dispatch onto it. Implement IETF FETCH dispatch and codecs across the supported draft versions. Cover standalone and relative joining requests, subscription lifetime @@ -26,20 +19,18 @@ 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. -Use an in-memory application responder for verification, without OPFS or an -archive writer. A browser publisher serves a native subscriber after a group -is evicted or was never cached; verify exact group/frame replay, empty groups, -missing groups, concurrent requests, and cancellation while awaiting a reply. -Run the supported-draft matrix and `just test interop --all` through CI. +Verify with an in-memory application responder: a browser publisher serves a +native IETF subscriber after a group is evicted or was never cached. Run the +supported-draft matrix and `just test interop --all` through CI. -Public API: a producer-side on-demand group request surface in `@moq/net`, -matching Rust's lifecycle. Wire: implement the existing supported IETF FETCH -formats; update relevant documentation and any MoQ draft claims that change. +Public API: none beyond JS ranges' surface. Wire: implement the existing +supported IETF FETCH formats; update relevant documentation and any MoQ draft +claims that change. ## Required -- [Dynamic track identity](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - settles shared producer identity before adding on-demand group requests +- [JS ranges](/quest/m1/subscribe-ranges/js.md) - the on-demand request surface this dispatches onto ## Related -- [Browser archive](/quest/m2/archive-browser.md) - supplies memory or OPFS archive data through this generic request surface +- [Browser archive](/quest/m3/archive-browser.md) - supplies memory or OPFS archive data through the same request surface diff --git a/quest/m1/js-prune-cache-window.md b/quest/m1/js-prune-cache-window.md deleted file mode 100644 index c955c2244e1..00000000000 --- a/quest/m1/js-prune-cache-window.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] js/net ages cached groups on a cache window, not max_age - -## Goal - -js/net retains cached groups the way Rust does. A wall-clock idle window -bounds memory, and `max_age` is only the media-time staleness budget, so a -congestion stall can't age content out of a JS publisher's cache. - -## Plan - -`#prune` (`js/net/src/track.ts`) evicts a group after `info.maxAge` of -wall-clock idleness, measured on the group's `activity`. Rust keeps those -apart: `track::Info::max_age` is measured in media timestamps, and the cache -pool's `expiry` is the separate wall-clock bound -(`rs/moq-net/src/model/cache.rs`). Give js/net a cache window of its own for -idle eviction, as Rust's pool has, and leave `maxAge` to `#drift` / -`#isStale`. Add a test with mocked time where a stalled track keeps its groups -past `maxAge`. - -[Generated @moq/net](/quest/m1/rs2ts/README.md) will replace this code with -Rust's model; the maintainer chose to fix it by hand first. - -Public API: none unless the window is configurable (keep it private). Wire: -none. - -## Related - -- [Generated @moq/net](/quest/m1/rs2ts/README.md) - retires js/net's hand-written model diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index fd5fe7cc0d9..e992ee90cd5 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -21,6 +21,11 @@ the same type in 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`. +Decided (2026-10-05): timedness is per track, in the shape [Typed +timedness](/quest/m1/typed-timedness.md) mirrors into `@moq/net`. Where the +2026-10-01 note above assumes a per-frame optional timestamp (an absent `at` +marking an untimed frame), that shape wins. + Public API: breaking. Wire: none. ## Required diff --git a/quest/m1/libmoq-final-release.md b/quest/m1/libmoq-final-release.md index 2792144099a..3378206c87f 100644 --- a/quest/m1/libmoq-final-release.md +++ b/quest/m1/libmoq-final-release.md @@ -2,14 +2,17 @@ ## Goal -The newest `libmoq` on crates.io is the code-free stub built from `main`'s -`rs/libmoq`, whose README points at `moq-c`. +The newest `libmoq` on crates.io is the code-free stub that `main`'s +`rs/libmoq` holds, whose README points at `moq-c`. Since #4738 publishing runs +only from `release`, so the condition clears at the next `main`-to-`release` +cut, which must take `main`'s stub for `rs/libmoq`. This quest tracks a condition outside the repository. When it holds, delete this quest and every `Required` entry that links it. ## Plan -As of 2026-10-02 the newest release is libmoq 0.6.9 (2026-09-30), cut from -`release`'s full crate, not the stub. Check with +As of 2026-10-05 the newest release is libmoq 0.6.10 (2026-10-03), again cut +from `release`'s full crate, not the stub, and the open release PR #4763 +bumps `release`'s full libmoq once more. Check with `curl -s https://crates.io/api/v1/crates/libmoq` for a newer `max_version`. diff --git a/quest/m1/moq-sh.md b/quest/m1/moq-sh.md index e64e0df75e4..0f0c222e9db 100644 --- a/quest/m1/moq-sh.md +++ b/quest/m1/moq-sh.md @@ -98,5 +98,5 @@ since the script and its hosting now both live in this repository. - [Ship capture and playback](/quest/m1/cli-packaging.md) - decides what the released binary this installs can do -- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - relay functionality joins +- [`moq relay`](/quest/m3/moq-relay-subcommand.md) - relay functionality joins the same executable independently of its installation method diff --git a/quest/m1/obs-epoch.md b/quest/m1/obs-epoch.md new file mode 100644 index 00000000000..0866b9fac08 --- /dev/null +++ b/quest/m1/obs-epoch.md @@ -0,0 +1,28 @@ +# [S] OBS publishes under epochs + +## Goal + +The OBS plugin publishes each Start Streaming under a fresh epoch, so a stop +and start in OBS is a clean takeover for viewers, like every other +first-party publisher in the [broadcast epoch](/quest/m0/broadcast-epoch/README.md) +line. + +## Plan + +Split from the m0 GStreamer and OBS quest in the 2026-10-05 audit, so the +release gate waits only on `moqsink`. + +- OBS gets the epoch through the generated C++ bindings from moq-ffi, which + the C++ line moves the plugin onto (decided in the 2026-09-30 audit: libmoq, + now moq-c, gets no new API). +- First check whether the plugin already inherits it: today it announces + through moq-c's `moq_publish_announce`, which calls + `broadcast::Producer::announce`. If Origin mints the epoch on that path, + the plugin needs no code, only a test. +- Show the full epoch path in the dock, and update `doc/bin/obs.md` if it + shows paths. + +## Required + +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the plugin publishes through the generated C++ +- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi exposes epochs diff --git a/quest/m1/obs-moq-video/adapter.md b/quest/m1/obs-moq-video/adapter.md index 33845995fe3..37a1103b8d6 100644 --- a/quest/m1/obs-moq-video/adapter.md +++ b/quest/m1/obs-moq-video/adapter.md @@ -18,3 +18,4 @@ One opt-in Use MoQ encoders choice publishes OBS video and audio through moq-vid - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ first - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - common policy - [Audio publishing](/quest/m1/obs-moq-video/audio-publish.md) - both adapters are needed for the combined opt-in UI +- [Codecs](/quest/m1/ffi-shape/codec.md) - the encoder and decoder types land once, in the `audio` and `video` namespaces (decided in the 2026-10-05 audit) diff --git a/quest/m1/obs-moq-video/audio-playback.md b/quest/m1/obs-moq-video/audio-playback.md index c5f74b42a48..8b103649e93 100644 --- a/quest/m1/obs-moq-video/audio-playback.md +++ b/quest/m1/obs-moq-video/audio-playback.md @@ -6,8 +6,8 @@ The MoQ source decodes subscribed audio with statically linked moq-audio instead ## Plan -- Today the source already plays audio: `moq_source_subscribe_audio` in `cpp/obs/src/moq-source.cpp` receives encoded frames through moq-c's `moq_consume_audio`, and `moq_source_decode_audio_frame` decodes them with libavcodec before `obs_source_output_audio`. Replace that decode, not the playback path. -- Decode through the generated C++ package with `MoqBroadcastConsumer::decode_audio` (a `MoqAudioConsumer` with a `next()` future per frame, cancel on drop), then feed its PCM to `obs_source_output_audio`. `decode_audio` accepts Opus and AAC-LC today; add PCM there rather than in the plugin. Keep device playback inside OBS; do not enable moq-audio device capture/playback features or open a second audio device. +- Today the source already plays audio: `moq_source_subscribe_audio` in `cpp/obs/src/moq-source.cpp` receives encoded frames, through moq-c's `moq_consume_audio` on `main` and the generated C++'s `subscribe_media` once the C++ line lands, and `moq_source_decode_audio_frame` decodes them with libavcodec before `obs_source_output_audio`. Replace that decode, not the playback path. +- Decode through the generated C++ package with the `audio` namespace's decoder that [Codecs](/quest/m1/ffi-shape/codec.md) moves `MoqBroadcastConsumer::decode_audio` into (a `next()` future per frame, cancel on drop), then feed its PCM to `obs_source_output_audio`. `decode_audio` accepts Opus and AAC-LC today; add PCM there rather than in the plugin. Keep device playback inside OBS; do not enable moq-audio device capture/playback features or open a second audio device. - Map catalog tracks, sample rates, channel layouts, and timestamps explicitly. Channel layouts: map each channel count to the default layout moq-audio uses, the WAVE convention (3 is 2.1, 4 is quad, 6 is 5.1, 8 is 7.1), picking the nearest OBS `speaker_layout`, and refuse counts OBS cannot place rather than guess. This replaces `audio_layout_to_speakers`, which maps from FFmpeg layouts, and absorbs the former m2 obs-wave-layout quest. Note the mapping in `doc/bin/obs.md`. - Share the source's media timebase with video, preserve reconnect and rendition changes, and bound audio buffering. `latency_max_ms` controls stalled-group skipping, not desired A/V playout delay. - Preserve OBS mixer, monitoring, mute, and volume behavior. Release every frame on output, conversion failure, stop, and late completion. Do not hold source state locks across callbacks into OBS. @@ -19,6 +19,7 @@ Decided: the earlier receive branch (#3498, merged only into the stranded `codex ## Required - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ first +- [Codecs](/quest/m1/ffi-shape/codec.md) - the encoder and decoder types land once, in the `audio` and `video` namespaces (decided in the 2026-10-05 audit) ## Related diff --git a/quest/m1/obs-moq-video/audio-publish.md b/quest/m1/obs-moq-video/audio-publish.md index 3b7cf9981a5..d3d0af3db34 100644 --- a/quest/m1/obs-moq-video/audio-publish.md +++ b/quest/m1/obs-moq-video/audio-publish.md @@ -16,3 +16,4 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ first - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - shared policy and truthful reporting +- [Codecs](/quest/m1/ffi-shape/codec.md) - the encoder and decoder types land once, in the `audio` and `video` namespaces (decided in the 2026-10-05 audit) diff --git a/quest/m1/open-gop-leading-pictures.md b/quest/m1/open-gop-leading-pictures.md index a932cd5101c..808f51edca9 100644 --- a/quest/m1/open-gop-leading-pictures.md +++ b/quest/m1/open-gop-leading-pictures.md @@ -53,8 +53,15 @@ decode, and the JS test should drive the software decoder. - 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 frames on the open-GOP fixture decode after they present - (`dts-before-pts`). Trim them at tune-in from the same signal, and make - `just test ts --open-gop` pass under `--strict`. + (`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 + `--strict`. Decided in the 2026-10-05 audit: the grader changes with it. + `test/ts/open-gop.py`'s decode-order check (a contiguous run of source + access units) and leading-pictures check, and the `test/ts/README.md` text + that says the round-trip must hand every leading picture on, both expect + 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 @@ -69,6 +76,10 @@ decode, and the JS test should drive the software decoder. group's leading pictures trimmed too, so an implementation that only trims the initial group fails. Both cases in both languages. +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - the TS export this trims lands with #4645 + ## 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 729c9c1d825..1df5ab14bb2 100644 --- a/quest/m1/origin-front-parks.md +++ b/quest/m1/origin-front-parks.md @@ -35,4 +35,5 @@ fronts' benchmark shows the retry loop's re-mint is noise. ## Required +- [Wildcard](/quest/m0/wildcard/README.md) - `routed_broadcast`, `request_broadcast`, and the pool code this reworks exist only on its line branch - [Shared fronts](/quest/m0/shared-fronts.md) - reworks the same fronts, and its benchmark decides whether this stays in m1 diff --git a/quest/m1/papercuts.md b/quest/m1/papercuts.md index 56a365d6e2f..80822b735d5 100644 --- a/quest/m1/papercuts.md +++ b/quest/m1/papercuts.md @@ -2,9 +2,9 @@ ## Goal -Three small fixes found while landing the m0 quests: `@moq/net` refuses to -serve a broadcast it did not produce, `just fix` and `just check` leave the -gitignored `.scratch/` alone, and `remote_wake_unparks` passes under load. +Two small fixes found while landing the m0 quests: `@moq/net` refuses to +serve a broadcast it did not produce, and `remote_wake_unparks` passes under +load. ## Plan @@ -16,11 +16,12 @@ gitignored `.scratch/` alone, and `remote_wake_unparks` passes under load. serving, e.g. `Request.accept(consumer)`, which labels upstream content with the local origin's hop. Refuse that loudly at the point it enters the origin, not in the lite publisher's `local(..) ?? demand(..)` resolve. -- `.scratch/`: add it to `.taplo.toml`'s excludes and to `.remarkignore`, so - `taplo format` and `sh/markdown.sh` stop rewriting agents' scratch clones. - biome, nixfmt, just, and shfmt already skip it. + - `rs/moq-uring/src/worker.rs` `remote_wake_unparks`: observe that the worker parked instead of sleeping 50 ms and asserting elapsed wall time, per the rule that unit tests mock time. +- Dropped in the 2026-10-05 audit: the `.scratch/` formatter excludes. #4598 + retired the agents' scratch-clone convention, and the only writer left is + the X11 capture benchmark's log, which no formatter touches. Public API: none. Wire: none. diff --git a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md index 8fa01db570a..86db0eff186 100644 --- a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md +++ b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md @@ -45,15 +45,25 @@ every QUIC timeout re-arm is an O(log n) map removal and insertion with `Rc` traffic. The #2875 design note called for a timer wheel. Not urgent at these connection counts, but it is on the same hot path and grows with it. -`moq_net::runtime::Runtime::now` (rs/moq-net/src/runtime.rs:128) is the -natural place to hand the current turn's instant down instead of having each -layer re-read it. Sample once per drive turn and pass it through `fire`, the -`handle_timeout`, and `poll_transmit`. +moq-net's runtime is crate-private now, and its drivers already receive the +current instant from their owner (`Runtime::now`, "the latest instant +supplied by the owner", in `rs/moq-net/src/runtime.rs`); moq-uring's worker +passes `Instant::now()` to `driver.poll` once per poll +(`rs/moq-uring/src/worker.rs`). Sample once per drive turn there and pass +that instant through `fire`, the `handle_timeout`, and `poll_transmit`. + +Decided in the 2026-10-05 audit: this edits the QUIC connection driver the +[hard fork](/quest/m1/quic/fork/README.md)'s switch renames and moves onto +`moq-quic`, so it waits for the fork and is measured there. Acceptance: `[vdso]` share in the `perf` profile on both flavors, relay CPU via `just bench BASE` on Linux, and the existing keep-alive and idle-timeout tests unchanged. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the driver this edits moves onto `moq-quic` + ## Closes - [#3122](https://github.com/moq-dev/moq/issues/3122) - close this issue when the quest finishes diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index da0792c0dda..043c86cc3c0 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -19,6 +19,10 @@ Quests branch from main unless they say otherwise. Planning quests can settle their contracts independently. Facts from the 2026-09 hot-path survey, so quests don't re-litigate them: +- Decided in the 2026-10-05 audit: perf quests that edit moq-uring's QUIC + driver (#3122, Run to quiescence) Require the + [hard fork](/quest/m1/quic/fork/README.md), so their before and after are + measured on `moq-quic` instead of being invalidated by the switch. - `moq-uring`'s only backend is noq. Every profile names its backend. The historical quiche-flavor numbers cited in [Run to quiescence](/quest/m1/perf/uring-quiescence.md) and diff --git a/quest/m1/perf/uring-one-enter.md b/quest/m1/perf/uring-one-enter.md index c6238cdf53c..9d8eb614424 100644 --- a/quest/m1/perf/uring-one-enter.md +++ b/quest/m1/perf/uring-one-enter.md @@ -36,6 +36,12 @@ glommio, and compio all fold the tick's submit into the park enter. fixed-bucket histogram of SQEs per enter and CQEs per enter, one row per worker. `enters` stays for the ratio the docs already describe. +Decided in the 2026-10-05 audit: driver-touching perf work waits on the +[hard fork](/quest/m1/quic/fork/README.md). This quest's worker loop, +`Shared::push`, and metrics changes do not touch the QUIC driver +(`rs/moq-uring/src/quic/noq`), so it can land first; any part that turns out +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. diff --git a/quest/m1/perf/uring-quiescence.md b/quest/m1/perf/uring-quiescence.md index 35b6f0bef0e..42254f0849b 100644 --- a/quest/m1/perf/uring-quiescence.md +++ b/quest/m1/perf/uring-quiescence.md @@ -49,5 +49,6 @@ meaning with a budget of 1 and gains a sibling proving the budget bound. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the noq driver this edits moves onto `moq-quic` (decided in the 2026-10-05 audit) - [One enter per turn](/quest/m1/perf/uring-one-enter.md) - the metrics and the submit placement this sweep is measured with diff --git a/quest/m1/publish-audio-channel-count.md b/quest/m1/publish-audio-channel-count.md index a1966bbbb16..63f4bad8f5e 100644 --- a/quest/m1/publish-audio-channel-count.md +++ b/quest/m1/publish-audio-channel-count.md @@ -15,10 +15,13 @@ decide. ## Plan -`js/publish/src/audio/capture.ts:178` sets +`js/publish/src/audio/capture.ts:245` sets `channelCountMode: requestedChannels !== undefined ? "explicit" : "max"`, so supplying `channelCount` is what puts the AudioWorklet behind a forced Web -Audio downmix. The `"max"` path, taken when the field is omitted, does not. +Audio downmix. Omitting it does not always take the `"max"` path: +`requestedChannels` (`capture.ts:183`) falls back to `requestedChannelCount`, +so an applied `getUserMedia` channelCount constraint forces `"explicit"` too. +Account for that path when isolating the cause. What was measured, on macOS headless Chromium through `just test media`, publishing a `MediaStreamAudioDestinationNode` track into a graph already @@ -41,7 +44,7 @@ What is not established, and should be first: 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:141`) exists for the macOS + default. `requestedChannelCount` (`capture.ts:318`) 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 3d70c72e364..b16bfc3a7ee 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -37,6 +37,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 - [Starvation](/quest/m1/qos/starvation.md) - per broadcast, how far behind the acknowledged frontier of its subscriptions is, in media time, plus the media dropped before it was acknowledged diff --git a/quest/m1/qos/lag-splice.md b/quest/m1/qos/lag-splice.md new file mode 100644 index 00000000000..3b506c5d128 --- /dev/null +++ b/quest/m1/qos/lag-splice.md @@ -0,0 +1,52 @@ +# [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. + +## Related + +- [Final lag sample](/quest/m1/qos/final-lag-sample.md) - the drop-time sample on the same sampler diff --git a/quest/m1/qos/publisher-timeliness.md b/quest/m1/qos/publisher-timeliness.md index 682ae47d869..1a976155556 100644 --- a/quest/m1/qos/publisher-timeliness.md +++ b/quest/m1/qos/publisher-timeliness.md @@ -37,10 +37,11 @@ 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. Pre-lite-05 -peers without a timescale stamp frames with `Timestamp::now()`, which would -read as perfectly on time; leave those tracks out of the histogram rather than -report a fiction. Update the stats section of `doc/bin/relay/config.md`. +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 +[Untimed model](/quest/m1/untimed-model.md) they arrive untimed. 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 @@ -51,6 +52,8 @@ excluded. ## Related +- [Untimed model](/quest/m1/untimed-model.md) - pre-lite-05 tracks arrive untimed instead of stamped on arrival + - [Starvation](/quest/m1/qos/starvation.md) - the egress half, same histogram shape - [Media stats](/quest/m1/stats/schema.md) - the publisher's own view diff --git a/quest/m1/quest-flat-lines.md b/quest/m1/quest-flat-lines.md index 7682890425d..4cfbbd4e3bb 100644 --- a/quest/m1/quest-flat-lines.md +++ b/quest/m1/quest-flat-lines.md @@ -56,10 +56,17 @@ Interview paper trail (โœ… marks the choice): Remaining: - Land each line's umbrella PR with `/quest-complete`, then delete its branch: - #4162 audio-jitter-target, #4403 wildcard, #4034 archive (with #4255 folded - in), #4039 auth, #4079 cpp, #4519 ffi-shape, #4080 obs-moq-video, #4133 qos, - #4437 rs2ts (with #4438 folded in), #4653 test-flakes-2, #4180 - transport-upgrade, #4640 tstd. + #4403 wildcard, #4034 archive, #4039 auth, #4079 cpp, #4519 ffi-shape, + #4080 obs-moq-video, #4133 qos (held until + [Lag across a splice](/quest/m1/qos/lag-splice.md) is fixed), #4437 rs2ts, + #4653 test-flakes-2, #4180 transport-upgrade, #4640 tstd. #4162 + (audio-jitter-target) landed, and #4438 folded into rs2ts. +- Fold #4255 (archive/track-timeline) into the archive branch before #4034 + lands; as of the 2026-10-05 audit it has not happened and #4034 is a draft. +- Before a line lands and its branch is deleted, merge or retarget every child + PR still based on it, or GitHub closes it with the branch. As of the + 2026-10-05 audit: #4645 (tstd/delay, retarget to `main` after #4640), + #4732 (ffi-shape/request-accept), and #4675 (auth/request-token). Done when `flake.nix` pins the new quest, no `quest/*README` branch remains, and `quest check` passes. diff --git a/quest/m1/quic/bbr-app-limited.md b/quest/m1/quic/bbr-app-limited.md index 90fc3e496ce..6d819956549 100644 --- a/quest/m1/quic/bbr-app-limited.md +++ b/quest/m1/quic/bbr-app-limited.md @@ -8,7 +8,7 @@ regression test in the fork proves it. ## Plan -moq-dev/noq#5 (in moq-noq 1.3.1; main pins 1.3.2) fixed the label bug this +moq-dev/noq#5 (in moq-noq 1.3.1; `main` pins 2.0.1 and `release` 1.3.3) fixed the label bug this quest was opened for. The transport calls `Controller::on_app_limited` on every empty poll that nothing held back, and BBR marks starvation before the next send. Its tests cover streams, datagrams, batched ACKs, and backlogs diff --git a/quest/m1/quic/fork/README.md b/quest/m1/quic/fork/README.md index fddb6cc6fcb..622e3af694d 100644 --- a/quest/m1/quic/fork/README.md +++ b/quest/m1/quic/fork/README.md @@ -45,7 +45,7 @@ them: advisories noq is missing; `release` stays on `moq-noq` until the next cut. [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) only tracks iroh's upstream noq, which the fork does not replace. -- **moq-dev/noq is frozen**: security patches for `main` only, archived once +- **moq-dev/noq is frozen**: security patches for `release` only, archived once no released MoQ crate depends on it. The other [QUIC quests](/quest/m1/quic/README.md) wait for this line and land in-tree. diff --git a/quest/m1/quic/reliable-reset.md b/quest/m1/quic/reliable-reset.md index 7ec7024ba82..7087609d6ad 100644 --- a/quest/m1/quic/reliable-reset.md +++ b/quest/m1/quic/reliable-reset.md @@ -40,10 +40,9 @@ header. Callers must not calculate or pass the hidden WebTransport header length. Preserve WebTransport application error codes unchanged on send, receive, and intermediary forwarding. -Use the same state machine from qmux. Because qmux runs over a reliable ordered -transport, serialization acknowledges the committed prefix immediately, but -the receiver must still delay the reset until that prefix is available. Remove -the qmux prototype's local `RESET_STREAM_AT` state once the shared core owns it. +qmux on this shared state machine is [qmux on the QUIC stream state +machine](/quest/m2/quic-qmux.md)'s (moved to m2 in the 2026-09-30 audit); +this quest is native QUIC and WebTransport only. Test negotiation on/off and 0-RTT, loss and reordering of both the frame and prefix data, shrinking Reliable Size, reset after FIN, flow-control blocking, diff --git a/quest/m1/quic/scheduler.md b/quest/m1/quic/scheduler.md index 6cad87bb3ad..661f8cb01e2 100644 --- a/quest/m1/quic/scheduler.md +++ b/quest/m1/quic/scheduler.md @@ -115,7 +115,7 @@ where the new implementation makes it redundant. - [moq#3320](https://github.com/moq-dev/moq/pull/3320) - removes the current dense-rank queue from the wide scalar path and records why a scalar cannot provide this fairness level -- [Ladder controller](/quest/m2/ladder/controller.md) - rendition priority is +- [Ladder controller](/quest/m3/ladder/controller.md) - rendition priority is 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 diff --git a/quest/m1/relay-iroh-opt-in.md b/quest/m1/relay-iroh-opt-in.md index 1a3270e8d07..43d431568c2 100644 --- a/quest/m1/relay-iroh-opt-in.md +++ b/quest/m1/relay-iroh-opt-in.md @@ -26,5 +26,5 @@ Guidance: ## Related -- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's -- [P2P](/quest/m2/p2p/README.md) - why moq-cli keeps iroh +- [`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/rendition-preference.md b/quest/m1/rendition-preference.md index 5a9e4c8a2f4..80ae4490e97 100644 --- a/quest/m1/rendition-preference.md +++ b/quest/m1/rendition-preference.md @@ -71,6 +71,10 @@ Decided in planning interviews on 2026-10-01: the field. moq-transcode producing same-size codec fallbacks; the consumer publishes its own. +## Required + +- [Enabled flag](/quest/m1/catalog-enabled.md) - the `enabled` field selection filters on first + ## Related - [JS rendition ranking](/quest/m1/js-ranked.md) - mirrors `Video::ranked` in `@moq/hang`, which sorts by preference first once this quest lands diff --git a/quest/m1/route-wakes.md b/quest/m1/route-wakes.md index 1e5352b2902..f2a5999179b 100644 --- a/quest/m1/route-wakes.md +++ b/quest/m1/route-wakes.md @@ -69,6 +69,7 @@ Public API: none. Wire: none. ## Required +- [Wildcard](/quest/m0/wildcard/README.md) - `sync_route`, `poke_below`, and the `origin/pool_churn` bench this reworks exist only on its line branch - [Viewer sessions share a front](/quest/m0/shared-fronts.md) - re-keys fronts, which this index hangs off; it lands after the wildcard line, which is where the pool code lives ## Related diff --git a/quest/m1/rs2ts/README.md b/quest/m1/rs2ts/README.md index c315b490c1b..c31e41c8762 100644 --- a/quest/m1/rs2ts/README.md +++ b/quest/m1/rs2ts/README.md @@ -53,9 +53,6 @@ anything else is generated. The IETF half (the sans-IO IETF session, generated IETF, and the IETF parameters quest on this line's branch) moved to m2 and waits on that go. -PR #4455 (branch `quest/m1/rs2ts/lite-leading-ones`) changes the lite-07 -varint wire and no quest tracks it; it coordinates with -[subscribe drop](/quest/m1/subscribe-drop.md)'s lite-07 edits. This README's own work is the no-downgrade report once generated lite ships: bundle size, per-frame CPU, and first-frame latency against the hand-written diff --git a/quest/m1/shaper-step-clock.md b/quest/m1/shaper-step-clock.md deleted file mode 100644 index 24218e78d31..00000000000 --- a/quest/m1/shaper-step-clock.md +++ /dev/null @@ -1,16 +0,0 @@ -# [XS] moq-shaper step test on mock time - -## Goal - -`moq-shaper`'s `a_step_gets_worse_part_way_through` asserts on a -paused or mock clock, not wall-clock latency, so a loaded runner cannot fail it. - -## Plan - -It failed once under a full-suite `just check --all` during the -[#4720](https://github.com/moq-dev/moq/pull/4720) merge (median latency -61.8ms before the 150ms step, 62.0ms after, against an expected +30ms), and -passed alone 3 times. Drive the shaper's delays from a paused Tokio clock or -the crate's own time source, then assert the step on that clock. - -Public API: none. Wire: none. diff --git a/quest/m1/shared-clock.md b/quest/m1/shared-clock.md index f742f84e72f..209609724ae 100644 --- a/quest/m1/shared-clock.md +++ b/quest/m1/shared-clock.md @@ -88,7 +88,7 @@ Decided (2026-10-05): downstream can recover the offset: the section's frame timestamp is the video clock at arrival plus that same offset. The field keeps its size and is clear even in an encrypted section, so TS export and the typed cues of - [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) + [#2279](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) read splice times on the broadcast timeline with no change of their own. - Rejected for SCTE-35: recording the offset in the `mpegts` catalog section for TS export to add (a new catalog field every typed consumer would also have to diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 460fb24dcd3..3f7301d0a85 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -94,7 +94,7 @@ kind. `drafts/draft-lcurley-moq-hang.md` specs the wire. Decided in the 2026-09-30 audit: a Rust encoder adapting its bitrate to viewer -feedback moved to [encoder feedback](/quest/m2/stats-encoder-feedback.md) (m2), +feedback moved to [encoder feedback](/quest/m3/stats-encoder-feedback.md) (m3), along with its open questions. This line only publishes and reads the reports. ## Required @@ -112,5 +112,5 @@ along with its open questions. This line only publishes and reads the reports. - [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other half of a health verdict -- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder +- [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder adapts its bitrate to what its viewers report diff --git a/quest/m1/subscribe-drop.md b/quest/m1/subscribe-drop.md index 6b836be43c5..97fc1d714ec 100644 --- a/quest/m1/subscribe-drop.md +++ b/quest/m1/subscribe-drop.md @@ -54,9 +54,6 @@ publisher skipped or never opened ends the track without waiting out the grace. Decided in the 2026-09-30 audit: the case moved here so the basic tail interop could land first. -PR #4455 (`quest/m1/rs2ts/lite-leading-ones`) also edits the lite-07 wire -(varints) and no quest tracks it; coordinate the draft's lite-07 changelog -with it. ## Related diff --git a/quest/m1/subscribe-live-time.md b/quest/m1/subscribe-live-time.md index d4d066fdd0a..b3fe3b09b75 100644 --- a/quest/m1/subscribe-live-time.md +++ b/quest/m1/subscribe-live-time.md @@ -7,13 +7,19 @@ 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. -Today (since [#4741](https://github.com/moq-dev/moq/pull/4741)) a front caches -nothing: its readers read the serving route's copy directly, and a track nobody -reads drops that copy, so an idle cache is never served. lite-07 SUBSCRIBE_OK -carries the largest position from the publisher's cache, which nothing reads yet. -A budget judges a group by where its successor starts, so past a gap an old -group's reach stays open. Re-scope before starting: the idle-cache case that -motivated this is gone. +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 diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 4a8a160150a..5ed8d2c2fb8 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -36,9 +36,7 @@ relay bounds a sparse FETCH only if the model can request ranges: locally missing groups becomes one standalone range FETCH, capped below the upstream's live group (which arrives via SUBSCRIBE), so it never blocks. moq-transport caps a FETCH at the Largest Object, so it can return the live - group's existing prefix but never wait for its future objects. Open: whether - the current joining FETCH for that prefix (a SUBSCRIBE starting mid-group - whose head isn't cached) stays, which today's bridge relies on. Downstream, + group's existing prefix but never wait for its future objects. Downstream, an IETF FETCH is served from the model's ranges, capped at the Largest Object. - Ranges are frame-precise (`Position`), not whole groups. The IETF joining diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 2112b134323..e404e0a471c 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -1,16 +1,35 @@ -# [M] JS ranges +# [L] JS ranges ## Goal `@moq/net` matches Rust: `Subscription` carries ranges and order, the lite-07 SUBSCRIBE carries them on the wire, FETCH is gone from lite-07, and -`fetchGroup` becomes a one-range subscription or is removed. +`fetchGroup` becomes a one-range subscription or is removed. A JavaScript +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. +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 +on-demand request surface takes range requests from the start instead of the +per-group `requested_group` shape Rust is replacing. That quest keeps only +IETF FETCH dispatch. Resized from [M] to [L] for it. + +- Expose an owned request handle rather than a storage callback; dropping a + request refuses it rather than leaving the subscriber waiting. Preserve + group sequence, frame boundaries, payload bytes, and track properties. + Storage, retention, and media catalog interpretation stay outside `js/net`. +- One logical dynamic track per broadcast and name: a cache-miss request + never creates a duplicate live producer. +- Verify with an in-memory responder, without OPFS or an archive writer: a + browser publisher serves a native subscriber after a group is evicted or + was never cached, covering exact replay, empty and missing groups, + concurrent requests, and cancellation while awaiting a reply. + ## Required - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the wire this speaks +- [Dynamic track identity](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - settles shared producer identity before adding on-demand requests diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 06706316338..61488389805 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -17,6 +17,10 @@ Guidance: request needs a rule. For example, the union of ranges, and desc wins when orders conflict. Decide it and write it down. - Replace `requested_group` and `fetch_group` rather than keep both. Update - every caller (relay, moq-archive, hls, the ladder) in the same PR. + every caller (relay, moq-archive, hls, the ladder) in the same PR, plus the + published surfaces built on them, per the cross-package table: moq-ffi + (`fetch_group`, `requested_group`), moq-c (`poll_requested_group`), every + binding wrapper and its `doc/lib` page, and `moq fetch` through + `moq_relay::fetch_group` (added in the 2026-10-05 audit). - Max Age caps every range. - Benchmark range count and span as separate axes (AGENTS.md fan-out rule). diff --git a/quest/m1/test-flakes-2/media-late-join.md b/quest/m1/test-flakes-2/media-late-join.md index 943532ef8bf..1e5c92dd93a 100644 --- a/quest/m1/test-flakes-2/media-late-join.md +++ b/quest/m1/test-flakes-2/media-late-join.md @@ -20,3 +20,11 @@ compared with `<=`) fails the same way on `main`: 16 frames behind with a 15-frame GOP on 09-24, 09-25, 09-28, and in [#4577](https://github.com/moq-dev/moq/pull/4577). It samples `live` just before the page opens. Treat it as the same flake (decided 2026-10-01). + +Recorded in the 2026-10-05 audit: on the test-flakes-2 line, +[#4719](https://github.com/moq-dev/moq/pull/4719) replaced +`MAX_LATE_JOIN_LAG_FRAMES` in the interop browser check with a +published-keyframe check: the latecomer's presented timestamp must be at or +after the published track's newest keyframe. That fixes the browser lane's +sampling. The original 16-frame failure was never reproduced, so what remains +is the Rust `just test media` late join under load. diff --git a/quest/m1/test-flakes-2/subscription-cut.md b/quest/m1/test-flakes-2/subscription-cut.md index 8819c67ed95..cb0a302430c 100644 --- a/quest/m1/test-flakes-2/subscription-cut.md +++ b/quest/m1/test-flakes-2/subscription-cut.md @@ -12,3 +12,11 @@ It ends `Ok(None)` with 10 of 20 frames in 3 of 8 full-suite runs on a clean tree, and passes alone (#4332). A clean end after a publisher disconnect is a real bug if the code can produce it, not only a test race: reproduce under load first, find which path reports the cut as a clean end, and fix it there. + +Recorded in the 2026-10-05 audit: [#4662](https://github.com/moq-dev/moq/pull/4662) +(closed 2026-10-01) did not reproduce it: eight full `moq-tokio` suite runs +passed every test, including this one. #4533 had already hardened +active-stream tail settling, and the aborted groups arrival readers skip are +[SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)'s, which overlaps this. Recheck +under the original broader workspace load, or after SUBSCRIBE_DROP lands, +before fixing anything. diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 171f37a2993..48c57b375ad 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -60,7 +60,7 @@ Direction to settle in the draft first, then the code: - 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 - [ladder controller](/quest/m2/ladder/controller.md), now in m2, wants that + [ladder controller](/quest/m3/ladder/controller.md), now in m3, wants that tiebreak; this quest owns the answer so the controller only consumes it. - 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. diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index e31403931b7..c42b0f3bffa 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -16,16 +16,19 @@ that the two agree across a relay on real QUIC. What stood in the way when the Rust half landed: -- `moq import` exits the moment stdin ends, closing its session with the tail - still in flight, so a finite CLI publisher cannot end a track cleanly. The - fix is a publisher that waits for its subscriptions to drain before it - closes; `moq export ts --linger` is the reader-side cousin. +- `moq import` exiting the moment stdin ends is cleared: since #4430 a + graceful close delivers finished tracks at stdin EOF. - The native JS subscriber (`test/interop/clients/js-native`) returns on the first frame. It needs a mode that reads a track to its end and reports how it ended and which groups it saw. The harness exposed a relay start-floor defect: when a newer group arrives -first, earlier in-flight groups can be lost. #4387 fixed it (merged 09-28). +first, earlier in-flight groups can be lost. #4387 (merged 09-28) fixed that +case, but the tail lanes still fail on this quest's PR #4225 after it: Interop +run 37139033242 (2026-10-03) failed `tail rust -> rust`, `rust -> +js-native-node`, and `rust -> js-native-bun`. Merge `main` (after #4741 and +#4813) into #4225, rerun, and record here whatever defect still fails; the +cause is untracked until then. Decided in the 2026-09-30 audit: the lite-07 drop case moved into [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)'s tests, so the basic Rust and diff --git a/quest/m1/transport-upgrade/README.md b/quest/m1/transport-upgrade/README.md index 3f5e03c10a7..91cbd58f60a 100644 --- a/quest/m1/transport-upgrade/README.md +++ b/quest/m1/transport-upgrade/README.md @@ -30,9 +30,10 @@ keeps the old session serving until it closes or overstays the handover cap, reports `Status::Migrating`, and `moq_net::Session::drain()` sends a GOAWAY on every version (a client may send one with an empty URI; only a redirect URI is forbidden to a moq-transport client). The origin's multi-route front prefers -the newest of two equal routes, and #4741's pump (`model/pump.rs`) resumes each -track from the new route at the first frame the subscriber lacks, cancelling -the old session's subscription once the new one feeds it. The JavaScript +the newest of two equal routes, and since #4741 a front resumes each track +from the new route's copy at the first frame the subscriber lacks +(`model/resume.rs`), cancelling the old session's subscription once the new +one feeds it. The JavaScript GOAWAY handover landed with the drain line, but it does not resume tracks yet; the JS half requires [JS track handover](/quest/m1/js-group-handover.md) for that. @@ -47,7 +48,7 @@ Shared decisions: narrowly beats QUIC would open two connections on every reconnect. - The old session gets `Goaway::new()` with the configured handover cap before it enters draining. The relay refuses new requests on it from then on; the - pump cancels its subscriptions once the new session feeds them. + front cancels its subscriptions once the new session feeds them. - One-shot `connect()` returns one session and never upgrades; every `Connection` upgrades, reconnecting or not. - Publishing over the old session is announced again over the new one; the diff --git a/quest/m1/ts-aac-pce-join.md b/quest/m1/ts-aac-pce-join.md index e31f2e1ff99..c519dee1bb4 100644 --- a/quest/m1/ts-aac-pce-join.md +++ b/quest/m1/ts-aac-pce-join.md @@ -10,19 +10,24 @@ missing PCE silences that one track instead of failing the whole program. Found in review of the audio-codecs line (#4081), 2026-09-30. -- Import: `aac::in_band_config` returns `ProgramConfigMissing` when the first - frame seen has no leading PCE, and `?` ends the whole TS import, video - included (`rs/moq-mux/src/container/ts/import.rs`). Instead, keep the - reservation, drop frames on that track until one leads with a PCE, and log - once. ffmpeg's ADTS muxer writes the PCE only in the first frame, so a late - join of an ffmpeg source stays silent; say so in the docs. +- Import: since #4733 a missing PCE no longer ends the import; it is a + Damaged unit (`unit_error` in `rs/moq-mux/src/container/ts/import.rs`). But + the AAC track still holds its catalog reservation until a PCE arrives, and + the catalog is withheld until every reservation drops + (`rs/moq-mux/src/catalog/producer.rs`), so a late join to an ffmpeg source + publishes nothing, video included. Decided in the 2026-10-05 audit: a + PCE-less AAC track releases its reservation, the catalog publishes without + it, and the track is added when a PCE arrives. Rejected: keeping the + reservation and withholding the program. ffmpeg's ADTS muxer writes the PCE + only in the first frame, so a late join of an ffmpeg source plays without + that AAC track; say so in the docs. - Export: `mux` takes the PCE on the first frame only (`rs/moq-mux/src/container/ts/export.rs`), so `resume()`/`rewind()` and any mid-stream receiver never see it. Repeat it, either on every frame or with each PAT/PMT, and pick whichever ffmpeg and the import side accept. - Regression: an export resumed before its first span re-emits the PCE, and an - import that starts on a PCE-less frame publishes the track once a PCE - arrives, while the other tracks keep flowing. + import that starts on a PCE-less frame publishes its catalog with the other + tracks at once, then adds the AAC track once a PCE arrives. Public API: none. Wire: none; TS output gains repeated PCEs. diff --git a/quest/m1/ts-export-rewind.md b/quest/m1/ts-export-rewind.md deleted file mode 100644 index a4c6e797c79..00000000000 --- a/quest/m1/ts-export-rewind.md +++ /dev/null @@ -1,52 +0,0 @@ -# [S] TS export restarts its clock only for a new timeline - -## Goal - -`moq export ts` keeps its program clock running through gaps and sets the PCR -`discontinuity_indicator` only when the clock really restarts: a `--linger` -resume or a replaced broadcast. One resume flags once. A track whose timestamps -restart within one broadcast fails the export. - -## Plan - -`rs/moq-mux/src/container/ts/export.rs` emits the PCR on a fixed media-time -grid and fills every slot a gap crosses, so a forward gap already keeps the -clock continuous. But it calls `rewind()`, restarting the whole program clock -and setting the flag, whenever any track's consumer generation changes, and -the consumer bumps its generation on a latency skip or gap walk too. Catching -up on a resume backlog therefore rewinds up to four extra times. - -Decided (2026-10-04): - -- A forward gap on any track, however long, is filled on the PCR grid; the - clock keeps running and nothing is flagged. With `mux_rate` padding the - export already emits null packets through quiet periods. -- Restart the clock and set the flag only on a resume or a replaced - broadcast. -- Timestamps restarting within one broadcast are a publisher bug (a name - always means the same content), so the export fails with an error rather - than rewinding. The only input timestamp is the frame's PTS, and it legally - moves backwards in decode order with B-frames (0, 120, 40, 80 ms); the - authored DTS cannot show a reset, since `author_dts` clamps every backwards - candidate to `prev + 1`. So the check runs on PTS before that clamp, and is - group-aware: reordering, including open-GOP leading pictures, stays inside - a group, so a frame whose PTS is below the largest PTS of the track's - previous group is a reset. -- No new public API: the generation-change handling lives behind the - crate-private `ExportSource`. -- [Fixed-delay release](/quest/m1/tstd/delay.md) rewrites the same release - path and re-anchors on each rewind; land this inside or after it. - -Tests: a resume that walks gaps on two tracks sets the indicator once; a 10 s -forward gap on one track keeps the PCR continuous with no flag; a source whose -timestamps restart at zero after 10 s fails the export, while a B-frame -sequence and open-GOP leading pictures are still accepted. - -## Closes - -- [#4767](https://github.com/moq-dev/moq/issues/4767) - close this issue when the quest finishes - -## Related - -- [Fixed-delay release](/quest/m1/tstd/delay.md) - re-anchors the release clock on each rewind -- [TS hitless](/quest/m2/ts-hitless.md) - discontinuity flags across a source switch diff --git a/quest/m1/ts-stats-module.md b/quest/m1/ts-stats-module.md index 8cf07e12262..6446be95b26 100644 --- a/quest/m1/ts-stats-module.md +++ b/quest/m1/ts-stats-module.md @@ -31,8 +31,13 @@ Decided while planning the follow-ups of - Update moq-cli's `publish.rs`, the only consumer that names these types. moq-srt only uses `stats::Log`. - Main still adds fields under the old names: #4584 added `crc_error`, and - the TR 101 290 counters added more. `Export::stats` - (#4577) also returns the old `ts::Stats`. The rename carries those at merge time. Update the type names in the quests still open + the TR 101 290 counters added more. The rename carries those at merge time. +- **One stats module for all TS stats** (decided in the 2026-10-05 audit). + `Export::stats` (#4577) returns the import's `ts::Stats` on `main`, and + [Fixed-delay release](/quest/m1/tstd/delay.md) (#4645) adds its own + `ts::export::Stats`. Both become `ts::stats::Export`, beside `Snapshot` and + `Stream`; whichever of #4645 and this quest lands second renames it. + Rejected: `ts::export::Stats` with this quest narrowed to the import. Update the type names in the quests still open when this lands, including [media stats schema](/quest/m1/stats/schema.md) and [Rust reporters](/quest/m1/stats/rust.md). diff --git a/quest/m1/tstd/delay.md b/quest/m1/tstd/delay.md index 307ef343d83..1e868206c20 100644 --- a/quest/m1/tstd/delay.md +++ b/quest/m1/tstd/delay.md @@ -60,12 +60,36 @@ order PTS 0, 120, 40, 80) loses nothing on a clean path. It must pass before the hold is deleted. Rerun the #4613 netem rig (10% loss, 120 s) and compare with #4618's numbers. +Decided in the 2026-10-05 audit: TS export rewind folds in here, since +#4645's jitter generations already keep the clock through a skipped group and +flag a PCR break only on a declared restart. What it still owes is the +backwards-time check: timestamps restarting within one broadcast are a +publisher bug (a name always means the same content), so the export fails +with an error rather than rewinding. The only input timestamp is the frame's +PTS, which legally moves backwards in decode order with B-frames (0, 120, 40, +80 ms), and the authored DTS cannot show a reset since `author_dts` clamps +every backwards candidate to `prev + 1`. So the check runs on PTS before that +clamp and is group-aware: a frame whose PTS is below the largest PTS of the +track's previous group is a reset. Test: a source whose timestamps restart at +zero after 10 s fails the export, while a B-frame sequence and open-GOP +leading pictures are still accepted. + +#4645 also completes [TS byte schedule](/quest/m1/tstd/byte-schedule.md); +delete both quests in it. It targets the retiring line branch, so retarget it +to `main` once the line (#4640) lands, and merge `main` in. + Update `doc/bin/cli.md` and the `moq export ts` examples. Public API: `ts::Export` takes the delay in place of its max age and loses the -hold; breaking. Wire: +hold; breaking. `Export::stats` returns `ts::stats::Export` (decided in the +2026-10-05 audit, matching [TS stats module](/quest/m1/ts-stats-module.md)), +not a new `ts::export::Stats`. Wire: none. +## Closes + +- [#4767](https://github.com/moq-dev/moq/issues/4767) - TS export rewinds its clock on every generation change + ## Related - [FLV export delay](/quest/m1/flv-export-delay.md) - adopts the release stage diff --git a/quest/m1/untimed-failover.md b/quest/m1/untimed-failover.md index 9e3abca8f04..7721f7f599a 100644 --- a/quest/m1/untimed-failover.md +++ b/quest/m1/untimed-failover.md @@ -57,4 +57,4 @@ Public API: none. Wire: none. ## Related - [JS track handover](/quest/m1/js-group-handover.md) - mirrors this rule in JS -- [Wall-clock age-out](/quest/m1/cache-wall-eviction.md) - retention of untimed groups, not a blocked reader +- [One max_age meaning](/quest/m1/cache-max-age.md) - retention of untimed groups, not a blocked reader diff --git a/quest/m1/untimed-model.md b/quest/m1/untimed-model.md index ecee372f9ab..5f972deb8af 100644 --- a/quest/m1/untimed-model.md +++ b/quest/m1/untimed-model.md @@ -131,5 +131,5 @@ published drafts change as the timestamp draft says. - [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) - drafts 14-16 stop sending timestamps without units, which then arrive untimed - [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - opting out of properties today falls back to arrival time - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - relay ingest measures arrival minus timestamp, and must skip untimed frames -- [Plan: cache age-out](/quest/m1/cache-wall-eviction.md) - whatever it decides, untimed groups age out only through the pool's expiry +- [One max_age meaning](/quest/m1/cache-max-age.md) - whatever it decides, untimed groups age out only through the pool's expiry - [Translator](/quest/m1/rs2ts/translator.md) - flags the nested `Option` in first-start resolution this touches diff --git a/quest/m1/video-auto-creep.md b/quest/m1/video-auto-creep.md new file mode 100644 index 00000000000..f67851da68b --- /dev/null +++ b/quest/m1/video-auto-creep.md @@ -0,0 +1,36 @@ +# [S] A video-only broadcast's auto target stops creeping + +## Goal + +In `@moq/watch`, a broadcast with no audio played at `"auto"` delay settles +on a target measured from its real arrival timing, instead of creeping upward +one step at a time as it does today. + +## Plan + +Found while landing [#4162](https://github.com/moq-dev/moq/pull/4162), and +planned as a follow-up of the 2026-10-05 audit. `doc/concept/audio-jitter.md` +explains the mechanism: a subscription cut to the target hides every frame +later than the target, so the estimate creeps up one bucket at a time while +the frames it should have measured go unplayed. In automatic mode the browser +escapes that only through the audio subscription, which subscribes with at +least the 2 s ceiling. Browser video keeps the shared subscription budget, +because a longer one fetches whole stale groups, so a video-only broadcast +measures only the lateness that budget lets through. + +- Reproduce first with a recorded or shaped video-only trace, and assert the + target series, as the audio replay tests do. +- Find a way for video to observe late frames without fetching whole stale + groups: for example, observe arrival at the container consumer before the + local budget applies, as audio does, or a separate observation budget. + Weigh the cost of fetching stale groups against a target that never + converges. +- Update `doc/concept/audio-jitter.md` with whatever changes, since it + documents today's limitation. + +Public API: none expected. Wire: none. + +## Related + +- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the estimator and the shared budget this works around +- [A/V clock](/quest/m1/av-clock.md) - the browser's sync between the tracks' targets diff --git a/quest/m1/watch-audio-time-stretch.md b/quest/m1/watch-audio-time-stretch.md index 34134a7e210..5ddae6d6197 100644 --- a/quest/m1/watch-audio-time-stretch.md +++ b/quest/m1/watch-audio-time-stretch.md @@ -29,3 +29,4 @@ 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 +- [A/V clock](/quest/m1/av-clock.md) - the clock the stretch converges toward diff --git a/quest/m2/README.md b/quest/m2/README.md index e6338c65185..bc943f7f47f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -10,15 +10,12 @@ 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 waits in [m3](/quest/m3/README.md); work +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). ## Required -- [P2P](/quest/m2/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy - [One port](/quest/m2/one-port/README.md) - a relay speaks QUIC and STUN on one UDP port and HTTP, RTMP, and RTMPS on one TCP port; WebRTC media is an embedder hook -- [Ladder](/quest/m2/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling -- [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access - [Bitrate claim](/quest/m2/rate-claim.md) - tokens and auth grants cap a session's upload and download bitrate, refused where unenforced and always on HTTP - [QUIC caps](/quest/m2/rate-quic.md) - paced MAX_DATA credit in and a capped pacer out hold a QUIC session to its token's bitrate - [WebSocket caps](/quest/m2/rate-websocket.md) - paced reads and writes over bounded socket buffers hold WebSocket to the same caps @@ -28,15 +25,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [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 -- [fMP4 emsg](/quest/m2/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them -- [ID3 catalog section](/quest/m2/id3.md) - timed ID3 as a first-class container-neutral catalog section -- [FLV script tags](/quest/m2/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import -- [#2279](/quest/m2/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/m2/captions-cea.md) - captions carried inside video SEI become a real text rendition at import -- [Browser archive](/quest/m2/archive-browser.md) - the same contract for browser-published broadcasts -- [Paced replay](/quest/m2/archive-paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end -- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary - [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback - [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback @@ -50,27 +39,24 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [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 - [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 + how far a send stream has been acknowledged and when +- [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the + backend-neutral hook on moq-net's own transport trait that awaits an + acknowledged stream offset, implemented by the moq-tokio and moq-uring adapters - [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 -- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - `moq-quic` reports - how far a send stream has been acknowledged and when -- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the - backend-neutral hook that awaits an acknowledged stream offset, implemented - for noq and released - [#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 -- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder - reads its viewers' feedback and adapts its bitrate -- [Text availability](/quest/m2/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline -- [Closure counters](/quest/m2/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw - [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 the stats producer, 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 +- [SEI separation study](/quest/m2/sei.md) - measure whether separating SEI saves enough, or has a metadata-only consumer, to justify a split - [AV1 metadata separation](/quest/m2/av1-metadata.md) - retain metadata OBUs inline while evaluating separate delivery - [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 @@ -93,7 +79,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [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, and export V4L2 buffers as DMA-BUFs +- [#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 @@ -114,9 +100,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [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 - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it -- [Interop graceful close](/quest/m2/interop-graceful-close.md) - successful runner publications withdraw before disconnecting; external repository approval required - [Egress profile](/quest/m2/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them -- [SEI separation study](/quest/m2/sei.md) - measure whether separating SEI saves enough, or has a metadata-only consumer, to justify a split - [Compressed tracks](/quest/m2/flate.md) - moq-ffi and every wrapper expose flate tracks through a `flate` namespace like `json` - [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table - [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, carrying the cluster route layer @@ -127,5 +111,5 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [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 - [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) - LARGEST_OBJECT, 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 +- [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 - [Dead worklet config](/quest/m2/worklet-dead-config.md) - delete moq-boy's unused worklet plugin and hang's unused `?worker&url` typings diff --git a/quest/m2/announce-shapes.md b/quest/m2/announce-shapes.md index db1263cce2f..5befc5175c2 100644 --- a/quest/m2/announce-shapes.md +++ b/quest/m2/announce-shapes.md @@ -100,7 +100,7 @@ routes independently of Rust. The slopes decide between a reversed-segment index and dropping suffix shapes from the quest. A non-prefix advertisement needs authorizing: -[advertise auth](/quest/m2/processor/advertise-auth.md) scopes are prefix-only +[advertise auth](/quest/m3/processor/advertise-auth.md) scopes are prefix-only today, and this quest extends them to the new shapes. Token patterns (`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. diff --git a/quest/m2/av1-metadata.md b/quest/m2/av1-metadata.md index afc4bec8343..a2a46d23744 100644 --- a/quest/m2/av1-metadata.md +++ b/quest/m2/av1-metadata.md @@ -29,8 +29,10 @@ Preserve `metadata_type`, the payload bytes, and ordering within the temporal unit. Test HDR10+ T.35 metadata, timecode, an unknown metadata type, several OBUs in one temporal unit, and a byte-identical round trip. +## Required + +- [SEI separation study](/quest/m2/sei.md) - this is conditional on its positive verdict + ## Related -- [SEI sidecars](/quest/m2/sei.md) - the H.26x contract this should - follow rather than duplicate -- [fMP4 emsg carriage](/quest/m2/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction +- [fMP4 emsg carriage](/quest/m3/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction diff --git a/quest/m2/browser-media-qa-engines.md b/quest/m2/browser-media-qa-engines.md index c20350bb349..135579bb715 100644 --- a/quest/m2/browser-media-qa-engines.md +++ b/quest/m2/browser-media-qa-engines.md @@ -20,8 +20,8 @@ Neither Playwright Firefox nor Playwright WebKit ships WebTransport, and WebKit also lacks the WebCodecs encoder, so neither can publish and neither can play over QUIC. What they can do is play over the WebSocket fallback. Real Firefox does use WebTransport; only Playwright's build lacks it, so a -fallback run covers the player, not Firefox's transport path (see open PR -[#4460](https://github.com/moq-dev/moq/pull/4460)). +fallback run covers the player, not Firefox's transport path (see +[#4460](https://github.com/moq-dev/moq/pull/4460), merged 2026-10-01). - Split the harness's publisher and subscriber roles so an engine can take one side: a Chromium fixture with a Firefox or WebKit player over the diff --git a/quest/m2/ietf-request-codes.md b/quest/m2/ietf-request-codes.md index 4792cbc0cc2..a2c9a08258d 100644 --- a/quest/m2/ietf-request-codes.md +++ b/quest/m2/ietf-request-codes.md @@ -7,10 +7,6 @@ the way the drafts say, without closing the session. Each answer uses the draft's code, or an existing code where the exact one costs more than it is worth and the fallback is recorded in `doc/concept/standard.md`: -- **LARGEST_OBJECT (0x09) in REQUEST_OK and REQUEST_UPDATE_OK** is - accepted. The draft makes it a MUST when objects exist. Today - `ietf/request.rs` allows only 0x08 and ACTIVE_COUNT, so a conformant - peer's reply closes the session with PROTOCOL_VIOLATION. - **Range Filters** get REQUEST_ERROR INVALID_FILTER (0x36), not 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 @@ -39,6 +35,11 @@ is worth and the fallback is recorded in `doc/concept/standard.md`: Decided with the maintainer on 2026-10-04 and 2026-10-05: +- **LARGEST_OBJECT moved to m0.** Decided in the 2026-10-05 audit: a + REQUEST_OK carrying it closes the session today, which Seattle interop + would hit, so [REQUEST_OK accepts + LARGEST_OBJECT](/quest/m0/ietf-largest-object.md) owns it. + - **Deliberate deviations stay.** DUPLICATE_SUBSCRIPTION and PREFIX_OVERLAP are never sent, because moq-net deduplicates. OBJECT_DELIVERY_TIMEOUT and SUBGROUP_DELIVERY_TIMEOUT never drop an object or reset a subgroup: they @@ -64,4 +65,5 @@ drafts. ## Related +- [REQUEST_OK accepts LARGEST_OBJECT](/quest/m0/ietf-largest-object.md) - the case split out ahead of Seattle - [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) - the session-level half of the same validator report diff --git a/quest/m2/msfts-convergence.md b/quest/m2/msfts-convergence.md index 010289aa5f4..38597b2599e 100644 --- a/quest/m2/msfts-convergence.md +++ b/quest/m2/msfts-convergence.md @@ -26,5 +26,5 @@ lands. [#4577](https://github.com/moq-dev/moq/pull/4577) (per-ES access units at export) has merged, and [#4579](https://github.com/moq-dev/moq/pull/4579) (export on the mux rate) closed in favour of the [T-STD line](/quest/m1/tstd/README.md). -[#4580](https://github.com/moq-dev/moq/pull/4580) (per-program SI) is still -open and touches the same area; land or rebase on it first. +[#4580](https://github.com/moq-dev/moq/pull/4580) (per-program SI) merged on +2026-10-01 and touches the same area. diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index bbef222df9c..f08de8f3807 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -20,8 +20,11 @@ reuseport shard groups are a later consumer, not a blocker. ## Plan -Deferred to m2 in the 2026-09-30 audit: the consumer is moq.pro's edge, SRT is -blocked upstream on srt-tokio, and STUN's only consumer is P2P, also m2. +Deferred to m2 in the 2026-09-30 audit: the consumer is moq.pro's edge, and +STUN's only consumer is P2P, now in m3. SRT is not blocked upstream: +[SRT demux](/quest/m2/one-port/srt-demux.md) decided on 2026-09-30 to drive +sans-io `srt-protocol` directly instead of waiting on a socket abstraction in +srt-tokio. ### Classifying a datagram @@ -49,8 +52,10 @@ fanned into virtual sockets, one per stack, each with the `AsyncUdpSocket` shape. Sends go straight to the shared socket, so every stack answers from the same address and port. noq accepts the virtual socket through `new_with_abstract_socket`. `moq-rtc`'s `Mux` already demuxes STUN by ufrag internally and only -needs a `feed` entry beside its `recv_from` loop. `srt-tokio` accepts a -`tokio::net::UdpSocket` but no abstraction; that is its own quest. +needs a `feed` entry beside its `recv_from` loop. SRT skips `srt-tokio`, +which accepts a `tokio::net::UdpSocket` but no abstraction, and feeds +datagrams to sans-io `srt-protocol` as [SRT demux](/quest/m2/one-port/srt-demux.md) +decided. ### STUN @@ -82,5 +87,5 @@ pre-accepted streams can stand behind. ## Related -- [P2P](/quest/m2/p2p/README.md) - the client that names the relay as its STUN server +- [P2P](/quest/m3/p2p/README.md) - the client that names the relay as its STUN server - [Stream sessions](/quest/m2/uring-tcp/README.md) - the io_uring workers that would host the same demux later diff --git a/quest/m2/one-port/udp-demux.md b/quest/m2/one-port/udp-demux.md index 9b44ff448ca..0ded76d93b0 100644 --- a/quest/m2/one-port/udp-demux.md +++ b/quest/m2/one-port/udp-demux.md @@ -54,4 +54,4 @@ Binding round trip against one bound port. `moq-relay` docs list the port once. ## Related -- [P2P](/quest/m2/p2p/README.md) - the client side of the STUN answer +- [P2P](/quest/m3/p2p/README.md) - the client side of the STUN answer diff --git a/quest/m2/quic-ack-hook.md b/quest/m2/quic-ack-hook.md index 9dbb125ee1c..c6d4a27bbc0 100644 --- a/quest/m2/quic-ack-hook.md +++ b/quest/m2/quic-ack-hook.md @@ -1,17 +1,24 @@ -# [S] web-transport-trait awaits an acknowledged stream offset +# [S] moq-net's send stream awaits an acknowledged offset ## Goal -A released `web-transport-trait` lets a sender await acknowledgment of a -named byte offset on a send stream, `web-transport-moq` implements -it, and every other backend reports that it cannot rather than returning a -guess. +moq-net's own `transport::poll::SendStream` lets a sender await +acknowledgment of a named byte offset on a send stream, the moq-tokio and +moq-uring adapters implement it over `moq-quic`, and every other backend +reports that it cannot rather than returning a guess. ## Plan -The trait method lives in `moq-dev/web-transport`. The `web-transport-moq` -adapter is in-tree after [the fork](/quest/m1/quic/fork/README.md). This quest supersedes the design in moq-dev/web-transport#368, -whose snapshot-counter shape loses the wakeups a latency sample needs. +Decided in the 2026-10-05 audit: re-planned on moq-net's own transport +traits. [moq-net owns its transport seam](/quest/m1/transport-seam.md) +removes moq-net's `web-transport-trait` dependency, so moq-net could not call +a hook that exists only upstream. The method lives on +`rs/moq-net/src/transport.rs`'s `poll::SendStream`, implemented by the +moq-tokio and moq-uring adapters (the in-tree web-transport-moq after +[the fork](/quest/m1/quic/fork/README.md)); no `web-transport-trait` release +is needed. Rejected: keeping the method upstream. This quest supersedes the +design in moq-dev/web-transport#368, whose snapshot-counter shape loses the +wakeups a latency sample needs. Add one method to `SendStream`, in the trait's poll style: @@ -29,8 +36,8 @@ use. A default body cannot construct a backend's own `Self::Error`, so unsupported has to live in the return type rather than the error, and a consumer must treat `None` as unknown, never as delivered. -Implement it in `web-transport-moq` over `moq-quic`'s accessor. Leave -`web-transport-wasm` on the default; the browser's `WebTransportSendStream.getStats()` is +Implement it in the moq-tokio and moq-uring adapters over `moq-quic`'s +accessor. Leave the browser transport on the default; the browser's `WebTransportSendStream.getStats()` is unimplemented in shipping Chrome and its `bytesAcknowledged` is at risk in the W3C draft. qmux over a reliable transport may treat serialization as acknowledgment only if the qmux quest decides that is honest; until then it @@ -41,13 +48,13 @@ the middle of an in-flight frame, several waiters on one stream in offset order, a waiter whose offset lies beyond the final size, reset by sender, STOP_SENDING by the receiver, and session close. -Cut a `web-transport-trait` release; the adapter lands in-tree against it. Decided in the 2026-09-30 audit: moved to m2 with its only consumer, [frame-granularity starvation](/quest/m2/starvation-frames.md). ## Required +- [moq-net owns its transport seam](/quest/m1/transport-seam.md) - the moq-net trait this method lives on - [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - the `moq-quic` accessor the adapter reads diff --git a/quest/m2/quic-ack-progress.md b/quest/m2/quic-ack-progress.md index cca026beb77..812cfb349dc 100644 --- a/quest/m2/quic-ack-progress.md +++ b/quest/m2/quic-ack-progress.md @@ -44,6 +44,6 @@ hook and [frame-granularity starvation](/quest/m2/starvation-frames.md). ## Related -- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the first +- [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the first consumer of the accessor - [noq#808](https://github.com/n0-computer/noq/issues/808) - the acked-offset ask to n0 diff --git a/quest/m2/quic-bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md index 1b6d118264f..a2a65d97061 100644 --- a/quest/m2/quic-bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -10,7 +10,8 @@ citations point at draft-06. ## Plan The lost-packet sample gap remains after the seven correctness fixes in -`noq-proto/src/congestion/bbr3/mod.rs` in moq-dev/noq: +BBR3 (`noq-proto/src/congestion/bbr3/mod.rs` today), which the +[hard fork](/quest/m1/quic/fork/README.md) re-ports into `moq-quic`: - Loss handling reuses the shared ACK sample (`self.rs`) as scratch space, and skips the inflight-too-high check when a loss arrives before any ACK @@ -25,8 +26,9 @@ requires. Preserve that behavior and its regression. While in the file, move the remaining draft-05 links and renamed pseudocode identifiers (such as `probe_up_acked_per_inc`) to draft-06; comment-only. -Start from released 1.3.1 or newer, without waiting for the broader QUIC stack -release. Add failing regressions on the shared test `Sim`: a loss before the +Decided in the 2026-10-05 audit: this waits on the hard fork, which the +maintainer prioritizes, and lands in `moq-quic`'s BBR3, not in the frozen +moq-dev/noq. Add failing regressions on the shared test `Sim`: a loss before the first ACK sample, and a loss between ACKs that must not alter the next ACK's sample. Retain the spurious-loss undo coverage through Refill. Internal only; no `Controller` or wire change. diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index 8bb1d76428b..52f7e80e969 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -29,6 +29,13 @@ 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. @@ -39,4 +46,5 @@ deadline; the maximum knob shortens the period. ## 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 diff --git a/quest/m2/quic-qmux.md b/quest/m2/quic-qmux.md index 5e1cf97bfc3..18c5dd3da19 100644 --- a/quest/m2/quic-qmux.md +++ b/quest/m2/quic-qmux.md @@ -46,7 +46,12 @@ making the whole QUIC connection public. `RESET_STREAM_AT` is a QUIC extension, not a qmux-specific frame. Once the reliable-reset quest lands, make qmux drive that shared send and receive state -instead of retaining the prototype's local parsing and transitions. +instead of retaining the prototype's local parsing and transitions. Because +qmux runs over a reliable ordered transport, serialization acknowledges the +committed prefix immediately, but the receiver must still delay the reset +until that prefix is available. Remove the qmux prototype's local +`RESET_STREAM_AT` state once the shared core owns it (moved here from +reliable reset in the 2026-10-05 audit). Carry the hierarchical send groups from the scheduler quest into qmux's record writer. Qmux over TCP, TLS, WebSocket, Unix sockets, and in-memory diff --git a/quest/m2/rate-quic.md b/quest/m2/rate-quic.md index 42858a73cc6..324057823f8 100644 --- a/quest/m2/rate-quic.md +++ b/quest/m2/rate-quic.md @@ -65,8 +65,5 @@ the same. ## Required - [Hard fork](/quest/m1/quic/fork/README.md) - the credit and pacer changes land in `moq-quic` +- [Peer limits](/quest/m1/quic/peer-limits.md) - adds the runtime `set_limits(Limits)` seam and shrink-as-debt behavior this extends - [Bitrate claim](/quest/m2/rate-claim.md) - the cap this enforces - -## Related - -- [Peer limits](/quest/m1/quic/peer-limits.md) - the same runtime limits seam, raised for cluster peers diff --git a/quest/m2/sei.md b/quest/m2/sei.md index 369c8d583b8..45829c93477 100644 --- a/quest/m2/sei.md +++ b/quest/m2/sei.md @@ -35,5 +35,5 @@ line without affecting captions or unrelated timed-metadata carriage. ## Related - [Catalog colour model](/quest/m2/color-catalog.md) - preserves display metadata semantics -- [fMP4 emsg](/quest/m2/emsg.md) - independently settles carriage for metadata already outside video -- [CEA-608/708](/quest/m2/captions-cea.md) - can read inline caption SEI without waiting for this experiment +- [fMP4 emsg](/quest/m3/emsg.md) - independently settles carriage for metadata already outside video +- [CEA-608/708](/quest/m3/captions-cea.md) - can read inline caption SEI without waiting for this experiment diff --git a/quest/m2/signed-priority.md b/quest/m2/signed-priority.md index 1dd13fb15c6..37f3b539ac9 100644 --- a/quest/m2/signed-priority.md +++ b/quest/m2/signed-priority.md @@ -42,9 +42,15 @@ moq-archive's `Info::priority` follows. Its version-1 `.info` stores the 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. It stays deferred unless it -ships in the same release as the moxygen default change, so the default -byte moves once instead of twice. +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 diff --git a/quest/m2/starvation-frames.md b/quest/m2/starvation-frames.md index bb71aa27221..c53282f4e8b 100644 --- a/quest/m2/starvation-frames.md +++ b/quest/m2/starvation-frames.md @@ -17,7 +17,7 @@ frontier it reads moves. `Writer` in `rs/moq-net/src/coding/writer.rs` gains a monotonic written-offset counter, since every write funnels through it, so at each frame end the per-group serve task knows the stream offset and the frame timestamp. Record `(offset, timestamp, bytes, written_at)` and await -`poll_acked(offset)` from the released `web-transport-trait` hook, +`poll_acked(offset)` on moq-net's own `transport::poll::SendStream`, interleaved with the writes of later frames so a lagging ACK never stalls sending. One waiter per stream suffices: offsets are acknowledged in order for the purpose of this metric, so poll the oldest @@ -56,5 +56,5 @@ unsupported. - [Starvation](/quest/m1/qos/starvation.md) - fixes the wire shape and the group-granularity fallback -- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the released +- [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - the hook this samples through diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index 94353878040..adf18b252d3 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -109,5 +109,5 @@ stating plainly because it is what a builder is comparing against. 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 schema](/quest/m2/text-schema.md) - non-media tracks in a catalog, - arrived at from the media side +- [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/video-codec-coverage.md b/quest/m2/video-codec-coverage.md index 423619c9ca3..b50bb6c92a4 100644 --- a/quest/m2/video-codec-coverage.md +++ b/quest/m2/video-codec-coverage.md @@ -29,6 +29,6 @@ Public API and wire: no changes during this study. ## Related -- [NVIDIA formats](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - existing AV1 encode and 10-bit scope +- [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) - [VP8/VP9](/quest/m1/obs-moq-video/vpx.md) - existing portable decoder scope - [VAAPI](/quest/m2/video-vaapi.md) - existing Linux codec expansion diff --git a/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md similarity index 86% rename from quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md rename to quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index 0ddef060e66..9f0d495b146 100644 --- a/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -9,9 +9,9 @@ exporter understands. Server-side ad insertion is a separate future quest. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. -Use the shared event contract [emsg](/quest/m2/emsg.md) settles. Deliver cues immediately, including when splice_time is in the +Use the shared event contract [emsg](/quest/m3/emsg.md) settles. Deliver cues immediately, including when splice_time is in the future; consumers need advance notification. Metadata group sequences are independent of media GOPs. @@ -42,10 +42,14 @@ schema: the draft is the normative spec, and a section Rust and JS emit must be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, `rs/moq-mux`, `doc/concept`. +## Required + +- [fMP4 emsg](/quest/m3/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first + ## Closes - [#2279](https://github.com/moq-dev/moq/issues/2279) - close this issue when the quest finishes ## Related -- [ID3 catalog section](/quest/m2/id3.md) - the other typed timed-metadata section, same rule +- [ID3 catalog section](/quest/m3/id3.md) - the other typed timed-metadata section, same rule diff --git a/quest/m3/README.md b/quest/m3/README.md index 0e5e3f52313..71e909e2050 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -2,17 +2,19 @@ ## Goal -Work whose first step is outside this repository: hardware nobody on the team -has, a partner or customer who asks for it, or a hosting provider's offer. -Nothing here should start by opening an editor. +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. ## Plan -A quest lands here when its gate is the outside world, not its priority. Its gate -is a condition quest beside it, as the root [questline](/quest/README.md) -describes. A -speculative feature with no consumer parks here rather than in m2, and is -deleted when it goes stale; git history keeps it. +A quest gated on the outside world has a condition quest beside it, as the +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. ## Required @@ -37,14 +39,32 @@ deleted when it goes stale; git history keeps it. - [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway replacing the VPN plus two unmanaged UDP flows, with QGroundControl and friends unchanged -- [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 - [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 - [Encode config](/quest/m3/intra-refresh-encode-config.md) - refresh mode extends the settled GOP contract; the producer cuts groups per sweep and publishes `warmup` - [NVENC refresh](/quest/m3/intra-refresh-nvenc.md) - the NVENC backend encodes refresh mode for H.264 and HEVC - [V4L2 refresh](/quest/m3/intra-refresh-v4l2.md) - the V4L2 backend encodes refresh mode - [Bindings](/quest/m3/intra-refresh-bindings.md) - moq-ffi and every wrapper expose refresh mode, additive on the ffi-shape `Gop` enum - [RTSP import](/quest/m3/rtsp-import.md) - `moq import rtsp` publishes an IP camera from its own network, through a reusable `moq-rtsp` crate +- [P2P](/quest/m3/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy +- [Route trust](/quest/m3/route-trust.md) - a peer grant lets a client link advertise the nodes behind it as one identity; P2P is its first consumer +- [Ladder](/quest/m3/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling +- [Processor](/quest/m3/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access +- [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 +- [#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 diff --git a/quest/m2/archive-browser.md b/quest/m3/archive-browser.md similarity index 79% rename from quest/m2/archive-browser.md rename to quest/m3/archive-browser.md index 1a6d5bc935f..97b34cd8773 100644 --- a/quest/m2/archive-browser.md +++ b/quest/m3/archive-browser.md @@ -10,7 +10,7 @@ layout, and FETCH behavior as native `moq-archive` users. Port the archive contract to the JS packages with memory and OPFS storage. The application explicitly enrolls video, audio, catalog, or arbitrary data tracks; the archive does not infer them from Hang. The JS timeline already publishes -through the Window (`js/hang/src/container/timeline.ts:134`, `:165`, backed by +through the Window (`js/hang/src/timeline.ts`, its `Consumer` and `Producer`, backed by `js/json/src/window/`) with pacing tracks and application-driven cuts; add the deferred commit Rust has (`Producer::deferred`, `rs/moq-mux/src/timeline.rs:917`). @@ -21,7 +21,7 @@ ascending delta-encoded IDs, and sequential timeline discovery used by Rust. A t one-group-per-frame audio groups. Match the Rust binary envelope bytes and `.info` property values, per the [Recording section](/drafts/draft-lcurley-moq-hang.md#recording), without inferring catalog-to-group applicability. [Catalog track identity](/quest/m2/catalog-tracks.md) addresses that separately. -Use [JavaScript FETCH](/quest/m1/js-fetch.md)'s on-demand group requests to +Use [JS ranges](/quest/m1/subscribe-ranges/js.md)'s on-demand range requests to answer cache misses from memory or OPFS after relay eviction. This quest owns storage lookup, the bounded segment LRU, and timeline-before-delete DVR retention; the generic request lifecycle and IETF wire support land in the @@ -31,10 +31,11 @@ the supported drafts without duplicating transport dispatch or codecs here. Ship the contract in the `@moq/*` packages. A dashboard browser-to-HLS proof remains downstream (moq.pro) work. -Deferred to m2 in the 2026-09-30 audit: no named consumer; the native archive +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer; the native archive lands first. ## Required -- [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH support +- [JS ranges](/quest/m1/subscribe-ranges/js.md) - generic on-demand range serving in `@moq/net` +- [JavaScript FETCH](/quest/m1/js-fetch.md) - IETF FETCH dispatch onto it - [Archive](/quest/m1/archive/README.md) - the native writer, reader, and DVR contract this ports diff --git a/quest/m2/archive-paced-replay.md b/quest/m3/archive-paced-replay.md similarity index 93% rename from quest/m2/archive-paced-replay.md rename to quest/m3/archive-paced-replay.md index 9286a610169..2729d00580b 100644 --- a/quest/m2/archive-paced-replay.md +++ b/quest/m3/archive-paced-replay.md @@ -25,7 +25,7 @@ who joins late joins mid-replay. - Test with paused time: record, replay paced, and assert a plain subscriber gets every group in order at media pace, that a late subscriber starts at the current group, and that two tracks stay aligned. -- Deferred to m2 in the 2026-09-30 audit: no named consumer; FETCH replay +- Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer; FETCH replay already serves DVR and HLS. ## Required diff --git a/quest/m2/captions-cea.md b/quest/m3/captions-cea.md similarity index 94% rename from quest/m2/captions-cea.md rename to quest/m3/captions-cea.md index e7f3be5cde3..6b35a6a1d28 100644 --- a/quest/m2/captions-cea.md +++ b/quest/m3/captions-cea.md @@ -8,7 +8,7 @@ without extraction those broadcasts have no captions in MoQ at all. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. Parse the `user_data_registered_itu_t_t35` SEI payloads that carry CEA-708 (with 608 compatibility bytes inside) out of H.264 and H.265 access units at diff --git a/quest/m2/closure-counters.md b/quest/m3/closure-counters.md similarity index 93% rename from quest/m2/closure-counters.md rename to quest/m3/closure-counters.md index 347c37f708d..174f12f26d9 100644 --- a/quest/m2/closure-counters.md +++ b/quest/m3/closure-counters.md @@ -9,7 +9,7 @@ explicit fresh segment. The rule is documented as a consumer-facing contract. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer. The stickiness fix ([moq#3625](https://github.com/moq-dev/moq/pull/3625)) keeps a departed node's last `Traffic` contribution and drops `Presence` diff --git a/quest/m3/cut-through/README.md b/quest/m3/cut-through/README.md index 7b85b846b5c..a42d96e2afa 100644 --- a/quest/m3/cut-through/README.md +++ b/quest/m3/cut-through/README.md @@ -74,6 +74,6 @@ stats field, which its quest documents inline. ## Related -- [Unordered qmux](/quest/m2/p2p/unordered.md) - the same head-of-line problem on the data channel transport +- [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 diff --git a/quest/m2/emsg.md b/quest/m3/emsg.md similarity index 92% rename from quest/m2/emsg.md rename to quest/m3/emsg.md index 77af76c5813..e51c00b0458 100644 --- a/quest/m2/emsg.md +++ b/quest/m3/emsg.md @@ -13,7 +13,7 @@ it rather than restating it. Deferred SEI extraction is not a prerequisite. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. The shared contract, recorded here and mirrored in the Hang draft: @@ -59,6 +59,6 @@ byte-identical. - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - the same silent drop in a different layer -- [ID3 catalog section](/quest/m2/id3.md) - gives one payload type carried here a +- [ID3 catalog section](/quest/m3/id3.md) - gives one payload type carried here a typed contract -- [FLV script tags](/quest/m2/flv-script.md) - likewise +- [FLV script tags](/quest/m3/flv-script.md) - likewise diff --git a/quest/m2/flv-script.md b/quest/m3/flv-script.md similarity index 80% rename from quest/m2/flv-script.md rename to quest/m3/flv-script.md index 0d90021f9c3..64510f0fbd5 100644 --- a/quest/m2/flv-script.md +++ b/quest/m3/flv-script.md @@ -7,7 +7,7 @@ FLV script tags survive RTMP and FLV import instead of being discarded, so ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. `rs/moq-mux/src/container/flv/import.rs` matches `TAG_SCRIPT => {}` and moves on, which drops every AMF data message an encoder sends. `onMetaData` is the @@ -17,7 +17,7 @@ through the same channel. Carry raw tag payloads without decoding AMF into a fixed vocabulary. Publish when received on independently sequenced metadata groups, with event time on the broadcast clock and source placement per the contract -[emsg](/quest/m2/emsg.md) settles. Tags before media +[emsg](/quest/m3/emsg.md) settles. Tags before media are delivered immediately and retain explicit pre-media placement; audio-only and script-only input do not require a dummy video rendition. Where `onMetaData` duplicates something the catalog already models (dimensions, @@ -28,6 +28,10 @@ Export reproduces the tags on the FLV path. Test `onMetaData`, an application message with a custom name, AMF0 and AMF3 payloads, a tag before the first 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 - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - likewise diff --git a/quest/m3/hidden-exemption.md b/quest/m3/hidden-exemption.md index 762a9de603b..1b1560fe6b9 100644 --- a/quest/m3/hidden-exemption.md +++ b/quest/m3/hidden-exemption.md @@ -12,9 +12,11 @@ for peers that predate it. In m3 because it waits on a deployment, not on code; it comes back once the mesh runs lite-07. -- Remove the `cluster_peer` argument from `connection::authorize` and its - callers in `rs/moq-relay/src/{connection,uring,websocket}.rs`, and the forced - `with_hidden(true)` on the outbound dial in `rs/moq-relay/src/cluster.rs`. +- Remove the `cluster_peer` exemption, now a local inside `Cluster::scope` + (`rs/moq-relay/src/cluster.rs`, with its TODO), so an inbound peer discovers + hidden routes only when it asks, and the forced `with_hidden(true)` on the + outbound dial in the same file. `connection::authorize` no longer exists on + `main`; only `release` still has that shape. - Replace `rs/moq-relay/tests/hidden_cluster.rs` with a lite-07 mesh test that still sees a `.`-prefixed hidden broadcast. diff --git a/quest/m2/id3.md b/quest/m3/id3.md similarity index 85% rename from quest/m2/id3.md rename to quest/m3/id3.md index dcec002c744..861b0fc6d00 100644 --- a/quest/m2/id3.md +++ b/quest/m3/id3.md @@ -10,10 +10,10 @@ stream. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. Define the catalog section and frame contract for complete ID3 tags on the -shared event contract [emsg](/quest/m2/emsg.md) settles. Publish tags when +shared event contract [emsg](/quest/m3/emsg.md) settles. Publish tags when received on independently sequenced groups, with their presentation time on the broadcast clock and an optional association to the program's rendition. ID3-only programs need no artificial media owner. Carry original tag bytes, @@ -37,6 +37,10 @@ large tags spanning PES packets, timestamp wrap, discontinuity, and an ID3-only program. Include non-ID3 and malformed stream type `0x15` fixtures that remain generic. +## Required + +- [fMP4 emsg](/quest/m3/emsg.md) - settles the shared timed-metadata contract this builds on, which needs maintainer agreement first + ## Related - [SEI sidecars](/quest/m2/sei.md) - the separate codec metadata diff --git a/quest/m2/interop-graceful-close.md b/quest/m3/interop-graceful-close.md similarity index 81% rename from quest/m2/interop-graceful-close.md rename to quest/m3/interop-graceful-close.md index d1d329b66b6..ee8e9645aee 100644 --- a/quest/m2/interop-graceful-close.md +++ b/quest/m3/interop-graceful-close.md @@ -14,3 +14,7 @@ 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/interop-runner-approval.md b/quest/m3/interop-runner-approval.md new file mode 100644 index 00000000000..3a674b73909 --- /dev/null +++ b/quest/m3/interop-runner-approval.md @@ -0,0 +1,10 @@ +# [XS] The maintainer approves posting to moq-interop-runner + +## 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. diff --git a/quest/m2/ladder/README.md b/quest/m3/ladder/README.md similarity index 93% rename from quest/m2/ladder/README.md rename to quest/m3/ladder/README.md index 55bfab5d781..bf2572440f7 100644 --- a/quest/m2/ladder/README.md +++ b/quest/m3/ladder/README.md @@ -15,11 +15,11 @@ state. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer for the +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for the publisher-side ladder. The catalog and player half is the rendition `enabled` flag -([enabled flag](/quest/m1/catalog-enabled.md)), which replaced the `stalled` +([enabled flag](/quest/m1/catalog-enabled.md)), which replaces the `stalled` state shipped in [moq#2865](https://github.com/moq-dev/moq/pull/2865): `enabled: false` means no frames are coming and a viewer must not select the rendition. Routing, decoder, and presentation identities are split so a @@ -80,9 +80,9 @@ encoders on every target change. ## Required -- [Controller](/quest/m2/ladder/controller.md) - one controller owns every +- [Controller](/quest/m3/ladder/controller.md) - one controller owns every rung's share, target, enabled state, and send order -- [Fetch and catalog](/quest/m2/ladder/fetch.md) - uncached FETCH encodes at +- [Fetch and catalog](/quest/m3/ladder/fetch.md) - uncached FETCH encodes at the shared applied target, and rung state survives a source catalog refresh ## Closes diff --git a/quest/m2/ladder/controller.md b/quest/m3/ladder/controller.md similarity index 96% rename from quest/m2/ladder/controller.md rename to quest/m3/ladder/controller.md index 17ac35eb23d..92853267a95 100644 --- a/quest/m2/ladder/controller.md +++ b/quest/m3/ladder/controller.md @@ -18,7 +18,7 @@ today's fixed-rate behavior exactly and never publishes congestion-induced `enabled` state, which is what keeps this additive. The controller subdivides that estimate across the ladder and applies the -band boundary from the [questline](/quest/m2/ladder/README.md), including the +band boundary from the [questline](/quest/m3/ladder/README.md), including the lowest rung's `max / 3` case. `moq_transcode::Ladder` is ascending: `new` sorts by configured maximum (`rs/moq-transcode/src/ladder.rs:101`) and `rungs()` is lowest first (`:125-128`), so the next lower rendition the @@ -73,6 +73,7 @@ priority where the subscriber's order wins, and a custom ladder order. ## Required - [Scope track priority](/quest/m1/track-priority-scope.md) - settles the priority ranking the controller assigns before the encoder side reads it +- [Enabled flag](/quest/m1/catalog-enabled.md) - the `enabled` field the controller publishes for rungs ## Related diff --git a/quest/m2/ladder/fetch.md b/quest/m3/ladder/fetch.md similarity index 95% rename from quest/m2/ladder/fetch.md rename to quest/m3/ladder/fetch.md index 458b56762cc..b9762de79f2 100644 --- a/quest/m2/ladder/fetch.md +++ b/quest/m3/ladder/fetch.md @@ -31,5 +31,5 @@ intact. ## Required -- [Controller](/quest/m2/ladder/controller.md) - there is no shared applied +- [Controller](/quest/m3/ladder/controller.md) - there is no shared applied target to read until the controller owns one diff --git a/quest/m2/moq-relay-subcommand.md b/quest/m3/moq-relay-subcommand.md similarity index 86% rename from quest/m2/moq-relay-subcommand.md rename to quest/m3/moq-relay-subcommand.md index 88833abf60b..27c97dc5660 100644 --- a/quest/m2/moq-relay-subcommand.md +++ b/quest/m3/moq-relay-subcommand.md @@ -9,8 +9,8 @@ decode, and render stack. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer, and [`moq --listen` -admission](/quest/m1/cli-serve.md) no longer waits on it. +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 @@ -39,4 +39,4 @@ admission](/quest/m1/cli-serve.md) no longer waits on it. ## Related -- [`moq --listen` admission](/quest/m1/cli-serve.md) - the CLI's listener is admitted through the same `serve` +- [`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/p2p/README.md b/quest/m3/p2p/README.md similarity index 90% rename from quest/m2/p2p/README.md rename to quest/m3/p2p/README.md index 5067a3e8de1..472328f69ba 100644 --- a/quest/m2/p2p/README.md +++ b/quest/m3/p2p/README.md @@ -29,7 +29,7 @@ under "One channel, qmux, ordered". ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer. +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer. ### The relay is the rendezvous and the fallback @@ -84,7 +84,7 @@ for free. 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/m2/p2p/harness.md) supplies the numbers that decide when +[harness](/quest/m3/p2p/harness.md) supplies the numbers that decide when that follow-up is worth it. Channel-per-stream is not planned. moq opens a stream per group, so it churns @@ -105,7 +105,7 @@ Decided 2026-10-01: a direct link wins only when the peer is the origin or a routing node; a watching tab never re-serves what it receives. Offloading a room of watchers is a customer relay's job (`moq-cli --p2p` is the small one), which keeps warm and cold costs and cache-aware routing out of the -protocol. [Direct peers win](/quest/m2/p2p/cost-scopes.md) sets the cost +protocol. [Direct peers win](/quest/m3/p2p/cost-scopes.md) sets the cost knobs and defaults. No Rust + WASM in-tab hop: [rs2ts](/quest/m1/rs2ts/remove-wasm.md) removes the @@ -125,14 +125,14 @@ WASM build, so the browser side stays TypeScript. ## Required -- [Data channel transport](/quest/m2/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes -- [Signaling and policy](/quest/m2/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used -- [Native data channel transport](/quest/m2/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent -- [moq-cli joins](/quest/m2/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop -- [Direct peers win](/quest/m2/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/m2/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route -- [Harness](/quest/m2/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision -- [Unordered qmux](/quest/m2/p2p/unordered.md) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream +- [Data channel transport](/quest/m3/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes +- [Signaling and policy](/quest/m3/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used +- [Native data channel transport](/quest/m3/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent +- [moq-cli joins](/quest/m3/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop +- [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) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream ## Related diff --git a/quest/m2/p2p/cli.md b/quest/m3/p2p/cli.md similarity index 89% rename from quest/m2/p2p/cli.md rename to quest/m3/p2p/cli.md index a5e3b161450..cad2429b9af 100644 --- a/quest/m2/p2p/cli.md +++ b/quest/m3/p2p/cli.md @@ -16,7 +16,7 @@ than adding startup checks. `--p2p-ice-server`, `Peers` takes; `select` is the CLI's built-in default of dialing everyone. The roster entry mirrors the `info.json` schema from -[signaling](/quest/m2/p2p/signal.md): the listener's LAN addresses as +[signaling](/quest/m3/p2p/signal.md): the listener's LAN addresses as WebTransport URLs, ordered the way `mdns::Peer::urls` orders them, with the listener's certificate fingerprint; the iroh endpoint id when `--iroh` is on, which is the first place an endpoint id appears in any roster; `webrtc: true`; @@ -35,5 +35,5 @@ Docs: a "P2P" section in `doc/bin/cli.md` beside the LAN cluster one. ## Required -- [Native data channel transport](/quest/m2/p2p/webrtc.md) -- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster and offer schema this mirrors +- [Native data channel transport](/quest/m3/p2p/webrtc.md) +- [Signaling and policy](/quest/m3/p2p/signal.md) - the roster and offer schema this mirrors diff --git a/quest/m2/p2p/cost-scopes.md b/quest/m3/p2p/cost-scopes.md similarity index 100% rename from quest/m2/p2p/cost-scopes.md rename to quest/m3/p2p/cost-scopes.md diff --git a/quest/m2/p2p/harness.md b/quest/m3/p2p/harness.md similarity index 94% rename from quest/m2/p2p/harness.md rename to quest/m3/p2p/harness.md index 383581bfffa..eb6512cb3e8 100644 --- a/quest/m2/p2p/harness.md +++ b/quest/m3/p2p/harness.md @@ -36,5 +36,5 @@ points. ## Required -- [moq-cli joins](/quest/m2/p2p/cli.md) -- [Signaling and policy](/quest/m2/p2p/signal.md) +- [moq-cli joins](/quest/m3/p2p/cli.md) +- [Signaling and policy](/quest/m3/p2p/signal.md) diff --git a/quest/m2/p2p/signal.md b/quest/m3/p2p/signal.md similarity index 95% rename from quest/m2/p2p/signal.md rename to quest/m3/p2p/signal.md index 2857a6881c4..226f2141cf8 100644 --- a/quest/m2/p2p/signal.md +++ b/quest/m3/p2p/signal.md @@ -11,7 +11,7 @@ size above which new negotiations stop using them. No new relay behavior. ## Plan `Peers` in `@moq/p2p` takes the shared origin and the policy knobs from the -[questline README](/quest/m2/p2p/README.md): `enabled`, `prefix`, +[questline README](/quest/m3/p2p/README.md): `enabled`, `prefix`, `iceServers`, `max`, `meta`, `select`. Publishing into the origin reaches the relay and the origin's announce stream is the roster. Tests inject a peer connection factory so `bun test` covers pairing, the roster gate, and @@ -28,9 +28,9 @@ the presenter public key that [peer grants](/quest/m1/auth/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/m2/p2p/cli.md). Unordered is advertised here so the dialer +[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/m2/p2p/unordered.md). +[unordered qmux](/quest/m3/p2p/unordered.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 +80,5 @@ there is no equal-scope shortcut. ## Required -- [Data channel transport](/quest/m2/p2p/transport.md) +- [Data channel transport](/quest/m3/p2p/transport.md) - [Peer grants](/quest/m1/auth/peer-grant.md) - the hop-bound, asymmetrically signed credential a direct session presents; HS256 keys issue none diff --git a/quest/m2/p2p/transport.md b/quest/m3/p2p/transport.md similarity index 91% rename from quest/m2/p2p/transport.md rename to quest/m3/p2p/transport.md index 4ba0a5931ea..1952e12a602 100644 --- a/quest/m2/p2p/transport.md +++ b/quest/m3/p2p/transport.md @@ -26,7 +26,7 @@ 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/m2/p2p/unordered.md) flips it without a second +[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. @@ -41,5 +41,5 @@ the sentence declaring P2P out of scope goes. `just drafts check` passes. ## Related -- [Signaling and policy](/quest/m2/p2p/signal.md) - supplies the peer connection and the agreed ALPN -- [Native data channel transport](/quest/m2/p2p/webrtc.md) - the same binding in Rust +- [Signaling and policy](/quest/m3/p2p/signal.md) - supplies the peer connection and the agreed ALPN +- [Native data channel transport](/quest/m3/p2p/webrtc.md) - the same binding in Rust diff --git a/quest/m2/p2p/unordered.md b/quest/m3/p2p/unordered.md similarity index 83% rename from quest/m2/p2p/unordered.md rename to quest/m3/p2p/unordered.md index a4dc1ffbf76..38f2bc518fd 100644 --- a/quest/m2/p2p/unordered.md +++ b/quest/m3/p2p/unordered.md @@ -38,15 +38,18 @@ 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: `draft-lcurley-qmux.md` gains the parameter and the relaxed rule; the +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/m2/p2p/harness.md) before and after: stall +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 -- [Harness](/quest/m2/p2p/harness.md) - the loss row this quest is measured against -- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists +- [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/p2p/watch.md b/quest/m3/p2p/watch.md similarity index 78% rename from quest/m2/p2p/watch.md rename to quest/m3/p2p/watch.md index 631b74ef2ac..29b9e906ff4 100644 --- a/quest/m2/p2p/watch.md +++ b/quest/m3/p2p/watch.md @@ -12,7 +12,7 @@ the peer goes away, with no visible interruption. `hang-watch` and `hang-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/m2/p2p/cost-scopes.md): +origin's, under the rule from [Direct peers win](/quest/m3/p2p/cost-scopes.md): a direct link to the origin or a routing node wins, and losing it falls back to the relay. @@ -21,6 +21,6 @@ directly, and watcher tabs pulling from a `moq-cli --p2p` hop. ## Required -- [Signaling and policy](/quest/m2/p2p/signal.md) -- [moq-cli joins](/quest/m2/p2p/cli.md) - the native hop the second topology shows -- [Direct peers win](/quest/m2/p2p/cost-scopes.md) +- [Signaling and policy](/quest/m3/p2p/signal.md) +- [moq-cli joins](/quest/m3/p2p/cli.md) - the native hop the second topology shows +- [Direct peers win](/quest/m3/p2p/cost-scopes.md) diff --git a/quest/m2/p2p/webrtc.md b/quest/m3/p2p/webrtc.md similarity index 91% rename from quest/m2/p2p/webrtc.md rename to quest/m3/p2p/webrtc.md index 6dfe54fc1f4..d9ee06b05c8 100644 --- a/quest/m2/p2p/webrtc.md +++ b/quest/m3/p2p/webrtc.md @@ -32,7 +32,7 @@ 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/m2/p2p/unordered.md), set from the roster before +[unordered qmux](/quest/m3/p2p/unordered.md), set from the roster before the channel is created, never from the first qmux record. Tests: an in-process str0m pair over loopback runs moq-net's session tests; @@ -41,6 +41,6 @@ candidate is offered and selected. Browser interop is the harness's job. ## Related -- [Data channel transport](/quest/m2/p2p/transport.md) - the browser side of the same binding -- [moq-cli joins](/quest/m2/p2p/cli.md) - the first consumer +- [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 diff --git a/quest/m2/processor/README.md b/quest/m3/processor/README.md similarity index 73% rename from quest/m2/processor/README.md rename to quest/m3/processor/README.md index 401ddba58f4..1a127f53ce2 100644 --- a/quest/m2/processor/README.md +++ b/quest/m3/processor/README.md @@ -20,24 +20,25 @@ and custom transforms use the same worker lifecycle. ## Plan Decided: derived output follows [Wildcard](/quest/m0/wildcard/README.md)'s -service-prefix layout, not `/.pro`. Suffix routing is -dropped everywhere, and a prefix claim needs the variable part of the path +service-prefix layout, not `/.pro`. Processor output does +not use suffix routing ([announcement shapes](/quest/m2/announce-shapes.md) +may add it to moq-lite separately), and a prefix claim needs the variable part of the path trailing, so the processor claims its prefix and mirrors the source path beneath it. The source's catalog reaches the output through a -cross-broadcast reference ([media contract](/quest/m2/processor/media-contract.md)). +cross-broadcast reference ([media contract](/quest/m3/processor/media-contract.md)). -Deferred to m2 in the 2026-09-30 audit: no processor customer is committed, +Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no processor customer is committed, and its end-to-end proof (processor-vision) was deleted. ## Required -- [Processor media contract](/quest/m2/processor/media-contract.md) - define +- [Processor media contract](/quest/m3/processor/media-contract.md) - define contribution references, source relations, and correlation in the Hang catalog -- [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) - a +- [Advertise-only authorization](/quest/m3/processor/advertise-auth.md) - a worker may advertise its service prefix without receiving permission to publish arbitrary paths under it -- [Expiring media grants](/quest/m2/processor/grant-lease.md) - enforce +- [Expiring media grants](/quest/m3/processor/grant-lease.md) - enforce short-lived exact grants on already-open consumer and producer handles ## Related diff --git a/quest/m2/processor/advertise-auth.md b/quest/m3/processor/advertise-auth.md similarity index 100% rename from quest/m2/processor/advertise-auth.md rename to quest/m3/processor/advertise-auth.md diff --git a/quest/m2/processor/grant-lease.md b/quest/m3/processor/grant-lease.md similarity index 100% rename from quest/m2/processor/grant-lease.md rename to quest/m3/processor/grant-lease.md diff --git a/quest/m2/processor/media-contract.md b/quest/m3/processor/media-contract.md similarity index 100% rename from quest/m2/processor/media-contract.md rename to quest/m3/processor/media-contract.md diff --git a/quest/m1/cluster-routing/route-trust.md b/quest/m3/route-trust.md similarity index 87% rename from quest/m1/cluster-routing/route-trust.md rename to quest/m3/route-trust.md index 07fbdfba3c0..571d0e6b854 100644 --- a/quest/m1/cluster-routing/route-trust.md +++ b/quest/m3/route-trust.md @@ -12,6 +12,11 @@ instead of two unrelated ones. ## Plan +Decided in the 2026-10-05 audit: route trust moved out of the cluster-routing +line to sit beside [P2P](/quest/m3/p2p/README.md), its first consumer, so +cluster routing finishes without it. Session-scoped ids already ship with +routes. + Decided 2026-10-01: - Session scoping is the default and ships with diff --git a/quest/m2/stats-encoder-feedback.md b/quest/m3/stats-encoder-feedback.md similarity index 96% rename from quest/m2/stats-encoder-feedback.md rename to quest/m3/stats-encoder-feedback.md index 7a160a3e948..6d1c55283f2 100644 --- a/quest/m2/stats-encoder-feedback.md +++ b/quest/m3/stats-encoder-feedback.md @@ -10,7 +10,7 @@ it already follows. Keyframe requests stay out. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer; the media stats it +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. - `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer @@ -86,5 +86,5 @@ Open, to settle before starting (moved from the - [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/m2/ladder/README.md) - the transcode ladder that adapts to +- [Ladder](/quest/m3/ladder/README.md) - the transcode ladder that adapts to its uplink today diff --git a/quest/m2/text-schema.md b/quest/m3/text-schema.md similarity index 93% rename from quest/m2/text-schema.md rename to quest/m3/text-schema.md index b7fd16f6c03..a84a5fe11b1 100644 --- a/quest/m2/text-schema.md +++ b/quest/m3/text-schema.md @@ -8,7 +8,7 @@ the audio or video timeline it transcribes. ## Plan -Deferred to m2 in the 2026-09-30 audit: no named consumer. +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