From 742b5053301f5315f53add6d5ca74a11e38ce43e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 11:59:37 -0700 Subject: [PATCH 1/9] quest: plan moq.pro audit follow-ups (RTSP library ingest, archive HLS renderer, client health, lite-07 final, GPU health) Co-Authored-By: Claude Opus 5.5 --- ...every-readme-example-fails-to-parse-and.md | 4 + quest/m1/README.md | 5 +- quest/m1/archive/README.md | 2 +- quest/m1/archive/hls.md | 97 ++++++++++++------- quest/m1/archive/proof.md | 1 - quest/m1/bench-buckets.md | 40 ++++++++ quest/m1/lite07-finalize.md | 62 ++++++++++++ quest/m1/stats-linger.md | 45 +++++++++ quest/m1/stats/README.md | 10 ++ quest/m1/stats/health.md | 63 ++++++++++++ quest/m1/stats/preflight.md | 48 +++++++++ quest/m2/README.md | 2 + quest/m2/gpu-health.md | 54 +++++++++++ quest/{m3 => m2}/rtsp-import.md | 39 ++++++-- quest/m3/README.md | 1 - quest/m3/lite07-mesh.md | 4 +- 16 files changed, 427 insertions(+), 50 deletions(-) create mode 100644 quest/m1/bench-buckets.md create mode 100644 quest/m1/lite07-finalize.md create mode 100644 quest/m1/stats-linger.md create mode 100644 quest/m1/stats/health.md create mode 100644 quest/m1/stats/preflight.md create mode 100644 quest/m2/gpu-health.md rename quest/{m3 => m2}/rtsp-import.md (60%) diff --git a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md index 85cf2477363..dc9e0c67728 100644 --- a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md +++ b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md @@ -30,3 +30,7 @@ moq-bench is 0.0.x, so this lands on main. ## Closes - [#3126](https://github.com/moq-dev/moq/issues/3126) - close this issue when the quest finishes + +## Related + +- [Mergeable bench buckets](/quest/m1/bench-buckets.md) - the interval buckets these percentiles can be computed from diff --git a/quest/m1/README.md b/quest/m1/README.md index 062676d01e7..b28ffb6e623 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -25,6 +25,7 @@ QUIC studies there on that rule. - [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 +- [Stats linger](/quest/m1/stats-linger.md) - a grouped stats broadcast stays announced for a linger after its last session, so viewer churn stops re-announcing it across the mesh - [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 @@ -55,6 +56,7 @@ QUIC studies there on that rule. - [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 - [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 +- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - lite-07 negotiates as `moq-lite-07` with a frozen wire, and the next release ships it - [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does - [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 @@ -128,7 +130,7 @@ QUIC studies there on that rule. - [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms - [Catalog track alias](/quest/m1/catalog-track-alias.md) - catalog rendition keys become aliases with an optional `track` name, so one catalog lists renditions from several broadcasts -- [Media stats](/quest/m1/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and a Rust encoder adapts to them +- [Media stats](/quest/m1/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and one model turns both into a health verdict and a preflight report - [JS track handover](/quest/m1/js-group-handover.md) - a JS track subscription resumes across a route swap from the first frame it lacks, so `test/drain` passes at zero latency budget - [JS GOAWAY requests](/quest/m1/js-goaway-requests.md) - after GOAWAY the JS client opens no new request on the old session, like Rust - [Drain handshakes](/quest/m1/drain-handshakes.md) - a drain GOAWAYs and waits for sessions still in their handshake instead of exiting under them @@ -144,6 +146,7 @@ QUIC studies there on that rule. - [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 +- [Mergeable bench buckets](/quest/m1/bench-buckets.md) - moq-bench emits per-interval latency buckets that sum across processes and hosts - [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 diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index c5313b0b1cd..29166e5aa43 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -115,7 +115,7 @@ owned by that prerequisite, not duplicated in archive storage. - [Recording writer](/quest/m1/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record - [Recording reader](/quest/m1/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` - [Replay provenance](/quest/m1/archive/provenance.md) - a replay's catalog names its timeline, replay path, store URL, and format version -- [Offline archive HLS](/quest/m1/archive/hls.md) - render playlists from the archive timeline and fetch segment media lazily +- [Bounded HLS playlists](/quest/m1/archive/hls.md) - a fresh viewer's playlist work is bounded by the window, with a stable media sequence, gap slots, and no video before a keyframe - [DVR rewind](/quest/m1/archive/dvr.md) - seek through a bounded archive and return to live playback - [Enrollment flake](/quest/m1/archive/enrollment-flake.md) - the opening-snapshot test waits for real enrollment, not the `.info` file - [Archive proof](/quest/m1/archive/proof.md) - prove persistence ordering, selective reads, exact FETCH replay, and timeline-only HLS generation diff --git a/quest/m1/archive/hls.md b/quest/m1/archive/hls.md index a967808de43..c644eba4d2a 100644 --- a/quest/m1/archive/hls.md +++ b/quest/m1/archive/hls.md @@ -1,42 +1,67 @@ -# [L] Offline archive HLS +# [M] Bounded HLS playlists ## Goal -`moq-hls` serves ordinary HLS from a growing or static archive without a second -stored media copy, and renders playlists without downloading media objects. +A fresh viewer joins a days-old broadcast, live or archived, and `moq-hls` +renders its playlists with work bounded by the advertised window, not by the +broadcast's age. The media playlist lists a sliding window whose +`EXT-X-MEDIA-SEQUENCE` every edge and every reload agree on. A span with no +media in one rendition keeps its slot as a duration-preserving `EXT-X-GAP` +without holding back later segments or sibling renditions. A video rendition +is not advertised until its window holds a segment that starts on a +keyframe, so a stock player is never sent to video it cannot start decoding. + +This is the generic renderer. Managed edges (moq.pro) only wire it to their +projects, routes, and auth. ## Plan -Use the archive catalog for rendition and initialization metadata, then reuse -the live HLS renderer against the timeline. Segment number, PTS, duration, -track ranges, gaps, and keyframe state provide everything needed for a media -playlist. Playlist generation and reloads read the timeline only; a regression -test must fail if they GET a media segment. - -When a player requests media, use the recording reader to GET only the selected -range-named object and transmux its groups on demand. Switching between -360p and 1080p must not download both rendition objects. Emit media URIs with -the track and inclusive group bounds from the timeline record, so the handler -can derive `groups/.` directly without listing or a -segment-ID lookup. HLS sequence numbers do not appear in storage keys. Keep -one storage object per track per timeline segment; a MoQ group need not be an -HLS segment, especially for one-group-per-frame audio. No LL-HLS parts. - -Emit `EXT-X-ENDLIST` exactly when the timeline track the exporter reads -finishes cleanly, as the live export already does -(`rs/moq-hls/src/export/mod.rs:325-327`, `rendition.rs:243-246`). The store -holds no completion marker: the reader finishes the replayed timeline track -when its caller supplies finality out of band, so a standalone or BYOB archive -without such a caller stays a reloadable playlist. - -Use the catalog supplied to the exporter. This quest does not establish which -catalog update applies to a historic group; timestamps do not provide an -explicit binding. Track immutability and update correlation belong to -[Catalog track identity](/quest/m2/catalog-tracks.md), independently of DVR. - -Prove aligned audio/video switching, missing track segments, discontinuities, -caller-supplied finality, and bounded LRU reads. - -## Required - -- [Recording reader](/quest/m1/archive/reader.md) +Decided 2026-10-05, from moq.pro's +[bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md): +the windowed sequence, gap slots, and keyframe gating are renderer rules every +`moq-hls` user needs, so they live here and moq.pro keeps only the edge +wiring. Rejected: keeping them in moq.pro. + +The offline archive HLS this quest used to describe is done on the archive +line's branch (#4115, #4155), which deletes this file. When that branch next +merges `main`, keep this quest. Its +per-track timelines quest already derives segments at the edge from group +timestamps and emits `EXT-X-GAP` for a rendition with no group start in a +span; whichever lands second rebases onto the other, and the rules here hold +for both shapes. + +Start by auditing `rs/moq-hls/src/export` against each rule; much exists +(`segments.rs` numbers aligned segments and carries gap rows, `playlist.rs` +writes `EXT-X-GAP`). Fix only what a test shows missing: + +- **Bounded join.** Rendering for a new viewer reads at most the window's + records from the timeline (`moq_json::Window`), never the whole history, + and never GETs or FETCHes media. A live publisher that never pops its + timeline must not make a join cost grow with broadcast age. +- **Stable sequence.** `EXT-X-MEDIA-SEQUENCE` is the window's first segment + number, derived from the timeline, so two edges and a reload after a pop + agree. +- **Gaps.** A record missing one track becomes a gap slot in that rendition + only; siblings keep listing, and a rendition switch after a gap lands on the + next real segment. +- **Keyframe gating.** The multivariant playlist omits a video rendition + until its window holds a keyframe-started segment. A catalog that arrives + first may expose audio only, or answer unavailable. + +Prove: a fresh join after simulated days of publishing reads a bounded number +of records (count them); catalog arrival before the first keyframe; gaps in +one track; switching after a gap; healthy siblings keep their listing; two +exporters over one timeline render identical sequence numbers. Tests mock +time. + +moq.pro pins `release`, so it adopts this through the next release that +carries it. + +Public API: none expected. Wire: none. + +Not blocked by the [recording reader](/quest/m1/archive/reader.md): the rules +apply to live timelines first, and a replayed archive inherits them. + +## Related + +- [moq.pro: bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md) - the edge wiring that adopts this renderer diff --git a/quest/m1/archive/proof.md b/quest/m1/archive/proof.md index 1f68bf73850..f53a3d94433 100644 --- a/quest/m1/archive/proof.md +++ b/quest/m1/archive/proof.md @@ -64,4 +64,3 @@ object directly without any listing or separate index object. ## Required - [Recording writer](/quest/m1/archive/writer.md) -- [Offline archive HLS](/quest/m1/archive/hls.md) diff --git a/quest/m1/bench-buckets.md b/quest/m1/bench-buckets.md new file mode 100644 index 00000000000..d76911b2d56 --- /dev/null +++ b/quest/m1/bench-buckets.md @@ -0,0 +1,40 @@ +# [S] moq-bench: mergeable interval buckets + +## Goal + +Every `moq-bench` JSONL line carries that interval's latency histogram in a +versioned, documented bucket layout, so the buckets from several bench +processes on several hosts sum element-wise over any window into one exact +distribution. A percentile computed once from the summed buckets matches one +computed from the concatenated samples. + +## Plan + +Decided 2026-10-05 in moq.pro's quest audit: percentiles neither window nor +merge, and moq.pro's load harness sums several generators against one relay, +so the bench emits mergeable buckets. Approved as recommended. + +- `Latency` (`rs/moq-bench/src/stats.rs`) already counts 1 ms buckets for the + whole run. Emit the interval's delta beside the cumulative fields, and + derive [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md)'s + per-interval percentiles from the same delta, so the two quests share one + representation; whichever lands second builds on the other. +- 60,001 dense buckets per line is too much JSON. Pick a compact layout (sparse + non-zero buckets, or a log-linear layout with bounded relative error) and + record why. +- The output documents: the layout version, units, the interval's start and + end, the sample count, and what an empty or partial interval (the first and + the last) looks like. +- Publisher and subscriber stay on one host, so latency closes on one clock; + `latency_clock_skew` keeps flagging a violation. +- A test sums fixture buckets from two runs and checks the percentiles + against the concatenated samples. Update `rs/moq-bench/README.md`. + +moq-bench is 0.0.x, so this lands on main. + +Public API: none (CLI output only). Wire: none. + +## Related + +- [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - per-interval percentiles from the same buckets +- [moq.pro: benchmark output pin](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/kick/bench-pin.md) - the load harness that sums these across generators diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md new file mode 100644 index 00000000000..725d4f3aff3 --- /dev/null +++ b/quest/m1/lite07-finalize.md @@ -0,0 +1,62 @@ +# [S] Finalize moq-lite-07 + +## Goal + +moq-lite-07 is a published version: it negotiates as `moq-lite-07`, the +`moq-lite-07-wip` identifier is gone, its draft revision describes the frozen +wire, and the next cut of `main` into `release` ships it in Rust and JS. A +deployment pinned to `release` can then roll lite-07 out without a wip wire +changing under it. Wire work after that targets a new `moq-lite-08-wip`. + +## Plan + +Decided 2026-10-05 in moq.pro's quest audit: finalizing lite-07 is upstream +work with its own quest. Until now nothing upstream owned it, while moq.pro's +mesh and customer rollouts waited on it and the +[mesh condition](/quest/m3/lite07-mesh.md) here waited on moq.pro. This quest +waits on nothing outside the repository; the rollouts and the mesh condition +follow it. + +"Final" means: + +- Every lite-07 wire change planned in m0 and m1 has landed, listed under + Required, plus the cache bug that only bites once lite-07 ships. +- The identifier becomes `moq-lite-07` in `rs/moq-net`, `js/net`, the draft + (whose text already names the rename), `doc/concept/moq-lite.md`, and the + CLI and relay docs. A wip peer and a final peer refuse each other by ALPN + rather than misparse; no compatibility shim. +- The draft's lite-07 changelog matches the wire and `just drafts check` + passes. Later changes start `moq-lite-08-wip` instead of editing lite-07. +- [Wire compatibility](/quest/m1/wire-compat.md) covers lite-07 once a + release carries it. + +Open, for the maintainer: + +- Whether a large in-flight change, such as subscribe ranges or live media + time, slips to lite-08 so lite-07 ships sooner. Recommended: keep the set + as planned, and revisit only if one of them stalls. +- Whether released clients offer lite-07 first by default, or accept it while + still offering lite-06 first for one release. Recommended: servers accept + it by default and clients keep lite-06 first for one release, so a + deployment rolls out on its own schedule. +- Whether Rust's `VarInt` must carry the full 64 bits + ([VarInt codec](/quest/m1/rs2ts/varint-codec.md)) before final, since Rust + refuses lite-07 values above 2^62-1 today. + +Public API: the lite-07 version constant and ALPN lose `-wip`. Wire: lite-07 +is frozen; older versions are unchanged. + +## Required + +- [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - lite-07 loses NO_CAPACITY and stamping +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07 restores SUBSCRIBE_DROP in place of `Stream Count` +- [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - SUBSCRIBE carries ranges and an order, and lite FETCH is gone +- [Live media time](/quest/m1/subscribe-live-time.md) - SUBSCRIBE_OK carries the publisher's live media time +- [Untimed lite-07](/quest/m1/lite-untimed.md) - an untimed track crosses the wire untimed +- [One route cost](/quest/m1/route-cost.md) - ANNOUNCE carries one cost +- [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - a lite-07 relay still delivers a group whose head it fetched + +## Related + +- [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment condition that follows this +- [moq.pro: lite-07 on cluster dials](https://github.com/moq-dev/moq.pro/blob/main/quest/m1/lite07.md) - the mesh rollout that adopts the finalized version, and the customer rollout after it diff --git a/quest/m1/stats-linger.md b/quest/m1/stats-linger.md new file mode 100644 index 00000000000..0380fe20763 --- /dev/null +++ b/quest/m1/stats-linger.md @@ -0,0 +1,45 @@ +# [S] Stats broadcasts linger + +## Goal + +A grouped stats broadcast (`//node/`) stays announced for +a linger after its group's last session and traffic row leave, so a viewer +leaving and another arriving within it causes no unannounce and no new +announce across the mesh. The counters it reports, and any usage read from +them, are unchanged. + +## Plan + +Decided 2026-10-05 in moq.pro's quest audit: approved as recommended. The +earlier plan was in the closed +[#4052](https://github.com/moq-dev/moq/pull/4052) beside tree-routed +announces; the linger is independent of that and lands alone. + +Data from moq.pro's live fleet: on 2026-09-29 one customer's node stats +broadcasts ended on 31 nodes at once every 2 to 4 minutes and returned 46 to +112 s later, and the fleet served about 148,000 `.stats` subscriptions against +7 media ones in that hour. Size the linger from those gaps, not the one minute +first proposed, and make it configurable. + +- `moq-stats`'s producer unpublishes a group broadcast on the drain where its + group has no traffic or session rows (`publish` in + `rs/moq-stats/src/produce.rs`). Keep it, and the epoch and group sequence it + publishes under ([stats epochs](/quest/m1/stats-epoch.md)), until the + linger elapses with the group still empty; a row returning re-arms it. +- Time decisions use `max(wall, pts)`; tests mock time. +- Depth 0 already lives for the producer's life and is unchanged. + +moq.pro tracks the `release` branch, so once this lands on `main` it is +backported to `release` (a cherry-pick PR). + +Test: a session closes and reopens within the linger with no unannounce; the +group unannounces after the linger; the reported totals match a run without +the linger. + +Public API: a linger knob on the stats producer config. Wire: none. + +## Related + +- [Stats epochs](/quest/m1/stats-epoch.md) - the name a lingering broadcast keeps +- [Bounded stats aggregate](/quest/m1/stats-aggregate-bound.md) - the aggregator's grace window for departed nodes +- [moq.pro: stats linger](https://github.com/moq-dev/moq.pro/blob/main/quest/m0/stats-linger.md) - the fleet adoption and its measurements diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 460fb24dcd3..20340567f3d 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -97,6 +97,12 @@ 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), along with its open questions. This line only publishes and reads the reports. +Decided 2026-10-05 (moq.pro audit): the client health model and preflight +media checks moq.pro planned against the pre-#4510 `.stats` broadcast are +generic, so they join this line as [client health](/quest/m1/stats/health.md) +and [preflight](/quest/m1/stats/preflight.md). moq.pro keeps the per-project +connection view and the dashboard flow. + ## Required - [Catalog track alias](/quest/m1/catalog-track-alias.md) - rendition keys @@ -107,6 +113,10 @@ along with its open questions. This line only publishes and reads the reports. moq-mux remuxes publish stats and feedback - [Browser reporters](/quest/m1/stats/js.md) - `` publishes stats and `` publishes feedback +- [Client health](/quest/m1/stats/health.md) - two snapshots become a + health sample and a verdict that names its observer, in Rust and JS +- [Preflight](/quest/m1/stats/preflight.md) - a bounded test run over a + broadcast reports which media layer is broken and why ## Related diff --git a/quest/m1/stats/health.md b/quest/m1/stats/health.md new file mode 100644 index 00000000000..77b8ab9fa70 --- /dev/null +++ b/quest/m1/stats/health.md @@ -0,0 +1,63 @@ +# [M] Client health from stats and feedback + +## Goal + +One shared model turns a client's reports into a health sample and a verdict. +Given two snapshots of a publisher's `stats` track or a viewer's `.echo` +feedback, it yields rates and loss as deltas over a stated interval, and +classifies the connection and each rendition as unknown, healthy, degraded, +or unhealthy, naming the observer of every number (the publisher's +self-report, a viewer's report). Missing or stale reports are unknown, never +healthy. Rust and JS compute the same verdict from the same fixtures, so the +demo dashboard, `moq` CLI sinks, [preflight](/quest/m1/stats/preflight.md), +and downstream dashboards share it. + +Not here: per-project or per-connection inventories, dashboards, history, or +any relay-side session table. Downstream (moq.pro) keeps its project view. + +## Plan + +Decided 2026-10-05, from moq.pro's +[connection health](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-connection-health.md): +the health sample and its classification are generic, so they move upstream +into this line; moq.pro keeps the per-project view and dashboard. Rejected: +deferring the model. + +The model reads the shapes this line settled after +[#4510](https://github.com/moq-dev/moq/pull/4510): the publisher's `stats` +track named in the catalog, keyed by rendition alias, and viewers' `.echo` +broadcasts. moq.pro's plan predates that and read a `.stats` broadcast that no +longer exists; do not revive it. + +Guidance, to be settled while building: + +- Inputs are the snapshot types from [the schema](/quest/m1/stats/schema.md): + `transport` (rtt, rate, loss, sample age) and the per-rendition counters. + Counters are cumulative, so a sample is the delta of two snapshots over + their interval; a counter reset (a new epoch) starts over rather than going + negative. +- Thresholds are a documented default the caller can override, not policy + baked into the types. Start from a few measured cases rather than guesses. +- A verdict carries its evidence: which inputs drove it and who observed them. + A browser publisher with only PROBE rtt yields unknown for what it cannot + see, never a guess. +- The relay's [QoS](/quest/m1/qos/README.md) counters (starvation, + timeliness) are the other half of a broadcast verdict. Leave a seam to + combine them, but this quest classifies client reports only. +- Lives beside the snapshot types in `hang` and `@moq/hang` unless building + it shows a better home. + +Prove a degrading publisher self-report, a degrading viewer report, a stale +report going unknown, and a counter reset, from shared fixtures in both +languages. Docs: the media section of `doc/concept/stats.md`. + +Public API: new health types in `hang` and `@moq/hang`. Wire: none. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the snapshot types the model reads + +## Related + +- [moq.pro: connection health](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-connection-health.md) - the per-project view built on this model +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other half of a broadcast verdict diff --git a/quest/m1/stats/preflight.md b/quest/m1/stats/preflight.md new file mode 100644 index 00000000000..0113cab12c9 --- /dev/null +++ b/quest/m1/stats/preflight.md @@ -0,0 +1,48 @@ +# [M] Preflight media checks + +## Goal + +A bounded test run against a published broadcast produces one report a person +can act on: catalog validity, codec support, time to the first keyframe, +bitrate and frame cadence per rendition, keyframe interval, audio/video skew, +timeline continuity, the [health verdict](/quest/m1/stats/health.md) from the +publisher's stats, and a clean unannounce at the end. A failure names the +broken layer and its evidence instead of one score, and the raw evidence is +kept so two people reach the same diagnosis. + +Not here: authorization, route selection, project-scoped test targets, or any +dashboard flow. Downstream (moq.pro) owns those. + +## Plan + +Decided 2026-10-05, from moq.pro's +[stream preflight](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-preflight.md): +the media checks are generic, so they live upstream in this line; moq.pro +keeps the project-scoped target and dashboard. Rejected: deferring them. + +Guidance, to be settled while building: + +- A library check over a `broadcast::Consumer` and its catalog, with a thin + `moq` CLI sink that runs it for a bounded window and prints the report as + JSON. The verb is the maintainer's call when the PR proposes it. +- Reads only what the broadcast already carries: the catalog, media timestamps + and keyframe flags, and the `stats` track when the catalog names one. A + broadcast without a stats track still gets the media checks, with health + reported as unknown. +- Codec support means "a stock player in this repo can decode it", checked + against the same rules rendition selection uses, not a separate list. +- One run, one report. No continuous pipeline. + +Prove a healthy publisher, and deterministic failures for an invalid +catalog, an unsupported codec, a missing first keyframe, excessive A/V skew, +and a timeline jump. Docs: `doc/bin/cli.md` for the sink. + +Public API: a preflight check and its report type, and a CLI sink. Wire: none. + +## Required + +- [Client health](/quest/m1/stats/health.md) - the verdict the report includes + +## Related + +- [moq.pro: stream preflight](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-preflight.md) - the project-scoped target and dashboard flow built on these checks diff --git a/quest/m2/README.md b/quest/m2/README.md index e6338c65185..896bcb9270b 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -15,6 +15,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). ## Required +- [RTSP import](/quest/m2/rtsp-import.md) - `moq import rtsp` publishes an IP camera from its own network, through a `moq-rtsp` crate whose one-session ingest a caller can supervise itself - [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 @@ -126,6 +127,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - H.264 and H.265 from an external Vulkan image on RADV, hand-rolled on ash, proven on an RX 9070 - [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - an explicit-sync DMA-BUF reaches Intel's encoder, proven on Arrow Lake - [A release carries multi-vendor GPU input](/quest/m2/gpu-release.md) - `release` ships all three so a pinned consumer drops its vendor code +- [GPU capacity and health](/quest/m2/gpu-health.md) - moq-video reports each device's sessions, memory, utilization, and health on NVIDIA, AMD, and Intel alike - [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 - [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/gpu-health.md b/quest/m2/gpu-health.md new file mode 100644 index 00000000000..c33ce0a4337 --- /dev/null +++ b/quest/m2/gpu-health.md @@ -0,0 +1,54 @@ +# [M] Vendor-neutral GPU capacity and health + +## Goal + +moq-video reports, per GPU device, what an admission controller needs to decide +whether one more encode or decode fits: encoder and decoder sessions in use +and any hard session limit, memory used and available, and engine +utilization. It also reports device health: whether the device is usable, +lost, or reset. The same API works on NVIDIA, AMD, and Intel, keyed by the +device identity [`Surface::Vulkan`](/quest/m2/gpu-surface.md) matches on, so a +caller writes no vendor code. A value a driver cannot provide is absent, never +guessed. + +Not here: admission policy, thresholds, frame-lateness tracking, or draining. +Those are the caller's. + +## Plan + +Decided 2026-10-05 in moq.pro's quest audit: vendor-neutral now, not +NVIDIA-scoped. Reason: [GPU surface](/quest/m2/gpu-surface.md), +[Vulkan encode](/quest/m2/vulkan-encode.md), and +[VA-API import](/quest/m2/vaapi-vulkan-import.md) make AMD and Intel encode +first-class, so an NVML-shaped API would be rewritten once they land. +moq.pro's transcode admission and its benchmarks assume NVML today; they +adopt this instead. + +Guidance, to be settled while building: + +- Prefer one source that spans vendors over three vendor paths. Candidates to + evaluate: `VK_EXT_memory_budget` for memory, DRM fdinfo or sysfs engine + busyness for utilization on amdgpu, i915, and xe, and NVML only where + NVIDIA offers nothing neutral (encoder session limits on consumer cards). + Record which source backs each field per vendor. +- Sessions moq-video opened itself are counted in process; device-wide counts + come from the driver where it reports them, since several processes may + share a GPU. +- Health covers a lost or reset device, surfaced from the backends' own + errors (`VK_ERROR_DEVICE_LOST`, CUDA and VA-API equivalents) and from the + driver's reset counters where exposed. +- A snapshot call, not a callback; cheap enough to poll about once a second. +- Additive, so it can reach `release` by backport without waiting for + [the multi-vendor release](/quest/m2/gpu-release.md). + +Test: a unit test of each source's parsing against recorded fixtures, and +ignored hardware tests in `just rs gpu`'s per-vendor branches that open an +encoder and see the session and memory counts move. + +Public API: a device capacity and health snapshot in moq-video. Wire: none. + +## Related + +- [One external GPU image for every encoder](/quest/m2/gpu-surface.md) - the device identity both key by +- [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - the AMD backend whose sessions this counts +- [moq.pro: transcode admission](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/transcode/ws3-admission.md) - the admission and health checks that consume this diff --git a/quest/m3/rtsp-import.md b/quest/m2/rtsp-import.md similarity index 60% rename from quest/m3/rtsp-import.md rename to quest/m2/rtsp-import.md index 9386d6494a0..71cebb8f20f 100644 --- a/quest/m3/rtsp-import.md +++ b/quest/m2/rtsp-import.md @@ -1,4 +1,4 @@ -# [S] RTSP import +# [M] RTSP import ## Goal @@ -8,13 +8,21 @@ own network, so a camera behind NAT needs no inbound port. A `moq-rtsp` library crate carries it, so other publishers reuse it the way they reuse moq-srt and moq-rtmp. +The library's entry point ingests one RTSP session into a broadcast the +caller supplies, with no reconnect: it returns when the session ends, fails, +or its timeline jumps. The CLI wraps it with reconnect and a fresh epoch per +session. A caller with its own supervisor, such as Pronto's truck, runs the +library directly, including two sessions (two URLs) into one broadcast. + Non-goals: an RTSP server (push ingest), a relay pulling cameras itself, and codecs nothing in the stack plays (G.711, MJPEG). -Parked in m3 until a camera customer asks (2026-10-01). - ## Plan +Moved from m3 to m2 on 2026-10-05: security cameras are moq.pro's priority +customer segment, so the "no consumer" reason for parking it is gone. moq.pro's +camera guide and Pronto's truck consume it. + Decided 2026-10-01: - retina is the RTSP client and depacketizer. RTP over TCP interleaved is @@ -27,9 +35,6 @@ Decided 2026-10-01: above all (common on cameras), is skipped with one clear warning and the broadcast goes on video-only. Transcoding it waits for a customer who needs it. -- A camera reboot or network blip reconnects in-process with backoff rather - than exiting for a supervisor to restart. This deliberately differs from - Pronto's truck, which exits so a supervisor surfaces half-dead sessions. - Each camera session publishes a new broadcast under a fresh epoch, per [Broadcast epochs](/quest/m0/broadcast-epoch/README.md), never spliced onto the last one. A new session's RTP time restarts, so a reconnect finishes the @@ -47,10 +52,24 @@ Decided 2026-10-01: - Prior art: moq.pro's `pronto/truck/src/camera.rs` is a working retina pull client, video only, run against mediamtx and real cameras. +Decided 2026-10-05: + +- The library ingests one session and never reconnects. The caller supplies + the broadcast (or the moq-mux importer state behind it), so two sessions, + such as the truck's H.264 SD and H.265 HD URLs, can publish renditions of one + broadcast. A session end, a failure, and a timeline jump all return to the + caller, which decides whether to retry. Reason: the truck deliberately exits + for systemd so a stuck Starlink session surfaces, and an in-process retry + inside the library would force it to opt out. +- `moq import rtsp` owns reconnect with backoff: each new session gets a fresh + epoch, a fresh catalog, and starts on a keyframe, as above. Rejected: the + truck adopting the crate's reconnect. + Test against a local RTSP source serving a known H.264 + AAC clip (Pronto uses mediamtx), checking the catalog and first frames; a G.711 source that -publishes video only; and a source restarted mid-stream, whose RTP time -resets, that ends the first broadcast cleanly and publishes a second one under +publishes video only; two sessions ingested into one caller broadcast; and a +source restarted mid-stream, whose RTP time resets: the library call returns, +and the CLI ends the first broadcast cleanly and publishes a second one under a new epoch, starting on a keyframe with its own catalog. `doc/bin/cli.md` documents `import rtsp`. @@ -60,4 +79,6 @@ Wire: none. ## Related - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the epoch each camera session's broadcast publishes under -- [moq.pro's Pronto truck](https://github.com/moq-dev/moq.pro/blob/main/pronto/truck/src/camera.rs) - the prior art this generalizes, and the first consumer +- [moq.pro's Pronto truck](https://github.com/moq-dev/moq.pro/blob/main/pronto/truck/src/camera.rs) - the prior art this generalizes +- [moq.pro: Pronto truck on moq-rtsp](https://github.com/moq-dev/moq.pro/blob/main/quest/m3/truck-rtsp.md) - runs the library entry point under its own supervisor +- [moq.pro: Camera (RTSP) guide](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/rtsp-guide.md) - documents `moq import rtsp` for customers once a release ships it diff --git a/quest/m3/README.md b/quest/m3/README.md index 0e5e3f52313..8695f914397 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -47,4 +47,3 @@ deleted when it goes stale; git history keeps it. - [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 diff --git a/quest/m3/lite07-mesh.md b/quest/m3/lite07-mesh.md index 8fb2d43a835..5490d8b75c9 100644 --- a/quest/m3/lite07-mesh.md +++ b/quest/m3/lite07-mesh.md @@ -12,4 +12,6 @@ this quest and every `Required` entry that links it. As of 2026-09-30 lite-07 ships only as the off-by-default `moq-lite-07-wip` ALPN, and moq.pro still has its lite-07 rollout quest open -(`quest/m1/lite07.md` in moq-dev/moq.pro). +(`quest/m1/lite07.md` in moq-dev/moq.pro). That rollout waits on +[Finalize moq-lite-07](/quest/m1/lite07-finalize.md), so this condition cannot +clear before a release carries the final version. From 1e059abe9e1433cc64b8691ac040d8cb3b6c1686 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:30:12 -0700 Subject: [PATCH 2/9] quest: address review on the moq.pro audit follow-ups Co-Authored-By: Claude Opus 5.5 --- ...-bench-every-readme-example-fails-to-parse-and.md | 4 +++- quest/m1/bench-buckets.md | 9 ++++++--- quest/m1/lite07-finalize.md | 12 ++++++++++-- quest/m1/stats-linger.md | 10 +++++++--- quest/m1/stats/preflight.md | 4 +++- quest/m2/gpu-health.md | 5 ++++- quest/m2/rtsp-import.md | 9 +++++---- 7 files changed, 38 insertions(+), 15 deletions(-) diff --git a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md index dc9e0c67728..02a942864f3 100644 --- a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md +++ b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md @@ -18,7 +18,9 @@ first groups landed while the swarm was still connecting. - Emit per-interval percentiles (or the interval histogram) beside the cumulative ones: keep the previous snapshot's buckets, diff, and compute - p50/p90/p99 over the delta. `latency_samples` is already per-line. + p50/p90/p99 over the delta. Report that interval's sample count as the + sum of the delta's buckets: `latency_samples` comes from the cumulative + snapshot, so it must not be paired with interval percentiles. - Document the new fields and update the methodology paragraph. The README examples parse today (`--connect`, `README.md:66-71`; `--file` is diff --git a/quest/m1/bench-buckets.md b/quest/m1/bench-buckets.md index d76911b2d56..5f9c98e3f6f 100644 --- a/quest/m1/bench-buckets.md +++ b/quest/m1/bench-buckets.md @@ -4,9 +4,11 @@ Every `moq-bench` JSONL line carries that interval's latency histogram in a versioned, documented bucket layout, so the buckets from several bench -processes on several hosts sum element-wise over any window into one exact +processes on several hosts sum element-wise over any window into one distribution. A percentile computed once from the summed buckets matches one -computed from the concatenated samples. +computed from the concatenated samples binned by the same layout and overflow +rule: the buckets are lossy, so the match is exact at bucket resolution, not +at raw-sample precision. ## Plan @@ -28,7 +30,8 @@ so the bench emits mergeable buckets. Approved as recommended. - Publisher and subscriber stay on one host, so latency closes on one clock; `latency_clock_skew` keeps flagging a violation. - A test sums fixture buckets from two runs and checks the percentiles - against the concatenated samples. Update `rs/moq-bench/README.md`. + against the concatenated samples, binned by the same layout and the same + overflow bucket (60,000 ms and above today) before the percentile is taken. Update `rs/moq-bench/README.md`. moq-bench is 0.0.x, so this lands on main. diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 725d4f3aff3..877d63fc9ac 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -19,8 +19,11 @@ follow it. "Final" means: -- Every lite-07 wire change planned in m0 and m1 has landed, listed under - Required, plus the cache bug that only bites once lite-07 ships. +- Every wire change listed under Required has landed, plus the cache bug + that only bites once lite-07 ships. That list is the whole freeze set: a + wire quest not on it, such as + [Routes and announces](/quest/m1/cluster-routing/routes.md), targets the + next wip version unless the maintainer adds it (open below). - The identifier becomes `moq-lite-07` in `rs/moq-net`, `js/net`, the draft (whose text already names the rename), `doc/concept/moq-lite.md`, and the CLI and relay docs. A wip peer and a final peer refuse each other by ALPN @@ -32,6 +35,11 @@ follow it. Open, for the maintainer: +- Whether [Routes and announces](/quest/m1/cluster-routing/routes.md)'s new + ROUTE and ANNOUNCE wire gates lite-07 or moves to lite-08. Recommended: + lite-08. It is [XL] and still in design, and holding lite-07 for it holds + announce compression for every mesh waiting on lite-07. + - Whether a large in-flight change, such as subscribe ranges or live media time, slips to lite-08 so lite-07 ships sooner. Recommended: keep the set as planned, and revisit only if one of them stalls. diff --git a/quest/m1/stats-linger.md b/quest/m1/stats-linger.md index c3ea7845f7c..41cc879ce01 100644 --- a/quest/m1/stats-linger.md +++ b/quest/m1/stats-linger.md @@ -26,15 +26,19 @@ first proposed, and make it configurable. `rs/moq-stats/src/produce.rs`). Keep it, and the epoch and group sequence it publishes under ([stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md)), until the linger elapses with the group still empty; a row returning re-arms it. + While it lingers empty, its live gauges and session presence read zero and + its cumulative traffic totals are kept, so a reader sees no stale live + counters. - Time decisions use `max(wall, pts)`; tests mock time. - Depth 0 already lives for the producer's life and is unchanged. moq.pro tracks the `release` branch, so once this lands on `main` it is backported to `release` (a cherry-pick PR). -Test: a session closes and reopens within the linger with no unannounce; the -group unannounces after the linger; the reported totals match a run without -the linger. +Test: a session closes and reopens within the linger with no unannounce; +while the group lingers empty, live gauges and presence are zero and +cumulative totals are unchanged; the group unannounces after the linger; the +reported totals match a run without the linger. Public API: a linger knob on the stats producer config. Wire: none. diff --git a/quest/m1/stats/preflight.md b/quest/m1/stats/preflight.md index 0113cab12c9..d6f64e2f09c 100644 --- a/quest/m1/stats/preflight.md +++ b/quest/m1/stats/preflight.md @@ -6,7 +6,9 @@ A bounded test run against a published broadcast produces one report a person can act on: catalog validity, codec support, time to the first keyframe, bitrate and frame cadence per rendition, keyframe interval, audio/video skew, timeline continuity, the [health verdict](/quest/m1/stats/health.md) from the -publisher's stats, and a clean unannounce at the end. A failure names the +publisher's stats, and whether the broadcast ends with a clean unannounce +(observed by the check; the publisher, which owns the `broadcast::Producer`, +does the unannounce). A failure names the broken layer and its evidence instead of one score, and the raw evidence is kept so two people reach the same diagnosis. diff --git a/quest/m2/gpu-health.md b/quest/m2/gpu-health.md index c33ce0a4337..87014788d34 100644 --- a/quest/m2/gpu-health.md +++ b/quest/m2/gpu-health.md @@ -30,7 +30,10 @@ Guidance, to be settled while building: evaluate: `VK_EXT_memory_budget` for memory, DRM fdinfo or sysfs engine busyness for utilization on amdgpu, i915, and xe, and NVML only where NVIDIA offers nothing neutral (encoder session limits on consumer cards). - Record which source backs each field per vendor. + Record which source backs each field per vendor, and whether each memory + value is process-scoped or device-wide: `VK_EXT_memory_budget`'s + `heapUsage` is this process's only, so device-wide usage needs a driver + source (DRM fdinfo per client, sysfs, or NVML). - Sessions moq-video opened itself are counted in process; device-wide counts come from the driver where it reports them, since several processes may share a GPU. diff --git a/quest/m2/rtsp-import.md b/quest/m2/rtsp-import.md index 71cebb8f20f..cccf84a6e7b 100644 --- a/quest/m2/rtsp-import.md +++ b/quest/m2/rtsp-import.md @@ -35,13 +35,14 @@ Decided 2026-10-01: above all (common on cameras), is skipped with one clear warning and the broadcast goes on video-only. Transcoding it waits for a customer who needs it. -- Each camera session publishes a new broadcast under a fresh epoch, per +- A reconnect publishes a new broadcast under a fresh epoch, per [Broadcast epochs](/quest/m0/broadcast-epoch/README.md), never spliced onto - the last one. A new session's RTP time restarts, so a reconnect finishes the + the last one. A new session's RTP time restarts, so the CLI finishes the old broadcast cleanly and builds a fresh catalog, tracks, and importers, starting on a keyframe. A timestamp jump inside one session (retina #64) - also ends that session's broadcast and starts a new one, instead of failing - the track. Decided 2026-10-02; shifting timestamps onto the existing + ends that library session and returns to its caller, which starts a new + broadcast, instead of failing the track. Separate URLs a library caller + publishes as renditions of one broadcast share its epoch and catalog. Decided 2026-10-02; shifting timestamps onto the existing catalog clock behind a `discontinuity()` marker was rejected, since a broadcast name always means the same content. - Credentials ride the URL's userinfo, as every RTSP tool takes them. retina From a1c33656dfb270a1941ecaf357000bb9e00f2c9b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:39:29 -0700 Subject: [PATCH 3/9] quest: apply the maintainer's decisions on the moq.pro audit follow-ups The route layer lands in lite-07 and gates its finalize, which needs the whole subscribe-ranges line; wire quests target the wip version until the maintainer cuts it, so the auth line moves off lite-06. Stats linger moves to m0 with a new epoch after the linger, HLS bounded playlists leave the archive line, GPU health keys by the render node, and the RTSP library takes a caller broadcast whose owner restarts every session on a jump. Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 4 + .../broadcast-epoch/stats-aggregate-bound.md | 1 + quest/{m1 => m0}/stats-linger.md | 30 ++++--- quest/m0/wildcard/README.md | 6 +- ...every-readme-example-fails-to-parse-and.md | 2 +- quest/m1/README.md | 6 +- quest/m1/archive/README.md | 4 +- quest/m1/archive/hls.md | 67 ---------------- quest/m1/archive/proof.md | 3 +- quest/m1/auth/README.md | 19 +++-- quest/m1/auth/interop.md | 8 +- quest/m1/auth/lite.md | 13 +-- quest/m1/auth/token-in-band.md | 8 +- quest/m1/auth/unauthorized.md | 6 +- quest/m1/bench-buckets.md | 28 ++++--- quest/m1/cluster-routing/README.md | 11 ++- quest/m1/cluster-routing/routes.md | 7 +- quest/m1/cluster-routing/selection.md | 4 +- quest/m1/hls-bounded.md | 80 +++++++++++++++++++ quest/m1/lite07-finalize.md | 67 +++++++++------- quest/m1/qos/README.md | 19 +++-- quest/m1/stats/README.md | 12 ++- quest/m1/stats/health.md | 34 +++++--- quest/m1/stats/preflight.md | 26 +++--- quest/m2/gpu-health.md | 40 +++++++--- quest/m2/gpu-surface.md | 5 +- quest/m2/rtsp-import.md | 66 +++++++++------ quest/m2/vaapi-vulkan-import.md | 14 ++-- quest/m3/lite07-mesh.md | 5 ++ 29 files changed, 360 insertions(+), 235 deletions(-) rename quest/{m1 => m0}/stats-linger.md (59%) delete mode 100644 quest/m1/archive/hls.md create mode 100644 quest/m1/hls-bounded.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 050683a4e08..680f4c71e5c 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -28,6 +28,9 @@ 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. +[Stats linger](/quest/m0/stats-linger.md) joined m0 on 2026-10-05 as a +standalone quest, not a release gate: moq.pro's m0 waits on a `release` +commit carrying it, so it lands on main and is backported. Routing: the wildcard line is prefix-only on the wire; its resolve and demand work is done on the line branch and waits to land. Serving the relay's @@ -56,6 +59,7 @@ a published `@moq/watch` break. - [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 - [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers, and viewer churn no longer leaks fronts +- [Stats linger](/quest/m0/stats-linger.md) - a grouped stats broadcast stays announced for a linger after its last session, so viewer churn stops re-announcing it across the mesh, backported to `release` - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh `@` epoch, viewers follow the newest live one, and bare names still resolve on every version - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess diff --git a/quest/m0/broadcast-epoch/stats-aggregate-bound.md b/quest/m0/broadcast-epoch/stats-aggregate-bound.md index 7fe85310c7c..7a89e753a6e 100644 --- a/quest/m0/broadcast-epoch/stats-aggregate-bound.md +++ b/quest/m0/broadcast-epoch/stats-aggregate-bound.md @@ -42,3 +42,4 @@ Public API: none expected beyond a possible grace-window knob on - [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 +- [Stats linger](/quest/m0/stats-linger.md) - a group's node broadcast outlives a short gap instead of churning an aggregate entry diff --git a/quest/m1/stats-linger.md b/quest/m0/stats-linger.md similarity index 59% rename from quest/m1/stats-linger.md rename to quest/m0/stats-linger.md index 41cc879ce01..b2e5c6a29d3 100644 --- a/quest/m1/stats-linger.md +++ b/quest/m0/stats-linger.md @@ -13,7 +13,9 @@ them, are unchanged. Decided 2026-10-05 in moq.pro's quest audit: approved as recommended. The earlier plan was in the closed [#4052](https://github.com/moq-dev/moq/pull/4052) beside tree-routed -announces; the linger is independent of that and lands alone. +announces; the linger is independent of that and lands alone. It sits in m0 +as a standalone quest, not a release gate, because moq.pro's m0 stats-linger +quest waits on a `release` commit carrying it (decided 2026-10-05). Data from moq.pro's live fleet: on 2026-09-29 one customer's node stats broadcasts ended on 31 nodes at once every 2 to 4 minutes and returned 46 to @@ -25,22 +27,32 @@ first proposed, and make it configurable. group has no traffic or session rows (`publish` in `rs/moq-stats/src/produce.rs`). Keep it, and the epoch and group sequence it publishes under ([stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md)), until the - linger elapses with the group still empty; a row returning re-arms it. - While it lingers empty, its live gauges and session presence read zero and - its cumulative traffic totals are kept, so a reader sees no stale live - counters. + linger elapses with the group still empty; a row returning within the + linger re-arms it. While it lingers empty, its live gauges and session + presence read zero and its cumulative traffic totals are kept, so a reader + sees no stale live counters. +- Once the linger elapses, the group broadcast unannounces. A later return + re-announces it under a new epoch, with its group sequence and totals + counted from zero + (decided 2026-10-05). This reverses stats epochs' one-epoch-per-producer + rule; [#4846](https://github.com/moq-dev/moq/pull/4846) writes that reversal + into the epoch line, so this quest only follows it. - Time decisions use `max(wall, pts)`; tests mock time. - Depth 0 already lives for the producer's life and is unchanged. moq.pro tracks the `release` branch, so once this lands on `main` it is -backported to `release` (a cherry-pick PR). +backported to `release` as an additive PR. The backport is rewritten against +`release`'s `produce.rs`, which has no epochs: a returning group starts a new +broadcast from the wall-clock group seed of #4810 instead. Test: a session closes and reopens within the linger with no unannounce; while the group lingers empty, live gauges and presence are zero and -cumulative totals are unchanged; the group unannounces after the linger; the -reported totals match a run without the linger. +cumulative totals are unchanged; the group unannounces after the linger, and +a return after that announces a new epoch counted from zero; the reported +totals match a run without the linger. -Public API: a linger knob on the stats producer config. Wire: none. +Public API: a linger knob on the stats producer config, surfaced in the relay +as `stats.linger` / `--stats-linger` beside `--stats-enabled`. Wire: none. ## Related diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index a8f7b1ad5ec..b53579c9d35 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -185,9 +185,9 @@ path, not with a route identity or a generation field. - **Patterns are independent of clustering.** The `moq-pattern` crate owns the matching semantics tokens and filters share, with no draft of its own; no announce message carries a pattern on either protocol (AUTH grants on - lite-06 do, per the [Auth](/quest/m1/auth/README.md) line). moq-cluster adds hop - lists, costs, pool selection, and request resolution to prefix - advertisements. + the wip lite version do, per the [Auth](/quest/m1/auth/README.md) line). + moq-cluster adds hop lists, costs, pool selection, and request resolution + to prefix advertisements. ### Where derived output lives diff --git a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md index 02a942864f3..220355d6e14 100644 --- a/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md +++ b/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md @@ -35,4 +35,4 @@ moq-bench is 0.0.x, so this lands on main. ## Related -- [Mergeable bench buckets](/quest/m1/bench-buckets.md) - the interval buckets these percentiles can be computed from +- [Mergeable bench buckets](/quest/m1/bench-buckets.md) - emits this quest's interval delta in a mergeable layout, and backports both to `release` diff --git a/quest/m1/README.md b/quest/m1/README.md index 07e2529ccfe..5f5c19e6971 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -39,7 +39,6 @@ blocks. The quests that gated m0 lines moved under them. - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net - [Hard fork](/quest/m1/quic/fork/README.md) - quinn hard-forked in-tree as `moq-quic`, ranked ahead of transport-seam and perf; the rest of the QUIC line follows it -- [Stats linger](/quest/m1/stats-linger.md) - a grouped stats broadcast stays announced for a linger after its last session, so viewer churn stops re-announcing it across the mesh - [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost - [Delete removed cluster flags](/quest/m1/cluster-shims.md) - `mesh` and `linger` leave `cluster::Config` and their flags become unknown @@ -68,7 +67,8 @@ blocks. The quests that gated m0 lines moved under them. - [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 -- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - lite-07 negotiates as `moq-lite-07` with a frozen wire, and the next release ships it +- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time +- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [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 - [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 @@ -87,7 +87,6 @@ blocks. The quests that gated m0 lines moved under them. - [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 - [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 -- [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()` - [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - @moq/json and @moq/flate consumers return each value's timestamp, with snapshot `next()` and `latest()` @@ -99,6 +98,7 @@ blocks. The quests that gated m0 lines moved under them. - [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 - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface +- [Bounded HLS playlists](/quest/m1/hls-bounded.md) - `moq-hls` renders a capped sliding window for a fresh viewer, with a stable media sequence, gap slots, and no video before a sync point - [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` diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index 29166e5aa43..fbc5f955689 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -115,13 +115,13 @@ owned by that prerequisite, not duplicated in archive storage. - [Recording writer](/quest/m1/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record - [Recording reader](/quest/m1/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` - [Replay provenance](/quest/m1/archive/provenance.md) - a replay's catalog names its timeline, replay path, store URL, and format version -- [Bounded HLS playlists](/quest/m1/archive/hls.md) - a fresh viewer's playlist work is bounded by the window, with a stable media sequence, gap slots, and no video before a keyframe - [DVR rewind](/quest/m1/archive/dvr.md) - seek through a bounded archive and return to live playback - [Enrollment flake](/quest/m1/archive/enrollment-flake.md) - the opening-snapshot test waits for real enrollment, not the `.info` file -- [Archive proof](/quest/m1/archive/proof.md) - prove persistence ordering, selective reads, exact FETCH replay, and timeline-only HLS generation +- [Archive proof](/quest/m1/archive/proof.md) - prove persistence ordering, selective reads, and exact FETCH replay; its HLS step is done on the line branch ## Related +- [Bounded HLS playlists](/quest/m1/hls-bounded.md) - the live renderer rules a replayed archive inherits, planned outside this line - [Catalog track identity](/quest/m2/catalog-tracks.md) - explore immutable definitions or explicit version binding independently of archives - [wildcard](/quest/m0/wildcard/README.md) - catch-all routing exposes an archive at its stable replay path diff --git a/quest/m1/archive/hls.md b/quest/m1/archive/hls.md deleted file mode 100644 index c644eba4d2a..00000000000 --- a/quest/m1/archive/hls.md +++ /dev/null @@ -1,67 +0,0 @@ -# [M] Bounded HLS playlists - -## Goal - -A fresh viewer joins a days-old broadcast, live or archived, and `moq-hls` -renders its playlists with work bounded by the advertised window, not by the -broadcast's age. The media playlist lists a sliding window whose -`EXT-X-MEDIA-SEQUENCE` every edge and every reload agree on. A span with no -media in one rendition keeps its slot as a duration-preserving `EXT-X-GAP` -without holding back later segments or sibling renditions. A video rendition -is not advertised until its window holds a segment that starts on a -keyframe, so a stock player is never sent to video it cannot start decoding. - -This is the generic renderer. Managed edges (moq.pro) only wire it to their -projects, routes, and auth. - -## Plan - -Decided 2026-10-05, from moq.pro's -[bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md): -the windowed sequence, gap slots, and keyframe gating are renderer rules every -`moq-hls` user needs, so they live here and moq.pro keeps only the edge -wiring. Rejected: keeping them in moq.pro. - -The offline archive HLS this quest used to describe is done on the archive -line's branch (#4115, #4155), which deletes this file. When that branch next -merges `main`, keep this quest. Its -per-track timelines quest already derives segments at the edge from group -timestamps and emits `EXT-X-GAP` for a rendition with no group start in a -span; whichever lands second rebases onto the other, and the rules here hold -for both shapes. - -Start by auditing `rs/moq-hls/src/export` against each rule; much exists -(`segments.rs` numbers aligned segments and carries gap rows, `playlist.rs` -writes `EXT-X-GAP`). Fix only what a test shows missing: - -- **Bounded join.** Rendering for a new viewer reads at most the window's - records from the timeline (`moq_json::Window`), never the whole history, - and never GETs or FETCHes media. A live publisher that never pops its - timeline must not make a join cost grow with broadcast age. -- **Stable sequence.** `EXT-X-MEDIA-SEQUENCE` is the window's first segment - number, derived from the timeline, so two edges and a reload after a pop - agree. -- **Gaps.** A record missing one track becomes a gap slot in that rendition - only; siblings keep listing, and a rendition switch after a gap lands on the - next real segment. -- **Keyframe gating.** The multivariant playlist omits a video rendition - until its window holds a keyframe-started segment. A catalog that arrives - first may expose audio only, or answer unavailable. - -Prove: a fresh join after simulated days of publishing reads a bounded number -of records (count them); catalog arrival before the first keyframe; gaps in -one track; switching after a gap; healthy siblings keep their listing; two -exporters over one timeline render identical sequence numbers. Tests mock -time. - -moq.pro pins `release`, so it adopts this through the next release that -carries it. - -Public API: none expected. Wire: none. - -Not blocked by the [recording reader](/quest/m1/archive/reader.md): the rules -apply to live timelines first, and a replayed archive inherits them. - -## Related - -- [moq.pro: bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md) - the edge wiring that adopts this renderer diff --git a/quest/m1/archive/proof.md b/quest/m1/archive/proof.md index f53a3d94433..0ffdb48f1ce 100644 --- a/quest/m1/archive/proof.md +++ b/quest/m1/archive/proof.md @@ -59,7 +59,8 @@ restart must finish this cleanup before accepting new groups. Finally render and reload HLS playlists while rejecting every media-object GET until a segment URI is requested. The range-bearing URI must resolve one -object directly without any listing or separate index object. +object directly without any listing or separate index object. This HLS step +is done on the archive line branch (#4115, #4169). ## Required diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index abbd24aa17e..26822c7824e 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -74,8 +74,9 @@ Decisions settled while planning, recorded so review does not relitigate them: scoped grant because the caller is another relay. - **Client API.** Tokens live on `moq_tokio::connect::Config`, the dial-side config, and `Connection` exposes the live session's auth handle. -- **Spec home.** The AUTH stream is lite-06 core in - `drafts/draft-lcurley-moq-lite.md`, the way routing is. moq-transport gets +- **Spec home.** The AUTH stream is core in the wip lite version + (`moq-lite-07-wip` today) in `drafts/draft-lcurley-moq-lite.md`, the way + routing is. moq-transport gets `drafts/draft-lcurley-moq-auth.md`, a setup-option-negotiated extension with AUTH, AUTH_OK, and AUTH_ERROR control messages, mirroring how moq-cluster is the IETF binding of lite's routing. @@ -83,18 +84,20 @@ Decisions settled while planning, recorded so review does not relitigate them: SUBSCRIBE_OK. Rust is `moq_net::auth` with `auth::Grant`, `auth::Handle`, `auth::Token`, and `auth::Request`; JS mirrors as `connection.auth`. -Everything here is additive: `Session::auth()` is new, the relay derives the -grant from the origin handles it already scopes, and AUTH is added to the -existing lite-06 ALPN. +Everything here is additive: `Session::auth()` is new, and the relay derives +the grant from the origin handles it already scopes. Decided 2026-10-05: wire +work targets the wip lite version until the maintainer cuts it, never a +published version in place, so AUTH and its stream code land in +`moq-lite-07-wip` (or whichever version is wip then), not lite-06. ## Required - [WebSocket refusal](/quest/m1/auth/ws-unauthorized.md) - the relay serves WebSocket through moq-tokio, so a refused token closes the session as Unauthorized, as QUIC does -- [Lite stream](/quest/m1/auth/lite.md) - both sides of a lite-06 session +- [Lite stream](/quest/m1/auth/lite.md) - both sides of a wip-version lite session exchange grants over AUTH streams, exposed as `Session::auth()`, and an out-of-scope announce aborts the session - [Interop grants](/quest/m1/auth/interop.md) - the interop matrix asserts - each lite-06 cell's grant and that a publish outside it fails loud + each AUTH-capable cell's grant and that a publish outside it fails loud - [Unauthorized reset](/quest/m1/auth/unauthorized.md) - a subscription that loses access resets with a dedicated UNAUTHORIZED stream code - [AUTH_OK preflight](/quest/m1/auth/auth-ok-preflight.md) - an unencodable IETF grant answers NOT_SUPPORTED with nothing written, as JS already does @@ -118,7 +121,7 @@ existing lite-06 ALPN. binding through moq-ffi - [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave the URL: a session starts on what the URL carried and its AUTH streams add - the rest, with the URL kept for peers below lite-06 + the rest, with the URL kept for peers without the AUTH stream - [Peer grants](/quest/m1/auth/peer-grant.md) - the relay issues a hop-bound, asymmetrically signed grant a browser can verify; HS256 keys issue none diff --git a/quest/m1/auth/interop.md b/quest/m1/auth/interop.md index 9d9ecf10722..216be0e7890 100644 --- a/quest/m1/auth/interop.md +++ b/quest/m1/auth/interop.md @@ -2,8 +2,8 @@ ## Goal -`just test interop --all` fails a lite-06 cell whose client did not receive -the grant its relay token implies, and a new negative round passes only when +`just test interop --all` fails an AUTH-capable (wip lite) cell whose client +did not receive the grant its relay token implies, and a new negative round passes only when a client publishing outside its grant fails loud with `Unauthorized`. Today the matrix checks media alone, so a malformed AUTH_OK that leaves a session with no grant passes silently. @@ -15,8 +15,8 @@ parseable line; `test/interop/interop.sh` compares it against the token the cell minted. The negative round mints a token that excludes the published path and expects the publisher's session to close with `Unauthorized` naming the path, and the subscriber to see -nothing. Cells below lite-06 skip both checks, as do binding clients until -[Bindings](/quest/m1/auth/bindings.md) gives them a grant to print; that +nothing. Cells on versions without the AUTH stream skip both checks, as do +binding clients until [Bindings](/quest/m1/auth/bindings.md) gives them a grant to print; that quest adds them to the same assertion. No public API or wire change. ## Required diff --git a/quest/m1/auth/lite.md b/quest/m1/auth/lite.md index 2c5eb5add95..a2d4c08be95 100644 --- a/quest/m1/auth/lite.md +++ b/quest/m1/auth/lite.md @@ -2,7 +2,8 @@ ## Goal -Both sides of a moq-lite-06 session learn what they may publish and subscribe +Both sides of a session on the wip lite version (`moq-lite-07-wip` today) +learn what they may publish and subscribe to. Right after SETUP each side opens an AUTH stream carrying an empty token and receives its grant; `Session::auth()` exposes the union of every grant and lets the app present more tokens, each on its own stream. A publisher whose @@ -45,7 +46,7 @@ opener withdraws a token by closing or resetting its stream. A stream reset before any reply, which is what a peer does with a stream type it does not understand (the existing rule at the STREAM_TYPE section), leaves the opener with no grant for that token, and the client reports it as `Unsupported` -rather than a refusal. Record it in the lite-06 changelog. Run +rather than a refusal. Record it in the wip version's changelog. Run `just drafts check`. ### Model @@ -112,10 +113,10 @@ before publishing what that token unlocks. On a miss, abort the session with teardown already formats one; log it at error level too, since `Error` carries no payload). -Gate everything on `Version::Lite06`; older versions never open the stream -and `auth().grant()` stays `None` there. Land the accept side and the -`Unsupported` handling before any build opens the stream, since -`moq-lite-06` is one ALPN with no sub-version. +Gate everything on the wip version (`Version::Lite07` while lite-07 is wip); +published versions never open the stream and `auth().grant()` stays `None` +there. Decided 2026-10-05: wire work targets the wip release, never a +published version in place. ### JavaScript diff --git a/quest/m1/auth/token-in-band.md b/quest/m1/auth/token-in-band.md index b3a5ab2cf5f..511951b4f1f 100644 --- a/quest/m1/auth/token-in-band.md +++ b/quest/m1/auth/token-in-band.md @@ -6,8 +6,8 @@ A client's credentials can travel inside the session instead of the URL, and several of them can ride one connection. Every client in this repository takes tokens as configuration separate from the address, presents each on its own AUTH stream at setup, and the relay admits the session on what the URL -carried and widens it as the streams are answered. Peers below lite-06 keep -working unchanged: the client puts the first token in the URL whenever any +carried and widens it as the streams are answered. Peers without the AUTH +stream keep working unchanged: the client puts the first token in the URL whenever any version it offers has no AUTH stream, so nothing is refused and nothing goes silent, and the token leaves the URL for good only once the offered set is AUTH-capable. @@ -42,8 +42,8 @@ AUTH can carry the full grant once the pattern-interest prerequisite lands. - Presenting: WebTransport negotiates the moq version as a subprotocol of the CONNECT request that carries the URL, so the client cannot wait to learn whether the peer speaks AUTH. The client copies the first configured - token into the URL query whenever any offered version lacks AUTH (today, - everything below lite-06), and omits it once every offered version has the + token into the URL query whenever any offered version lacks AUTH (every + published lite version, since AUTH lands in the wip one), and omits it once every offered version has the stream. A token that went into the URL or the setup option is the connection credential, and the empty-token stream is its one and only stream; every other configured token gets its own AUTH stream on an diff --git a/quest/m1/auth/unauthorized.md b/quest/m1/auth/unauthorized.md index f52c1e110f5..17f9b28e6d9 100644 --- a/quest/m1/auth/unauthorized.md +++ b/quest/m1/auth/unauthorized.md @@ -10,9 +10,9 @@ tells revocation apart from a session closing. Today it resets with ## Plan Assign `0x3A UNAUTHORIZED` in the lite draft's stream error table, the next -code in the application block after `TIMESTAMP_MISMATCH`, on lite-06: a -published lite-06 peer already maps an unknown stream code to a generic -error, so the addition is compatible. Add the matching `StreamError` +code in the application block after `TIMESTAMP_MISMATCH`, in the wip lite +version that carries the AUTH stream (`moq-lite-07-wip` today), never a +published one in place (decided 2026-10-05). Add the matching `StreamError` variant (the enum is non-exhaustive) in Rust and JS, send it from every revocation path the lite stream added, and cover it in the Rust and JS tests. Map it to the existing `Unauthorized` protocol kind in diff --git a/quest/m1/bench-buckets.md b/quest/m1/bench-buckets.md index 5f9c98e3f6f..4b45304c138 100644 --- a/quest/m1/bench-buckets.md +++ b/quest/m1/bench-buckets.md @@ -17,27 +17,37 @@ merge, and moq.pro's load harness sums several generators against one relay, so the bench emits mergeable buckets. Approved as recommended. - `Latency` (`rs/moq-bench/src/stats.rs`) already counts 1 ms buckets for the - whole run. Emit the interval's delta beside the cumulative fields, and - derive [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md)'s - per-interval percentiles from the same delta, so the two quests share one - representation; whichever lands second builds on the other. + whole run. [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) + adds the interval's delta for its per-interval percentiles; this quest + emits that same delta in a mergeable layout, so the two share one + representation. - 60,001 dense buckets per line is too much JSON. Pick a compact layout (sparse non-zero buckets, or a log-linear layout with bounded relative error) and record why. - The output documents: the layout version, units, the interval's start and end, the sample count, and what an empty or partial interval (the first and the last) looks like. -- Publisher and subscriber stay on one host, so latency closes on one clock; - `latency_clock_skew` keeps flagging a violation. +- Harness rule: publisher and subscriber run on one host, so latency closes + on one clock and buckets from several hosts merge without skew; + `latency_clock_skew` keeps flagging a violation. Replace the README's + advice to NTP-sync separate publisher and subscriber hosts + (`rs/moq-bench/README.md:117-118`) with this rule. - A test sums fixture buckets from two runs and checks the percentiles against the concatenated samples, binned by the same layout and the same - overflow bucket (60,000 ms and above today) before the percentile is taken. Update `rs/moq-bench/README.md`. + overflow bucket (60,000 ms and above today) before the percentile is + taken. Update `rs/moq-bench/README.md`. -moq-bench is 0.0.x, so this lands on main. +Lands on main, then is backported to `release` as an additive cherry-pick +PR, like [Stats linger](/quest/m0/stats-linger.md), since moq.pro's load +harness tracks `release` (decided 2026-10-05). The backport carries #3126's +delta along if `release` does not have it yet. Public API: none (CLI output only). Wire: none. +## Required + +- [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - the per-interval bucket delta these buckets emit + ## Related -- [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - per-interval percentiles from the same buckets - [moq.pro: benchmark output pin](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/kick/bench-pin.md) - the load harness that sums these across generators diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index c5629579139..f71672a7664 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -58,8 +58,8 @@ vector the 2026-09-30 cache-tiers audit kept: partitioned swarm's traffic to itself through the CDN (BGP's partitioned-AS problem). Folding a large customer cluster into one id at its boundary is [Routing cost domains](/quest/m3/routing-cost-domains.md)'s. -- **Every session speaks it**, relays, apps, and browsers, in the wip lite - version; a plain client with one link advertises only itself. Node ids are +- **Every session speaks it**, relays, apps, and browsers, in lite-07 (the + current wip version, decided 2026-10-05); 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. Promoting them is @@ -77,8 +77,11 @@ vector the 2026-09-30 cache-tiers audit kept: own ([Link quality](/quest/m1/cluster-routing/link-quality.md)). - **Topology now, wire later.** moq.pro's edge and core migration runs on today's lite-06 path vector with upstream links; the route layer lands in - the wip version afterwards with no re-layout, once - [the simulator](/quest/m1/cluster-routing/sim.md) has compared it. + lite-07 (the current wip version) afterwards with no re-layout, once + [the simulator](/quest/m1/cluster-routing/sim.md) has compared it. Decided + 2026-10-05: this line gates + [Finalize moq-lite-07](/quest/m1/lite07-finalize.md), and lite-07 loses + its hop list and `Hop Base`/`Hop Keep` compression. Kept from 2026-09-30: core links are configured and may skip PoPs; Warm and Cold collapse to one cost ([One route cost](/quest/m1/route-cost.md)); diff --git a/quest/m1/cluster-routing/routes.md b/quest/m1/cluster-routing/routes.md index 3e656df8ed5..93b14e79b75 100644 --- a/quest/m1/cluster-routing/routes.md +++ b/quest/m1/cluster-routing/routes.md @@ -2,8 +2,8 @@ ## Goal -Routing info splits into two layers on the session's announce stream, in the -wip lite version, for every session. A ROUTE advertises reachability of one +Routing info splits into two layers on the session's announce stream, in +lite-07 (the current wip version, decided 2026-10-05), for every session. A ROUTE advertises reachability of one origin node; an ANNOUNCE says a prefix lives at a route's node and carries no path. A link flap or relay loss sends one ROUTE change per origin whose best route changed, never a re-announce per broadcast; ending a broadcast reaches @@ -27,7 +27,8 @@ Decided 2026-10-01 (see the [line's decisions](/quest/m1/cluster-routing/README. route stays up. An announce never changes its Route ID: another origin serving the same path is another ANNOUNCE. An ANNOUNCE naming an unknown Route ID is a protocol violation, and ROUTE_END ends that stream's - ANNOUNCEs on the route. The hop list leaves this version. + ANNOUNCEs on the route. The hop list leaves lite-07, and with it the + `Hop Base`/`Hop Keep` compression. ```text ROUTE_START node=0x7a3f seqno=41 metric=12 -> route 0 diff --git a/quest/m1/cluster-routing/selection.md b/quest/m1/cluster-routing/selection.md index 7cf5d58a6be..31d80688044 100644 --- a/quest/m1/cluster-routing/selection.md +++ b/quest/m1/cluster-routing/selection.md @@ -52,8 +52,8 @@ Candidate mechanics: - A refusal follows Wildcard's refusal rule: every refusal is terminal, and an origin sheds load by withdrawing or re-pricing its route instead. -Wire: none expected; if one is needed it goes in the current wip lite -version with the draft. Tests cover an HRW split across an equal-cost +Wire: none expected; if one is needed it goes in lite-07 (the current wip +version, where the route layer also lands) with the draft. Tests cover an HRW split across an equal-cost pool, a terminal refusal, and a same-path pair failing over mid-group with no timestamp rewind. diff --git a/quest/m1/hls-bounded.md b/quest/m1/hls-bounded.md new file mode 100644 index 00000000000..b7af16c6754 --- /dev/null +++ b/quest/m1/hls-bounded.md @@ -0,0 +1,80 @@ +# [M] Bounded HLS playlists + +## Goal + +A fresh viewer joins a days-old broadcast, live or archived, and `moq-hls` +renders its playlists with work bounded by the advertised window, not by the +broadcast's age. The media playlist lists a sliding window whose +`EXT-X-MEDIA-SEQUENCE` every edge and every reload agree on. A span with no +media in one rendition keeps its slot as a duration-preserving `EXT-X-GAP` +without holding back later segments or sibling renditions. A video rendition +is not advertised until its window holds a segment that starts at a group +start (a sync point), so a stock player is never sent to video it cannot +start decoding. + +This is the generic renderer. Managed edges (moq.pro) only wire it to their +projects, routes, and auth. + +## Plan + +Decided 2026-10-05, from moq.pro's +[bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md): +the windowed sequence, gap slots, and sync-point gating are renderer rules +every `moq-hls` user needs, so they live here and moq.pro keeps only the edge +wiring. Rejected: keeping them in moq.pro. Also decided 2026-10-05: this +quest lives at the m1 root on `main`, outside the archive line, since live +timelines need it first. + +The offline archive HLS that `quest/m1/archive/hls.md` used to describe is +done on the archive line's branch (#4115, #4155, #4169). The per-track gap +behaviour lives on that line's track-timeline questline +(`quest/m1/archive/track-timeline/README.md`, #4280, `spans.rs`), which +derives segments at the edge from group timestamps and emits `EXT-X-GAP` for +a rendition with no group start in a span. Whichever lands second rebases +onto the other, and the rules here hold for both shapes. + +Start by auditing `rs/moq-hls/src/export` against each rule; much exists +(`segments.rs` numbers aligned segments and carries gap rows, `playlist.rs` +writes `EXT-X-GAP`). Fix only what a test shows missing: + +- **Bounded join.** Rendering for a new viewer reads at most the window's + records from the timeline (`moq_json::window`), never the whole history, + and never GETs or FETCHes media. A live publisher that never pops its + timeline must not make a join cost grow with broadcast age. +- **Capped window, decided 2026-10-05.** A durable (store-backed) timeline + still advertises a capped sliding window: a live playlist lists a bounded + window even when the store retains more. A full VOD or EVENT listing is a + separate, explicit replay mode. This conflicts with #4155's durable listing + on the archive line branch, which lists the whole durable timeline without + the live window; reconcile it there when that branch next merges `main`. +- **Stable sequence.** `EXT-X-MEDIA-SEQUENCE` is the window's first segment + number, derived from the timeline, so two edges and a reload after a pop + agree. +- **Gaps.** A span with no media in one track becomes a gap slot in that + rendition only; siblings keep listing, and a rendition switch after a gap + lands on the next real segment. A failed rendition timeline is not a gap: + per #4552 its playlist ends at its last covered segment. +- **Sync-point gating.** The multivariant playlist omits a video rendition + until its window holds a segment starting at a group start that is a sync + point. Phrase the check by group start and sync point, not by keyframe, so + it stays right for intra-refresh streams and agrees with + [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md). A + catalog that arrives first may expose audio only, or answer unavailable. + +Prove: a fresh join after simulated days of publishing reads a bounded number +of records (count them); a durable timeline holding more than the window +still lists only the window; catalog arrival before the first group start; +gaps in one track; switching after a gap; healthy siblings keep their +listing; two exporters over one timeline render identical sequence numbers. +Tests mock time. + +moq.pro pins `release`, so it adopts this through the next release that +carries it. + +Public API: none expected. Wire: none. + +## Related + +- [moq.pro: bounded live playlist](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/archive/playable.md) - the edge wiring that adopts this renderer +- [Archive](/quest/m1/archive/README.md) - a replayed archive inherits these rules +- [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md) - which group starts the HLS export marks as sync points diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 877d63fc9ac..6abb80945b0 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -2,11 +2,11 @@ ## Goal -moq-lite-07 is a published version: it negotiates as `moq-lite-07`, the -`moq-lite-07-wip` identifier is gone, its draft revision describes the frozen -wire, and the next cut of `main` into `release` ships it in Rust and JS. A -deployment pinned to `release` can then roll lite-07 out without a wip wire -changing under it. Wire work after that targets a new `moq-lite-08-wip`. +When the maintainer says to cut it, moq-lite-07 becomes a published version: +it negotiates as `moq-lite-07`, the `moq-lite-07-wip` identifier is gone, its +draft revision describes the wire as it stands, and the next cut of `main` +into `release` ships it in Rust and JS. A deployment pinned to `release` can +then roll lite-07 out without a wip wire changing under it. ## Plan @@ -17,48 +17,54 @@ mesh and customer rollouts waited on it and the waits on nothing outside the repository; the rollouts and the mesh condition follow it. -"Final" means: +Freeze policy, decided by the maintainer 2026-10-05: "just keep adding stuff +to lite-07 until I say to cut it. quests should target the -wip release." +Every wire quest targets the current wip version, and lite-07 keeps growing +until the maintainer calls the cut. This quest is the mechanical rename and +checks done at that call; the Required list is the work already known to land +first, not a closed freeze set. -- Every wire change listed under Required has landed, plus the cache bug - that only bites once lite-07 ships. That list is the whole freeze set: a - wire quest not on it, such as - [Routes and announces](/quest/m1/cluster-routing/routes.md), targets the - next wip version unless the maintainer adds it (open below). -- The identifier becomes `moq-lite-07` in `rs/moq-net`, `js/net`, the draft - (whose text already names the rename), `doc/concept/moq-lite.md`, and the - CLI and relay docs. A wip peer and a final peer refuse each other by ALPN +The route layer of [Cluster routing](/quest/m1/cluster-routing/README.md) +(ROUTE_START/UPDATE/END, path-less ANNOUNCE, the hop list dropped) lands in +lite-07, decided 2026-10-05. That removes lite-07's `Hop Base`/`Hop Keep` +announce compression along with the hop list, and moq.pro's lite-07 rollout +(moq.pro#2210) has to plan for a lite-07 without hop lists. + +The cut: + +- Every quest under Required has landed, plus the cache bug that only bites + once lite-07 ships. +- The identifier becomes `moq-lite-07` in `rs/moq-net` and `js/net`, in the + draft (whose text already names the rename), and at every site spelling + the wip ALPN: `rs/moq-tokio/src/connect.rs` and `listen.rs`, + `rs/moq-relay/src/cluster.rs`, `rs/moq-relay/tests/smoke.rs`, + `test/interop/bare-fin.ts`, `test/interop/lite-varint.ts`, and + `doc/concept/moq-lite.md`; grep for `moq-lite-07-wip` to catch new ones. A wip peer and a final peer refuse each other by ALPN rather than misparse; no compatibility shim. - The draft's lite-07 changelog matches the wire and `just drafts check` - passes. Later changes start `moq-lite-08-wip` instead of editing lite-07. -- [Wire compatibility](/quest/m1/wire-compat.md) covers lite-07 once a - release carries it. + passes. -Open, for the maintainer: +Decided 2026-10-05: Rust's 64-bit `VarInt` is not required first. The draft +already specifies 64 bits; Rust refusing values above 2^62-1 is an +implementation limit that [VarInt codec](/quest/m1/rs2ts/varint-codec.md) +fixes whenever it lands. -- Whether [Routes and announces](/quest/m1/cluster-routing/routes.md)'s new - ROUTE and ANNOUNCE wire gates lite-07 or moves to lite-08. Recommended: - lite-08. It is [XL] and still in design, and holding lite-07 for it holds - announce compression for every mesh waiting on lite-07. +Open, for the maintainer: -- Whether a large in-flight change, such as subscribe ranges or live media - time, slips to lite-08 so lite-07 ships sooner. Recommended: keep the set - as planned, and revisit only if one of them stalls. - Whether released clients offer lite-07 first by default, or accept it while still offering lite-06 first for one release. Recommended: servers accept it by default and clients keep lite-06 first for one release, so a deployment rolls out on its own schedule. -- Whether Rust's `VarInt` must carry the full 64 bits - ([VarInt codec](/quest/m1/rs2ts/varint-codec.md)) before final, since Rust - refuses lite-07 values above 2^62-1 today. Public API: the lite-07 version constant and ALPN lose `-wip`. Wire: lite-07 -is frozen; older versions are unchanged. +is published; older versions are unchanged. ## Required +- [Cluster routing](/quest/m1/cluster-routing/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone - [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - lite-07 loses NO_CAPACITY and stamping - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07 restores SUBSCRIBE_DROP in place of `Stream Count` -- [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - SUBSCRIBE carries ranges and an order, and lite FETCH is gone +- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Live media time](/quest/m1/subscribe-live-time.md) - SUBSCRIBE_OK carries the publisher's live media time - [Untimed lite-07](/quest/m1/lite-untimed.md) - an untimed track crosses the wire untimed - [One route cost](/quest/m1/route-cost.md) - ANNOUNCE carries one cost @@ -67,4 +73,5 @@ is frozen; older versions are unchanged. ## Related - [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment condition that follows this +- [Wire compatibility](/quest/m1/wire-compat.md) - the nightly covers lite-07 once a release carries it - [moq.pro: lite-07 on cluster dials](https://github.com/moq-dev/moq.pro/blob/main/quest/m1/lite07.md) - the mesh rollout that adopts the finalized version, and the customer rollout after it diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index b16bfc3a7ee..5cf20d24474 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -6,9 +6,8 @@ Publishers, relays, and viewers report the telemetry that broadcast health and congestion views need: how far behind viewers are according to what the network has acknowledged, how timely publishers are against their own media clock, and what publishers and viewers report for themselves through -[media stats](/quest/m1/stats/README.md). Together they can drive an -unknown/healthy/degraded/unhealthy verdict per broadcast with congestion -visible for viewers in aggregate, the way CMSD does for HLS. +[media stats](/quest/m1/stats/README.md), with congestion visible for viewers +in aggregate, the way CMSD does for HLS. ## Plan @@ -26,9 +25,17 @@ histograms, which stay monotonic and merge-patch friendly, and which any consumer can diff into a distribution. Clients report for themselves through hang stats and `.echo` feedback tracks, planned in their own line on `main`. -The counters and channels land here. The moq.pro (downstream) dashboard work, -including the health badge, connection-health drill-down, and stream -preflight, consumes them downstream. +The counters and channels land here. Client health and preflight are +[client health](/quest/m1/stats/health.md) and +[preflight](/quest/m1/stats/preflight.md) in the media stats line. The +moq.pro (downstream) dashboard work, including the health badge and the +connection-health drill-down, consumes both. + +Open, for the maintainer (the same question is recorded in +[client health](/quest/m1/stats/health.md)): whether anything computes a +per-broadcast verdict combining client reports, the relay's starvation, and +publisher timeliness, and where it would live. This line only reports the +counters. Decided (2026-09-28): the line's moq-stats changes break the published crate. Client stats left the line (2026-09-29) diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 3737a037ff3..35c1e31e385 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -7,7 +7,9 @@ that wants to hear from its viewers can solicit feedback there too. The publisher's `stats` track is one snapshot of what it sent, per rendition and for its connection. A viewer publishes one `.echo` broadcast per soliciting catalog it reads, carrying what it received and played, per rendition, and -its own connection. A dashboard reads both the same way a publisher does. Stats and +its own connection. A dashboard reads both the same way a publisher does. One +shared model turns either report into a health verdict, and a bounded +preflight run reports which media layer of a broadcast is broken. Stats and feedback cost nothing on the network unless someone subscribes. Not here: the relay's `moq-stats` layout, which stays as it is; clock synchronization; any requirement that a client report; and feedback as an input to billing, @@ -95,7 +97,8 @@ kind. Decided in the 2026-09-30 audit: a Rust encoder adapting its bitrate to viewer 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. +along with its open questions. This line publishes, reads, and classifies the +reports; no encoder acts on them here. Decided 2026-10-05 (moq.pro audit): the client health model and preflight media checks moq.pro planned against the pre-#4510 `.stats` broadcast are @@ -120,7 +123,8 @@ connection view and the dashboard flow. ## Related -- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other - half of a health verdict +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters; whether a + combined per-broadcast verdict reads both is open in + [client health](/quest/m1/stats/health.md) - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder adapts its bitrate to what its viewers report diff --git a/quest/m1/stats/health.md b/quest/m1/stats/health.md index 77b8ab9fa70..2657903ae83 100644 --- a/quest/m1/stats/health.md +++ b/quest/m1/stats/health.md @@ -8,9 +8,10 @@ feedback, it yields rates and loss as deltas over a stated interval, and classifies the connection and each rendition as unknown, healthy, degraded, or unhealthy, naming the observer of every number (the publisher's self-report, a viewer's report). Missing or stale reports are unknown, never -healthy. Rust and JS compute the same verdict from the same fixtures, so the -demo dashboard, `moq` CLI sinks, [preflight](/quest/m1/stats/preflight.md), -and downstream dashboards share it. +healthy. Rust and JS compute the same verdict from the same fixtures, so +[preflight](/quest/m1/stats/preflight.md) and downstream dashboards share it. +The demo dashboard and a `moq` CLI sink are possible consumers; wiring them +is follow-up work, not this quest. Not here: per-project or per-connection inventories, dashboards, history, or any relay-side session table. Downstream (moq.pro) keeps its project view. @@ -34,22 +35,31 @@ Guidance, to be settled while building: - Inputs are the snapshot types from [the schema](/quest/m1/stats/schema.md): `transport` (rtt, rate, loss, sample age) and the per-rendition counters. Counters are cumulative, so a sample is the delta of two snapshots over - their interval; a counter reset (a new epoch) starts over rather than going - negative. + their interval. A reset is detected by a counter decreasing or by the + reporting broadcast's path or epoch changing + ([Broadcast epochs](/quest/m0/broadcast-epoch/README.md)); the sample then + starts over rather than going negative. +- Container sections such as `mpegts` are excluded from the verdict; their + counters are read by their own consumers + ([TS health counters](/quest/m2/ts-health-stats.md)). - Thresholds are a documented default the caller can override, not policy baked into the types. Start from a few measured cases rather than guesses. - A verdict carries its evidence: which inputs drove it and who observed them. A browser publisher with only PROBE rtt yields unknown for what it cannot see, never a guess. -- The relay's [QoS](/quest/m1/qos/README.md) counters (starvation, - timeliness) are the other half of a broadcast verdict. Leave a seam to - combine them, but this quest classifies client reports only. +- This quest classifies client reports only. + +Open, for the maintainer (the same question is recorded in +[QoS](/quest/m1/qos/README.md)): whether anything computes a per-broadcast +verdict combining client reports, the relay's starvation, and publisher +timeliness, and where it would live. Nothing here depends on the answer, and +no quest promises it until it is decided. - Lives beside the snapshot types in `hang` and `@moq/hang` unless building it shows a better home. Prove a degrading publisher self-report, a degrading viewer report, a stale -report going unknown, and a counter reset, from shared fixtures in both -languages. Docs: the media section of `doc/concept/stats.md`. +report going unknown, and a counter reset by both a decrease and an epoch +change, from shared fixtures in both languages. Docs: the media section of `doc/concept/stats.md`. Public API: new health types in `hang` and `@moq/hang`. Wire: none. @@ -60,4 +70,6 @@ Public API: new health types in `hang` and `@moq/hang`. Wire: none. ## Related - [moq.pro: connection health](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-connection-health.md) - the per-project view built on this model -- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other half of a broadcast verdict +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, which a combined verdict would also read (open above) +- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a new epoch is one way a counter reset shows +- [TS health counters](/quest/m2/ts-health-stats.md) - container counters kept out of the verdict diff --git a/quest/m1/stats/preflight.md b/quest/m1/stats/preflight.md index d6f64e2f09c..e317155f6cc 100644 --- a/quest/m1/stats/preflight.md +++ b/quest/m1/stats/preflight.md @@ -5,12 +5,12 @@ A bounded test run against a published broadcast produces one report a person can act on: catalog validity, codec support, time to the first keyframe, bitrate and frame cadence per rendition, keyframe interval, audio/video skew, -timeline continuity, the [health verdict](/quest/m1/stats/health.md) from the -publisher's stats, and whether the broadcast ends with a clean unannounce -(observed by the check; the publisher, which owns the `broadcast::Producer`, -does the unannounce). A failure names the -broken layer and its evidence instead of one score, and the raw evidence is -kept so two people reach the same diagnosis. +media timestamp continuity, the [health verdict](/quest/m1/stats/health.md) +from the publisher's stats, and whether the broadcast ends with a clean +unannounce (observed by the check; the publisher, which owns the +`broadcast::Producer`, does the unannounce). A failure names the broken layer +and its evidence instead of one score, and the raw evidence is kept so two +people reach the same diagnosis. Not here: authorization, route selection, project-scoped test targets, or any dashboard flow. Downstream (moq.pro) owns those. @@ -34,17 +34,25 @@ Guidance, to be settled while building: - Codec support means "a stock player in this repo can decode it", checked against the same rules rendition selection uses, not a separate list. - One run, one report. No continuous pipeline. +- A publisher still live when the window closes is normal: the run ends at + the window and reports the unannounce check as not observed, never as a + failure. -Prove a healthy publisher, and deterministic failures for an invalid -catalog, an unsupported codec, a missing first keyframe, excessive A/V skew, -and a timeline jump. Docs: `doc/bin/cli.md` for the sink. +Prove a healthy publisher end to end against a publisher from +[Rust reporters](/quest/m1/stats/rust.md), a publisher outliving the window, +and deterministic failures for an invalid catalog, an unsupported codec, a +missing first keyframe, excessive A/V skew, and a media timestamp jump. Docs: +`doc/bin/inspect.md` is the home, with the sink's flags in `doc/bin/cli.md`. Public API: a preflight check and its report type, and a CLI sink. Wire: none. ## Required - [Client health](/quest/m1/stats/health.md) - the verdict the report includes +- [Rust reporters](/quest/m1/stats/rust.md) - a publisher with a stats track for the end-to-end proof ## Related +- [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - the relay's view of the same timestamp lateness and monotonicity +- [Intra-refresh](/quest/m2/intra-refresh/README.md) - a stream without IDR keyframes, which the first-keyframe check must not fail - [moq.pro: stream preflight](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-preflight.md) - the project-scoped target and dashboard flow built on these checks diff --git a/quest/m2/gpu-health.md b/quest/m2/gpu-health.md index 87014788d34..5c8405e8114 100644 --- a/quest/m2/gpu-health.md +++ b/quest/m2/gpu-health.md @@ -5,11 +5,12 @@ moq-video reports, per GPU device, what an admission controller needs to decide whether one more encode or decode fits: encoder and decoder sessions in use and any hard session limit, memory used and available, and engine -utilization. It also reports device health: whether the device is usable, -lost, or reset. The same API works on NVIDIA, AMD, and Intel, keyed by the -device identity [`Surface::Vulkan`](/quest/m2/gpu-surface.md) matches on, so a -caller writes no vendor code. A value a driver cannot provide is absent, never -guessed. +utilization. It also reports device health (whether the device is usable, +lost, or reset) and the GPU model, which moq.pro's admission keys its +per-model limits on. The same API works on NVIDIA, AMD, and Intel, keyed by +the device's render node `dev_t`, the identity +[`Surface::Vulkan`](/quest/m2/gpu-surface.md) carries, so a caller writes no +vendor code. A value a driver cannot provide is absent, never guessed. Not here: admission policy, thresholds, frame-lateness tracking, or draining. Those are the caller's. @@ -24,12 +25,20 @@ first-class, so an NVML-shaped API would be rewritten once they land. moq.pro's transcode admission and its benchmarks assume NVML today; they adopt this instead. +Decided 2026-10-05: one device identity everywhere, the render node's +`dev_t`, shared with [VA-API import](/quest/m2/vaapi-vulkan-import.md). +NVIDIA's device UUID maps to its node through `VK_EXT_physical_device_drm`. +That is why this Requires [GPU surface](/quest/m2/gpu-surface.md). + Guidance, to be settled while building: - Prefer one source that spans vendors over three vendor paths. Candidates to evaluate: `VK_EXT_memory_budget` for memory, DRM fdinfo or sysfs engine - busyness for utilization on amdgpu, i915, and xe, and NVML only where - NVIDIA offers nothing neutral (encoder session limits on consumer cards). + busyness for utilization on amdgpu, i915, and xe, and on NVIDIA, + `NV_ENC_CAPS_DYNAMIC_QUERY_ENCODER_CAPACITY` through moq-nvenc's + `get_encode_caps`, with NVML only where NVIDIA offers nothing neutral. + NVML may not report the consumer-card encoder session cap at all; verify + that while building rather than assume it. Record which source backs each field per vendor, and whether each memory value is process-scoped or device-wide: `VK_EXT_memory_budget`'s `heapUsage` is this process's only, so device-wide usage needs a driver @@ -41,17 +50,24 @@ Guidance, to be settled while building: errors (`VK_ERROR_DEVICE_LOST`, CUDA and VA-API equivalents) and from the driver's reset counters where exposed. - A snapshot call, not a callback; cheap enough to poll about once a second. -- Additive, so it can reach `release` by backport without waiting for - [the multi-vendor release](/quest/m2/gpu-release.md). +- The snapshot is additive, but it keys by the surface's identity, and the + surface change is breaking, so it reaches `release` with + [the multi-vendor release](/quest/m2/gpu-release.md), not by an earlier + backport. Test: a unit test of each source's parsing against recorded fixtures, and -ignored hardware tests in `just rs gpu`'s per-vendor branches that open an -encoder and see the session and memory counts move. +ignored hardware tests in `just rs gpu`'s per-vendor branches (the recipe +[GPU surface](/quest/m2/gpu-surface.md) adds) that open an encoder and see +the session and memory counts move. Public API: a device capacity and health snapshot in moq-video. Wire: none. +## Required + +- [One external GPU image for every encoder](/quest/m2/gpu-surface.md) - the render node identity this keys by, and the `just rs gpu` recipe its tests run in + ## Related -- [One external GPU image for every encoder](/quest/m2/gpu-surface.md) - the device identity both key by +- [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - picks a render node by the same `dev_t` - [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - the AMD backend whose sessions this counts - [moq.pro: transcode admission](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/transcode/ws3-admission.md) - the admission and health checks that consume this diff --git a/quest/m2/gpu-surface.md b/quest/m2/gpu-surface.md index 2f7b8d8828c..73bb1c21e3a 100644 --- a/quest/m2/gpu-surface.md +++ b/quest/m2/gpu-surface.md @@ -29,7 +29,10 @@ added this quest): memory type index too: a Vulkan import must reuse both (VUID 01742), and an `OPAQUE_FD` handle cannot be queried for its properties. A `DMA_BUF` importer picks its memory type from the handle's properties; - - the device and driver UUID; + - the device and driver UUID, and the render node's `dev_t` (decided + 2026-10-05: the one device identity + [VA-API import](/quest/m2/vaapi-vulkan-import.md) and + [GPU health](/quest/m2/gpu-health.md) key by); - the timeline: an `OPAQUE_FD` timeline semaphore handle, the value the producer signals when the image is ready, and the value the consumer signals when it is done reading. Both handles belong to the slot and live diff --git a/quest/m2/rtsp-import.md b/quest/m2/rtsp-import.md index cccf84a6e7b..98742721b59 100644 --- a/quest/m2/rtsp-import.md +++ b/quest/m2/rtsp-import.md @@ -5,14 +5,16 @@ `moq import rtsp --connect rtsp://camera/stream` publishes an IP camera's H.264 or H.265 video and AAC audio as a broadcast. It runs on the camera's own network, so a camera behind NAT needs no inbound port. A `moq-rtsp` -library crate carries it, so other publishers reuse it the way they reuse -moq-srt and moq-rtmp. +library crate carries it, so other publishers embed the ingest instead of +shelling out to the CLI. -The library's entry point ingests one RTSP session into a broadcast the -caller supplies, with no reconnect: it returns when the session ends, fails, -or its timeline jumps. The CLI wraps it with reconnect and a fresh epoch per -session. A caller with its own supervisor, such as Pronto's truck, runs the -library directly, including two sessions (two URLs) into one broadcast. +The library's entry point ingests one RTSP session into a +`broadcast::Producer` the caller supplies, as moq-mux's importers take one, +with no reconnect; importer state stays private. It returns when the session +ends, fails, or its timeline jumps. The CLI wraps it with reconnect and a +fresh epoch per run. A caller with its own supervisor, such as Pronto's +truck, runs the library directly, including two sessions (two URLs) into one +broadcast. Non-goals: an RTSP server (push ingest), a relay pulling cameras itself, and codecs nothing in the stack plays (G.711, MJPEG). @@ -35,16 +37,17 @@ Decided 2026-10-01: above all (common on cameras), is skipped with one clear warning and the broadcast goes on video-only. Transcoding it waits for a customer who needs it. -- A reconnect publishes a new broadcast under a fresh epoch, per - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md), never spliced onto - the last one. A new session's RTP time restarts, so the CLI finishes the - old broadcast cleanly and builds a fresh catalog, tracks, and importers, - starting on a keyframe. A timestamp jump inside one session (retina #64) - ends that library session and returns to its caller, which starts a new - broadcast, instead of failing the track. Separate URLs a library caller - publishes as renditions of one broadcast share its epoch and catalog. Decided 2026-10-02; shifting timestamps onto the existing - catalog clock behind a `discontinuity()` marker was rejected, since a - broadcast name always means the same content. +- A broadcast name always means the same content, so a timeline restart is + never spliced onto the old broadcast. A new session's RTP time restarts, + and a timestamp jump inside one session (retina #64) ends that library + session and returns to its caller instead of failing the track. The caller + owns the broadcast: it finishes it cleanly and restarts every session + sharing it under a fresh epoch, per + [Broadcast epochs](/quest/m0/broadcast-epoch/README.md), with a fresh + catalog, tracks, and importers starting on a keyframe. The CLI publishes + each run (each reconnect) under a fresh epoch. Decided 2026-10-02 and + 2026-10-05; shifting timestamps onto the existing catalog clock behind a + `discontinuity()` marker was rejected. - Credentials ride the URL's userinfo, as every RTSP tool takes them. retina refuses a URL with userinfo, so strip it into `SessionOptions::creds` before `describe`, and log only the redacted URL (`RedactedUrl`). A @@ -56,10 +59,12 @@ Decided 2026-10-01: Decided 2026-10-05: - The library ingests one session and never reconnects. The caller supplies - the broadcast (or the moq-mux importer state behind it), so two sessions, - such as the truck's H.264 SD and H.265 HD URLs, can publish renditions of one - broadcast. A session end, a failure, and a timeline jump all return to the - caller, which decides whether to retry. Reason: the truck deliberately exits + the `broadcast::Producer` and importer state stays private, so two + sessions, such as the truck's H.264 SD and H.265 HD URLs, can publish + renditions of one broadcast. Two sessions on one catalog need + [Shared import clock](/quest/m1/shared-clock.md) to land on one timeline. + A session end, a failure, and a timeline jump all return to the caller, + which decides whether to retry. Reason: the truck deliberately exits for systemd so a stuck Starlink session surfaces, and an in-process retry inside the library would force it to opt out. - `moq import rtsp` owns reconnect with backoff: each new session gets a fresh @@ -68,18 +73,27 @@ Decided 2026-10-05: Test against a local RTSP source serving a known H.264 + AAC clip (Pronto uses mediamtx), checking the catalog and first frames; a G.711 source that -publishes video only; two sessions ingested into one caller broadcast; and a -source restarted mid-stream, whose RTP time resets: the library call returns, -and the CLI ends the first broadcast cleanly and publishes a second one under +publishes video only; two sessions ingested into one caller broadcast, where +one session's timestamp jump has the test caller restart both under a new +epoch; and a source restarted mid-stream, whose RTP time resets: the library +call returns, and the CLI ends the first broadcast cleanly and publishes a second one under a new epoch, starting on a keyframe with its own catalog. `doc/bin/cli.md` documents `import rtsp`. Public API: the `moq-rtsp` crate and the `moq import rtsp` subcommand. -Wire: none. +Wire: none. Both are additive, so it is backported to `release` once it +lands on main. + +The moq.pro guide link below resolves once moq.pro#2210 merges. + +## Required + +- [Shared import clock](/quest/m1/shared-clock.md) - two sessions importing into one caller broadcast share one timeline ## Related -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the epoch each camera session's broadcast publishes under +- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - the fresh epoch a caller and the CLI mint for each restarted broadcast +- [Import at the first frame](/quest/m1/import-first-frame.md) - a lone session's catalog publishes at its first frame - [moq.pro's Pronto truck](https://github.com/moq-dev/moq.pro/blob/main/pronto/truck/src/camera.rs) - the prior art this generalizes - [moq.pro: Pronto truck on moq-rtsp](https://github.com/moq-dev/moq.pro/blob/main/quest/m3/truck-rtsp.md) - runs the library entry point under its own supervisor - [moq.pro: Camera (RTSP) guide](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/rtsp-guide.md) - documents `moq import rtsp` for customers once a release ships it diff --git a/quest/m2/vaapi-vulkan-import.md b/quest/m2/vaapi-vulkan-import.md index b1db7452ffe..caec02d989d 100644 --- a/quest/m2/vaapi-vulkan-import.md +++ b/quest/m2/vaapi-vulkan-import.md @@ -40,13 +40,12 @@ sync_file import, so an explicit-sync producer races it. probes, or `MOQ_VAAPI_DEVICE`) in a `OnceLock`. The encoder, decoder, and resize share it so a DMA-BUF moves between them without a copy. Choosing a node per surface makes `device()` per-node, so keep decode, resize, and - encode on one node per DMA-BUF. Open: - - map the surface's UUID to a render node with - `VK_EXT_physical_device_drm`, which needs a Vulkan instance on the VA-API - side; - - have the producer put the render node's `dev_t` in the surface, read from - its own `VK_EXT_physical_device_drm`. This is recommended: it is simpler - and adds a field to the [surface](/quest/m2/gpu-surface.md). + encode on one node per DMA-BUF. Decided 2026-10-05: the producer puts the + render node's `dev_t` in the [surface](/quest/m2/gpu-surface.md), read from + its own `VK_EXT_physical_device_drm`, and VA-API opens that node. It is + the one device identity [GPU health](/quest/m2/gpu-health.md) keys by too. + Rejected: mapping the surface's UUID to a node on the VA-API side, which + needs a Vulkan instance there. On the test host the iGPU is `renderD128` and an AMD card is `renderD129`. - Import the DMA-BUF with its modifier, and convert BGRA or RGBA to NV12 @@ -66,5 +65,6 @@ Public API: none beyond the surface quest's. Wire: none. - [Vulkan Video encode on AMD](/quest/m2/vulkan-encode.md) - the AMD half of the same proof - [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode on the same backend +- [GPU capacity and health](/quest/m2/gpu-health.md) - reports per device keyed by the same render node `dev_t` - [Linux OBS GPU input](/quest/m3/obs-linux-gpu.md) - a DMA-BUF producer that needs the same explicit sync - [Video hardware validation](/quest/m3/video-hardware.md) - VA-API so far ran only on Meteor Lake diff --git a/quest/m3/lite07-mesh.md b/quest/m3/lite07-mesh.md index 5490d8b75c9..ff8c5a92447 100644 --- a/quest/m3/lite07-mesh.md +++ b/quest/m3/lite07-mesh.md @@ -15,3 +15,8 @@ ALPN, and moq.pro still has its lite-07 rollout quest open (`quest/m1/lite07.md` in moq-dev/moq.pro). That rollout waits on [Finalize moq-lite-07](/quest/m1/lite07-finalize.md), so this condition cannot clear before a release carries the final version. + +Decided 2026-10-05: [Cluster routing](/quest/m1/cluster-routing/README.md)'s +route layer lands in lite-07, so the final lite-07 carries ROUTE and +path-less ANNOUNCE instead of hop lists, and loses the `Hop Base`/`Hop Keep` +announce compression. moq.pro's rollout must plan for that wire. From 87ab8af38e6d2a053f216f4bdbd3cf5c24b7b03c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:40:27 -0700 Subject: [PATCH 4/9] quest: address review on linger totals, bucket windows, and the HLS bound Co-Authored-By: Claude Opus 5.5 --- quest/m0/stats-linger.md | 25 +++++++++++++++---------- quest/m1/bench-buckets.md | 5 +++-- quest/m1/hls-bounded.md | 4 +++- quest/m1/lite07-finalize.md | 4 ++-- quest/m1/stats/health.md | 5 +++-- 5 files changed, 26 insertions(+), 17 deletions(-) diff --git a/quest/m0/stats-linger.md b/quest/m0/stats-linger.md index b2e5c6a29d3..79042d0db81 100644 --- a/quest/m0/stats-linger.md +++ b/quest/m0/stats-linger.md @@ -26,15 +26,20 @@ first proposed, and make it configurable. - `moq-stats`'s producer unpublishes a group broadcast on the drain where its group has no traffic or session rows (`publish` in `rs/moq-stats/src/produce.rs`). Keep it, and the epoch and group sequence it - publishes under ([stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md)), until the - linger elapses with the group still empty; a row returning within the - linger re-arms it. While it lingers empty, its live gauges and session - presence read zero and its cumulative traffic totals are kept, so a reader - sees no stale live counters. + publishes under ([stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md)), + until the linger elapses with the group still empty; a row returning + within the linger re-arms it. While it lingers empty, its live gauges and + session presence read zero, so a reader sees no stale live counters. +- Under one epoch a path's cumulative totals never go backwards or count + twice. The producer drops a path's registry entry, and its totals, when + the path leaves (`flush` in `produce.rs`), and readers already treat a path + missing from a frame as restarted. So either the path drops out of frames + while the group lingers and its return reads as a restart, or the producer + carries its last totals forward and a returning entry resumes from them. + Pick while building and record why. - Once the linger elapses, the group broadcast unannounces. A later return re-announces it under a new epoch, with its group sequence and totals - counted from zero - (decided 2026-10-05). This reverses stats epochs' one-epoch-per-producer + counted from zero (decided 2026-10-05). This reverses stats epochs' one-epoch-per-producer rule; [#4846](https://github.com/moq-dev/moq/pull/4846) writes that reversal into the epoch line, so this quest only follows it. - Time decisions use `max(wall, pts)`; tests mock time. @@ -45,9 +50,9 @@ backported to `release` as an additive PR. The backport is rewritten against `release`'s `produce.rs`, which has no epochs: a returning group starts a new broadcast from the wall-clock group seed of #4810 instead. -Test: a session closes and reopens within the linger with no unannounce; -while the group lingers empty, live gauges and presence are zero and -cumulative totals are unchanged; the group unannounces after the linger, and +Test: a session closes and reopens within the linger with no unannounce, +and no path's total goes backwards or counts twice across the return; while +the group lingers empty, live gauges and presence are zero; the group unannounces after the linger, and a return after that announces a new epoch counted from zero; the reported totals match a run without the linger. diff --git a/quest/m1/bench-buckets.md b/quest/m1/bench-buckets.md index 4b45304c138..9b01ab28be3 100644 --- a/quest/m1/bench-buckets.md +++ b/quest/m1/bench-buckets.md @@ -4,8 +4,9 @@ Every `moq-bench` JSONL line carries that interval's latency histogram in a versioned, documented bucket layout, so the buckets from several bench -processes on several hosts sum element-wise over any window into one -distribution. A percentile computed once from the summed buckets matches one +processes on several hosts sum element-wise over any window of whole report +intervals into one distribution; a window cutting through an interval cannot +separate that interval's samples. A percentile computed once from the summed buckets matches one computed from the concatenated samples binned by the same layout and overflow rule: the buckets are lossy, so the match is exact at bucket resolution, not at raw-sample precision. diff --git a/quest/m1/hls-bounded.md b/quest/m1/hls-bounded.md index b7af16c6754..2a44e24d9a0 100644 --- a/quest/m1/hls-bounded.md +++ b/quest/m1/hls-bounded.md @@ -38,7 +38,9 @@ Start by auditing `rs/moq-hls/src/export` against each rule; much exists writes `EXT-X-GAP`). Fix only what a test shows missing: - **Bounded join.** Rendering for a new viewer reads at most the window's - records from the timeline (`moq_json::window`), never the whole history, + records from the timeline (`moq_json::window`; a new group repeats at most + `CHECKPOINT_RECORDS = 256` recent records, in `moq-mux`'s `timeline.rs`), + never the whole history, and never GETs or FETCHes media. A live publisher that never pops its timeline must not make a join cost grow with broadcast age. - **Capped window, decided 2026-10-05.** A durable (store-backed) timeline diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 6abb80945b0..c21e12f036c 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -32,8 +32,8 @@ announce compression along with the hop list, and moq.pro's lite-07 rollout The cut: -- Every quest under Required has landed, plus the cache bug that only bites - once lite-07 ships. +- Every quest under Required has landed, including the cache bug that only + bites once lite-07 ships. - The identifier becomes `moq-lite-07` in `rs/moq-net` and `js/net`, in the draft (whose text already names the rename), and at every site spelling the wip ALPN: `rs/moq-tokio/src/connect.rs` and `listen.rs`, diff --git a/quest/m1/stats/health.md b/quest/m1/stats/health.md index 2657903ae83..f042ed40f22 100644 --- a/quest/m1/stats/health.md +++ b/quest/m1/stats/health.md @@ -27,8 +27,9 @@ deferring the model. The model reads the shapes this line settled after [#4510](https://github.com/moq-dev/moq/pull/4510): the publisher's `stats` track named in the catalog, keyed by rendition alias, and viewers' `.echo` -broadcasts. moq.pro's plan predates that and read a `.stats` broadcast that no -longer exists; do not revive it. +broadcasts. moq.pro's plan predates that and read client stats from a +`.stats` broadcast, which #4510 replaced with these tracks (the relay's own +`.stats/node/` is unchanged); do not revive the client one. Guidance, to be settled while building: From 8e3b3b022dd09a868ccffb5a303ff25683d55899 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:41:12 -0700 Subject: [PATCH 5/9] quest: snapshot producers choose their group sequence Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/snapshot-sequence.md | 47 +++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 quest/m1/snapshot-sequence.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 07e2529ccfe..7a2a6d15dfb 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -40,6 +40,7 @@ blocks. The quests that gated m0 lines moved under them. - [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 - [Stats linger](/quest/m1/stats-linger.md) - a grouped stats broadcast stays announced for a linger after its last session, so viewer churn stops re-announcing it across the mesh +- [Snapshot producers choose their group sequence](/quest/m1/snapshot-sequence.md) - a recomposed or restarted snapshot or catalog producer resumes past cached groups instead of restarting at 0 - [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost - [Delete removed cluster flags](/quest/m1/cluster-shims.md) - `mesh` and `linger` leave `cluster::Config` and their flags become unknown diff --git a/quest/m1/snapshot-sequence.md b/quest/m1/snapshot-sequence.md new file mode 100644 index 00000000000..47666f96ff6 --- /dev/null +++ b/quest/m1/snapshot-sequence.md @@ -0,0 +1,47 @@ +# [S] Snapshot producers choose their group sequence + +## Goal + +`moq_json::snapshot::Producer`, and moq-mux's `catalog::Producer` over it, let +the caller seed or choose each snapshot group's sequence number instead of +always taking `append_group()`'s next one. A producer that is recomposed or +restarted under the same track name can then publish sequences that keep +increasing across restarts, such as `max(last + 1, now_ms)`, so a subscriber or +relay holding the old run's groups never waits for the counter to catch up. +Every snapshot group starts with a full snapshot, so gaps between sequences +are legal. + +## Plan + +Decided 2026-10-05 in moq.pro's follow-ups (approved by the maintainer): the +consumer is moq.pro's edge-composed overlay catalog, which recomposes a +`catalog.pro` whenever its source or services change and must not restart at +group 0. + +- `write_snapshot` (`rs/moq-json/src/snapshot/producer.rs`) opens each group + with `self.inner.append_group()`. Add a way to pick the sequence: a seed in + `Config`, a caller-supplied allocator, or both. Pick the smallest shape that + covers a wall-clock seed and a shared allocator, and record why. A sequence + at or below the last one written is refused, never reordered. +- `moq-stats` already solved this for its own snapshots with a producer-wide + allocator seeded from the wall clock (moq#4739, moq#4810), by wrapping the + encoder in its own `Snapshot` writer (`rs/moq-stats/src/produce.rs`). Move + that onto the shared producer and delete the duplicate writer, so one path + numbers every snapshot track. +- `catalog::Producer` (`rs/moq-mux/src/catalog/producer.rs`) builds two + snapshot producers (`hang` and `hangz`); pass the choice through to both so + their groups stay paired. +- JS: `js/json`'s snapshot producer gets the same option if it has the same + `append_group` shape; mirror the name. +- Tests: a seeded producer starts at the seed; a recreated producer seeded + from `max(last + 1, now_ms)` resumes past a cached group; a non-increasing + choice is refused; a subscriber reading across a gap gets a full snapshot. + +Public API: a sequence option on `moq_json::snapshot::Producer` and +`moq_mux::catalog::Producer` (and the JS mirror). Wire: none. + +## Related + +- [Coalesce dynamic tracks](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - preserves sequences when a dynamic track's producer is replaced inside moq-net; this covers producers the caller recreates +- [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - stats' other answer to restarts +- [moq.pro: overlay catalog](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/overlay/catalog.md) - the recomposing producer that needs it From 11445d37f735a7833e7ec07fc9aaf04f3e5c219f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:52:19 -0700 Subject: [PATCH 6/9] quest: pair the catalog's hang and hangz sequences Co-Authored-By: Claude Opus 5.5 --- quest/m1/snapshot-sequence.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quest/m1/snapshot-sequence.md b/quest/m1/snapshot-sequence.md index 47666f96ff6..18df4d9e5a0 100644 --- a/quest/m1/snapshot-sequence.md +++ b/quest/m1/snapshot-sequence.md @@ -29,8 +29,9 @@ group 0. that onto the shared producer and delete the duplicate writer, so one path numbers every snapshot track. - `catalog::Producer` (`rs/moq-mux/src/catalog/producer.rs`) builds two - snapshot producers (`hang` and `hangz`); pass the choice through to both so - their groups stay paired. + snapshot producers (`hang` and `hangz`). Each catalog update picks one + sequence and writes it to both, so their groups stay paired; a test checks + the pair shares a sequence. - JS: `js/json`'s snapshot producer gets the same option if it has the same `append_group` shape; mirror the name. - Tests: a seeded producer starts at the seed; a recreated producer seeded From d04843c9fb0a498eee6394af03ab8f9332d7f7a9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:52:20 -0700 Subject: [PATCH 7/9] quest: preflight checks sync points, linger totals follow #4846 on main Co-Authored-By: Claude Opus 5.5 --- quest/m0/stats-linger.md | 15 ++++++++------- quest/m1/stats/health.md | 4 ++-- quest/m1/stats/preflight.md | 17 ++++++++++------- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/quest/m0/stats-linger.md b/quest/m0/stats-linger.md index 79042d0db81..7e1255a20b4 100644 --- a/quest/m0/stats-linger.md +++ b/quest/m0/stats-linger.md @@ -30,13 +30,14 @@ first proposed, and make it configurable. until the linger elapses with the group still empty; a row returning within the linger re-arms it. While it lingers empty, its live gauges and session presence read zero, so a reader sees no stale live counters. -- Under one epoch a path's cumulative totals never go backwards or count - twice. The producer drops a path's registry entry, and its totals, when - the path leaves (`flush` in `produce.rs`), and readers already treat a path - missing from a frame as restarted. So either the path drops out of frames - while the group lingers and its return reads as a restart, or the producer - carries its last totals forward and a returning entry resumes from them. - Pick while building and record why. +- Under one epoch totals never go backwards or count twice. On `main`, #4846 + (stats split, idle groups, decided 2026-10-05) settles it: a group + returning within the linger keeps its epoch and its totals continue, and + the per-path maps are gone. The `release` backport keeps today's per-path + map, which drops a path's entry and totals when it leaves (`flush` in + `produce.rs`); there, either the path drops out of frames while the group + lingers so its return reads as a restart, or the producer carries its last + totals forward. Pick while building the backport and record why. - Once the linger elapses, the group broadcast unannounces. A later return re-announces it under a new epoch, with its group sequence and totals counted from zero (decided 2026-10-05). This reverses stats epochs' one-epoch-per-producer diff --git a/quest/m1/stats/health.md b/quest/m1/stats/health.md index f042ed40f22..2264777ecfb 100644 --- a/quest/m1/stats/health.md +++ b/quest/m1/stats/health.md @@ -49,14 +49,14 @@ Guidance, to be settled while building: A browser publisher with only PROBE rtt yields unknown for what it cannot see, never a guess. - This quest classifies client reports only. +- Lives beside the snapshot types in `hang` and `@moq/hang` unless building + it shows a better home. Open, for the maintainer (the same question is recorded in [QoS](/quest/m1/qos/README.md)): whether anything computes a per-broadcast verdict combining client reports, the relay's starvation, and publisher timeliness, and where it would live. Nothing here depends on the answer, and no quest promises it until it is decided. -- Lives beside the snapshot types in `hang` and `@moq/hang` unless building - it shows a better home. Prove a degrading publisher self-report, a degrading viewer report, a stale report going unknown, and a counter reset by both a decrease and an epoch diff --git a/quest/m1/stats/preflight.md b/quest/m1/stats/preflight.md index e317155f6cc..dadfab78743 100644 --- a/quest/m1/stats/preflight.md +++ b/quest/m1/stats/preflight.md @@ -3,8 +3,9 @@ ## Goal A bounded test run against a published broadcast produces one report a person -can act on: catalog validity, codec support, time to the first keyframe, -bitrate and frame cadence per rendition, keyframe interval, audio/video skew, +can act on: catalog validity, codec support, time to the first sync point +(a group start a decoder can begin at), bitrate and frame cadence per +rendition, sync point interval, audio/video skew, media timestamp continuity, the [health verdict](/quest/m1/stats/health.md) from the publisher's stats, and whether the broadcast ends with a clean unannounce (observed by the check; the publisher, which owns the @@ -28,7 +29,7 @@ Guidance, to be settled while building: `moq` CLI sink that runs it for a bounded window and prints the report as JSON. The verb is the maintainer's call when the PR proposes it. - Reads only what the broadcast already carries: the catalog, media timestamps - and keyframe flags, and the `stats` track when the catalog names one. A + and group starts, and the `stats` track when the catalog names one. A broadcast without a stats track still gets the media checks, with health reported as unknown. - Codec support means "a stock player in this repo can decode it", checked @@ -40,9 +41,11 @@ Guidance, to be settled while building: Prove a healthy publisher end to end against a publisher from [Rust reporters](/quest/m1/stats/rust.md), a publisher outliving the window, -and deterministic failures for an invalid catalog, an unsupported codec, a -missing first keyframe, excessive A/V skew, and a media timestamp jump. Docs: -`doc/bin/inspect.md` is the home, with the sink's flags in `doc/bin/cli.md`. +an intra-refresh source (no IDR keyframes) passing the sync point checks, and +deterministic failures for an invalid catalog, an unsupported codec, a +missing first sync point, excessive A/V skew, and a media timestamp jump. +Docs: `doc/bin/inspect.md` is the home, with the sink's flags in +`doc/bin/cli.md`. Public API: a preflight check and its report type, and a CLI sink. Wire: none. @@ -54,5 +57,5 @@ Public API: a preflight check and its report type, and a CLI sink. Wire: none. ## Related - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - the relay's view of the same timestamp lateness and monotonicity -- [Intra-refresh](/quest/m2/intra-refresh/README.md) - a stream without IDR keyframes, which the first-keyframe check must not fail +- [Intra-refresh](/quest/m2/intra-refresh/README.md) - a stream without IDR keyframes, which the sync point checks must not fail - [moq.pro: stream preflight](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/qos-preflight.md) - the project-scoped target and dashboard flow built on these checks From 10ecad46d0b0b72d926ae273f9c929275c70fb48 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 13:54:21 -0700 Subject: [PATCH 8/9] quest: address CodeRabbit on GPU identity, HLS density, and health inputs Co-Authored-By: Claude Opus 5.5 --- quest/m1/hls-bounded.md | 8 +++++--- quest/m1/lite07-finalize.md | 3 ++- quest/m1/qos/README.md | 2 +- quest/m1/stats/health.md | 5 +++-- quest/m1/stats/preflight.md | 6 +++--- quest/m2/gpu-health.md | 4 +++- quest/m2/gpu-surface.md | 4 +++- 7 files changed, 20 insertions(+), 12 deletions(-) diff --git a/quest/m1/hls-bounded.md b/quest/m1/hls-bounded.md index 2a44e24d9a0..3cfb9de98bf 100644 --- a/quest/m1/hls-bounded.md +++ b/quest/m1/hls-bounded.md @@ -40,9 +40,11 @@ writes `EXT-X-GAP`). Fix only what a test shows missing: - **Bounded join.** Rendering for a new viewer reads at most the window's records from the timeline (`moq_json::window`; a new group repeats at most `CHECKPOINT_RECORDS = 256` recent records, in `moq-mux`'s `timeline.rs`), - never the whole history, - and never GETs or FETCHes media. A live publisher that never pops its - timeline must not make a join cost grow with broadcast age. + never the whole history, and never GETs or FETCHes media. A live publisher + that never pops its timeline must not make a join cost grow with broadcast + age. The window is bounded by duration, so very short segments still mean + many records per window: decide while building whether a record cap also + applies, and test dense input against it. - **Capped window, decided 2026-10-05.** A durable (store-backed) timeline still advertises a capped sliding window: a live playlist lists a bounded window even when the store retains more. A full VOD or EVENT listing is a diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index c21e12f036c..56a91b3312e 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -37,7 +37,8 @@ The cut: - The identifier becomes `moq-lite-07` in `rs/moq-net` and `js/net`, in the draft (whose text already names the rename), and at every site spelling the wip ALPN: `rs/moq-tokio/src/connect.rs` and `listen.rs`, - `rs/moq-relay/src/cluster.rs`, `rs/moq-relay/tests/smoke.rs`, + `rs/moq-tokio/tests/`, `rs/moq-relay/src/cluster.rs`, + `rs/moq-relay/tests/smoke.rs`, `test/interop/bare-fin.ts`, `test/interop/lite-varint.ts`, and `doc/concept/moq-lite.md`; grep for `moq-lite-07-wip` to catch new ones. A wip peer and a final peer refuse each other by ALPN rather than misparse; no compatibility shim. diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index 5cf20d24474..1ef63ffeb80 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -7,7 +7,7 @@ congestion views need: how far behind viewers are according to what the network has acknowledged, how timely publishers are against their own media clock, and what publishers and viewers report for themselves through [media stats](/quest/m1/stats/README.md), with congestion visible for viewers -in aggregate, the way CMSD does for HLS. +in aggregate. ## Plan diff --git a/quest/m1/stats/health.md b/quest/m1/stats/health.md index 2264777ecfb..fd2e81a8967 100644 --- a/quest/m1/stats/health.md +++ b/quest/m1/stats/health.md @@ -35,8 +35,9 @@ Guidance, to be settled while building: - Inputs are the snapshot types from [the schema](/quest/m1/stats/schema.md): `transport` (rtt, rate, loss, sample age) and the per-rendition counters. - Counters are cumulative, so a sample is the delta of two snapshots over - their interval. A reset is detected by a counter decreasing or by the + Rendition rates come from cumulative counters, so a sample is the delta of + two snapshots over their interval; `transport` gauges (rtt, rate, loss) + are read as reported, never re-derived, so both languages agree. A reset is detected by a counter decreasing or by the reporting broadcast's path or epoch changing ([Broadcast epochs](/quest/m0/broadcast-epoch/README.md)); the sample then starts over rather than going negative. diff --git a/quest/m1/stats/preflight.md b/quest/m1/stats/preflight.md index dadfab78743..d7cede4fbdc 100644 --- a/quest/m1/stats/preflight.md +++ b/quest/m1/stats/preflight.md @@ -39,9 +39,9 @@ Guidance, to be settled while building: the window and reports the unannounce check as not observed, never as a failure. -Prove a healthy publisher end to end against a publisher from -[Rust reporters](/quest/m1/stats/rust.md), a publisher outliving the window, -an intra-refresh source (no IDR keyframes) passing the sync point checks, and +Prove, end to end, a clean report for a healthy publisher built on +[Rust reporters](/quest/m1/stats/rust.md); a publisher outliving the window; +an intra-refresh source (no IDR keyframes) passing the sync point checks; and deterministic failures for an invalid catalog, an unsupported codec, a missing first sync point, excessive A/V skew, and a media timestamp jump. Docs: `doc/bin/inspect.md` is the home, with the sink's flags in diff --git a/quest/m2/gpu-health.md b/quest/m2/gpu-health.md index 5c8405e8114..7479f071b0a 100644 --- a/quest/m2/gpu-health.md +++ b/quest/m2/gpu-health.md @@ -42,7 +42,9 @@ Guidance, to be settled while building: Record which source backs each field per vendor, and whether each memory value is process-scoped or device-wide: `VK_EXT_memory_budget`'s `heapUsage` is this process's only, so device-wide usage needs a driver - source (DRM fdinfo per client, sysfs, or NVML). + source (sysfs or NVML). DRM fdinfo is per client: summing it covers only + the clients this process can see and may double-count shared buffers, so + report it as client-scoped unless building shows a sound device-wide sum. - Sessions moq-video opened itself are counted in process; device-wide counts come from the driver where it reports them, since several processes may share a GPU. diff --git a/quest/m2/gpu-surface.md b/quest/m2/gpu-surface.md index 73bb1c21e3a..1a71f8d5a0b 100644 --- a/quest/m2/gpu-surface.md +++ b/quest/m2/gpu-surface.md @@ -32,7 +32,9 @@ added this quest): - the device and driver UUID, and the render node's `dev_t` (decided 2026-10-05: the one device identity [VA-API import](/quest/m2/vaapi-vulkan-import.md) and - [GPU health](/quest/m2/gpu-health.md) key by); + [GPU health](/quest/m2/gpu-health.md) key by). A device without + `VK_EXT_physical_device_drm` or a render node carries none, and a + backend that needs it refuses the surface rather than guess; - the timeline: an `OPAQUE_FD` timeline semaphore handle, the value the producer signals when the image is ready, and the value the consumer signals when it is done reading. Both handles belong to the slot and live From a6013b8e6c7aa37c0a8c621a7302f07522e010ed Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 14:34:08 -0700 Subject: [PATCH 9/9] quest: drop snapshot-sequence; derived services stay on bare paths (moq#4817) Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/snapshot-sequence.md | 48 ----------------------------------- 2 files changed, 49 deletions(-) delete mode 100644 quest/m1/snapshot-sequence.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 924187025c9..5f5c19e6971 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -39,7 +39,6 @@ blocks. The quests that gated m0 lines moved under them. - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net - [Hard fork](/quest/m1/quic/fork/README.md) - quinn hard-forked in-tree as `moq-quic`, ranked ahead of transport-seam and perf; the rest of the QUIC line follows it -- [Snapshot producers choose their group sequence](/quest/m1/snapshot-sequence.md) - a recomposed or restarted snapshot or catalog producer resumes past cached groups instead of restarting at 0 - [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [One route cost](/quest/m1/route-cost.md) - Warm and Cold collapse to one static route cost - [Delete removed cluster flags](/quest/m1/cluster-shims.md) - `mesh` and `linger` leave `cluster::Config` and their flags become unknown diff --git a/quest/m1/snapshot-sequence.md b/quest/m1/snapshot-sequence.md deleted file mode 100644 index 18df4d9e5a0..00000000000 --- a/quest/m1/snapshot-sequence.md +++ /dev/null @@ -1,48 +0,0 @@ -# [S] Snapshot producers choose their group sequence - -## Goal - -`moq_json::snapshot::Producer`, and moq-mux's `catalog::Producer` over it, let -the caller seed or choose each snapshot group's sequence number instead of -always taking `append_group()`'s next one. A producer that is recomposed or -restarted under the same track name can then publish sequences that keep -increasing across restarts, such as `max(last + 1, now_ms)`, so a subscriber or -relay holding the old run's groups never waits for the counter to catch up. -Every snapshot group starts with a full snapshot, so gaps between sequences -are legal. - -## Plan - -Decided 2026-10-05 in moq.pro's follow-ups (approved by the maintainer): the -consumer is moq.pro's edge-composed overlay catalog, which recomposes a -`catalog.pro` whenever its source or services change and must not restart at -group 0. - -- `write_snapshot` (`rs/moq-json/src/snapshot/producer.rs`) opens each group - with `self.inner.append_group()`. Add a way to pick the sequence: a seed in - `Config`, a caller-supplied allocator, or both. Pick the smallest shape that - covers a wall-clock seed and a shared allocator, and record why. A sequence - at or below the last one written is refused, never reordered. -- `moq-stats` already solved this for its own snapshots with a producer-wide - allocator seeded from the wall clock (moq#4739, moq#4810), by wrapping the - encoder in its own `Snapshot` writer (`rs/moq-stats/src/produce.rs`). Move - that onto the shared producer and delete the duplicate writer, so one path - numbers every snapshot track. -- `catalog::Producer` (`rs/moq-mux/src/catalog/producer.rs`) builds two - snapshot producers (`hang` and `hangz`). Each catalog update picks one - sequence and writes it to both, so their groups stay paired; a test checks - the pair shares a sequence. -- JS: `js/json`'s snapshot producer gets the same option if it has the same - `append_group` shape; mirror the name. -- Tests: a seeded producer starts at the seed; a recreated producer seeded - from `max(last + 1, now_ms)` resumes past a cached group; a non-increasing - choice is refused; a subscriber reading across a gap gets a full snapshot. - -Public API: a sequence option on `moq_json::snapshot::Producer` and -`moq_mux::catalog::Producer` (and the JS mirror). Wire: none. - -## Related - -- [Coalesce dynamic tracks](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - preserves sequences when a dynamic track's producer is replaced inside moq-net; this covers producers the caller recreates -- [Stats epochs](/quest/m0/broadcast-epoch/stats-epoch.md) - stats' other answer to restarts -- [moq.pro: overlay catalog](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/overlay/catalog.md) - the recomposing producer that needs it