From daf5d613f5ae718b5922907142277d647ca81f9a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:04:33 -0800 Subject: [PATCH 01/11] quest: plan the API shape fixes from the release-vs-main audit An audit of release against main and the open quests scored 127 API clusters. This plans its approved changes: a route's role becomes its type, JS durations become classes, native playout sync decouples its tracks, sentinels and moq-video's env reads go, gateways share one ingest config, Rust drops the stream credit hook, and an api-shape epic batches the small per-area fixes. It also edits the plans the findings touch. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 + quest/m1/explicit-state/ffi-state.md | 8 ++++ quest/m1/explicit-state/publish-capture.md | 6 ++- quest/m1/hosted-assets.md | 21 +++++++++ quest/m1/stream-credit/README.md | 7 +++ quest/m1/stream-credit/no-credit-hook.md | 29 ++++++++++++ quest/m1/watch-supported-default.md | 16 +++++++ quest/m2/README.md | 14 ++++++ quest/m2/api-shape/README.md | 53 ++++++++++++++++++++++ quest/m2/api-shape/apps.md | 35 ++++++++++++++ quest/m2/api-shape/bindings.md | 23 ++++++++++ quest/m2/api-shape/js.md | 35 ++++++++++++++ quest/m2/api-shape/media.md | 28 ++++++++++++ quest/m2/api-shape/native.md | 27 +++++++++++ quest/m2/api-shape/net.md | 51 +++++++++++++++++++++ quest/m2/api-shape/transport.md | 23 ++++++++++ quest/m2/cluster-routing/routes/session.md | 10 ++++ quest/m2/gateway-ingest.md | 30 ++++++++++++ quest/m2/js-time-types.md | 49 ++++++++++++++++++++ quest/m2/moq-quic-unused-surface.md | 15 +++++- quest/m2/mux-sync.md | 38 ++++++++++++++++ quest/m2/no-sentinels.md | 29 ++++++++++++ quest/m2/rendition-stats-type.md | 7 ++- quest/m2/route-roles.md | 43 ++++++++++++++++++ quest/m2/time-addressing/model.md | 9 +++- quest/m2/video-devices.md | 22 +++++++++ quest/m3/quic-sansio-driver.md | 7 ++- quest/m3/release/README.md | 1 + quest/m3/release/api-review.md | 16 +++++++ quest/m3/release/cut.md | 9 +++- quest/m3/release/migrate-audit.md | 20 ++++++++ quest/m3/release/qmux-rs-retire.md | 19 ++++++++ quest/m3/rtc-pacing.md | 7 ++- quest/m3/srt-rate-handle.md | 5 +- quest/m4/README.md | 2 + quest/m4/api-diff-gst.md | 18 ++++++++ quest/m4/binding-export-coverage.md | 17 +++++++ quest/m4/env-knobs.md | 10 ++-- 38 files changed, 748 insertions(+), 13 deletions(-) create mode 100644 quest/m1/hosted-assets.md create mode 100644 quest/m1/stream-credit/no-credit-hook.md create mode 100644 quest/m1/watch-supported-default.md create mode 100644 quest/m2/api-shape/README.md create mode 100644 quest/m2/api-shape/apps.md create mode 100644 quest/m2/api-shape/bindings.md create mode 100644 quest/m2/api-shape/js.md create mode 100644 quest/m2/api-shape/media.md create mode 100644 quest/m2/api-shape/native.md create mode 100644 quest/m2/api-shape/net.md create mode 100644 quest/m2/api-shape/transport.md create mode 100644 quest/m2/gateway-ingest.md create mode 100644 quest/m2/js-time-types.md create mode 100644 quest/m2/mux-sync.md create mode 100644 quest/m2/no-sentinels.md create mode 100644 quest/m2/route-roles.md create mode 100644 quest/m2/video-devices.md create mode 100644 quest/m3/release/qmux-rs-retire.md create mode 100644 quest/m4/api-diff-gst.md create mode 100644 quest/m4/binding-export-coverage.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 39f77f2cd7b..154fd066deb 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -44,6 +44,8 @@ moves what remains of them once their claims merge. - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; time-stretched browser playback without steady-state underruns and a native trace replay remain - [Buffered playback subscribes in ascending order](/quest/m1/buffered-ascending.md) - a buffered `` asks for the oldest group first, so a voice reply's opening arrives first, and audio's head hold shrinks to the floor +- [One assets() for every hosted file](/quest/m1/hosted-assets.md) - `@moq/hang` owns `assets()`, which also points the libav polyfill at the hosted wasm +- [Watch sources default to the decoder's probe](/quest/m1/watch-supported-default.md) - a source built without `in.supported` plays instead of selecting nothing - [Push-to-talk's press-to-audible latency fits a budget on the defaults](/quest/m1/push-to-talk-latency.md) - press to audible on the browser defaults, excluding device output, stays under a kixtop-measured budget that `just test push-to-talk` enforces - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide - [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them diff --git a/quest/m1/explicit-state/ffi-state.md b/quest/m1/explicit-state/ffi-state.md index 05f9282b283..2993048db67 100644 --- a/quest/m1/explicit-state/ffi-state.md +++ b/quest/m1/explicit-state/ffi-state.md @@ -51,6 +51,14 @@ Also sweep: - `MoqServer` (`server.rs`): its lifecycle is spread over four places. - `MoqTrackProducer.keep: None`, which means both "finished" and "has no family". +- `MoqConnectionState` (`session.rs`) is a flat snapshot (`revision`, + `phase`, `connects`, `failure`, `version`), so `failure` and `version` are + readable in phases where they mean nothing. It carries each phase's data + with that phase, mirroring whatever shape Rust's connection state takes, + and moq-c's `moq_connection_state` follows (renaming its `protocol` to + `version`). It breaks every binding, so under the epic's milestone rule + this item splits into its own m2 quest when this quest starts (added + 2026-11-07, maintainer, /quest-plan from the API shape audit). - moq-c's global id counter, whose wrap lets a stale route id name a newer broadcast. Use generation-tagged ids or clear ids on close. diff --git a/quest/m1/explicit-state/publish-capture.md b/quest/m1/explicit-state/publish-capture.md index bdb07356c98..2bee77f4bee 100644 --- a/quest/m1/explicit-state/publish-capture.md +++ b/quest/m1/explicit-state/publish-capture.md @@ -45,6 +45,10 @@ Also sweep: - The preview `Transcode.#active`. - The `` and `` enable latches (`#enabled`, `#connected`, `#invalid`, `#resume`). Derive enabled as connected with no - invalid attributes. + invalid attributes. ``'s `announce` getter returns + `AnnounceMode`, and an invalid `announce` attribute suspends announcing + through `#invalid` like every other attribute, instead of the getter + returning `undefined` (added 2026-11-07, maintainer, /quest-plan from the + API shape audit). - `js/moq-boy/src/game.ts`: a command sent while disconnected replays on reconnect. diff --git a/quest/m1/hosted-assets.md b/quest/m1/hosted-assets.md new file mode 100644 index 00000000000..7973ba7c5d4 --- /dev/null +++ b/quest/m1/hosted-assets.md @@ -0,0 +1,21 @@ +# [S] One assets() for every hosted file + +## Goal + +A page that serves the player's files itself (for a strict +`Content-Security-Policy` with no `blob:` workers) calls one `assets(url)`, +and that call also points the libav AAC polyfill at the hosted wasm. Today +`@moq/watch` and `@moq/publish` each carry an identical copy of `assets()` +(`js/watch/src/assets.ts`, `js/publish/src/assets.ts`), and an app that +needs the polyfill must also import `@moq/libav` and set its mutable +`LibAV.base`, a transitive dependency our API never mentions. + +## Plan + +Found by the 2026-11-07 API shape audit (browser media). Move `assets` and +its resolver into `@moq/hang`, the shared dependency whose +`Util.Libav.polyfill()` (`js/hang/src/util/libav.ts`) loads libav, and have +the polyfill take its base from it. `@moq/watch` and `@moq/publish` +re-export it, so their existing `assets()` callers keep working and nothing +breaks. `@moq/libav` stays an implementation dependency. Future hosted files +(the watch worker) join the same call. Test it on the CSP demo pages. diff --git a/quest/m1/stream-credit/README.md b/quest/m1/stream-credit/README.md index deebfe36d1d..fcda393f586 100644 --- a/quest/m1/stream-credit/README.md +++ b/quest/m1/stream-credit/README.md @@ -36,6 +36,12 @@ which JS cannot raise; Chrome stalled at 103, Firefox at 100): browser test stays this README's own work. Not chosen: holding the whole quest until #7670 merges. +- Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): + ✅ delete Rust's `StreamCredit` hook too, with no replacement hook + ([no-credit-hook](/quest/m1/stream-credit/no-credit-hook.md)). #7894's + reversal removed the JS half; the Rust trait kept it because the open line + reads it. Not chosen: keeping the hook and recording why. + This epic owns the end-to-end test: a browser reader and a Rust relay over WebTransport, 300 live tracks of mixed priority, the highest-priority ones receiving every group, and nothing hanging. @@ -43,3 +49,4 @@ receiving every group, and nothing hanging. ## Required - [Takeover](/quest/m1/stream-credit/takeover.md) - on lite-07 a higher-priority group takes over an acknowledged stream, and a group that lost its stream resumes +- [Transports report no stream credit](/quest/m1/stream-credit/no-credit-hook.md) - `StreamCredit` and the `poll::Session::stream_credit` hook are gone, and the open line infers a credit wait from its own state diff --git a/quest/m1/stream-credit/no-credit-hook.md b/quest/m1/stream-credit/no-credit-hook.md new file mode 100644 index 00000000000..301831fb95d --- /dev/null +++ b/quest/m1/stream-credit/no-credit-hook.md @@ -0,0 +1,29 @@ +# [S] Transports report no stream credit + +## Goal + +`moq_net::transport::StreamCredit`, `Dir`, and the `poll::Session::stream_credit` +hook are gone, so no transport implements a credit API. The open line +(`rs/moq-net/src/transport/open.rs`) decides when a waiting open preempts a +lower-ranked stream from its own state, as `js/net` already does, and an +open waiting on something other than credit still never triggers a reset. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): +✅ "Delete, no hooks" (rejected: keeping the hook and recording why). This +follows the [moq-dev/moq#7894](https://github.com/moq-dev/moq/pull/7894) +reversal recorded in this epic ("the signal is the open line's waiting +state, with no transport credit or blocked API") and overrides +[moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088)'s refutation, +which kept the hook because the open line reads it. + +The hook exists today so an open waiting on a WebTransport stream header is +not mistaken for a credit wait (`make_room`, open.rs). Remove that case at +its source, for example by having a transport's open complete only once +credit is granted and write the header after, so a pending head always means +credit. Implementers of `poll::Session` (moq-tokio, moq-uring, qmux, the +memory transport) drop their implementations. + +Breaking for transport implementers; the Impact section says what replaces +the hook. diff --git a/quest/m1/watch-supported-default.md b/quest/m1/watch-supported-default.md new file mode 100644 index 00000000000..75b08dae4df --- /dev/null +++ b/quest/m1/watch-supported-default.md @@ -0,0 +1,16 @@ +# [XS] Watch sources default to the decoder's probe + +## Goal + +A composer that builds `@moq/watch`'s `Audio.Source` or `Video.Source` +without `in.supported` gets playback. Today the input defaults to +`undefined`, and "nothing is selected until one is provided" +(`js/watch/src/audio/source.ts`), so forgetting it is silent non-playback. +When `in.supported` is absent, the source uses its decoder's `supported` +probe. + +## Plan + +Found by the 2026-11-07 API shape audit (browser media). Additive: callers +that pass `supported`, such as the `` element, are unchanged. Add a test that a source built without it selects a +rendition. diff --git a/quest/m2/README.md b/quest/m2/README.md index bfbcd17fba8..f3241f470a0 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -163,6 +163,13 @@ Added 2026-11-04 (maintainer): the relay reports the native sessions its drain deadline force-closes while still open, apart from those only finishing their end report, so an embedder's drain alert pages on real cuts. +Added 2026-11-07 (maintainer, /quest-plan from an API shape audit of +`release` against `main` and the open quests): the breaks it found that the +cut would otherwise publish. A route's role becomes its type; JS durations +and instants become objects; native playout sync decouples its tracks like +the browser's; sentinels, moq-video's environment reads, and per-gateway +ingest setters go; and an epic batches the small fixes per area. + Decided 2026-11-05 (maintainer, /quest-audit): blockers rank above the quests that require them. @@ -178,6 +185,7 @@ quests that require them. - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate (held in m1 by an open claim) - [Cluster routing](/quest/m2/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design +- [A route's role is its type](/quest/m2/route-roles.md) - no route method panics, throws, or errors because the other constructor made the route; prototypes of a single prefix route and an exact/prefix split decide the shape - [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - the wire names every abandoned group and the drop signal is public, so readers count losses instead of stalling - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out (held in m1 by an open claim) - [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it @@ -185,6 +193,12 @@ quests that require them. - [Session policy lives in moq-net](/quest/m1/session-policy/README.md) - accept and connect deadlines, admission, window widening and reconnect live once in moq-net; moq-tokio and moq-relay's io_uring path call them (held in m1 by an open claim) - [moq-quic drops inherited surfaces with no consumer](/quest/m2/moq-quic-unused-surface.md) - unused accept, connection, and stream-id surfaces leave moq-quic's public API before the cut - [Publish reports rendition stats as hang's type](/quest/m2/rendition-stats-type.md) - `Rendition.stats` and `Report.Writer` take the rendition stats schema's input type, so encoders write plain numbers +- [No sentinel values in public API](/quest/m2/no-sentinels.md) - receive windows, cache durations, reconnect timeouts, and the FFI test clock use `Option` instead of a huge value or zero +- [moq-video takes devices, not environment variables](/quest/m2/video-devices.md) - VA-API and V4L2 device paths are config fields, and `moq_video::ENV` never ships +- [Gateways share one ingest config and one rate cap](/quest/m2/gateway-ingest.md) - `moq_mux::Ingest` replaces 18 per-gateway setters, and the live rate cap moves to `moq_net::bandwidth` +- [Native playout sync keeps tracks decoupled](/quest/m2/mux-sync.md) - `moq_mux::timeline` becomes `moq_mux::sync`, and one slow track no longer stalls or moves another +- [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile +- [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings - [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto (held in m1 by an open claim) - [Cut readiness](/quest/m2/cut-gate/README.md) - the checks the cut needs that break nothing: main no slower than release, vendored fixes ported, and moq-c at parity - [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; browser padding is parked in m3 (held in m2 by open claims; moves to m3) diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md new file mode 100644 index 00000000000..1936e5df2c4 --- /dev/null +++ b/quest/m2/api-shape/README.md @@ -0,0 +1,53 @@ +# [L] Small API fixes before the cut + +## Goal + +The surfaces `main` adds since `release` follow the repository's API rules +before the cut publishes them: one path and one spelling per item, names by +role, no dead or unreachable public items, no setter that a caller can apply +to the wrong role, and Rust, JS, and the bindings mirrored. Each child is a +batch of small, mostly breaking fixes to one area, sized so one PR reviews in +one sitting. + +## Plan + +Planned 2026-11-07 (maintainer, /quest-plan) from an audit of `release` +(a005c7ad9a) against `main` (a9d7925123) plus the open quests. Nine +read-only reviewers (net model, net session, transport, media formats, +native media, apps, JS core, browser media, bindings) scored 127 clusters +for performance, usability, testability, and future fit, using +`just api-diff` and consumer searches in this repository and its +downstream applications. The maintainer approved the plan as shown. The larger findings +became their own m1, m2, m3, and m4 quests; this epic holds the rest. + +This audit ran while [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088), +the previous API audit's final pass, was open, and none of its children +repeats an item #8088 changes. A child that starts after #8088 merges +rechecks each item against `main` and drops what is already done. + +Rules every child follows: + +- Removal beats addition. A public item with no caller in this repository, + a known downstream application goes private, unless an m1 or m2 quest plans a + caller. +- No serde aliases, refusals, or shims for a spelling `release` never + shipped. +- Each child lists its public API and wire impact in its PR, and its Impact + section says how to migrate. + +Rejected in planning: + +- One audit PR for every area: each child touches a different owner's code, + and #8088 showed that a 100-file audit PR spends weeks rebasing. +- Folding these items into the larger quests: those wait on decisions or + prototypes, and these do not. + +## Required + +- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, and priority surface, and no public wire codes +- [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals +- [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name +- [Native media's small surface fixes](/quest/m2/api-shape/native.md) - audio encode internals go private, `on_demand` has one meaning, and video and render setters fold into their constructors +- [Apps' small surface fixes](/quest/m2/api-shape/apps.md) - the relay, gateways, moq-hls, moq-cli, and moq-boy drop dead or unreachable surface and gain role names +- [JS packages' small surface fixes](/quest/m2/api-shape/js.md) - track info, connection, qmux, watch, publish, ui, video, boy, and auth exports each have one path and one name +- [Bindings' small surface fixes](/quest/m2/api-shape/bindings.md) - Go's read cancel, JSON producer construction, and the Python wheel's test module diff --git a/quest/m2/api-shape/apps.md b/quest/m2/api-shape/apps.md new file mode 100644 index 00000000000..81600d3356e --- /dev/null +++ b/quest/m2/api-shape/apps.md @@ -0,0 +1,35 @@ +# [M] Apps' small surface fixes + +## Goal + +- moq-relay: + - `Internal::with_uring` becomes crate-private; it takes a type nobody + outside can build since `uring` went private. + - The hidden refusals for config keys and flags `release` never shipped + (`[session]`, `[peer]`, `--peer-*`, `--limits-*-requests`, + `auth.verifications`) are deleted. + - `cluster::Options.session` becomes `client`, matching its type and the + `[limits.client]` key. + - `Relay::{rtmp, webrtc}` become take-once `&mut self -> Option<_>`, like + `admissions()`. + - `session::View` and `shutdown::{Tally, Drained}` get + `#[non_exhaustive]`. +- moq-webrtc drops the dead `Error::{SessionNotFound, SessionClosed}` and + hides `p2p` (`#[doc(hidden)]`, as on release) until the + [m4 p2p work](/quest/m4/p2p/README.md) has a caller. +- moq-srt's `dial` module becomes private; `Client` keeps one path. +- moq-hls gains `Error::is_denied()`, so embedders stop matching nested + errors. +- `moq export hls`'s listener flags become `--hls-listen` and + `--hls-tls-{cert,key,generate,root}`, matching the `MOQ_HLS_*` + environment, with named refusals for the old flags, which shipped. +- moq-boy's Rust crate stops exporting its internals (the JS half is in + [the JS child](/quest/m2/api-shape/js.md)). + +## Plan + +Found by the 2026-11-07 API shape audit (apps); see the +[epic](/quest/m2/api-shape/README.md). Decided 2026-11-07 (maintainer): +✅ hide `p2p` until m4 (rejected: keep it public; delete it). Gateway ingest +is [gateway-ingest](/quest/m2/gateway-ingest.md). Downstream code that +matches the deleted webrtc variants loses only dead arms. diff --git a/quest/m2/api-shape/bindings.md b/quest/m2/api-shape/bindings.md new file mode 100644 index 00000000000..f192962f155 --- /dev/null +++ b/quest/m2/api-shape/bindings.md @@ -0,0 +1,23 @@ +# [S] Bindings' small surface fixes + +## Goal + +- Go: a cancelled context on `Next`, `ReadFrame`, or `RecvGroup` cancels + only that read, as in Python, Swift, Kotlin, Dart, and C++. Today + `go/wrapper/subscribe.go` passes the consumer's `Cancel`, so a caller + cannot bound one read and continue. Range-loop iterators still cancel the + consumer when the loop exits. Check first that the Go generator fork + supports a per-call cancel. +- JSON tracks have one constructor shape in moq-ffi and every wrapper: a + producer the catalog advertises comes from the catalog producer, not from + a free constructor that the caller must then register. +- Python: `moq.testing` leaves the published wheel; tests import it from the + source tree. + +## Plan + +Found by the 2026-11-07 API shape audit (bindings); see the +[epic](/quest/m2/api-shape/README.md). The generated check that each +hand-written wrapper exports every FFI item is +[binding-export-coverage](/quest/m4/binding-export-coverage.md). moq-c's +renames are in [moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060). diff --git a/quest/m2/api-shape/js.md b/quest/m2/api-shape/js.md new file mode 100644 index 00000000000..a6b4a3f68de --- /dev/null +++ b/quest/m2/api-shape/js.md @@ -0,0 +1,35 @@ +# [M] JS packages' small surface fixes + +## Goal + +- `@moq/net`: + - A resolved `Track.Info` uses `null` for "none" (`maxAge`, `timescale`); + `Track.infoDefaults` and the `Track.rescale` alias go. + - `Connection.Established` becomes `Session`, and the orphan + `Connection.Extensions` type goes. + - `readBool` goes; it has no caller and no Rust mirror. + - `RouteOptions.instance` takes `{ id, epoch }`, like Rust's + `with_instance(instance, epoch)`. +- `@moq/qmux` exports `Session` by name instead of an anonymous default. +- `@moq/watch`: the decoder and source plumbing outputs are `@internal`, the + renderer's output is a named `Video.RendererOutput`, and ``'s + `player` property goes private, so each component has one path. +- `@moq/publish`: `Rendition.onDemand` becomes an enum, `Broadcast.join` + becomes a `Getter`, and the five internal source helpers are unexported. +- `@moq/ui` and `@moq/video` mark their helpers `@internal`; only `Support`, + `Report`, `Show`, `Level`, and `Status` stay public in `@moq/ui`, and + `rotateVideoDimensions`, `Dimensions`, `Presentation`, and + `Preview.Transcode` leave `@moq/video`'s public API. +- `@moq/boy` stops exporting `Game`, `GameConfig`, `KEY_MAP`, and its + `Moq` and `Watch` namespace re-exports, keeping the element and status + schemas. +- `@moq/auth`'s `Key.sign` takes one spelling for caps. + +## Plan + +Found by the 2026-11-07 API shape audit (JS core and browser media); see +the [epic](/quest/m2/api-shape/README.md). Durations are +[js-time-types](/quest/m2/js-time-types.md); hosted assets and the +`supported` default are m1 quests. Each change updates its package's +`api/*.api.md`, and moq.dev's npm consumer is checked for each removed +export. diff --git a/quest/m2/api-shape/media.md b/quest/m2/api-shape/media.md new file mode 100644 index 00000000000..eb4080ab6b7 --- /dev/null +++ b/quest/m2/api-shape/media.md @@ -0,0 +1,28 @@ +# [M] Media crates' small surface fixes + +## Goal + +Each item below has one path and one name: + +- moq-mux exporters (fmp4, mkv, flv, mp4): the fmp4 and catalog internals + no caller uses become private, flv returns a typed error instead of a + string, and every exporter names its wait the same way (the name moq-mux's + TS exporter uses since [moq-dev/moq#7981](https://github.com/moq-dev/moq/pull/7981)). +- The container `Consumer` has one constructor, through + `container::Playout`; `with_delay` goes. +- hang's `catalog::Range` becomes `ColorRange`, and the MoQ epoch constant + lives only in `kio::clock::Wall`; hang and moq-mux re-export nothing. +- `moq_mux::rate::Follower` becomes `rate::Grant`, so it no longer collides + with `ts::Follower`. +- moq-stats drops its ten `moq_net::stats` re-exports. +- `moq_mux::json::Options` folds into `json::Config`. +- `msf::Track.init_data` returns to `Option`. + +## Plan + +Found by the 2026-11-07 API shape audit (media formats); see the +[epic](/quest/m2/api-shape/README.md). The playout clock is +[mux-sync](/quest/m2/mux-sync.md), and rendition stats are +[rendition-stats-type](/quest/m2/rendition-stats-type.md). Check the +`ts::Follower` and `ts::Release` collision too, and rename whichever name +the PR shows is ambiguous. diff --git a/quest/m2/api-shape/native.md b/quest/m2/api-shape/native.md new file mode 100644 index 00000000000..991ab6b31ed --- /dev/null +++ b/quest/m2/api-shape/native.md @@ -0,0 +1,27 @@ +# [M] Native media's small surface fixes + +## Goal + +- moq-audio's `encode::{Control, State, Status}` become private, and + `publish_capture` stays the public path. +- `on_demand` means one thing across crates. moq-video's closes the camera + between viewers and defaults to `false`; moq-audio's keeps the device open, + defers encoding, and replays retained PCM, and defaults to `true`. Audio's + gets a name for its role (for example `retain`), and `@moq/publish`'s + audio `capture` mode is checked for the same name. +- moq-video's encode producer folds `with_track` into `new`. +- `encode::Applied` reports `cut`, so callers stop matching + `CutUnsupported` to learn it. +- moq-audio's playback `Sink::{set_volume, volume, peak}` go, since + `Control` has them, and the audio decode `Consumer::max_delay()` duplicate + goes. +- The render `Exporter::new` returns the settled `encode::Config` instead + of rewriting the caller's `&mut` config. + +## Plan + +Found by the 2026-11-07 API shape audit (native media); see the +[epic](/quest/m2/api-shape/README.md). moq-ffi, moq-c, and the wrappers +follow each rename. The device paths are in +[video-devices](/quest/m2/video-devices.md). Check downstream audio +callers of `on_demand` before picking the new name. diff --git a/quest/m2/api-shape/net.md b/quest/m2/api-shape/net.md new file mode 100644 index 00000000000..f8f19cc3011 --- /dev/null +++ b/quest/m2/api-shape/net.md @@ -0,0 +1,51 @@ +# [M] moq-net's small surface fixes + +## Goal + +Each item below lands in moq-net (and moq-auth for the mesh constants) with +its JS and binding mirrors: + +- Remove `Client::with_origin` (`rs/moq-net/src/client.rs`). It is sugar + for `with_publisher(&o).with_subscriber(o)`, release's + `Server::with_origin` is already gone, and its six callers (moq-boy, + moq-stats, the relay's cluster and stats, a moq-ffi test, and moq-tokio's + forwarder) switch to the two calls. +- Make `Version::{code, from_code}` `pub(crate)`. The relay compares + `version.code() >= 0xff0dad05` (`rs/moq-relay/src/cluster.rs`) and moq-cli + scans `0xff0dad00..=0xff0dadff`; each asks a named question of `Version` + instead (add the predicate the relay needs, and let moq-cli list + `Version`'s supported set). +- Make `group::Producer::demand` and `group::Demand` `pub(crate)`. Nothing + outside moq-net calls them, and flights stop through + `Fill::poll_unwanted`. Update `rs/moq-net/MIGRATE.md`'s mention. +- Replace `compress: bool` on track info with a `Compression` enum that + matches the wire's values, in Rust, `@moq/net`, moq-ffi, and moq-c. +- Rename `server::{Activity, Active}` to `server::{Admission, Admitted}`. +- Rename `RefusalKind::Lan` and `Refusals.lan` to `Membership` and + `membership` ("a membership proof was missing or invalid"), so moq-net's + counters name no relay flag. No serde alias: the field is new since + release. moq-stats and stats dashboards follow. +- Add `reconnect::Attempt::client(&self, &Client) -> Client`, which sets the + URL, places the token where the client's own versions put it, and attaches + the token handle. It replaces `Attempt::token()`, `Reconnect::with_tokens`'s + `versions` argument, and the caller's separate `with_auth` call. +- Make `moq_auth::mesh::{PROOF_CONTEXT, CHALLENGE_LEN, proof_message}` + private. +- Rename the datagram `Producer::poll_priority(waiter, last)` to + `poll_priority_changed(&mut self, waiter)`, keeping its own last value like + `poll_wanted_changed`. +- `Producer::route` and `Request::route` refuse an instance that + `is_minted()`, so a caller cannot claim a random instance as stable. +- After [moq-dev/moq#8063](https://github.com/moq-dev/moq/pull/8063) removes + `RouteEvent::Takeover`, un-hide `origin::Consumer::routes`, `Routes`, and + `RouteEvent`, documented as the relay-level stream that moq-relay and + downstream relays already consume, and fix `request`'s doc to say what #8063 made it + do. + +## Plan + +Found by the 2026-11-07 API shape audit (net model and net session); see +the [epic](/quest/m2/api-shape/README.md). Each item is XS except +`Attempt::client` and `Compression` (S each). `RefusalKind` is a stats-wire +field, so say in the PR which deployed dashboards read it. If #8063 has not +merged when this starts, leave the un-hide for a follow-up and say so. diff --git a/quest/m2/api-shape/transport.md b/quest/m2/api-shape/transport.md new file mode 100644 index 00000000000..d7372270b15 --- /dev/null +++ b/quest/m2/api-shape/transport.md @@ -0,0 +1,23 @@ +# [S] Transports take shared types + +## Goal + +- moq-uring stops defining its own congestion and TLS types. Its QUIC + configs take a `moq_congestion` factory (BBR3 by default, matching + moq-tokio; today `moq_uring::quic::Congestion` defaults to `Loss`) and an + `Arc` or `Arc`, as moq-tokio's + do. `moq_uring::quic::Congestion`, `Identity`, `ClientAuth`, and the client + TLS fields are gone. +- moq-tokio's `server::Request::quic()` is removed; nothing outside the + crate calls it, and it exposes the QUIC backend through the session API. + +## Plan + +Found by the 2026-11-07 API shape audit (transport); see the +[epic](/quest/m2/api-shape/README.md). The relay's io_uring path builds its +configs the way the tokio path does, so it loses its conversion code. The +moq-quic config knobs and re-export fan-out are in +[moq-quic-unused-surface](/quest/m2/moq-quic-unused-surface.md), and the +shared sans-IO driver in [quic-sansio-driver](/quest/m3/quic-sansio-driver.md). +Run the uring benches before and after, since the default controller +changes. diff --git a/quest/m2/cluster-routing/routes/session.md b/quest/m2/cluster-routing/routes/session.md index a6f2c1a9dc0..ff9943ea622 100644 --- a/quest/m2/cluster-routing/routes/session.md +++ b/quest/m2/cluster-routing/routes/session.md @@ -146,6 +146,16 @@ by a proven key, every remaining attack stays inside the forger's grant, with no grant field, no issuer-coordinated labels, and support for token-less admission. +Added 2026-11-07 (maintainer, /quest-plan from the API shape audit), for +the PR that lands this ([moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)): + +- An origin has one identity on both wires, seeded from `Config.hop`, not a + hop ID beside a separate random route identity. +- `Cost::{MAX, DRAIN}` become `pub(crate)`. A drained route is the lowest + preference, never a saturated metric ("drain is a preference state", in + the [epic](/quest/m2/cluster-routing/README.md)), so sessions stop + stamping `Cost::DRAIN` on GOAWAY, including on moq-transport. + ## Related - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the contract diff --git a/quest/m2/gateway-ingest.md b/quest/m2/gateway-ingest.md new file mode 100644 index 00000000000..7e8c30772fe --- /dev/null +++ b/quest/m2/gateway-ingest.md @@ -0,0 +1,30 @@ +# [M] Gateways share one ingest config and one rate cap + +## Goal + +Every protocol gateway configures ingest the same way, and no setter applies +to a direction it cannot affect: + +- `moq_mux::Ingest { max_age, bandwidth, linger }` (`#[non_exhaustive]`, + `Default`) replaces the 18 `with_max_age`/`with_bandwidth`/`with_linger` + setters and fields on moq-rtmp's and moq-srt's `Client` and `Publish`, and + moq-webrtc's `server::Config` and `client::Config`. It is taken by + `rtmp::Publish::accept`, `rtmp::Client::pull`, `srt::Publish::accept`, + `srt::Client::pull`, `moq_webrtc::whip::Request`, and + `moq_rtsp::Client::pull`. Egress keeps its own setters on `publish`. +- `moq_webrtc::rate::{Cap, Limit}` move to `moq_net::bandwidth` beside + `Rate`, so WHIP, WHEP, SRT, and the relay's grant caps share one live cap + handle. + +## Plan + +Found by the 2026-11-07 API shape audit (apps). Today a bidirectional client +documents its ingest setters as "pull direction only", so setting +`with_linger` and then calling `publish` is silently ignored. moq-rtsp +publishes with fixed defaults and gains the same knobs. Land before the cut +so moq-webrtc never ships its own `Cap`/`Limit` and moq-srt never copies +them: [srt-rate-handle](/quest/m3/srt-rate-handle.md) and +[rtc-pacing](/quest/m3/rtc-pacing.md) take `bandwidth::Limit`. moq-cli's +`import --max-age`/`--linger` build one `Ingest`. Whether +`moq_quic::limits::Rate`'s `Unlimited` variant can become `Option` is +out of scope. diff --git a/quest/m2/js-time-types.md b/quest/m2/js-time-types.md new file mode 100644 index 00000000000..58f4bf51e6e --- /dev/null +++ b/quest/m2/js-time-types.md @@ -0,0 +1,49 @@ +# [L] JS time values are types, not numbers + +## Goal + +Every public duration and instant in the published JS packages is a +`Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to +compile and cannot be stripped by `as number` or arithmetic. Today +`@moq/clock` and `@moq/signals` take `Nano`, `@moq/net` takes `Milli` +(`ConnectProps.timeout`, `Backoff`, `Delay`, `Info.maxAge`, fetch `maxDelay`, +`Goaway.handover`, `Drain.timeout`, `Probe.rtt`), and `@moq/qmux` takes raw +unbranded milliseconds (`Config.idleTimeout`, `handshakeTimeout`). That +costs 54 non-test unit conversions in `js/` alone. Covers +`@moq/clock`, `@moq/signals`, `@moq/net`, `@moq/qmux`, `@moq/hang`, +`@moq/json`, `@moq/room`, `@moq/watch`, and `@moq/publish`. `@moq/net` +re-exports `Clock` as it re-exports `Signals`. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): +"Can we make a proper new type instead of an alias? Converting to number is +easy but dangerous." ✅ `Duration` and `Instant` classes, mirroring +`kio::clock` (rejected: a `Duration` class with `Instant` kept a branded +number; branded `Nano` everywhere, which keeps the `as number` escape; +moving everything to `Milli`, which reverses #5706 and loses timer +precision). + +- `Clock.Duration` is immutable, with unit constructors (`Duration.millis`, + `secs`, `micros`, `nanos`), unit accessors, `add`/`sub`/`mul`, comparison, + and no implicit number conversion (`valueOf` refuses). `Clock.Instant` + supports `add(Duration)`, `since(Instant) -> Duration`, and comparison; + `Wall` follows the same rule. +- The wire still carries whole milliseconds; rounding stays inside the + encoders, as it does today. +- `Manual`, `sleep`, `timeout`, `interval`, and the signals timers take the + new types. +- Per-frame paths now allocate (watch `Sync`, the audio jitter ring, hang's + container reader, publish encoders). Run their benches (`js/*/bench`) + against main and report the deltas in the PR; avoid allocations where a + hot loop can keep an internal number without exposing it. +- Decide here whether `Time.Timestamp.value` becomes a `bigint` or keeps a + `number`, together with [time addressing's JS half](/quest/m2/time-addressing/js.md), + which makes group starts `bigint` timestamps. + +Breaking in every listed package; the Impact section gives the migration +(`x as Milli` becomes `Clock.Duration.millis(x)`). + +## Related + +- [Time addressing in JS](/quest/m2/time-addressing/js.md) - rekeys groups by timestamp in the same packages diff --git a/quest/m2/moq-quic-unused-surface.md b/quest/m2/moq-quic-unused-surface.md index 2c610dd793a..8018c28ae94 100644 --- a/quest/m2/moq-quic-unused-surface.md +++ b/quest/m2/moq-quic-unused-surface.md @@ -6,7 +6,17 @@ moq-quic's public API loses the inherited surfaces nothing calls: `endpoint::{Accepting, Accepted}`, `Endpoint::{start_accept, finish_accept}`, `Connection::{side, is_handshaking}`, and `stream::Id::{new, dir, initiator}`. Each is removed, not just made private, unless a caller inside moq-quic needs -it, in which case it becomes private. The PR's Impact section says how to +it, in which case it becomes private. + +The config knobs nothing outside moq-quic sets become private at their +current defaults: `packet_threshold`, `time_threshold`, +`persistent_congestion_threshold`, `allow_spin`, `crypto_buffer_size`, +`pad_to_mtu`, `send_fairness`, `min_mtu`, `min_reset_interval`, +`retry_token_lifetime`, `incoming_buffer_size_total`, and `initial_rtt`. +moq-tokio, moq-uring, and qmux each replace their lists of moq-quic names +(20 in moq-tokio's `quic::driver`) with one `pub use moq_quic;`, so each +item has one path and a moq-quic bump changes no list. qmux keeps `Version`, +its own wire concept. The PR's Impact section says how to migrate; the release cut copies that into `MIGRATE.md`. ## Plan @@ -17,5 +27,8 @@ before the cut, since removing public API after it would be another break. Not chosen: folding the list into the post-cut [dead-code audit](/quest/m3/audit-dead-code.md). +Added 2026-11-07 (maintainer, /quest-plan from the API shape audit): the +config knobs and the re-export fan-out, which grows the quest from [XS]. + Confirm each has no caller across the workspace, bindings, and vendored crates before removing it. diff --git a/quest/m2/mux-sync.md b/quest/m2/mux-sync.md new file mode 100644 index 00000000000..92f6a3296db --- /dev/null +++ b/quest/m2/mux-sync.md @@ -0,0 +1,38 @@ +# [M] Native playout sync keeps tracks decoupled + +## Goal + +`moq_mux::timeline` becomes `moq_mux::sync` and follows the browser +player's model: lip sync in the steady state, but one slow track never stalls +or moves another. A wall-clock reference holds the broadcast's delay, each +track converges on it (audio by time-stretching toward it), and audio no +longer owns the anchor. `moq play` (`rs/moq-cli/src/play/`) moves to it, and +the module's duplicate `Kind` gives way to `container::Kind`. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): +✅ decouple and rename (rejected: rename only, keeping the audio anchor; +keeping it as is). The 2026-11-02 decision behind +[moq-dev/moq#7759](https://github.com/moq-dev/moq/pull/7759) ("while audio +plays, only audio moves the anchor") is superseded by the 2026-11-05 ruling +on [moq-dev/moq#7941](https://github.com/moq-dev/moq/pull/7941) for the JS +player: "I kind of don't want one slow track to impact everything. We want +lip sync in the steady state but desync during the congestion state." + +- ✅ Name: `moq_mux::sync`, matching `@moq/watch`'s `Sync` by role + (rejected: `presentation`, "presentation sucks"; `playhead`; `schedule`). + `container::Playout` keeps its name. +- Port the JS semantics from `js/watch/src/sync.ts` (per-track timelines on + one reference, rework in #7941) rather than inventing a third model. + `Producer::{audio_restarted, audio_stopped}` and `Consumer::target` likely + go. +- `moq play`'s timeline tests move with the module and change where audio + stalls used to hold video; add a case where stalled audio no longer holds + video. +- moq-dev/studio's moq-scene playout consumes this module through a path + dependency and adapts on its next pin; this PR names that migration in its + Impact section. + +Breaking: the module is new on main, but release had an unrelated +`moq_mux::timeline`, so the cut's MIGRATE entry says both are gone. diff --git a/quest/m2/no-sentinels.md b/quest/m2/no-sentinels.md new file mode 100644 index 00000000000..02a256feb6d --- /dev/null +++ b/quest/m2/no-sentinels.md @@ -0,0 +1,29 @@ +# [S] No sentinel values in public API + +## Goal + +No public type uses a huge value or zero as a marker for "none" or +"unbounded"; each uses `Option` (or `NonZero*` where zero is invalid): + +- `moq_net::transport::ReceiveWindow.connection` is documented as + `u64::MAX` "when streams share none"; it becomes `Option`, + matching `transport::Limits.receive_window`. +- `cache_duration` defaults to `Duration::MAX` on `origin::Config` and + `broadcast::Info` in moq-net, and `moq_relay::cache::Cache.duration` does + the same; each becomes `Option`, `None` meaning no ceiling. +- `moq_net::reconnect`'s `Config.timeout`, `Backoff.timeout`, and + `Backoff.max` use zero for unbounded; they become `Option`, as + `Server::with_timeout` already is. The JS mirror (`Connection.Backoff`) + follows, and the Rust (10 s) and JS (unlimited) defaults for the backoff + timeout agree. +- moq-ffi's `moq_ffi_test_clock_now` returns `u64::MAX` when no clock runs; + it reports absence without a sentinel. + +## Plan + +Found by the 2026-11-07 API shape audit (net-model, net-session, apps, +bindings). AGENTS.md: "Never use a huge value like `u64::MAX` as a marker." +Each struct already breaks in this release, so no extra break is taken. +`Range::oldest()`'s `Relative(u64::MAX)` is owned by +[anchor-oldest](https://github.com/moq-dev/moq/pull/8149), not here. Pick +the aligned backoff default in the PR and say why. diff --git a/quest/m2/rendition-stats-type.md b/quest/m2/rendition-stats-type.md index ca0c15418bf..2157accdc23 100644 --- a/quest/m2/rendition-stats-type.md +++ b/quest/m2/rendition-stats-type.md @@ -6,7 +6,9 @@ type (`z.input` of the schema behind `Stats.Rendition`), so publish no longer keeps its own `RenditionStats` shape (`js/publish/src/rendition-internal.ts`) beside the schema it writes. The encoders keep writing plain numbers into it -(`effect.proxy` in `js/publish/src/{video,audio}/encoder.ts`). +(`effect.proxy` in `js/publish/src/{video,audio}/encoder.ts`). The same +applies to `@moq/publish`'s `Video.Stats` and `Audio.Stats`, which also +restate the schema's fields by hand. ## Plan @@ -19,4 +21,7 @@ same input type, since the encoders write it directly, not through `Report.Writer`. Not chosen: dropping the `u53` brand from the stats schemas, which would lose the 53-bit integer check on read. +Added 2026-11-07 (maintainer, /quest-plan from the API shape audit): +`Video.Stats` and `Audio.Stats`, a third and fourth copy of the shape. + It changes a published TypeScript type, so it lands before the cut. diff --git a/quest/m2/route-roles.md b/quest/m2/route-roles.md new file mode 100644 index 00000000000..b856f5b4562 --- /dev/null +++ b/quest/m2/route-roles.md @@ -0,0 +1,43 @@ +# [L] A route's role is its type + +## Goal + +No route method panics, throws, or returns an error because the route was +made by the other constructor. Today one `Route` type serves both exact +routes (`origin.route(path)`) and prefix routes (`route_prefix`): +`Route::broadcast()` panics on a prefix route in Rust +(`rs/moq-net/src/model/origin.rs`, "# Panics"), throws in JS +(`js/net/src/origin.ts`), and returns `MoqError::Internal` in moq-ffi +(`rs/moq-ffi/src/origin.rs`), while `requested()` ends at once on an exact +route. The fix lands in Rust, JS, moq-ffi, the hand-written C ABI, and every +binding wrapper, and `RouteInfo`'s public `Default` (whose `instance()` +panics) goes private. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): +replace [moq-dev/moq#7806](https://github.com/moq-dev/moq/pull/7806)'s +single handle with a shape where the misuse is unrepresentable. ✅ Prototype +two shapes and pick from the prototypes (rejected: an `Option`-returning +`broadcast()`, which keeps a runtime check in every caller; keeping #7806 as +is). "Every route is a prefix on the wire" (maintainer), so: + +- **Single prefix Route**: one `Route` always claims a prefix. + `route.broadcast(suffix)` publishes a broadcast under it, an exact route is + the empty suffix, and `requested()` yields requests for any suffix the + route covers. +- **Split**: `route()` returns `Route` (with `broadcast()`), `route_prefix()` + returns a `Claim` (with `requested()`), and the shared methods (`announce`, + `withdraw`, `set_cost`, `set_auth`, `instance`) are on both. + +Build both in Rust first, port each to the in-repo callers (moq-mux, hang, +moq-cli, moq-relay, moq-archive, moq-ffi, moq-c) and sketch the diff for +downstream callers (`.route(` and `route_prefix` sites), then +put the comparison in the PR under `## Waiting` with a recommendation. After +the maintainer picks, land the winner in JS, moq-ffi, moq-c, and the +wrappers in the same PR. The route instance accessor's five spellings across +bindings stay with [the exporter](/quest/m3/ffi-exporter.md). + +## Required + +- [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - changes how `Request::route` lends a claim's instance, which both shapes must keep diff --git a/quest/m2/time-addressing/model.md b/quest/m2/time-addressing/model.md index a1ecaab2f5a..e8c7495e797 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -128,6 +128,12 @@ recorded only sequencing. stamps the catalog from the broadcast clock and refuses to list a track off that clock's timescale, or a scale-less track beside timed ones. moq-net tracks stay independent. +- **No local clock in the model.** Added 2026-11-07 (maintainer, + /quest-plan from the API shape audit): `Timestamp::now()`, the only model + API that reads the local clock, is removed, and its caller (moq-boy) + stamps from its own clock. `Timed

` moves from moq-net's root to + moq-json, whose producers and readers are its only users, and its `at` + becomes required under the rule above. - **Open, for whoever starts this, with the maintainer:** how lite-05/06, which carry both a sequence and frame timestamps, map on the way out. @@ -174,7 +180,8 @@ The PR's Impact section says how to migrate. Public API: breaking. `group::Info`, `create_group`, `append_group`, `Position`, `Range` ends, `fetch_group`, `Subscriber::floor`, and group consumers address by start timestamp, every producer write takes a required -timestamp, and untimed tracks become scale-less. +timestamp, untimed tracks become scale-less, `Timestamp::now` is gone, and +`Timed` is moq-json's. Wire: no format change; legacy and lite-07-wip group IDs become start ticks. ## Required diff --git a/quest/m2/video-devices.md b/quest/m2/video-devices.md new file mode 100644 index 00000000000..d6cb225691f --- /dev/null +++ b/quest/m2/video-devices.md @@ -0,0 +1,22 @@ +# [S] moq-video takes devices, not environment variables + +## Goal + +moq-video reads no environment. The VA-API render node and the V4L2 encoder +and decoder device paths are Linux-only `Option` fields on +`encode::Config` and `decode::Config`, next to `encode::Config::input`. +`moq_video::ENV` and the reads in `rs/moq-video/src/frame/vaapi.rs` and +`rs/moq-video/src/v4l2.rs` are gone. moq-cli declares `MOQ_VAAPI_DEVICE`, +`MOQ_V4L2_ENCODER`, and `MOQ_V4L2_DECODER` as its own settings and passes +them in, so moq-ffi, studio, and other embedders can pick a device in code. + +## Plan + +Found by the 2026-11-07 API shape audit (native-media, scored 3/10). +[env-knobs](/quest/m4/env-knobs.md) decided on 2026-10-25 that "a library +reads no environment", but it lands after the cut while `ENV` is new public +surface since release. This quest takes moq-video's half before the cut so +`ENV` never ships; env-knobs keeps the test and bench knobs. Tests stop +mutating process environment (`frame/vaapi.rs`). Decide in the PR whether +moq-ffi and moq-c expose the device fields now or when a binding consumer +asks; the audit found none. diff --git a/quest/m3/quic-sansio-driver.md b/quest/m3/quic-sansio-driver.md index 617c5dc1ba6..58102c8bec0 100644 --- a/quest/m3/quic-sansio-driver.md +++ b/quest/m3/quic-sansio-driver.md @@ -40,7 +40,12 @@ Open, for whoever starts it: - How it builds its TLS configs (identity, roots, fingerprint pinning) without moq-tokio's `tls` module. -Mirror the two drivers' names and signatures where they overlap. Test it against +Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit): +this driver is the one shared core, not a third copy. moq-tokio's +`quic::driver` and moq-uring's `quic` become I/O loops around it, so the +endpoint, connection table, and timer logic exist once. Not chosen: a third +driver that mirrors the other two. Mirror the two drivers' names and +signatures where they still differ. Test it against moq-tokio's server over loopback on simulated time. Bound a hostile peer's cost as the other drivers do. diff --git a/quest/m3/release/README.md b/quest/m3/release/README.md index 6c97681a750..0accc575b42 100644 --- a/quest/m3/release/README.md +++ b/quest/m3/release/README.md @@ -41,6 +41,7 @@ production stability proven merely because upstream artifacts published. - [Retire libmoq](/quest/m3/release/libmoq-retire.md) - cleanup only after that publication - [Retire hand-written C](/quest/m3/release/c-retire.md) - delete the hand-written crate once generated C publishes - [Retire the web-transport JS qmux](/quest/m3/release/qmux-js-retire.md) - once `@moq/qmux` publishes from `js/qmux`, deprecate `@moq/web-socket-stream` and stop the second publisher +- [Retire the web-transport Rust qmux](/quest/m3/release/qmux-rs-retire.md) - once `qmux` publishes from `rs/qmux`, moq-dev/web-transport stops publishing the crate - [moq.sh deployment](/quest/m3/release/moq-sh-deploy.md) - verify its release-triggered publication - [Runner client bump](/quest/m3/release/runner-client-bump.md) - the upstream interop runner's Rust client moves to the published moq-tokio, so it stops stamping every object - [Smoke clients use request and follow](/quest/m3/release/smoke-bindings-rename.md) - condition: a binding release ships the renames; then the native smoke clients move to them diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 6ab00ec24d2..9104e5c0d67 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -28,6 +28,22 @@ each approved change as a quest in m2, which holds the cut until it lands. Model items only the built-in sessions use stay private ([moq-dev/moq#6747](https://github.com/moq-dev/moq/pull/6747)); this review judges the shape of what ships. +This run's first pass, ahead of m2 (2026-11-07, maintainer, /quest-plan): +an audit of `release` (a005c7ad9a) against `main` (a9d7925123) plus the open +quests. `just api-diff` gave the mechanical inventory; nine read-only +reviewers (net model, net session, transport, media formats, native media, +apps, JS core, browser media, bindings) scored 127 clusters out of 10 for +performance, usability, testability, and future fit, and searched for +consumers in this repository and its downstream applications. Mean 6.9; three +clusters were restrictive (the native playout clock, JS duration units, and +moq-video's environment knobs). Its approved changes are m2 quests +(route-roles, js-time-types, mux-sync, no-sentinels, video-devices, +gateway-ingest, and the [api-shape epic](/quest/m2/api-shape/README.md)), +two m1 quests, and plan edits. Check first, next run: surfaces `just +api-diff` cannot see (GStreamer properties, CLI flags and env, MIGRATE drift) +and publish versions of packages exempt from the cut's version. +This review still runs after m2 lands, over what changed since. + ## Required - [Breaking release readiness](/quest/m2/README.md) - the release's code is final before it is reviewed diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 45f6d150f14..09c2a6f0dcd 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -12,7 +12,14 @@ then main into release using merge commits. Confirm the maintainer's cut instruction before executing it. Right after merging release into main, set every eligible package with `just version 0.22.0` for this cut, then one minor up per cut, following [Versions](/CONTRIBUTING.md#versions), including -packages that did not change. Rust +packages that did not change. `@moq/qmux` and the Rust `qmux` crate are +exempt from that version (`version.json`), so check each against its +registry by hand: npm already has `@moq/qmux` 0.3.3 and 0.3.4, published +from moq-dev/web-transport, while `js/qmux` is at 0.3.3. Publishing 0.3.3 +fails, and `workspace:^` would resolve `@moq/net`'s dependency to +web-transport's 0.3.4, a different API. `js/qmux` must publish above 0.3.4; +the maintainer picks the version (found 2026-11-07 by the API shape audit). +Rust publication remains owned by release-plz. This supersedes keeping `moq-rs` at its unpublished 0.6.0 (decided 2026-11-01). Run candidate compatibility, draft, package, and all-language interop checks, and verify diff --git a/quest/m3/release/migrate-audit.md b/quest/m3/release/migrate-audit.md index 65eebaf2d2d..45a62e30e0e 100644 --- a/quest/m3/release/migrate-audit.md +++ b/quest/m3/release/migrate-audit.md @@ -69,6 +69,26 @@ m1 quest on 2026-10-22. Write it into `rs/moq-relay/MIGRATE.md`'s transition section (its `## Unreleased` section until the cut names the version). +- Known drift (added 2026-11-07, from the API shape audit), to fix in the + guide each names: + - moq-webrtc: `rs/moq-webrtc/MIGRATE.md` is still titled "Migrating + moq-rtc" and documents `wire::Source`, which + [moq-dev/moq#6454](https://github.com/moq-dev/moq/pull/6454) removed. + - moq-boy: `rs/moq-boy/MIGRATE.md` documents `.socket/{name}` and + `.socket/viewer-*` paths and grants; the code serves `.server/{name}` + and `.client/{id}`. + - moq-cli: `rtmp` is listed under `--max-delay` but its flag is `--delay`; + the `--connect-once` removal and the `MOQ_LISTEN_TLS_*` to + `MOQ_HLS_TLS_*` rename are missing; the `export archive` entry reads as a + break of something release never had. + - moq-relay: the line saying no transport enforces bitrate caps is stale + (QUIC enforces them through the pacer); the two `receive_window` floor + entries (64 MiB, then 1 MiB) collapse into the net change; and the + removed `moq_relay_stale_datagrams_total` metric has no note. + - moq-gst: the request pad's `encoder` property, shipped in + `moq-gst-v0.4.24`, was removed with no entry, so a `gst-launch` line + setting it now fails at runtime. + ## Required - [Breaking release readiness](/quest/m2/README.md) - all breaking work and the MIGRATE.md convention have landed diff --git a/quest/m3/release/qmux-rs-retire.md b/quest/m3/release/qmux-rs-retire.md new file mode 100644 index 00000000000..023603d24ea --- /dev/null +++ b/quest/m3/release/qmux-rs-retire.md @@ -0,0 +1,19 @@ +# [XS] Retire the web-transport Rust qmux + +## Goal + +After the first `qmux` crate built from `rs/qmux` in this repository is on +crates.io, moq-dev/web-transport no longer publishes `qmux`: its `rs/qmux` +is frozen or removed, its release-plz config drops the crate, and its README +points at moq-dev/moq, so one repository owns the crate name. + +Check with `cargo info qmux` (its repository names moq-dev/moq) and the +web-transport release-plz config. + +## Plan + +Found by the 2026-11-07 API shape audit (transport); mirrors +[qmux-js-retire](/quest/m3/release/qmux-js-retire.md) for the Rust crate. +web-transport still carries `qmux` 0.6.6 and live quests that change it; +move or close them there. Waiting on the crate's publication and a +maintainer with rights in moq-dev/web-transport. diff --git a/quest/m3/rtc-pacing.md b/quest/m3/rtc-pacing.md index 92206ab8cda..900f61428bf 100644 --- a/quest/m3/rtc-pacing.md +++ b/quest/m3/rtc-pacing.md @@ -58,8 +58,11 @@ WHEP enforcement needs it and nobody owned it. Public API: a rate handle on moq-webrtc's WHEP server. Decided 2026-10-30 (maintainer): `whep::accept` takes the same shape as `whip::accept`, a -`whep::Request` struct with `Request::with_rate(rate::Limit)`, replacing -its argument list rather than adding a fifth argument. Wire: none. +`whep::Request` struct with `Request::with_rate(bandwidth::Limit)`, +replacing its argument list rather than adding a fifth argument. The handle +is `moq_net::bandwidth::Limit`, which replaces moq-webrtc's +`rate::{Cap, Limit}` in [gateway-ingest](/quest/m2/gateway-ingest.md) +(2026-11-07, maintainer, /quest-plan from the API shape audit). Wire: none. ## Required diff --git a/quest/m3/srt-rate-handle.md b/quest/m3/srt-rate-handle.md index b359a861551..c28d78420d5 100644 --- a/quest/m3/srt-rate-handle.md +++ b/quest/m3/srt-rate-handle.md @@ -52,7 +52,10 @@ enforcement needs it and nobody owned it. included, stays under the cap is untouched; under the cap nothing changes. Public API: a rate handle and a rate-limit close reason on moq-srt's server. -Wire: none. +The handle is `moq_net::bandwidth::Limit`, shared with WHIP, WHEP, and the +relay's grant caps since [gateway-ingest](/quest/m2/gateway-ingest.md) +(2026-11-07, maintainer, /quest-plan from the API shape audit), not a +moq-srt copy. Wire: none. ## Required diff --git a/quest/m4/README.md b/quest/m4/README.md index 217bbd487ae..35d8c12062c 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -66,6 +66,8 @@ deleted. - [Drop kio's epoch fence](/quest/m4/crossbeam-pin-fence.md) - waiting on crossbeam#1352, then the `Read::drop` fence goes - [A cancelled miss stops waiting](/quest/m4/fill-wait-cancel-test.md) - a test proves a relay miss waiting on its own fill ends when no reader wants it - [No MOQ_* knobs outside the binaries](/quest/m4/env-knobs.md) - test, bench, and library knobs leave the `MOQ_*` prefix +- [The API diff reports GStreamer element properties](/quest/m4/api-diff-gst.md) - `just api-diff` lists added, removed, and changed moq-gst properties +- [Hand-written wrappers reach every FFI item](/quest/m4/binding-export-coverage.md) - Python, Go, and Swift fail a test when an FFI item has no wrapper path, as Kotlin does - [The HLS server follows each path once](/quest/m4/hls-follow-once.md) - `Following` reports synced absence, so moq-hls resolves with one follow - [moq-bench pins the instances it measures](/quest/m4/bench-epoch-pin.md) - pooled requests pin their announced epoch, so a takeover is not counted as the same broadcast - [moq-bench reports sub-millisecond latency](/quest/m4/bench-latency-resolution.md) - steady-window latency resolves finer than 1 ms diff --git a/quest/m4/api-diff-gst.md b/quest/m4/api-diff-gst.md new file mode 100644 index 00000000000..4a7b1a51f13 --- /dev/null +++ b/quest/m4/api-diff-gst.md @@ -0,0 +1,18 @@ +# [S] The API diff reports GStreamer element properties + +## Goal + +`just api-diff` lists added, removed, and changed properties of `moqsink`, +`moqsrc`, and their pads (name, type, flags, default) between two refs, so +a removed property shows up in the cut's API review. Today +`cargo-semver-checks` sees only Rust items and reports moq-gst unchanged, +which is how the `encoder` pad property left with no MIGRATE entry. + +## Plan + +Found by the 2026-11-07 API shape audit (bindings). Dump the properties for +each ref with `gst-inspect-1.0` on a built plugin (or a small Rust test that +walks the elements' `ParamSpec`s, which avoids a GStreamer install +difference between refs) and diff the dumps in `sh/api-diff/`. The missing +`encoder` MIGRATE entry itself is in +[migrate-audit](/quest/m3/release/migrate-audit.md). diff --git a/quest/m4/binding-export-coverage.md b/quest/m4/binding-export-coverage.md new file mode 100644 index 00000000000..2246a155127 --- /dev/null +++ b/quest/m4/binding-export-coverage.md @@ -0,0 +1,17 @@ +# [S] Hand-written wrappers reach every FFI item + +## Goal + +The Python, Go, and Swift wrappers each fail a test when a moq-ffi record, +enum, or handle has no wrapper path, as Kotlin's smoke test already does +(`SmokeTest.kt`). Today these three hand-wrap 3,000 to 5,000 lines each, +and parity depends on review. + +## Plan + +Found by the 2026-11-07 API shape audit (bindings). Generate the list of +FFI items from UniFFI's metadata once, and have each wrapper's test check +it against the wrapper's public types, with an explicit allowlist for items +a wrapper deliberately hides. Kotlin keeps its own check or moves to the +shared list. When [the exporter](/quest/m3/ffi-exporter.md) replaces UniFFI, +the list comes from it. diff --git a/quest/m4/env-knobs.md b/quest/m4/env-knobs.md index f98bb0c918b..9d56a97722b 100644 --- a/quest/m4/env-knobs.md +++ b/quest/m4/env-knobs.md @@ -11,7 +11,9 @@ from [moq-dev/moq#6633](https://github.com/moq-dev/moq/pull/6633). - Rename test and bench knobs out of `MOQ_*` (for example `MOQ_SHAPER_SEED`, `MOQ_QUIC_SEED`, `MOQ_JSON_SEED`, `MOQ_AUDIO_DEVICE`, `MOQ_BENCH_*`, `MOQ_X11_BENCH_LOG`), updating CI and docs that set them. -- moq-video reads `MOQ_VAAPI_DEVICE` and `MOQ_V4L2_*` from the environment as - a library. Decided 2026-10-25 (recommendation, maintainer delegated): a - library reads no environment; the binaries that link moq-video declare these - as settings and pass them in. +- Decided 2026-10-25 (recommendation, maintainer delegated): a library reads + no environment; the binaries that link it declare their settings and pass + them in. moq-video's half (`MOQ_VAAPI_DEVICE`, `MOQ_V4L2_*`, and the public + `moq_video::ENV`) moved to [video-devices](/quest/m2/video-devices.md) on + 2026-11-07 (maintainer, /quest-plan from the API shape audit), because + `ENV` is new public API the cut would otherwise ship. From 9be112e59d4f5c084e4dbdafe19e3dbe0b0f0503 Mon Sep 17 00:00:00 2001 From: quest fixer Date: Sat, 7 Nov 2026 14:46:44 -0800 Subject: [PATCH 02/11] fix(quest): keep route session audit additions in Plan --- quest/m2/cluster-routing/routes/session.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/quest/m2/cluster-routing/routes/session.md b/quest/m2/cluster-routing/routes/session.md index 86f5d51e220..905d2b61296 100644 --- a/quest/m2/cluster-routing/routes/session.md +++ b/quest/m2/cluster-routing/routes/session.md @@ -32,15 +32,6 @@ node table, and the public API drops what the route layer replaced. Remove them, or hide them behind those wires, when the rollout window closes (see Waiting). -## Waiting - -- Maintainer: decide when `Hops`, `RouteInfo::hops`, and the saturating - `Cost` leave the public API. Every older wire still fills them, so an agent - cannot drop them without picking the rollout's end. Options: **when lite-06 - retires (recommended)**, since removing them now only moves them behind a - private type; or **now**, keeping a private chain type for the older wires. - Done when the Plan item above names the point. - Added 2026-11-07 (maintainer, /quest-plan from the API shape audit), for the PR that lands this ([moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)): @@ -51,6 +42,15 @@ the PR that lands this ([moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8 the [epic](/quest/m2/cluster-routing/README.md)), so sessions stop stamping `Cost::DRAIN` on GOAWAY, including on moq-transport. +## Waiting + +- Maintainer: decide when `Hops`, `RouteInfo::hops`, and the saturating + `Cost` leave the public API. Every older wire still fills them, so an agent + cannot drop them without picking the rollout's end. Options: **when lite-06 + retires (recommended)**, since removing them now only moves them behind a + private type; or **now**, keeping a private chain type for the older wires. + Done when the Plan item above names the point. + ## Related - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the contract From 82e6784c31ab1f88af19c6f61ca1cdd6263aeb57 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:06:14 -0800 Subject: [PATCH 03/11] quest: plan the API fixes from a sweep of open PRs and remaining quests A sweep of the 29 open PRs and the m0-m5 quests scored 91 clusters of planned API. This fences the surfaces later quests grow, settles the shapes they would otherwise break after the cut, and fixes plans that contradict #8063, #8088, and #8191: - m2: public spawning constructors, moq-audio's codec seam, consuming finish, the bus signatures, moq-auth's iroh variant, and the warmup contract; hop chains leave the public API; anchors collapse to {Oldest, Relative, Time} with inclusive ends. - api-shape children gain the non_exhaustive fences, the RouteEvent struct, stats arguments, exporter delays, mp4-atom and tungstenite decoupling, a worker-safe renderer output, and the capture handle. - Deleted: mount-takeover, socket-old-hop-signal, uring-controller, and anchor-oldest (absorbed); broadcast-fairness parks in m5; teleop drops the moq-robot crate. Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/finish-final.md | 5 +- quest/m2/README.md | 15 ++- quest/m2/anchor-oldest.md | 13 --- quest/m2/api-shape/README.md | 14 ++- quest/m2/api-shape/apps.md | 6 ++ quest/m2/api-shape/bindings.md | 10 ++ quest/m2/api-shape/js.md | 11 ++- quest/m2/api-shape/media.md | 19 +++- quest/m2/api-shape/native.md | 8 +- quest/m2/api-shape/net.md | 23 ++++- quest/m2/api-shape/transport.md | 23 ++++- quest/m2/audio-codec-seam.md | 23 +++++ quest/{m4 => m2}/auth-drop-iroh.md | 2 + quest/{m3 => m2}/bus-minus-several.md | 2 +- quest/{m3 => m2}/bus-positioned-write.md | 2 +- quest/m2/cluster-routing/routes/README.md | 1 - .../cluster-routing/routes/mount-takeover.md | 21 ---- quest/m2/cluster-routing/routes/session.md | 40 ++++---- quest/m2/finish-self.md | 21 ++++ quest/m2/gateway-ingest.md | 6 ++ quest/m2/group-drops.md | 13 +++ .../intra-refresh-boundary.md} | 2 + quest/m2/js-time-types.md | 4 + quest/m2/lite07-finalize.md | 6 ++ quest/m2/no-sentinels.md | 6 +- quest/m2/sequence-reuse.md | 10 ++ quest/m2/spawn-constructors.md | 25 +++++ quest/m2/time-addressing/model.md | 19 +++- quest/m3/README.md | 3 - quest/m3/audit-dead-code.md | 2 + quest/m3/bandwidth-multi-connection.md | 2 + quest/m3/cli-packaging.md | 2 + quest/m3/drm/mp4-atom.md | 2 + quest/m3/export-live-start.md | 2 + quest/m3/fetch-synced.md | 2 + quest/m3/h265-min-width.md | 2 + quest/m3/import-metadata-policy.md | 2 + quest/m3/intra-refresh/README.md | 2 +- quest/m3/intra-refresh/consumer-warmup.md | 2 +- quest/m3/intra-refresh/h264-import.md | 2 +- quest/m3/json-snapshot-resync.md | 2 + quest/m3/mesh/README.md | 2 +- quest/m3/mesh/cert-credentials.md | 8 ++ quest/m3/mesh/endpoint.md | 2 + quest/m3/mux-source-cut.md | 2 + quest/m3/obs-moq-video/adapter.md | 2 + quest/m3/probe-rung-disable-js.md | 2 + quest/m3/qos/lag-histogram.md | 2 + quest/m3/quic-ack-hook.md | 2 + quest/m3/quic-realtime/README.md | 1 - quest/m3/quic-realtime/moqsink-feedback.md | 2 + quest/m3/quic-realtime/uring-controller.md | 18 ---- quest/m3/relay-test-stats.md | 2 + quest/m3/relay-undialable-peers.md | 2 +- quest/m3/rtc-pacing.md | 2 + quest/m3/session-outcome-records.md | 2 + quest/m3/spawn-audit.md | 2 + quest/m3/stats/rust.md | 2 + quest/m3/stream/rust.md | 2 + quest/m3/video-publish-grant.md | 2 + quest/m3/watch-worker.md | 2 + quest/m4/README.md | 1 - quest/m4/aac-sbr-config.md | 2 + quest/m4/cache-fairness.md | 4 +- quest/m4/p2p/cli.md | 2 + quest/m4/p2p/signal.md | 2 + quest/m4/peer-grant-bound.md | 2 +- quest/m4/perf/shard-default.md | 2 + quest/m4/perf/stream/codec.md | 2 + quest/m5/README.md | 4 +- quest/m5/audio-decode-mediacodec.md | 2 + quest/m5/audio-decode-mediafoundation.md | 2 + quest/m5/audio-encode-audiotoolbox.md | 2 + quest/m5/audio-encode-mediacodec.md | 2 + quest/m5/audio-encode-mediafoundation.md | 2 + quest/m5/auth-http-request-kind.md | 2 + quest/{m3 => m5}/broadcast-fairness.md | 2 +- quest/m5/emsg.md | 2 + quest/m5/ffi-e2ee.md | 2 + quest/m5/json-value-diff.md | 2 + quest/m5/latency-ledger.md | 2 + quest/m5/net-wrap/traits.md | 2 + quest/m5/rate-grant.md | 2 + quest/m5/receive-pool.md | 2 +- quest/m5/socket-old-hop-signal.md | 97 ------------------- quest/m5/stats-encoder-feedback.md | 2 + quest/m5/teleop-arbitration.md | 2 +- quest/m5/teleop-mavlink.md | 2 +- quest/m5/teleop-proof.md | 4 +- quest/m5/teleop-robot.md | 18 +++- 90 files changed, 396 insertions(+), 216 deletions(-) delete mode 100644 quest/m2/anchor-oldest.md create mode 100644 quest/m2/audio-codec-seam.md rename quest/{m4 => m2}/auth-drop-iroh.md (83%) rename quest/{m3 => m2}/bus-minus-several.md (66%) rename quest/{m3 => m2}/bus-positioned-write.md (77%) delete mode 100644 quest/m2/cluster-routing/routes/mount-takeover.md create mode 100644 quest/m2/finish-self.md rename quest/{m3/intra-refresh/plan-boundary.md => m2/intra-refresh-boundary.md} (88%) create mode 100644 quest/m2/spawn-constructors.md delete mode 100644 quest/m3/quic-realtime/uring-controller.md rename quest/{m3 => m5}/broadcast-fairness.md (96%) delete mode 100644 quest/m5/socket-old-hop-signal.md diff --git a/quest/m1/explicit-state/finish-final.md b/quest/m1/explicit-state/finish-final.md index 46daf52f24d..669c1c68b87 100644 --- a/quest/m1/explicit-state/finish-final.md +++ b/quest/m1/explicit-state/finish-final.md @@ -47,5 +47,6 @@ Instances to sweep: encoder. The importer and producer `finish` signatures are public API. A move to -`finish(self)` is breaking, so if this child takes it, it leaves the epic and -becomes its own m2 quest under the epic's rule. +`finish(self)` is breaking, so it is its own m2 quest, +[finish-self](/quest/m2/finish-self.md) (decided 2026-11-07, maintainer, +/quest-plan from the API sweep). This child keeps the internal state. diff --git a/quest/m2/README.md b/quest/m2/README.md index ab4cbc6096b..df394f09c70 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -170,6 +170,13 @@ and instants become objects; native playout sync decouples its tracks like the browser's; sentinels, moq-video's environment reads, and per-gateway ingest setters go; and an epic batches the small fixes per area. +Added 2026-11-07 (maintainer, /quest-plan from an API sweep of the open PRs +and the remaining quests): the shapes later quests would otherwise break +after the cut. Public spawning constructors, moq-audio's codec seam, +consuming `finish`, the new `bus` signatures, the moq-auth iroh variant, and +the `warmup` contract settle here; growing structs are fenced with +`#[non_exhaustive]` through the api-shape epic. + Decided 2026-11-05 (maintainer, /quest-audit): blockers rank above the quests that require them. @@ -198,9 +205,15 @@ quests that require them. - [Native playout sync keeps tracks decoupled](/quest/m2/mux-sync.md) - `moq_mux::timeline` becomes `moq_mux::sync`, and one slow track no longer stalls or moves another - [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile - [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings +- [Public constructors spawn nothing, or say why](/quest/m2/spawn-constructors.md) - each public library entry point that spawns returns a driver its caller polls, or is listed as kept +- [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - `encode` and `decode` return any number of outputs and gain `flush`, as moq-video's do +- [Finishing consumes the producer](/quest/m2/finish-self.md) - importers and producers take `finish(self)`, so a finished producer cannot be written +- [Bus writes land at a bus position](/quest/m2/bus-positioned-write.md) - callers sync audio to video without copying the bus's private latency, before the cut first publishes `bus` +- [A mix-minus removes several sources](/quest/m2/bus-minus-several.md) - a guest's return feed drops every copy of their own sound +- [Drop moq-auth's iroh transport](/quest/m2/auth-drop-iroh.md) - this breaking moq-auth release drops `Transport::Iroh` and the JS `"iroh"` value +- [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - the catalog's new `warmup` contract is settled before the cut publishes it - [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto (held in m1 by an open claim) - [A recreated or restarted track cannot reuse group sequences](/quest/m2/sequence-reuse.md) - recreating a track or restarting an instance cannot give new content an old group identity unless the app seeds past it, and datagrams are documented as exempt -- [Subscriptions name the oldest group without a u64::MAX sentinel](/quest/m2/anchor-oldest.md) - `Anchor` gets an explicit oldest variant, decoded the same way on every wire - [moq auth serve bounds what a leaked token or public caller can do](/quest/m2/auth-serve-policy.md) - tokens need an `exp` unless the operator opts out, and a public listener authenticates relays - [Cut readiness](/quest/m2/cut-gate/README.md) - the checks the cut needs that break nothing: main no slower than release, vendored fixes ported, and moq-c at parity - [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; browser padding is parked in m3 (held in m2 by open claims; moves to m3) diff --git a/quest/m2/anchor-oldest.md b/quest/m2/anchor-oldest.md deleted file mode 100644 index f479a911d38..00000000000 --- a/quest/m2/anchor-oldest.md +++ /dev/null @@ -1,13 +0,0 @@ -# [S] Subscriptions name the oldest group without a u64::MAX sentinel - -## Goal - -`Anchor` has an explicit variant for "the oldest group", and `Relative(n)` always means n groups before the latest. Today `Range::oldest` is `Anchor::Relative(u64::MAX)` (`rs/moq-net/src/model/subscription.rs`), against the repository's rule never to use a huge value as a marker. A peer on lite-07 or IETF can send `u64::MAX` or `u64::MAX - 1`, which clamp to the same group but differ in window start, demand shape and `is_wire`, and the lite encoder treats any `back > MAX_QUIC` as oldest, which the model does not. - -## Plan - -Found by the 2026-11-07 invariant audit (model-4). Add the variant, decode and encode it consistently on every wire (lite-07, lite-06 and earlier, IETF), and mirror it in JS and the bindings. m2 because `Anchor` is public API. - -## Related - -- [Subscribe ranges](/quest/m2/subscribe-ranges/README.md) - owns the range model this anchor lives in diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index 1936e5df2c4..8ecf8f03755 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -25,10 +25,20 @@ the previous API audit's final pass, was open, and none of its children repeats an item #8088 changes. A child that starts after #8088 merges rechecks each item against `main` and drops what is already done. +Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): fences for +what later quests grow (`#[non_exhaustive]` on structs and enums m3 to m5 +add to), shapes those quests would otherwise break, and this epic's own +work: before the cut, run a "public item used only by its definition" +search over the published crates and remove each hit, starting with +`moq_tokio::Server::serve_both`, `hang::Catalog::to_json_pretty`, and +`moq_audio::Format::{is_planar, is_float}`, the shortlist of +[the dead code audit](/quest/m3/audit-dead-code.md). The audit itself stays +in m3 for private code. + Rules every child follows: -- Removal beats addition. A public item with no caller in this repository, - a known downstream application goes private, unless an m1 or m2 quest plans a +- Removal beats addition. A public item with no caller in this repository + or a known downstream application goes private, unless an m1 or m2 quest plans a caller. - No serde aliases, refusals, or shims for a spelling `release` never shipped. diff --git a/quest/m2/api-shape/apps.md b/quest/m2/api-shape/apps.md index 81600d3356e..64ffd89b20a 100644 --- a/quest/m2/api-shape/apps.md +++ b/quest/m2/api-shape/apps.md @@ -25,6 +25,12 @@ environment, with named refusals for the old flags, which shipped. - moq-boy's Rust crate stops exporting its internals (the JS half is in [the JS child](/quest/m2/api-shape/js.md)). +- moq-relay's `cluster::Options.network`, a `moq_tokio::sim::Network` test + hook added by [moq-dev/moq#8139](https://github.com/moq-dev/moq/pull/8139), + is `#[doc(hidden)]` test support, so the published config names no + simulator type. If an embedder needs injected dials, the shape is a + take-once `Cluster::dials()` handle, not a config field (added + 2026-11-07, maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests). ## Plan diff --git a/quest/m2/api-shape/bindings.md b/quest/m2/api-shape/bindings.md index f192962f155..00a5cdb3040 100644 --- a/quest/m2/api-shape/bindings.md +++ b/quest/m2/api-shape/bindings.md @@ -13,9 +13,19 @@ a free constructor that the caller must then register. - Python: `moq.testing` leaves the published wheel; tests import it from the source tree. +- moq-ffi's `MoqVideoSurface` gets `#[non_exhaustive]`: it has one variant, + and Android HardwareBuffer, D3D11, and DMA-BUF surfaces are planned in m3. + Check any other output-only UniFFI enum an m3 quest plans to grow. +- Go's `*DecoderOutput` aliases go (from + [the OBS adapter](/quest/m3/obs-moq-video/adapter.md)). +- Dart's wrapper names the route instance accessor `instance()`, as the + other bindings do, so [the exporter](/quest/m3/ffi-exporter.md) changes no + Dart call site. ## Plan +Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the video surface fence, the Go aliases, and Dart's `instance()`. + Found by the 2026-11-07 API shape audit (bindings); see the [epic](/quest/m2/api-shape/README.md). The generated check that each hand-written wrapper exports every FFI item is diff --git a/quest/m2/api-shape/js.md b/quest/m2/api-shape/js.md index a6b4a3f68de..b4f94747d5f 100644 --- a/quest/m2/api-shape/js.md +++ b/quest/m2/api-shape/js.md @@ -12,8 +12,13 @@ `with_instance(instance, epoch)`. - `@moq/qmux` exports `Session` by name instead of an anonymous default. - `@moq/watch`: the decoder and source plumbing outputs are `@internal`, the - renderer's output is a named `Video.RendererOutput`, and ``'s - `player` property goes private, so each component has one path. + renderer's output is a named `Video.RendererOutput` with no `frame` (a + `VideoFrame` signal cannot cross a worker, so + [the watch worker](/quest/m3/watch-worker.md) would break it; the paused + poster reads an internal painted flag), and ``'s `player` + property goes private, so each component has one path. +- `@moq/room` exposes timestamps and stats instead of `Video.Renderer` and + `Video.Decoder`, so the worker's break lands in one package. - `@moq/publish`: `Rendition.onDemand` becomes an enum, `Broadcast.join` becomes a `Getter`, and the five internal source helpers are unexported. - `@moq/ui` and `@moq/video` mark their helpers `@internal`; only `Support`, @@ -27,6 +32,8 @@ ## Plan +Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the worker-safe renderer output and room's narrower surface. + Found by the 2026-11-07 API shape audit (JS core and browser media); see the [epic](/quest/m2/api-shape/README.md). Durations are [js-time-types](/quest/m2/js-time-types.md); hosted assets and the diff --git a/quest/m2/api-shape/media.md b/quest/m2/api-shape/media.md index eb4080ab6b7..e78e1a7dc6f 100644 --- a/quest/m2/api-shape/media.md +++ b/quest/m2/api-shape/media.md @@ -6,8 +6,21 @@ Each item below has one path and one name: - moq-mux exporters (fmp4, mkv, flv, mp4): the fmp4 and catalog internals no caller uses become private, flv returns a typed error instead of a - string, and every exporter names its wait the same way (the name moq-mux's - TS exporter uses since [moq-dev/moq#7981](https://github.com/moq-dev/moq/pull/7981)). + string, and fMP4, MP4, MKV, and FLV take a `moq_net::Delay { min, max }` + (`min` the start behind the live edge, `max` today's skip budget), the + pair [export-live-start](/quest/m3/export-live-start.md) needs, instead of + one `Duration` under three spellings. TS keeps its jitter `delay`, a + different role ([moq-dev/moq#7981](https://github.com/moq-dev/moq/pull/7981)). +- moq-mux stops re-exporting `mp4_atom` (`container::fmp4`), and + `fmp4::Wire::{new, trak}` become `pub(crate)` or give way to the one + accessor moq-hls needs, so an mp4-atom bump (two are planned in m3) is not + a moq-mux break. +- hang's echo drops `latency` in Rust, JS, and the draft: nothing produces + it, and [latency-ledger](/quest/m5/latency-ledger.md) adds its measurement + additively. +- `moq_json::{diff, Diff}` become `pub(crate)`. +- `moq_mux::codec::aac::Config` gets `#[non_exhaustive]`, since + [aac-sbr-config](/quest/m4/aac-sbr-config.md) adds a field. - The container `Consumer` has one constructor, through `container::Playout`; `with_delay` goes. - hang's `catalog::Range` becomes `ColorRange`, and the MoQ epoch constant @@ -20,6 +33,8 @@ Each item below has one path and one name: ## Plan +Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): exporter delays, mp4-atom, echo latency, the JSON diff, and the AAC config. + Found by the 2026-11-07 API shape audit (media formats); see the [epic](/quest/m2/api-shape/README.md). The playout clock is [mux-sync](/quest/m2/mux-sync.md), and rendition stats are diff --git a/quest/m2/api-shape/native.md b/quest/m2/api-shape/native.md index 991ab6b31ed..dadb658788b 100644 --- a/quest/m2/api-shape/native.md +++ b/quest/m2/api-shape/native.md @@ -2,8 +2,12 @@ ## Goal -- moq-audio's `encode::{Control, State, Status}` become private, and - `publish_capture` stays the public path. +- `publish_capture` returns a handle plus a driver in both moq-audio and + moq-video, mirroring each other, and moq-audio's `encode::{Control, State, + Status}` stop being separate public names. The handle may start with only + the state accessors audio has today, so + [video-publish-grant](/quest/m3/video-publish-grant.md) adds `grant()` + without a break (added 2026-11-07, maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests). - `on_demand` means one thing across crates. moq-video's closes the camera between viewers and defaults to `false`; moq-audio's keeps the device open, defers encoding, and replays retained PCM, and defaults to `true`. Audio's diff --git a/quest/m2/api-shape/net.md b/quest/m2/api-shape/net.md index f8f19cc3011..001a1c091ff 100644 --- a/quest/m2/api-shape/net.md +++ b/quest/m2/api-shape/net.md @@ -40,7 +40,22 @@ its JS and binding mirrors: `RouteEvent::Takeover`, un-hide `origin::Consumer::routes`, `Routes`, and `RouteEvent`, documented as the relay-level stream that moq-relay and downstream relays already consume, and fix `request`'s doc to say what #8063 made it - do. + do. `RouteEvent` becomes `struct RouteEvent { kind: RouteKind, announce: + Announce }` with `enum RouteKind { Start, Update, Restart, End }`, + mirroring JS's `{ kind } & Routed`, so callers need no or-pattern and no + accessors. +- `stats::Registry::report` takes an explicit `now`, and + `stats::Handle::{refuse, session}` take `#[non_exhaustive]` argument + structs with a `new(label, ..)` constructor (named by role, not clashing + with `server::Admission`), so [lag-histogram](/quest/m3/qos/lag-histogram.md) + and [session-outcome-records](/quest/m3/session-outcome-records.md) add + fields instead of breaking moq-net again. +- `group::MAX_CACHE_BYTES` becomes `pub(crate)`: byte-holes turns it from a + size cap into a tail budget, and moq-json's `max_group_bytes` keeps its own + 32 MiB default. +- `auth::Grant` gets `#[non_exhaustive]`, since + [rate-grant](/quest/m5/rate-grant.md) adds rates to it; callers outside + moq-net build it from `Grant::default()`. ## Plan @@ -49,3 +64,9 @@ the [epic](/quest/m2/api-shape/README.md). Each item is XS except `Attempt::client` and `Compression` (S each). `RefusalKind` is a stats-wire field, so say in the PR which deployed dashboards read it. If #8063 has not merged when this starts, leave the un-hide for a follow-up and say so. + +Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the `RouteEvent` +struct, the stats arguments, the cache cap, and `Grant`. The `RouteEvent` +reshape replaces [moq-dev/moq#7862](https://github.com/moq-dev/moq/pull/7862)'s +accessors; if its author takes the reshape in that PR, it lands there for +credit and this item only un-hides. diff --git a/quest/m2/api-shape/transport.md b/quest/m2/api-shape/transport.md index d7372270b15..14d26b26390 100644 --- a/quest/m2/api-shape/transport.md +++ b/quest/m2/api-shape/transport.md @@ -6,13 +6,32 @@ configs take a `moq_congestion` factory (BBR3 by default, matching moq-tokio; today `moq_uring::quic::Congestion` defaults to `Loss`) and an `Arc` or `Arc`, as moq-tokio's - do. `moq_uring::quic::Congestion`, `Identity`, `ClientAuth`, and the client - TLS fields are gone. + do. `Identity`, `ClientAuth`, and the client TLS fields are gone. + `moq_uring::quic::Congestion` stays as a convenience that converts into a + factory, so the built-in families keep their names while the config holds + only a factory. The relay's io_uring runtime installs the controller a + `moq_tokio::quic::Config::controller` carries instead of refusing it + (`rs/moq-tokio/src/quic.rs`), so an embedder gets the same controller on + either runtime. +- qmux names no tungstenite type: TLS is qmux's own `tls::Client` config, + `WebSocketConfig` folds into qmux's record-size limits, `Upgraded::new` + takes the raw upgraded IO plus a role, `Error::WebSocket` is opaque, and + `pub use tokio_tungstenite` goes (`rs/qmux/src/ws.rs`), so a tungstenite + major is not a qmux break. - moq-tokio's `server::Request::quic()` is removed; nothing outside the crate calls it, and it exposes the QUIC backend through the session API. ## Plan +Decided 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): ✅ the +`Congestion` enum converts to a factory, and the config takes only a factory +(rejected: delete the enum; keep the enum with a factory variant). This +reconciles the 2026-11-01 decision that the enum keeps its built-in families +with one factory both runtimes install, and absorbs the deleted m3 +uring-controller quest. qmux's tungstenite exposure is from +[the stream codec bench](/quest/m4/perf/stream/codec.md), which stays +perf-only. + Found by the 2026-11-07 API shape audit (transport); see the [epic](/quest/m2/api-shape/README.md). The relay's io_uring path builds its configs the way the tokio path does, so it loses its conversion code. The diff --git a/quest/m2/audio-codec-seam.md b/quest/m2/audio-codec-seam.md new file mode 100644 index 00000000000..4180bf7d282 --- /dev/null +++ b/quest/m2/audio-codec-seam.md @@ -0,0 +1,23 @@ +# [S] moq-audio codecs return zero or more outputs + +## Goal + +moq-audio's `Encoder::encode` and `Decoder::decode` return zero or more +packets or frames, and each has a `flush`, the shape moq-video's codecs +already use. Today `Encoder::encode(&[f32]) -> Result` +(`rs/moq-audio/src/encode/encoder.rs`) and `Decoder::decode(&[u8]) -> +Result` (`rs/moq-audio/src/decode/decoder.rs`) return exactly one, +unchanged since `release`. libopus and PCM keep producing one per call. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs +and remaining quests): ✅ reshape in this breaking cut (rejected: leaving it +to the m5 backends). Every planned platform backend (AudioToolbox, +MediaCodec, Media Foundation, and WebCodecs in m5's audio encode and decode +quests) emits zero or more outputs per call and needs a flush, so each would +otherwise break `encode`'s one-packet return in its own release. + +Mirror moq-video's names and return types. moq-ffi, moq-c, and the wrappers +follow if they expose the codec. Bench the libopus path before and after, +since it allocates per call if the return becomes a `Vec`. diff --git a/quest/m4/auth-drop-iroh.md b/quest/m2/auth-drop-iroh.md similarity index 83% rename from quest/m4/auth-drop-iroh.md rename to quest/m2/auth-drop-iroh.md index 348c45d0f68..11bc5f39325 100644 --- a/quest/m4/auth-drop-iroh.md +++ b/quest/m2/auth-drop-iroh.md @@ -22,6 +22,8 @@ an older relay: an unrecognized name deserializes to `Unknown` (`#[serde(other)]` in Rust, `z.catch` in JS). Update the auth contract docs and any test or fixture naming `iroh`. +Moved from m4 to m2: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). This cut already breaks moq-auth (for example [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) removes the peer grants), so it is that release. + Public API: breaking in moq-auth and `@moq/auth` (one enum variant). Wire: the auth JSON contract loses the `iroh` transport value. diff --git a/quest/m3/bus-minus-several.md b/quest/m2/bus-minus-several.md similarity index 66% rename from quest/m3/bus-minus-several.md rename to quest/m2/bus-minus-several.md index 2a3125bd10c..46d3fc5c16a 100644 --- a/quest/m3/bus-minus-several.md +++ b/quest/m2/bus-minus-several.md @@ -7,7 +7,7 @@ can drop every copy of that guest's own sound. ## Plan -Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the studio is a named consumer that is not urgent. +Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the studio is a named consumer that is not urgent. Moved to m2: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). `moq_audio::bus` is new since `release`, so changing `minus` after the cut would cost another moq-audio major. `Mix::minus` (`rs/moq-audio/src/bus.rs`) takes one `Strip`. A studio guest with a camera and a screen share has two sources of their own sound, so their diff --git a/quest/m3/bus-positioned-write.md b/quest/m2/bus-positioned-write.md similarity index 77% rename from quest/m3/bus-positioned-write.md rename to quest/m2/bus-positioned-write.md index ccc19453911..7419e725599 100644 --- a/quest/m3/bus-positioned-write.md +++ b/quest/m2/bus-positioned-write.md @@ -8,7 +8,7 @@ copying the bus's private latency and padding rules. ## Plan -Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the studio is a named consumer that is not urgent. +Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the studio is a named consumer that is not urgent. Moved to m2: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). `moq_audio::bus` is new since `release`, so the cut publishes `Channel::write` for the first time, and this break after it would cost another moq-audio major. If the positioned-write semantics can't settle in time, land `write(Write { position: Option, data })` so positioning is additive. - ✅ **Positioned writes**, a breaking change to `Channel::write`. Rejected: exposing a channel's buffered depth and latency, which leaves the diff --git a/quest/m2/cluster-routing/routes/README.md b/quest/m2/cluster-routing/routes/README.md index 1816813739e..9810626f7e2 100644 --- a/quest/m2/cluster-routing/routes/README.md +++ b/quest/m2/cluster-routing/routes/README.md @@ -543,7 +543,6 @@ benchmarks. - [Firefox tabs prove their route key](/quest/m2/cluster-routing/routes/browser-proof.md) - a current Firefox tab opens a lite-07 session with a route-key proof the relay verifies, once neqo's exporter follows the draft - [Playwright bundles Chromium's spec exporter](/quest/m2/cluster-routing/routes/playwright-pin.md) - the toolchain's Playwright bundles Chromium 158+, so the route key lane proves the Chromium tab - [A declined lite-06 route is reconsidered when the lite-07 path fails](/quest/m2/cluster-routing/routes/lite06-failover.md) - a mixed-version relay fails over to the lite-06 route it declined -- [A covering predecessor's takeover shows under a mount](/quest/m2/cluster-routing/routes/mount-takeover.md) - lite-07 presents a takeover beneath a mount as lite-06 does ## Related diff --git a/quest/m2/cluster-routing/routes/mount-takeover.md b/quest/m2/cluster-routing/routes/mount-takeover.md deleted file mode 100644 index 6e7fdcb571c..00000000000 --- a/quest/m2/cluster-routing/routes/mount-takeover.md +++ /dev/null @@ -1,21 +0,0 @@ -# [S] A covering predecessor's takeover shows under a mount - -## Goal - -Under a mounted grant (for example, tenant B seeing tenant A's `public` at -`shared`), a lite-07 claim whose predecessor covers the mount's target -arrives beneath the mount point as a takeover, as it does on lite-06. Today -it arrives as a start, because the predecessor has no name beneath the -mount point. - -## Plan - -Decided 2026-11-06 (maintainer, /quest-complete, a follow-up of -[moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)): ✅ m2, in this -epic, so lite-07 presents mounts as lite-06 does before the cut. Not chosen: -m3; m4. - -Extend `rs/moq-net/tests/integration/mount.rs`, which #8023 adds, with the -covering-predecessor case on both versions. - -Starts once #8023 lands. Public API: none. Wire: none. diff --git a/quest/m2/cluster-routing/routes/session.md b/quest/m2/cluster-routing/routes/session.md index 86f5d51e220..9706ee7a561 100644 --- a/quest/m2/cluster-routing/routes/session.md +++ b/quest/m2/cluster-routing/routes/session.md @@ -27,29 +27,23 @@ node table, and the public API drops what the route layer replaced. change and per interest (`Router::advertise`), so a large origin costs linear work per update. Do it with the scoping change, which reshapes the same per-stream presentation. -- Public API: `Hops`, `RouteInfo::hops`, and the saturating `Cost` stay while - lite-06 and the moq-transport cluster extension still carry hop chains. - Remove them, or hide them behind those wires, when the rollout window - closes (see Waiting). - -## Waiting - -- Maintainer: decide when `Hops`, `RouteInfo::hops`, and the saturating - `Cost` leave the public API. Every older wire still fills them, so an agent - cannot drop them without picking the rollout's end. Options: **when lite-06 - retires (recommended)**, since removing them now only moves them behind a - private type; or **now**, keeping a private chain type for the older wires. - Done when the Plan item above names the point. - -Added 2026-11-07 (maintainer, /quest-plan from the API shape audit), for -the PR that lands this ([moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)): - -- An origin has one identity on both wires, seeded from `Config.hop`, not a - hop ID beside a separate random route identity. -- `Cost::{MAX, DRAIN}` become `pub(crate)`. A drained route is the lowest - preference, never a saturated metric ("drain is a preference state", in - the [epic](/quest/m2/cluster-routing/README.md)), so sessions stop - stamping `Cost::DRAIN` on GOAWAY, including on moq-transport. +- Public API: the hop chains leave it before the cut. Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): + ✅ now, behind a private chain type that lite-06 and the moq-transport + cluster extension keep filling (rejected: when lite-06 retires, which ships + them in the cut and breaks them later; only the `Cost` constants now). The + sweep found no reader outside this repository. + - `Hops`, `RouteInfo::hops`, `RouteInfo::is_anonymous`, and + `Cost::{MAX, DRAIN}` become `pub(crate)`; `Cost::{new, value}` stay. + JS `RouteInfo.hops`, moq-ffi's `MoqRouteInfo` hops, and moq-c's route + info drop their mirrors. + - A drained route is the lowest preference, never a saturated metric + ("drain is a preference state", in the + [epic](/quest/m2/cluster-routing/README.md)), so sessions stop stamping + `Cost::DRAIN` on GOAWAY, including on moq-transport. + - An origin has one identity on both wires, seeded from `Config.hop`. Today + the lite-07 route node is `route::Node::random()` + (`rs/moq-net/src/model/origin.rs`) and lite-06 derives a different hop + from it (`route_hop`). ## Related diff --git a/quest/m2/finish-self.md b/quest/m2/finish-self.md new file mode 100644 index 00000000000..73bba9f276b --- /dev/null +++ b/quest/m2/finish-self.md @@ -0,0 +1,21 @@ +# [S] Finishing consumes the producer + +## Goal + +Every public importer and producer whose `finish` takes `&mut self` takes +`self` instead, so a finished producer cannot be written to and no runtime +"already finished" refusal is needed. moq-rtmp and moq-srt already consume +on finish. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs +and remaining quests): ✅ settle it as m2 before the cut (rejected: leaving +it to [a failed finish is final](/quest/m1/explicit-state/finish-final.md)'s +"if this child takes it", which ships `finish(&mut self)` plus a refusal or +breaks after the cut). finish-final keeps the internal state work; this +quest changes the signatures. A `finish` that can fail returns the +producer in its error when the caller can retry, and the PR says which do. +List every changed signature with its migration in the Impact section, +including moq-ffi and moq-c, whose handles keep a runtime check because a +foreign caller can't be consumed. diff --git a/quest/m2/gateway-ingest.md b/quest/m2/gateway-ingest.md index 7e8c30772fe..e69ef0a7ae6 100644 --- a/quest/m2/gateway-ingest.md +++ b/quest/m2/gateway-ingest.md @@ -28,3 +28,9 @@ them: [srt-rate-handle](/quest/m3/srt-rate-handle.md) and `import --max-age`/`--linger` build one `Ingest`. Whether `moq_quic::limits::Rate`'s `Unlimited` variant can become `Option` is out of scope. + +Added 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the per-session request shapes settle here too, so m3's rate, report, and wire work adds fields instead of `with_*` setters after the cut. + +- `whep::accept` takes a `whep::Request` (`#[non_exhaustive]`), mirroring `whip::Request`, moved here from [rtc-pacing](/quest/m3/rtc-pacing.md), so its rate handle is additive. +- moq-webrtc's `server::Config.udp_bind` becomes `socket: server::Socket` (`#[non_exhaustive]`, only `Bind(SocketAddr)` today), so a fed socket from [one port](/quest/m3/one-port/README.md) is additive. +- Per-session knobs m3 adds (the rate `Limit`, report and echo, the SRT `Wire`) are fields on these request structs or on `Ingest`, never new setters on `Client` or `Publish`. diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 17e6c1fa04f..41c4790ec67 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -67,6 +67,18 @@ Decided 2026-11-05 (maintainer, /quest-audit): ✅ this waits for [Drop set](/quest/m1/drop-set.md), since both rewrite the lite-07 SUBSCRIBE_DROP draft wording and the drop signal's `Delivered` argument. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): ✅ key the drop signal by group start and land after +[time addressing's model](/quest/m2/time-addressing/model.md), so its public +API never ships sequence-keyed (rejected: landing first and rekeying with +the model). ✅ Drops surface as a `Gap { range, error }` item on +`track::Ordered`, which already skips gaps through `poll_drop`, mirroring +the container consumer's `Read::Gap` (`rs/moq-mux/src/container/consumer.rs`); +`recv_group` is unchanged (rejected: a separate `recv_drop` read; a drop +variant on `recv_group`). Answer the maintainer's question above first: if +receive-window eviction can wait for the header, take the no-wire path, and +remove this quest from [lite07-finalize](/quest/m2/lite07-finalize.md)'s +Required. + Public API: additive for a separate read; breaking if folded into `recv_group` (its `Result>` return changes for every caller), with MIGRATE notes. `@moq/net` and the bindings mirror it only with a named consumer. @@ -75,6 +87,7 @@ Wire: possibly lite-07 (SUBSCRIBE_DROP for a stopped group), decided here. ## Required - [Drop set](/quest/m1/drop-set.md) - owns the per-cursor drop runs this reports +- [Address groups by timestamp](/quest/m2/time-addressing/model.md) - the drop range is keyed by start ## Related - [The receive-windows benchmark](/quest/m1/receive-windows-evicted.md) - its overcommitted cells wait on this (skipped by [moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838) until it lands) diff --git a/quest/m3/intra-refresh/plan-boundary.md b/quest/m2/intra-refresh-boundary.md similarity index 88% rename from quest/m3/intra-refresh/plan-boundary.md rename to quest/m2/intra-refresh-boundary.md index 8b71cc1ceeb..4985fbaf44b 100644 --- a/quest/m3/intra-refresh/plan-boundary.md +++ b/quest/m2/intra-refresh-boundary.md @@ -8,6 +8,8 @@ earlier ones. Rewrite the import and consumer quests around that contract. ## Plan +Moved from the m3 intra-refresh epic to m2: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). The catalog's `warmup` field is new in this release, so its contract (a safe upper bound published before the content it covers) is settled before the cut publishes it. The implementation quests stay in m3. + The 2026-10-11 TS audit found the proposed catalog duration is not yet a sufficient guarantee. `h264-import` raises the global value after observing a longer sweep. diff --git a/quest/m2/js-time-types.md b/quest/m2/js-time-types.md index 58f4bf51e6e..b6ccdf94bd0 100644 --- a/quest/m2/js-time-types.md +++ b/quest/m2/js-time-types.md @@ -29,6 +29,10 @@ precision). and no implicit number conversion (`valueOf` refuses). `Clock.Instant` supports `add(Duration)`, `since(Instant) -> Duration`, and comparison; `Wall` follows the same rule. +- `Clock.Instant`'s arithmetic mirrors `kio::clock::Instant`'s. If + [moq-dev/moq#8151](https://github.com/moq-dev/moq/pull/8151)'s + peer-arithmetic drops kio's `Duration` operators for checked and saturating + forms, JS gets `checkedAdd` and `saturatingAdd` too (added 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests)). - The wire still carries whole milliseconds; rounding stays inside the encoders, as it does today. - `Manual`, `sleep`, `timeout`, `interval`, and the signals timers take the diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index ed267863216..de3cb88ff77 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -111,6 +111,10 @@ Timestamp provenance landed in [#6150](https://github.com/moq-dev/moq/pull/6150), and the 2^61 - 1 timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): Required names every quest that may still change lite-07 bytes. +The explicit `Oldest` anchor rides [time addressing's model](/quest/m2/time-addressing/model.md), +whose lite-07 encoding [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries. + ## Required - [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone @@ -119,6 +123,8 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - the job's route inherits the claim's instance, with no new wire message - [Takeover](/quest/m1/stream-credit/takeover.md) - lite-07 lets a group stream take over for another group +- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - may add SUBSCRIBE_DROP for a stopped group; leaves this list if it takes the no-wire path +- [Delete the old start bookkeeping](/quest/m2/subscribe-ranges/start-bookkeeping.md) - may change START per update on lite-07 ## Related diff --git a/quest/m2/no-sentinels.md b/quest/m2/no-sentinels.md index 02a256feb6d..29ca57b0078 100644 --- a/quest/m2/no-sentinels.md +++ b/quest/m2/no-sentinels.md @@ -16,6 +16,10 @@ No public type uses a huge value or zero as a marker for "none" or `Server::with_timeout` already is. The JS mirror (`Connection.Backoff`) follows, and the Rust (10 s) and JS (unlimited) defaults for the backoff timeout agree. +- moq-relay's `runtime.workers` uses `0` for "share the session runtime"; + it becomes `"shared" | "auto" | `, defaulting to `"shared"`, so a later + default change never reinterprets an unset or zero value (from + [shard-default](/quest/m4/perf/shard-default.md)). - moq-ffi's `moq_ffi_test_clock_now` returns `u64::MAX` when no clock runs; it reports absence without a sentinel. @@ -25,5 +29,5 @@ Found by the 2026-11-07 API shape audit (net-model, net-session, apps, bindings). AGENTS.md: "Never use a huge value like `u64::MAX` as a marker." Each struct already breaks in this release, so no extra break is taken. `Range::oldest()`'s `Relative(u64::MAX)` is owned by -[anchor-oldest](https://github.com/moq-dev/moq/pull/8149), not here. Pick +[time addressing's model](/quest/m2/time-addressing/model.md), not here. Pick the aligned backoff default in the PR and say why. diff --git a/quest/m2/sequence-reuse.md b/quest/m2/sequence-reuse.md index adf56b73720..f944f86746c 100644 --- a/quest/m2/sequence-reuse.md +++ b/quest/m2/sequence-reuse.md @@ -17,6 +17,16 @@ Decided 2026-11-07 (maintainer, invariant-audit planning): reuse is misuse that m2 because `append_group`/`create_group` and the origin splice start refusing calls that succeed today, which callers recreating tracks must adapt to (the questline's breaking-change test). The API shape for the explicit seed is the implementer's call; prefer reusing `create_group` with an explicit sequence over a new method. [moq-dev/moq#8063](https://github.com/moq-dev/moq/pull/8063) changes how a job's route continues its claim's instance; build on whichever lands first. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): ✅ the high-water mark is in group keys (starts, once time addressing +lands), and there is no seed method: an application that reuses a name +passes the start it wants to `create_group` (rejected: a seed API; landing +before the model and rekeying). Lands with or after +[time addressing's model](/quest/m2/time-addressing/model.md). + +## Required + +- [Address groups by timestamp](/quest/m2/time-addressing/model.md) - the high-water mark is a start + ## Related - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - instance continuity across a claim's jobs diff --git a/quest/m2/spawn-constructors.md b/quest/m2/spawn-constructors.md new file mode 100644 index 00000000000..27c44e5da98 --- /dev/null +++ b/quest/m2/spawn-constructors.md @@ -0,0 +1,25 @@ +# [S] Public constructors spawn nothing, or say why + +## Goal + +Before the cut publishes them, every public constructor or method in a +published library crate that spawns an async task either returns a handle or +driver its caller polls, or is recorded as kept with its reason. moq-tokio is +the tokio edge and may keep spawning. For example, moq-hls's server spawns in +its own path (`rs/moq-hls/src/server/mod.rs`), and `tokio::spawn` or a +runtime spawn appears outside tests in more than 20 library crates. + +## Plan + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs +and remaining quests): ✅ settle the public half before the cut (rejected: +leaving it all to [the remaining library spawns](/quest/m3/spawn-audit.md)). +Changing a public constructor's return type after the cut would break up to +ten published crates at once (moq-hls, moq-rtmp, moq-rtsp, moq-srt, +moq-webrtc, moq-transcode, moq-video, moq-mux, qmux, and others found). + +Inventory public spawning entry points with a search per crate, then +convert each to a `kio::Tasks` child or a returned driver, following +[spawn-audit](/quest/m3/spawn-audit.md)'s rule ("poll everywhere, no +spawn"), or list it as kept. spawn-audit keeps the private spawns. Each +converted signature gets a migration note in the PR's Impact section. diff --git a/quest/m2/time-addressing/model.md b/quest/m2/time-addressing/model.md index e8c7495e797..19a777ebf0a 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -134,6 +134,22 @@ recorded only sequencing. stamps from its own clock. `Timed

` moves from moq-net's root to moq-json, whose producers and readers are its only users, and its `at` becomes required under the rule above. +- **One anchor rule.** Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): ✅ collapse `Anchor` to `{Oldest, + Relative(n), Time(ts)}` with every end inclusive (rejected: keep + `Absolute` and make it inclusive; only add `Oldest`). Today an `Absolute` + end is exclusive while `Relative` and `Time` ends include their group + (`rs/moq-net/src/model/subscription.rs`), and "oldest" is the sentinel + `Relative(u64::MAX)`. Once keys are starts, `Absolute(key)` and `Time(ts)` + name the same group, so `Absolute` goes; a legacy exclusive end `E` maps + to `Time(E - 1)`, since legacy keys pass through. `Oldest` is explicit and + encoded the same on every wire (lite-07, lite-06 and earlier, IETF), where + today the lite encoder treats any `back > MAX_QUIC` as oldest and the + model does not. `Range::groups(RangeBounds)` and + `Subscription::with_range` go. JS's omitted start keeps meaning `Oldest`. + This absorbs the deleted anchor-oldest quest (from the 2026-11-07 + invariant audit, model-4). +- **Fence what grows after the cut.** Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `Position` becomes + `#[non_exhaustive]`, so byte-holes can add a byte offset without a break. - **Open, for whoever starts this, with the maintainer:** how lite-05/06, which carry both a sequence and frame timestamps, map on the way out. @@ -181,7 +197,8 @@ Public API: breaking. `group::Info`, `create_group`, `append_group`, `Position`, `Range` ends, `fetch_group`, `Subscriber::floor`, and group consumers address by start timestamp, every producer write takes a required timestamp, untimed tracks become scale-less, `Timestamp::now` is gone, and -`Timed` is moq-json's. +`Timed` is moq-json's, and `Anchor` is `{Oldest, Relative, Time}` with inclusive +ends. Wire: no format change; legacy and lite-07-wip group IDs become start ticks. ## Required diff --git a/quest/m3/README.md b/quest/m3/README.md index d216e94b528..d83e7f83e25 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -57,7 +57,6 @@ federation) land. - [A runtime-free QUIC driver](/quest/m3/quic-sansio-driver.md) - a caller's own loop moves UDP datagrams and polls moq sessions over moq-quic, for rust2's bindings - [QoS](/quest/m3/qos/README.md) - the relay's egress `lag` histogram and `dropped` counters on the stats totals and prefix tracks - [The DASH manifest keeps segments across a reconfigure](/quest/m3/dash-reconfigure.md) - a same-codec reconfigure keeps the old instance's segments listed in DASH, as HLS does -- [Broadcast fairness](/quest/m3/broadcast-fairness.md) - broadcasts share a cluster link fairly, so one tenant's priority never starves another's - [Plan: watch worker](/quest/m3/plan-watch-worker.md) - prototype an invisible page worker against app-spawned workers, and land the jank harness that decides - [Watch worker](/quest/m3/watch-worker.md) - watch playback runs in a worker onto an OffscreenCanvas, so main-thread jank never stalls video or audio - [Vulkan Video encode on AMD](/quest/m3/vulkan-encode.md) - H.264 and H.265 from an external Vulkan image on RADV, hand-rolled on ash, proven on an RX 9070 @@ -185,8 +184,6 @@ federation) land. - [MP4 export trims exactly at both ends](/quest/m3/mp4-export-window.md) - a presentation window with no lead-in and no presented tail - [Container export ends cleanly when its broadcast closes](/quest/m3/export-close.md) - every container export returns `None` when its instance closes, whichever signal arrives first - [Audio capture opens a format the mix accepts](/quest/m3/audio-capture-negotiate.md) - multichannel and odd-rate devices capture, with discrete input selection -- [A mix-minus removes several sources](/quest/m3/bus-minus-several.md) - a guest's return feed drops every copy of their own sound -- [Bus writes land at a bus position](/quest/m3/bus-positioned-write.md) - callers sync audio to video without copying the bus's private latency - [moq-mux imports a regular MP4](/quest/m3/mp4-import.md) - non-fragmented MP4, `moov` first or last - [An audio encoder flushes without ending its track](/quest/m3/audio-encode-flush.md) - a clip's last partial frame is heard while the source stays live - [Padding probes from the browser](/quest/m3/probe-padding.md) - parked: the maintainer doubts padding is the right way for a browser to probe diff --git a/quest/m3/audit-dead-code.md b/quest/m3/audit-dead-code.md index 412e5bbe9ea..95da4a339be 100644 --- a/quest/m3/audit-dead-code.md +++ b/quest/m3/audit-dead-code.md @@ -81,6 +81,8 @@ From the 2026-10-25 run: - Locals and fields still named `dynamic` after the `requests()` rename ([moq-dev/moq#6752](https://github.com/moq-dev/moq/pull/6752)). +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the public-item pass runs before the cut as [api-shape](/quest/m2/api-shape/README.md)'s own work, removing this run's shortlist (`Server::serve_both`, `Catalog::to_json_pretty`, `Format::{is_planar, is_float}`); this audit keeps private code. + ## Required - [Release cut](/quest/m3/release/cut.md) - the release in flight ships before the next audit starts diff --git a/quest/m3/bandwidth-multi-connection.md b/quest/m3/bandwidth-multi-connection.md index 9c40b97c7a9..40ecd42c2fe 100644 --- a/quest/m3/bandwidth-multi-connection.md +++ b/quest/m3/bandwidth-multi-connection.md @@ -22,3 +22,5 @@ Recommendation, not settled: one reservation per connection, with the encoder following the lowest grant among connections that still have readers, rather than merging estimates into one allocator. Benchmark the fan-out over both connection and track count. + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the combination is an `Allocator` (for example `bandwidth::Allocator::lowest(impl IntoIterator)`), so no encoder or gateway signature changes. Local readers are told apart inside `track::Demand`, not through a new `reserve` parameter. diff --git a/quest/m3/cli-packaging.md b/quest/m3/cli-packaging.md index fa6fdc34cf4..3169af1175c 100644 --- a/quest/m3/cli-packaging.md +++ b/quest/m3/cli-packaging.md @@ -63,6 +63,8 @@ Decided in the 2026-10-06 audit: this does not wait on the library `capture` defaults. moq-cli's `capture` feature enables `moq-video/capture` and `moq-audio/capture` explicitly, and `release` enables `capture`. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the moq-cli feature that enables everything is named `full`, not `release`. + ## Required - [Audio capture without runtime system libraries](/quest/m3/capture-alsa-link.md) - the microphone path must start without system audio libraries before every distribution can ship it diff --git a/quest/m3/drm/mp4-atom.md b/quest/m3/drm/mp4-atom.md index d0cabe6c56e..e86d54d0b2f 100644 --- a/quest/m3/drm/mp4-atom.md +++ b/quest/m3/drm/mp4-atom.md @@ -17,3 +17,5 @@ Parse `moof`'s `pssh` too, even though key rotation stays out of scope, so the i Cover `tenc` versions 0 and 1, since `cbcs` uses version 1's crypt and skip byte blocks and a constant IV. Open the PR on kixelated/mp4-atom, release it through that repository's process, and bump `mp4-atom` in `[workspace.dependencies]` here, absorbing any API churn the bump brings. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/media](/quest/m2/api-shape/media.md) stops moq-mux re-exporting `mp4_atom` before the cut, so this bump is not a moq-mux break. diff --git a/quest/m3/export-live-start.md b/quest/m3/export-live-start.md index a947821ec2c..0f22862cb86 100644 --- a/quest/m3/export-live-start.md +++ b/quest/m3/export-live-start.md @@ -17,3 +17,5 @@ recorder ([moq-dev/studio#18](https://github.com/moq-dev/studio/pull/18)) sets 2 and so every recording also starts up to 2 s before it was started (`rs/moq-studio/src/record.rs`). Only TS export reports stats today; fMP4 and MP4 report no sample counts, which the recorder needs to say what it wrote. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/media](/quest/m2/api-shape/media.md) gives fMP4, MP4, MKV, and FLV a `moq_net::Delay { min, max }` before the cut, so splitting the start from the skip budget is an implementation fix, not a break. diff --git a/quest/m3/fetch-synced.md b/quest/m3/fetch-synced.md index dadc19c5ad5..f55b9b3863a 100644 --- a/quest/m3/fetch-synced.md +++ b/quest/m3/fetch-synced.md @@ -14,3 +14,5 @@ Decided 2026-10-30 (maintainer, follow-up of [moq-dev/moq#7366](https://github.c - Tests: a fetch for an unannounced broadcast on a synced origin returns 404 without advancing the clock to the deadline. A fetch whose broadcast is announced after the request but before sync still serves the group. A fetch for an unannounced broadcast while an upstream session hasn't synced yet waits for that sync; an announced broadcast is served without waiting on it. Public API: none. Wire: none. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): this adds a public method, so its Public API line says so instead of "none". diff --git a/quest/m3/h265-min-width.md b/quest/m3/h265-min-width.md index 20f547e334f..8a7774dd27c 100644 --- a/quest/m3/h265-min-width.md +++ b/quest/m3/h265-min-width.md @@ -41,6 +41,8 @@ prerequisite inside this quest. Public API: maybe a minimum size on the encoder probe in moq-video. Wire: none. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the probe stays private, and the typed error names the minimum width. It becomes public only when a consumer asks. + ## Related - [VA-API encode is correct on radeonsi](/quest/m1/vaapi-radeonsi.md) - the same AMD hardware run diff --git a/quest/m3/import-metadata-policy.md b/quest/m3/import-metadata-policy.md index cf69b1a3584..d72d097a3fb 100644 --- a/quest/m3/import-metadata-policy.md +++ b/quest/m3/import-metadata-policy.md @@ -19,3 +19,5 @@ Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-a - Document the policy once, in moq-mux's import docs, and make both importers' bounds `pub const`s as #7232's are. Public API: possibly new `pub const` bounds and a shared refusal error in moq-mux. Wire: none. + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the policy's bounds are private, with no `pub const` (as [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) did for `fmp4::MAX_*`). diff --git a/quest/m3/intra-refresh/README.md b/quest/m3/intra-refresh/README.md index fdbf4afb17b..df1ca9fe9d5 100644 --- a/quest/m3/intra-refresh/README.md +++ b/quest/m3/intra-refresh/README.md @@ -50,7 +50,7 @@ make these presentation guarantees true even when sweep lengths change. ## Required - [Dual decoder](/quest/m3/intra-refresh/dual-decoder.md) - js/watch's two decoders open on an H.264 recovery point in Firefox and Safari, as they now do in Chromium -- [Plan: recovery boundaries](/quest/m3/intra-refresh/plan-boundary.md) - settle publication ordering for a later, longer sweep +- [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - settle publication ordering for a later, longer sweep - [Consumer warmup](/quest/m3/intra-refresh/consumer-warmup.md) - the transcoder decodes the groups covering `warmup` as history before each group, except at a true IDR - [H.264 import](/quest/m3/intra-refresh/h264-import.md) - the splitter keeps `recovery_frame_cnt` and import publishes `warmup` from it - [H.265 import](/quest/m3/intra-refresh/h265-import.md) - the splitter reads the recovery-point SEI so an HEVC intra-refresh stream forms groups and publishes `warmup` diff --git a/quest/m3/intra-refresh/consumer-warmup.md b/quest/m3/intra-refresh/consumer-warmup.md index 659ce5be31b..01b2ea619de 100644 --- a/quest/m3/intra-refresh/consumer-warmup.md +++ b/quest/m3/intra-refresh/consumer-warmup.md @@ -54,4 +54,4 @@ The fix is history rather than a withhold rule: ## Required -- [Plan: recovery boundaries](/quest/m3/intra-refresh/plan-boundary.md) - K derives from `warmup`, which must be a safe upper bound +- [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - K derives from `warmup`, which must be a safe upper bound diff --git a/quest/m3/intra-refresh/h264-import.md b/quest/m3/intra-refresh/h264-import.md index 1318a5b4c68..43c8e19568b 100644 --- a/quest/m3/intra-refresh/h264-import.md +++ b/quest/m3/intra-refresh/h264-import.md @@ -48,4 +48,4 @@ follows the hang draft, which rounds up ## Required -- [Plan: recovery boundaries](/quest/m3/intra-refresh/plan-boundary.md) - resolve the later-mutated warmup contract before implementing it +- [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - resolve the later-mutated warmup contract before implementing it diff --git a/quest/m3/json-snapshot-resync.md b/quest/m3/json-snapshot-resync.md index 6a7c5dafd5a..f01ed8c5fad 100644 --- a/quest/m3/json-snapshot-resync.md +++ b/quest/m3/json-snapshot-resync.md @@ -35,6 +35,8 @@ state. The maintainer approved planning the fix from #7693's iterate. Public API: a new decode error in `@moq/json` and `moq-json`. Wire: none. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the consumer resyncs itself. It drops the bad group, resets its frame count and delta base, and counts the skip (optionally a `skipped()` counter), with no new error variant; a terminal error stays terminal, so room and moq-boy need no change. + ## Related - [Benchmark a Value merge-patch diff for moq-json](/quest/m5/json-value-diff.md) - may replace the Rust diff this consumer applies diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index 42301df4952..31965823ad1 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -115,4 +115,4 @@ the third, and survives a relay restart. - [P2P](/quest/m4/p2p/README.md) - internet peer sessions, which the m3 mesh does not use - [Mesh over ICE](/quest/m5/mesh-ice.md) - deferred direct paths between mesh nodes on different networks - [End-to-end encryption](/quest/m5/e2ee/README.md) - the AEAD the encryption level will reuse -- [Teleoperation](/quest/m5/teleop-robot.md) - robot track shapes that could ride the mesh +- [Teleoperation](/quest/m5/teleop-robot.md) - robot track conventions that could ride the mesh diff --git a/quest/m3/mesh/cert-credentials.md b/quest/m3/mesh/cert-credentials.md index 1108e7237d5..ded9d3ab9ce 100644 --- a/quest/m3/mesh/cert-credentials.md +++ b/quest/m3/mesh/cert-credentials.md @@ -54,6 +54,14 @@ Public API: new credential types in `moq-auth` and `@moq/auth`, and a trust store handle on the relay. Wire: a new credential form wherever a JWT is accepted. +Added 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests), before any code: pin the credential encoding, since it is permanent once shipped. + +- A self-describing, versioned encoding (for example a `moqc1.` prefix, or a distinct token type) in a slot named by role. If the query key stays `jwt` for compatibility, the prefix still makes it dispatchable without sniffing, and moq-transport uses its AUTHORIZATION TOKEN type field. +- One proof structure whose signed payload has a `nonce | timestamp` field, so [the challenge](/quest/m4/cert-challenge.md) reuses it instead of adding a second format. +- Revocation is data in the trust-store handle (a revoked SPKI-hash or serial set the application replaces), not a per-connection predicate. +- Chains are 2 to 4 KB in base64, close to common 8 KB URL limits; cache verified chains by fingerprint, and say in the PR how a long chain is carried. +- The shared token corpus planned in [moq-dev/moq#8151](https://github.com/moq-dev/moq/pull/8151) includes this credential form. + ## Required - [Mesh relay node](/quest/m3/mesh/node.md) - the node that checks these credentials for its LAN peers diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index cbd03ee47cb..a0b66c24b3b 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -37,6 +37,8 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, local [mesh relay node](/quest/m3/mesh/node.md). - Write a short porting note into the [guide](/quest/m3/mesh/guide.md). +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one socket endpoint per service at prefix `mesh/`, with the grant adding publish `mesh/*/.server/` and `mesh/*/.client/`, so `moq_net::socket` ships unchanged and needs no service field. + ## Required - [Rust byte streams](/quest/m3/stream/rust.md) - the stream this API returns diff --git a/quest/m3/mux-source-cut.md b/quest/m3/mux-source-cut.md index d7bce453a03..b6630d419e3 100644 --- a/quest/m3/mux-source-cut.md +++ b/quest/m3/mux-source-cut.md @@ -38,6 +38,8 @@ its listed segments and returns `Ok(None)`, mirroring [moq-dev/moq#7399](https:/ Public API: `moq_mux::Source` gains a way to follow its own path. Wire: none. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): additive. Add a method named by role (for example `Source::instances()`) and leave `Source::follow`'s documented contract alone. + ## Related - [A recording stalled on an open group reports what it waits for](/quest/m3/hls-stalled-segment.md) - the other [moq-dev/moq#7399](https://github.com/moq-dev/moq/pull/7399) follow-up diff --git a/quest/m3/obs-moq-video/adapter.md b/quest/m3/obs-moq-video/adapter.md index ebe3bbefebc..8ebb88ba0a9 100644 --- a/quest/m3/obs-moq-video/adapter.md +++ b/quest/m3/obs-moq-video/adapter.md @@ -13,3 +13,5 @@ One opt-in Use MoQ encoders choice publishes OBS video and audio through moq-vid - Establish bounded submission/packet queues, explicit raw-frame drop behavior, thread confinement, cancellation, late completion, device loss, resize and color metadata. Never block OBS's graphics thread on network backpressure. The CPU path is a correctness/fallback baseline; platform quests establish accelerated input. - The audio side is the internal `moq_opus` encoder, whose settings are `bitrate` (kbps) and `preset` (`low_latency`, `balanced`, `quality`). Use MoQ encoders creates it in place of `ffmpeg_opus`; it is the only audio choice the combined mode offers until AAC encoding lands. - Test rejection, saturation, drain, stop during encode, delayed completion, and repeated start/stop. Validate real decoded pixels and audio continuity, matched timestamps, preset reporting, and frame-to-packet latency. Validate the new binding docs, feature combinations, package dependencies and native plugin linking. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the Go `*DecoderOutput` alias deletion lands before the cut in [api-shape/bindings](/quest/m2/api-shape/bindings.md); `DecodeStart::Latest` stays here. diff --git a/quest/m3/probe-rung-disable-js.md b/quest/m3/probe-rung-disable-js.md index f4aff56c956..410d2aca130 100644 --- a/quest/m3/probe-rung-disable-js.md +++ b/quest/m3/probe-rung-disable-js.md @@ -34,6 +34,8 @@ proves recovery end to end. Public API: whatever knob `@moq/publish` exposes for the rule. Wire: none. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no new knob. Mirror `moq_mux::rate::Policy`'s rule and constants, and let `enabled` combine with them. + ## Required - [Padding probes](/quest/m3/probe-padding.md) - the browser's sender, which raises the estimate so a disabled rung can resume diff --git a/quest/m3/qos/lag-histogram.md b/quest/m3/qos/lag-histogram.md index 43a00984215..dd8d4674d03 100644 --- a/quest/m3/qos/lag-histogram.md +++ b/quest/m3/qos/lag-histogram.md @@ -98,6 +98,8 @@ re-exported by `moq-stats`. Wire: the stats JSON gains the egress fields. Update `doc/concept/stats.md` and the stats section of `doc/bin/relay/config.md`. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/net](/quest/m2/api-shape/net.md) makes `stats::Registry::report` take `now` and the handle's arguments `#[non_exhaustive]` before the cut, so this adds fields and is not breaking. + ## Required - [poll_acked on moq-net's send stream](/quest/m3/quic-ack-hook.md) - the diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index c3f8397df69..1d545107d2c 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -97,3 +97,5 @@ close. Decided in the 2026-09-30 audit: moved to m2 with its consumers, the [viewer lag histogram](/quest/m3/qos/lag-histogram.md) and the [delivery-delay histogram](/quest/m5/delivery-delay.md). + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no `Option<()>` outcome. Return a named `enum Acked { Delivered, Unsupported }` (or add `fn acks(&self) -> bool` and make the poll a plain `Result`), and use one offset type on both layers. diff --git a/quest/m3/quic-realtime/README.md b/quest/m3/quic-realtime/README.md index d0adb1d96c1..a73e0b53a84 100644 --- a/quest/m3/quic-realtime/README.md +++ b/quest/m3/quic-realtime/README.md @@ -178,7 +178,6 @@ owns that feedback. ## Required -- [io_uring runs an application's controller](/quest/m3/quic-realtime/uring-controller.md) - moq-uring takes a controller factory, so the winner installs the same way on both runtimes - [moqsink encoder feedback](/quest/m3/quic-realtime/moqsink-feedback.md) - GStreamer publishers retune their encoder to the target rate ## Related diff --git a/quest/m3/quic-realtime/moqsink-feedback.md b/quest/m3/quic-realtime/moqsink-feedback.md index 27eafcd79f3..eaeb41579c0 100644 --- a/quest/m3/quic-realtime/moqsink-feedback.md +++ b/quest/m3/quic-realtime/moqsink-feedback.md @@ -25,6 +25,8 @@ latency win once `Realtime` lands. - Document the behavior in `doc/bin/gstreamer.md`; tests drive it with mocked time. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): per-element `bitrate` properties with a unit table, failing loud on an unknown encoder; a custom GStreamer event only if a named consumer needs a wrapper bin. + ## Related - [Realtime uplink congestion control](/quest/m3/quic-realtime/README.md) - the controller whose rate this follows diff --git a/quest/m3/quic-realtime/uring-controller.md b/quest/m3/quic-realtime/uring-controller.md deleted file mode 100644 index c5fbba4aaae..00000000000 --- a/quest/m3/quic-realtime/uring-controller.md +++ /dev/null @@ -1,18 +0,0 @@ -# [S] io_uring workers run an application's own congestion controller - -## Goal - -moq-uring's QUIC transport config (`rs/moq-uring/src/quic/transport.rs`) takes a `moq_congestion::ControllerFactory` as well as its built-in `Congestion` families, and the relay's io_uring runtime installs the controller a `moq_tokio::quic::Config::controller` carries, instead of refusing that config. An application embedding the relay gets the same controller on either runtime. - -## Plan - -Follows [moq-dev/moq#7467](https://github.com/moq-dev/moq/pull/7467) (open), which adds `quic::Config::controller` to moq-tokio, a factory the QUIC backend builds one controller from per connection, and has the relay's io_uring runtime refuse a config that carries one. This waits on #7467 landing. - -Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-afk run): m2, in this epic, because shipping `Realtime` "in moq-tokio and moq-uring" (the README's own work) is simpler once moq-uring takes a factory like moq-quic's `transport::Config::congestion` does: the winner becomes one factory both runtimes install, not a new enum variant per crate. - -- moq-uring's `Congestion` enum keeps its built-in families; add a factory variant or field, mirroring how #7467 shaped moq-tokio's, so the two crates' configs stay mirrored. -- `rs/moq-relay/src/uring.rs` (the `transport.congestion` mapping, about line 500) passes the factory through and drops #7467's refusal. -- The io_uring workers are thread-per-core: the factory is shared across workers, and each connection's controller lives on its worker. State the factory's `Send + Sync` requirement in its docs. -- Test as #7467's `a_custom_controller_reaches_the_live_connection` does, on a ring worker: a counting factory builds the controller a live connection runs. Linux-only; run it in the `io-uring` nextest group. - -Public API: a factory option on moq-uring's QUIC transport config; the relay's io_uring runtime accepts `quic::Config::controller`. Wire: none. diff --git a/quest/m3/relay-test-stats.md b/quest/m3/relay-test-stats.md index cb465d2f417..5ece4ad0328 100644 --- a/quest/m3/relay-test-stats.md +++ b/quest/m3/relay-test-stats.md @@ -14,3 +14,5 @@ Decided 2026-11-05 (maintainer, on moq-dev/studio's /quest-plan): m3, since the where `stats::Config.enabled` is false, and takes no arguments. The studio's health test builds its own relay to get stats. Prefer a config the helper takes over a second helper, since `foo_with_x` variants are banned. + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): additive. Expose `moq_relay::test_config() -> Config` and `TestRelay::start(Config)`, and keep `test_relay()` as is, rather than a `test_relay_with_*` twin. diff --git a/quest/m3/relay-undialable-peers.md b/quest/m3/relay-undialable-peers.md index b562d60cf06..e18b11e4b9f 100644 --- a/quest/m3/relay-undialable-peers.md +++ b/quest/m3/relay-undialable-peers.md @@ -53,4 +53,4 @@ Public API: additive in moq-tokio. Wire: none. ## Related -- [Drop moq-auth's iroh transport](/quest/m4/auth-drop-iroh.md) - the other iroh leftover +- [Drop moq-auth's iroh transport](/quest/m2/auth-drop-iroh.md) - the other iroh leftover diff --git a/quest/m3/rtc-pacing.md b/quest/m3/rtc-pacing.md index 33c1707fd88..8d6965ea7b8 100644 --- a/quest/m3/rtc-pacing.md +++ b/quest/m3/rtc-pacing.md @@ -64,6 +64,8 @@ is `moq_net::bandwidth::Limit`, which replaces moq-webrtc's `rate::{Cap, Limit}` in [gateway-ingest](/quest/m2/gateway-ingest.md) (2026-11-07, maintainer, /quest-plan from the API shape audit). Wire: none. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `whep::Request` itself lands before the cut in [gateway-ingest](/quest/m2/gateway-ingest.md); this quest adds its rate field. + ## Related - [SRT rate handle](/quest/m3/srt-rate-handle.md) - the same pacing and retransmit charging on SRT diff --git a/quest/m3/session-outcome-records.md b/quest/m3/session-outcome-records.md index f4434775ed5..65ca1911446 100644 --- a/quest/m3/session-outcome-records.md +++ b/quest/m3/session-outcome-records.md @@ -56,3 +56,5 @@ records): Tests: a refused session and an abnormal end each produce exactly one record under the right label; a flood past the rate produces summaries whose counts match the counters; an admitted session that ends normally produces none. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/net](/quest/m2/api-shape/net.md) makes `stats::Handle::{refuse, session}` take `#[non_exhaustive]` structs before the cut, so the records add fields and are not breaking. diff --git a/quest/m3/spawn-audit.md b/quest/m3/spawn-audit.md index d2616809e79..9c5c4308925 100644 --- a/quest/m3/spawn-audit.md +++ b/quest/m3/spawn-audit.md @@ -60,3 +60,5 @@ server entry above): Public API: constructors that spawned return a handle to poll instead; an Impact migration note per published crate. Wire: none. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [spawn-constructors](/quest/m2/spawn-constructors.md) settles public spawning entry points before the cut; this quest keeps the private spawns. diff --git a/quest/m3/stats/rust.md b/quest/m3/stats/rust.md index b6389eec934..a6c57e0ce9a 100644 --- a/quest/m3/stats/rust.md +++ b/quest/m3/stats/rust.md @@ -63,6 +63,8 @@ TS release section holds the drops (from [moq-dev/moq#6654](https://github.com/moq-dev/moq/pull/6654)). +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): a gateway takes its report and echo as fields on its request struct or on `moq_mux::Ingest` ([gateway-ingest](/quest/m2/gateway-ingest.md)), not as `with_report` and `with_echo` builders. + ## Related - [Encrypted native CLI](/quest/m5/e2ee/cli.md) - refuses stats and feedback on an encrypted broadcast diff --git a/quest/m3/stream/rust.md b/quest/m3/stream/rust.md index 6a882c2af2d..ae449581d63 100644 --- a/quest/m3/stream/rust.md +++ b/quest/m3/stream/rust.md @@ -30,3 +30,5 @@ frame per TCP read, no fill handler. before the frame ends, round-trip bytes, half-close each way, reset each way, a reader ending `Evicted` surfaced as a reset, and a relay restart ending the stream with a typed error. + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the `AsyncRead`/`AsyncWrite` adapter lives in moq-tokio, the tokio edge, not beside moq-net's socket module. diff --git a/quest/m3/video-publish-grant.md b/quest/m3/video-publish-grant.md index 8302b8d4ea3..66b900999c9 100644 --- a/quest/m3/video-publish-grant.md +++ b/quest/m3/video-publish-grant.md @@ -18,3 +18,5 @@ only figure a caller sees is the target reported through the catalog stats. Consumer: the studio's encode-control rungs and Health panel ([moq-dev/studio#25](https://github.com/moq-dev/studio/pull/25)). Recommendation: return a handle from the publish call that carries the grant, rather than a callback. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/native](/quest/m2/api-shape/native.md) makes `publish_capture` return a handle in both crates before the cut, so `grant()` is an additive method on it. diff --git a/quest/m3/watch-worker.md b/quest/m3/watch-worker.md index c859678d3b6..fb621ca3ef1 100644 --- a/quest/m3/watch-worker.md +++ b/quest/m3/watch-worker.md @@ -28,6 +28,8 @@ Wire: none. Gate on the plan's jank harness and N-player sweep, both nightly. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/js](/quest/m2/api-shape/js.md) ships `Video.RendererOutput` without `frame` and narrows `@moq/room` before the cut, so those two breaks are gone from this quest. + ## Required - [Plan: watch worker](/quest/m3/plan-watch-worker.md) - picks the worker model and rewrites this quest diff --git a/quest/m4/README.md b/quest/m4/README.md index 782cd15498f..27ee0f32699 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -54,7 +54,6 @@ deleted. - [The relay over QUIC on the sim](/quest/m4/quic-sim.md) - the relay and moq-tokio's `Client` and `Server` run over `moq-quic` on the seeded sim - [moq-shaper's own socket never passes for path loss](/quest/m4/shaper-socket.md) - relay-sized buffers and its own socket drops reported beside path drops - [Auth session caps cost O(1)](/quest/m4/auth-session-index.md) - per-token and per-remote counts and a time-ordered expiry queue replace the scans, after #7211 -- [Drop moq-auth's iroh transport](/quest/m4/auth-drop-iroh.md) - the next breaking moq-auth release drops `Transport::Iroh` and the JS `"iroh"` value - [Relays and moq-tokio offer versioned qmux-02 first](/quest/m4/qmux-02-subprotocols.md) - one shared qmux version list prefers 02, so JS clients negotiate it - [Smoke tests make their certificates without a system OpenSSL config](/quest/m4/smoke-libressl.md) - moxygen and Cloudflare smoke pass `-config`, as the conformance runner does - [ashpd uses maintained D-Bus crates](/quest/m4/ashpd-maintained.md) - upgrade to ashpd 0.14 (zbus 6) and remove the portal dependency exceptions diff --git a/quest/m4/aac-sbr-config.md b/quest/m4/aac-sbr-config.md index 3e3cdd25a44..d7e363846bd 100644 --- a/quest/m4/aac-sbr-config.md +++ b/quest/m4/aac-sbr-config.md @@ -11,3 +11,5 @@ Follow-up of [moq-dev/moq#7398](https://github.com/moq-dev/moq/pull/7398), which Decided 2026-10-30 (maintainer, follow-up planning after the /quest-afk run). Add the field to moq-mux's public config and delete moq-audio's own parse; test an implicit and an explicit SBR config. Public API: an additive field on `moq_mux::codec::aac::Config`. Wire: none. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/media](/quest/m2/api-shape/media.md) makes `aac::Config` `#[non_exhaustive]` before the cut, so the new field is additive. diff --git a/quest/m4/cache-fairness.md b/quest/m4/cache-fairness.md index 0b6244fed00..a3879079e64 100644 --- a/quest/m4/cache-fairness.md +++ b/quest/m4/cache-fairness.md @@ -43,7 +43,7 @@ share, before building. Open, for the design: what keys a tenant, such as the grant root, which exists today. Pick the same key as -[broadcast fairness](/quest/m3/broadcast-fairness.md)'s tenant keying. +[broadcast fairness](/quest/m5/broadcast-fairness.md)'s tenant keying. Public API: likely a relay cache setting if per-tenant shares need a knob. Wire: none. @@ -54,5 +54,5 @@ Wire: none. ## Related -- [Broadcast fairness](/quest/m3/broadcast-fairness.md) - the same tenant fair share on cluster links +- [Broadcast fairness](/quest/m5/broadcast-fairness.md) - the same tenant fair share on cluster links - [Receive pool](/quest/m5/receive-pool.md) - one per-worker budget covering receive credit and the cache diff --git a/quest/m4/p2p/cli.md b/quest/m4/p2p/cli.md index a965979e7ce..bae71e94129 100644 --- a/quest/m4/p2p/cli.md +++ b/quest/m4/p2p/cli.md @@ -39,6 +39,8 @@ Discovery alone does not initiate a connection. Docs: a "P2P" section in `doc/bin/cli.md` beside the LAN cluster one. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no `max` flag ([signal](/quest/m4/p2p/signal.md)). + ## Required - [Native pairs over ICE and QUIC](/quest/m4/p2p/native-quic.md) - the native-to-native path diff --git a/quest/m4/p2p/signal.md b/quest/m4/p2p/signal.md index e2db53633ce..17e81d827bf 100644 --- a/quest/m4/p2p/signal.md +++ b/quest/m4/p2p/signal.md @@ -85,3 +85,5 @@ never crosses a peer session: a `moq_auth` JWT is a bearer credential, so a peer that received one could replay it against the relay. Rejected: relay-issued, key-bound peer grants with a possession proof (the earlier plan), until a use case needs per-peer scopes. + +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): each selected or admitted peer takes its own `iceServers` (default: `Peers`' list); `max` and its CLI flag go, and `enabled` stays only as the element attribute, not on `Peers`. diff --git a/quest/m4/peer-grant-bound.md b/quest/m4/peer-grant-bound.md index d38d99bf979..6ea92d20a0e 100644 --- a/quest/m4/peer-grant-bound.md +++ b/quest/m4/peer-grant-bound.md @@ -59,4 +59,4 @@ before and after. ## Related - [A regrant re-checks only the routes it can change](/quest/m4/regrant-route-recheck.md) - the route fan-out after a regrant, which this leaves alone; whichever lands second adapts to the other -- [Fair share across broadcasts](/quest/m3/broadcast-fairness.md) - the other per-session CPU and bandwidth fairness concern +- [Fair share across broadcasts](/quest/m5/broadcast-fairness.md) - the other per-session CPU and bandwidth fairness concern diff --git a/quest/m4/perf/shard-default.md b/quest/m4/perf/shard-default.md index a291a85498a..ce7b2d53db1 100644 --- a/quest/m4/perf/shard-default.md +++ b/quest/m4/perf/shard-default.md @@ -59,6 +59,8 @@ way until a measurement justifies the flip. Update `doc/bin/relay/` for the default change. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [no-sentinels](/quest/m2/no-sentinels.md) makes `runtime.workers` `"shared" | "auto" | ` before the cut, so flipping the default changes only the default. + ## Related - [kio channel contention](/quest/m4/perf/kio-channel-contention/README.md) - its per-thread spikes run on the workers diff --git a/quest/m4/perf/stream/codec.md b/quest/m4/perf/stream/codec.md index 54f79ceb181..096f40e9965 100644 --- a/quest/m4/perf/stream/codec.md +++ b/quest/m4/perf/stream/codec.md @@ -57,3 +57,5 @@ Public API: the `tokio_tungstenite` and `tungstenite` re-exports and the migrate in `qmux` and `moq-tokio`. The existing qmux interop tests (the `qmux06` dev-dependency) and the browser path in `js/qmux` must keep passing unchanged. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): qmux's tungstenite exposure is removed before the cut in [api-shape/transport](/quest/m2/api-shape/transport.md), whatever this bench finds; this quest is perf-only. diff --git a/quest/m5/README.md b/quest/m5/README.md index f9af65133f8..0ff4dde5147 100644 --- a/quest/m5/README.md +++ b/quest/m5/README.md @@ -30,6 +30,7 @@ lite-07; bitrate enforcement is not part of the next release. - [Mesh over ICE](/quest/m5/mesh-ice.md) - mesh nodes on different networks connect directly through the P2P line's ICE pairs, once a mesh user needs it - [Video validation hardware is on hand](/quest/m5/video-hardware-access.md) - the machines the validation runs on, including a Raspberry Pi 4/5 for embedded presenting +- [Fair share across broadcasts on cluster links](/quest/m5/broadcast-fairness.md) - broadcasts share a cluster link fairly, so one tenant's priority never starves another's, once a tenant identity exists - [Video hardware validation](/quest/m5/video-hardware.md) - run the encode, capture, and zero-copy paths that were never run on real machines, including PipeWire on KDE, the camera portal, and a Pi - [An Ada NVIDIA GPU is available](/quest/m5/ada-gpu.md) - the hardware AV1 NVENC is verified on - [NVENC AV1](/quest/m5/nvenc-av1.md) - AV1 encode through NVENC, once an Ada-generation GPU is available @@ -58,7 +59,7 @@ lite-07; bitrate enforcement is not part of the next release. - [moq-transport cluster peers](/quest/m5/ietf-cluster-peers.md) - the cluster draft carries the route layer, so moq-transport relays peer again, once a moq-transport relay operator asks - [The moq.pro mesh runs lite-07](/quest/m5/lite07-mesh.md) - the deployment that makes the exemption dead code - [Drop the hidden cluster exemption](/quest/m5/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire -- [Robot teleoperation primitive](/quest/m5/teleop-robot.md) - a `moq-robot` crate for video down and control up, once a robotics consumer appears +- [Robot teleoperation conventions](/quest/m5/teleop-robot.md) - documented track shapes for video down and control up, implemented by the MAVLink gateway, once a robotics consumer appears - [Operator arbitration](/quest/m5/teleop-arbitration.md) - one operator holds control at a time - [MAVLink bridge](/quest/m5/teleop-mavlink.md) - a `moq-mavlink` gateway replacing the VPN plus two unmanaged UDP flows, with QGroundControl and @@ -106,7 +107,6 @@ lite-07; bitrate enforcement is not part of the next release. - [Receive pool](/quest/m5/receive-pool.md) - one byte budget per worker covers every connection's receive credit and the cache, billing each frame once - [Front parking](/quest/m5/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [A route stream's interest is a set of prefixes](/quest/m5/route-interest-prefixes.md) - one Announce Stream covers several subtrees, with floors and certification proved over the set -- [A socket dial learns its peer is behind an older hop](/quest/m5/socket-old-hop-signal.md) - a relay finds the dialed endpoint behind its older moq-lite session and marks that path, so the dial fails `Unsupported` while one to an absent peer still waits - [Fewer allocations in announce fan-out](/quest/m5/announce-fanout-allocs.md) - a deep path costs no more allocations per subscriber than a shallow one - [moq-room scales to large rooms](/quest/m5/room-bench.md) - a benchmark measures `Room` with large participant counts, and polling narrows only if it shows a slope - [Route health](/quest/m5/route-health/README.md) - epoch-only active/passive track recovery over metadata-only subscriptions diff --git a/quest/m5/audio-decode-mediacodec.md b/quest/m5/audio-decode-mediacodec.md index 4578ceef909..e7482483642 100644 --- a/quest/m5/audio-decode-mediacodec.md +++ b/quest/m5/audio-decode-mediacodec.md @@ -28,6 +28,8 @@ behind a new optional audio `mediacodec` feature and the decode seam, on `target - The binding ships in the moq-ffi Android slice, which is how Kotlin and Dart reach it. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. + ## Related - [Android capture](/quest/m3/mobile-capture-android.md) - the video MediaCodec family this sits beside diff --git a/quest/m5/audio-decode-mediafoundation.md b/quest/m5/audio-decode-mediafoundation.md index dee9a050786..f8f15d2955b 100644 --- a/quest/m5/audio-decode-mediafoundation.md +++ b/quest/m5/audio-decode-mediafoundation.md @@ -22,6 +22,8 @@ ones. Behind the decode seam as the first candidate on `target_os = - Verification runs on a Windows host; the per-PR CI only compiles the platform code (`just rs windows`). +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. + ## Related - [Windows decoded frames](/quest/m5/obs-decode-windows.md) - the OBS Windows line this feeds diff --git a/quest/m5/audio-encode-audiotoolbox.md b/quest/m5/audio-encode-audiotoolbox.md index 1535945569b..c1780fcb094 100644 --- a/quest/m5/audio-encode-audiotoolbox.md +++ b/quest/m5/audio-encode-audiotoolbox.md @@ -33,6 +33,8 @@ the encode seam as the platform candidate on macOS and iOS. duplicates as holes and resets AAC between them. Shift the whole timeline by the deficit instead, including the terminal end (found in #4081 review). +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. + ## Required - [AudioToolbox decode](/quest/m3/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it diff --git a/quest/m5/audio-encode-mediacodec.md b/quest/m5/audio-encode-mediacodec.md index 5ef9c74bb0f..638104c4a36 100644 --- a/quest/m5/audio-encode-mediacodec.md +++ b/quest/m5/audio-encode-mediacodec.md @@ -23,6 +23,8 @@ behind the `mediacodec` feature and the encode seam. - Round-trip regression through the MediaCodec decoder; runtime proof on a device or emulator through `just rs android-test`, as in the decode quest. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. + ## Required - [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m5/audio-encode-mediafoundation.md b/quest/m5/audio-encode-mediafoundation.md index d0bb8cf4578..83ea5692653 100644 --- a/quest/m5/audio-encode-mediafoundation.md +++ b/quest/m5/audio-encode-mediafoundation.md @@ -18,6 +18,8 @@ behind the encode seam on Windows. - Round-trip regression through the Media Foundation decoder; verification on a Windows host, since the per-PR CI compiles only. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. + ## Required - [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - changes `Encoder::encode` to a zero-or-more packet return with a flush, which this backend implements diff --git a/quest/m5/auth-http-request-kind.md b/quest/m5/auth-http-request-kind.md index 13d76e6e910..2d6e29756c7 100644 --- a/quest/m5/auth-http-request-kind.md +++ b/quest/m5/auth-http-request-kind.md @@ -29,6 +29,8 @@ yet. Public API: additive (HTTP auth contract fields). Wire: none. +Re-planned 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) removes `auth::Request::{kind, path}`, so this quest starts by re-adding them, additively, only once an auth server asks for per-request decisions. Needs a fresh `/quest-plan` then. + ## Related - [Token auth follow-ups](/quest/m3/token-auth-followups.md) - the rest of #7211's follow-ups diff --git a/quest/m3/broadcast-fairness.md b/quest/m5/broadcast-fairness.md similarity index 96% rename from quest/m3/broadcast-fairness.md rename to quest/m5/broadcast-fairness.md index 6bf43ec5e7b..206992baba0 100644 --- a/quest/m3/broadcast-fairness.md +++ b/quest/m5/broadcast-fairness.md @@ -13,7 +13,7 @@ strict priority across the session, as today. ## Plan -Needs a fresh `/quest-plan` before starting: there is no settled design. +Needs a fresh `/quest-plan` before starting: there is no settled design. Parked in m5: Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). No tenant identity exists to key the share on, and the scheduler trait change stays cheap after the cut. Every transport already shares moq-quic's scheduler since qmux moved onto it ([moq-dev/moq#6231](https://github.com/moq-dev/moq/pull/6231)); revisit once the auth line carries a tenant identity. diff --git a/quest/m5/emsg.md b/quest/m5/emsg.md index fa6eae92737..de5c10428c4 100644 --- a/quest/m5/emsg.md +++ b/quest/m5/emsg.md @@ -55,6 +55,8 @@ Test version 0 and version 1 boxes, an emsg before the first moof, several on one fragment, an unknown scheme, a zero duration, and a round trip that is byte-identical. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one catalog `events` section, `[{track, scheme, rendition?}]` keyed by scheme URI, shared with SCTE-35, ID3, and FLV script data as schemes with their own parsing helpers, instead of one top-level section per format. + ## Related - [ID3 catalog section](/quest/m5/id3.md) - gives one payload type carried here a diff --git a/quest/m5/ffi-e2ee.md b/quest/m5/ffi-e2ee.md index 4181c2c45c2..4653b521b5d 100644 --- a/quest/m5/ffi-e2ee.md +++ b/quest/m5/ffi-e2ee.md @@ -20,6 +20,8 @@ the binding layer, and keep the encrypting publisher's refusal of a shared or explicit epoch. Add a binding test that decrypts a JS-published broadcast and the reverse to the interop suite. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the bindings wrap moq-crypto's concrete `broadcast::{Producer, Consumer}` directly, without waiting on [net-wrap](/quest/m5/net-wrap/README.md). + ## Required - [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md) - the producer these bindings wrap diff --git a/quest/m5/json-value-diff.md b/quest/m5/json-value-diff.md index 9a08b3abb98..b003314adb3 100644 --- a/quest/m5/json-value-diff.md +++ b/quest/m5/json-value-diff.md @@ -54,6 +54,8 @@ Context: - `moq_json::diff` has no in-repo callers since #7400. With a `Value` diff it could take `&Value`, or be removed. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `moq_json::{diff, Diff}` become private before the cut ([api-shape/media](/quest/m2/api-shape/media.md)), so this work is internal. + ## Related - [Compile time audit](/quest/m3/audit-compile-time.md) diff --git a/quest/m5/latency-ledger.md b/quest/m5/latency-ledger.md index 65d6bb999bd..840823a25d7 100644 --- a/quest/m5/latency-ledger.md +++ b/quest/m5/latency-ledger.md @@ -46,6 +46,8 @@ probes, which was the right trade to get it running. This quest promotes them. so the sum-to-end-to-end identity (with its named `unaccounted` remainder) can be added once a spanning clock exists. +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): hang echo's producer-less `latency` is deleted before the cut ([api-shape/media](/quest/m2/api-shape/media.md)), so this adds its measurement additively. + ## Required - [Rust reporters](/quest/m3/stats/rust.md) - `moq play --echo` publishes the feedback snapshot these stages join diff --git a/quest/m5/net-wrap/traits.md b/quest/m5/net-wrap/traits.md index 701fae0d39c..d8bebbc5399 100644 --- a/quest/m5/net-wrap/traits.md +++ b/quest/m5/net-wrap/traits.md @@ -68,6 +68,8 @@ Public API: new moq-net traits, plus the hidden test-wrapper feature. Wire: none Decided 2026-10-22 (maintainer): the traits break moq-net's public API, so they wait for the breaking release cut. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): trait only what adopters call: the broadcast, track, group, and frame producer chain, `track::Consumer` to `Subscriber` to `Ordered`, `requests` with `requested_track`, `tracks`, and datagrams. `Fill`, `Fetching`, and `Resolving` stay concrete until a wrapped consumer needs them. + ## Required - [Breaking release cut](/quest/m3/release/cut.md) - the traits land after the cut that ships m2's breaks diff --git a/quest/m5/rate-grant.md b/quest/m5/rate-grant.md index 971748bf55d..83236b96a43 100644 --- a/quest/m5/rate-grant.md +++ b/quest/m5/rate-grant.md @@ -44,3 +44,5 @@ target never exceeds the cap minus overhead; a raised cap lets it climb back. Public API: the in-band grant types in `rs/moq-net` and `js/net` gain the two rates, and the publishers gain a clamp. Wire: the AUTH grant gains optional rates, on the next unpublished lite version after lite-07 only. + +Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/net](/quest/m2/api-shape/net.md) makes `auth::Grant` `#[non_exhaustive]` before the cut, so the rates are additive fields. diff --git a/quest/m5/receive-pool.md b/quest/m5/receive-pool.md index ebf6c2f818d..ba4f651f8a7 100644 --- a/quest/m5/receive-pool.md +++ b/quest/m5/receive-pool.md @@ -77,5 +77,5 @@ harness. Report peak resident bytes against the budget, evictions, and throughpu sets half of `MIN_RECEIVE_WINDOW` - [Perf](/quest/m4/perf/README.md) - the per-worker hot paths this budget must not add contention to -- [Broadcast fairness](/quest/m3/broadcast-fairness.md) - the receive rank's +- [Broadcast fairness](/quest/m5/broadcast-fairness.md) - the receive rank's fairness domains diff --git a/quest/m5/socket-old-hop-signal.md b/quest/m5/socket-old-hop-signal.md deleted file mode 100644 index c112e03adeb..00000000000 --- a/quest/m5/socket-old-hop-signal.md +++ /dev/null @@ -1,97 +0,0 @@ -# [L] A socket dial learns its peer is behind an older hop - -## Goal - -A socket dial to a peer whose endpoint an older moq-lite hop withholds fails -with `Unsupported` instead of waiting, while a dial to a peer that isn't -online yet keeps waiting. The relay holding the older session tells the -dialer on the wire. Dialers and relays on versions without that signal keep -today's wait. - -## Plan - -Planned 2026-11-04 with the maintainer, from the limit -[moq-dev/moq#7888](https://github.com/moq-dev/moq/pull/7888) documented. -Milestone m2 (maintainer). - -Where it gets lost: an endpoint's `.server/` broadcast is hidden, and -before lite-07 ANNOUNCE_REQUEST has no hidden opt-in. When a peer `P` -reaches its relay `R` over a moq-lite-06 (or older) client session whose -publish half isn't opted into hidden routes, `R` never learns `P`'s -endpoint. Since #7888, `P` sees this from its own session version -(crate-private `HiddenWithheld` in `rs/moq-net/src/model/origin.rs`) and -fails its own dials and accepts. A lite-07 dialer `D` gets nothing: it waits -for `P`'s announcement as for a peer not online yet. `R` can't tell the two -apart either, since it never sees `P`'s hidden path. What `R` does know is -which of its sessions are older moq-lite with a publish half not opted into -hidden, and each one's publish scope from its grants. - -The signal must be about the peer, not the grant. A session's publish -grant says only that it *may* publish under a prefix, not that the dialed -endpoint exists behind it. A marker covering an older session's grant would -also fail a dial to a peer that isn't online yet under that grant, which is -exactly the case that must keep waiting. So the grant only narrows where to -look, and the evidence has to name the endpoint. - -Recommended design, to settle in this quest: - -- **Find the endpoint.** When a dial's interest in `/.server/` - reaches a relay, the relay asks each of its older sessions whose publish - grant covers that path, with an ANNOUNCE_REQUEST naming the path, held - open while the dial waits so a peer that comes online later is seen. Such a - request names the hidden segment, so a lite-06 peer does announce its - endpoint (#7888's round-1 review response, - `rs/moq-net/src/lite/publisher.rs`). A session that may publish nothing - (a viewer) is never asked. -- **Tell the dialer.** If an older session announces the endpoint, the relay - sends a marker for that exact path on the wire: the endpoint exists behind - an older hop. `D`'s endpoint fails the dial with `Unsupported`, and only - for that path. With no answer, nothing is marked, and the dial waits as - for an absent peer. The marker tracks that announcement: it goes when the - older session unannounces the endpoint or ends, whichever comes first. -- **An announced route wins.** While any route announces the endpoint (for - example, a current session overlapping an older one during a reconnect), - the dial uses it and ignores the marker. -- **Across a cluster.** Relay-to-relay links ask for everything, not for a - dialer's narrow interest, so the relay holding the older session may never - see the dial, and a dial sends no SUBSCRIBE until the endpoint is - announced. Settle how the dialer's narrow interest reaches the holding - relay (for example, cluster links forwarding narrow interest under - `.server`), and how markers cross cluster links. -- **Where the marker rides.** Its own announce-stream message, or a flag on - the [route layer](/quest/m2/cluster-routing/routes/README.md)'s messages if - that layer has landed. Choose whichever leaves the draft simpler. -- **Not chosen:** routing the dial once the probe finds the endpoint. The - peer can't tell that its relay probes, so it keeps failing its own dials - and accepts (#7888), and the session would connect from one side only. - -Versions and compatibility: - -- The signal goes in whichever moq-lite wip is current when this lands - (lite-07-wip before its cut, per the - [freeze policy](/quest/m2/lite07-finalize.md), otherwise the next wip), - with its draft text in the same PR. -- A dialer whose relay doesn't send it, or whose own session predates it, - waits as it does today. Published versions are unchanged. -- moq-transport hops carry no marker, so a dial across one waits as today. - No IETF-only surface is added. -- Rust, `@moq/net`'s socket and moq-ffi behave alike. `doc/concept/socket.md` - and the `Endpoint` rustdoc replace the "waits as for an absent peer" - limit. - -Tests, in the relay harness (`rs/moq-net/tests/integration/socket.rs`): a -lite-07 dial to a peer behind a lite-06 hop fails `Unsupported`, including -across a cluster hop. A dial to an absent peer still waits, including one -whose path lies under another lite-06 session's publish grant. A viewer-only -lite-06 session is never asked. A dial that starts before the older -session announces the endpoint fails `Unsupported` once it does. A marker goes when the older session -unannounces the endpoint, and a current route announcing the same endpoint -wins over it. A peer opted into hidden routes over lite-06 -(`an_older_hop_opted_into_hidden_connects`) still connects. - -Public API: none expected; dials return the existing `Error::Unsupported`. -Wire: a new per-path marker on the current moq-lite wip. - -## Related - -- [Routes and announces](/quest/m2/cluster-routing/routes/README.md) - the route layer a marker may ride, and how interest crosses cluster links diff --git a/quest/m5/stats-encoder-feedback.md b/quest/m5/stats-encoder-feedback.md index 29c7ee76404..821d42c5345 100644 --- a/quest/m5/stats-encoder-feedback.md +++ b/quest/m5/stats-encoder-feedback.md @@ -85,6 +85,8 @@ Open, to settle before starting (moved from the like the token rights, or carry the catalog's broadcast in the snapshot and ignore reports for another. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): encoders take pressure, not echo. `moq_mux::rate::Control` accepts a generic pressure input beside the bandwidth estimate; a hang or moq-stats aggregator turns announced echoes into it, moq-cli wires the two, and the encode producers drop their `echo` option. + ## Required - [Rust reporters](/quest/m3/stats/rust.md) - the viewers that report and diff --git a/quest/m5/teleop-arbitration.md b/quest/m5/teleop-arbitration.md index f6e47033c64..4fd076cd8b1 100644 --- a/quest/m5/teleop-arbitration.md +++ b/quest/m5/teleop-arbitration.md @@ -42,4 +42,4 @@ not attempt. ## Required -- [Robot teleoperation primitive](/quest/m5/teleop-robot.md) +- [Robot teleoperation conventions](/quest/m5/teleop-robot.md) diff --git a/quest/m5/teleop-mavlink.md b/quest/m5/teleop-mavlink.md index 95b6811b753..bbe93b62108 100644 --- a/quest/m5/teleop-mavlink.md +++ b/quest/m5/teleop-mavlink.md @@ -89,5 +89,5 @@ small, real contribution and its own future quest. ## Required -- [Robot teleoperation primitive](/quest/m5/teleop-robot.md) +- [Robot teleoperation conventions](/quest/m5/teleop-robot.md) - [Operator arbitration](/quest/m5/teleop-arbitration.md) diff --git a/quest/m5/teleop-proof.md b/quest/m5/teleop-proof.md index 2b36f410164..4bdb3d6e483 100644 --- a/quest/m5/teleop-proof.md +++ b/quest/m5/teleop-proof.md @@ -20,7 +20,7 @@ otherwise dominates the latency budget and would make the demo a measurement of somebody's webcam. The ground station's catalog and delivery-class shapes come from a zod -schema mirroring the `moq-robot` types, written once and extending the root +schema mirroring the documented robot conventions, written once and extending the root schema through the same seam `js/hang/src/catalog/root.ts` uses (there is no `@moq/mux`). Decided 2026-10-08: no separate `@moq/robot` package until a second browser consumer needs it; the schema folds in here. A browser @@ -37,4 +37,4 @@ the maintenance. ## Related -- [Robot teleoperation primitive](/quest/m5/teleop-robot.md) - the Rust types the zod schema mirrors +- [Robot teleoperation conventions](/quest/m5/teleop-robot.md) - the conventions the zod schema mirrors diff --git a/quest/m5/teleop-robot.md b/quest/m5/teleop-robot.md index 23b7c46705b..f915a9bb124 100644 --- a/quest/m5/teleop-robot.md +++ b/quest/m5/teleop-robot.md @@ -1,13 +1,23 @@ -# [L] Robot teleoperation primitive +# [M] Robot teleoperation conventions ## Goal -A `moq-robot` crate carries the track shapes and discovery every teleoperated -machine needs, so an integrator writes an adapter rather than a stack. It is -the gate for the rest of the questline. +The track shapes and discovery every teleoperated machine needs are +documented conventions in `doc/`, built on moq-net and moq-json, that +[the MAVLink gateway](/quest/m5/teleop-mavlink.md) implements, so an +integrator writes an adapter rather than a stack. There is no `moq-robot` +crate. It is the gate for the rest of the questline. ## Plan +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): ✅ no `moq-robot` crate (rejected: a generic robot +crate, too niche for a published library with no second consumer). The +shapes below become documented conventions, and `moq-mavlink` ships as a +moq-cli gateway like moq-srt. If a second consumer appears, generalize +moq-boy's announce-prefix fan-in into moq-net instead of adding a robot +crate. Where the text below says "the crate", read the conventions and +their implementation in moq-mavlink. + Decided 2026-10-08: parked in m5. No teleoperation consumer needs the crate yet; telemetry beside video needs [data sync](/quest/m3/watch-data-sync.md), not this primitive. From 356439fd3814202e2c201b7fd694be6e58e345b2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:18:50 -0800 Subject: [PATCH 04/11] quest: address review threads on the API sweep plan Fix or clarify each automated review finding on the sweep's quest edits, and fold #8088's with_proxy follow-up into api-shape/net. Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/publish-capture.md | 5 ++- quest/m1/hosted-assets.md | 20 ++++++--- quest/m2/api-shape/README.md | 2 +- quest/m2/api-shape/media.md | 6 ++- quest/m2/api-shape/net.md | 17 ++++++-- quest/m2/api-shape/transport.md | 10 ++++- quest/m2/audio-codec-seam.md | 5 ++- quest/m2/cluster-routing/routes/acceptance.md | 7 +++ quest/m2/finish-self.md | 5 ++- quest/m2/group-drops.md | 10 +++-- quest/m2/no-sentinels.md | 4 +- quest/m2/rendition-stats-type.md | 5 +++ quest/m2/time-addressing/model.md | 19 +++++--- quest/m3/README.md | 2 +- quest/m3/cli-packaging.md | 14 +++--- quest/m3/fetch-synced.md | 4 +- quest/m3/h265-min-width.md | 5 +-- quest/m3/import-metadata-policy.md | 6 +-- quest/m3/json-snapshot-resync.md | 25 +++++------ quest/m3/mesh/README.md | 7 ++- quest/m3/mesh/cert-credentials.md | 2 +- quest/m3/mesh/endpoint.md | 28 ++++++++++-- quest/m3/nixpkgs-cli.md | 4 +- quest/m3/probe-rung-disable-js.md | 4 +- quest/m3/quic-ack-hook.md | 43 +++++++++++-------- quest/m3/release/api-review.md | 6 ++- quest/m3/release/cut.md | 7 ++- quest/m3/release/qmux-js-retire.md | 7 +++ quest/m3/release/qmux-rs-retire.md | 11 ++++- quest/m3/rtc-pacing.md | 7 ++- quest/m4/binding-export-coverage.md | 13 +++--- quest/m4/p2p/README.md | 16 +++---- quest/m4/p2p/cli.md | 8 ++-- quest/m4/p2p/signal.md | 28 ++++++------ quest/m4/p2p/watch.md | 2 +- ...te-35-ad-cue-signaling-carried-opaquely.md | 11 ++--- quest/m5/README.md | 2 +- quest/m5/audio-encode-audiotoolbox.md | 9 ++-- quest/m5/audio-encode-mediacodec.md | 8 ++-- quest/m5/audio-encode-mediafoundation.md | 6 ++- quest/m5/emsg.md | 2 +- quest/m5/ffi-e2ee.md | 8 ++-- quest/m5/id3.md | 16 ++++--- quest/m5/teleop-robot.md | 23 +++++----- 44 files changed, 285 insertions(+), 164 deletions(-) diff --git a/quest/m1/explicit-state/publish-capture.md b/quest/m1/explicit-state/publish-capture.md index 2bee77f4bee..ebabc5d5ca5 100644 --- a/quest/m1/explicit-state/publish-capture.md +++ b/quest/m1/explicit-state/publish-capture.md @@ -49,6 +49,9 @@ Also sweep: `AnnounceMode`, and an invalid `announce` attribute suspends announcing through `#invalid` like every other attribute, instead of the getter returning `undefined` (added 2026-11-07, maintainer, /quest-plan from the - API shape audit). + API shape audit). An invalid attribute stays detectable the way every + other one already is: its parse error is thrown from + `attributeChangedCallback` and `enabled` turns false. The getter's type + narrows, so TypeScript readers still compile; say so in the PR. - `js/moq-boy/src/game.ts`: a command sent while disconnected replays on reconnect. diff --git a/quest/m1/hosted-assets.md b/quest/m1/hosted-assets.md index 7973ba7c5d4..4c13093eb81 100644 --- a/quest/m1/hosted-assets.md +++ b/quest/m1/hosted-assets.md @@ -12,10 +12,16 @@ needs the polyfill must also import `@moq/libav` and set its mutable ## Plan -Found by the 2026-11-07 API shape audit (browser media). Move `assets` and -its resolver into `@moq/hang`, the shared dependency whose -`Util.Libav.polyfill()` (`js/hang/src/util/libav.ts`) loads libav, and have -the polyfill take its base from it. `@moq/watch` and `@moq/publish` -re-export it, so their existing `assets()` callers keep working and nothing -breaks. `@moq/libav` stays an implementation dependency. Future hosted files -(the watch worker) join the same call. Test it on the CSP demo pages. +Found by the 2026-11-07 API shape audit (browser media). Move the resolver +into `@moq/hang`, the shared dependency whose `Util.Libav.polyfill()` +(`js/hang/src/util/libav.ts`) loads libav, as a small per-package directory +helper, and have the polyfill take its base from the package that loads it. +`@moq/watch`'s and `@moq/publish`'s `assets()` keep their signatures and +their own directories, so an app that hosts each package's files in a +different directory keeps working and nothing breaks; each also sets the +libav base on the `@moq/hang` instance it imports, so a page that resolves +two `@moq/hang` copies still configures the one each package uses. Each +package's `assets/` ships the libav wasm it needs. `@moq/libav` stays an +implementation dependency. Future hosted files (the watch worker) join the +same call. Test it on the CSP demo pages, including watch and publish +configured with different directories. diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index 8ecf8f03755..4d5f362324e 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -54,7 +54,7 @@ Rejected in planning: ## Required -- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, and priority surface, and no public wire codes +- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, proxy, and priority surface, and no public wire codes - [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals - [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name - [Native media's small surface fixes](/quest/m2/api-shape/native.md) - audio encode internals go private, `on_demand` has one meaning, and video and render setters fold into their constructors diff --git a/quest/m2/api-shape/media.md b/quest/m2/api-shape/media.md index e78e1a7dc6f..fbd3ae4f7c3 100644 --- a/quest/m2/api-shape/media.md +++ b/quest/m2/api-shape/media.md @@ -14,7 +14,11 @@ Each item below has one path and one name: - moq-mux stops re-exporting `mp4_atom` (`container::fmp4`), and `fmp4::Wire::{new, trak}` become `pub(crate)` or give way to the one accessor moq-hls needs, so an mp4-atom bump (two are planned in m3) is not - a moq-mux break. + a moq-mux break. The errors leak it too: `moq_mux::Error::Mp4` and + `fmp4::Error::Mp4` wrap `mp4_atom::Error`, `fmp4::Error::{UnknownCodec, + UnsupportedCodec}` carry `mp4_atom::FourCC` and `mp4_atom::Codec`, and + both have `From`. Those variants carry an opaque source + and moq-mux's own codec name, and the public `From` impls go. - hang's echo drops `latency` in Rust, JS, and the draft: nothing produces it, and [latency-ledger](/quest/m5/latency-ledger.md) adds its measurement additively. diff --git a/quest/m2/api-shape/net.md b/quest/m2/api-shape/net.md index 001a1c091ff..e342b8957c8 100644 --- a/quest/m2/api-shape/net.md +++ b/quest/m2/api-shape/net.md @@ -53,6 +53,14 @@ its JS and binding mirrors: - `group::MAX_CACHE_BYTES` becomes `pub(crate)`: byte-holes turns it from a size cap into a tail budget, and moq-json's `max_group_bytes` keeps its own 32 MiB default. +- Remove `origin::Consumer::with_proxy` (from + [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)) in favor of + `origin::Producer::with_proxy`, which already reaches every consumer taken + from that producer. Only tests call the consumer override, but the moq-net + integration harness (`rs/moq-net/tests/integration/support/harness.rs`) + passes it about 195 scoped consumers, and `mount.rs` and moq-mux's + `container/test_util.rs` call it too; each sets proxy on the producer it + consumes from instead. - `auth::Grant` gets `#[non_exhaustive]`, since [rate-grant](/quest/m5/rate-grant.md) adds rates to it; callers outside moq-net build it from `Grant::default()`. @@ -61,12 +69,15 @@ its JS and binding mirrors: Found by the 2026-11-07 API shape audit (net model and net session); see the [epic](/quest/m2/api-shape/README.md). Each item is XS except -`Attempt::client` and `Compression` (S each). `RefusalKind` is a stats-wire +`Attempt::client`, `Compression`, and the `with_proxy` removal (S each). `RefusalKind` is a stats-wire field, so say in the PR which deployed dashboards read it. If #8063 has not merged when this starts, leave the un-hide for a follow-up and say so. Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the `RouteEvent` struct, the stats arguments, the cache cap, and `Grant`. The `RouteEvent` reshape replaces [moq-dev/moq#7862](https://github.com/moq-dev/moq/pull/7862)'s -accessors; if its author takes the reshape in that PR, it lands there for -credit and this item only un-hides. +accessors. #7862 closed without taking it, so the reshape lands here. + +Decided 2026-11-07 (maintainer, /quest-complete, from +[moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088)'s follow-ups): +✅ remove `origin::Consumer::with_proxy` in favor of the producer's. diff --git a/quest/m2/api-shape/transport.md b/quest/m2/api-shape/transport.md index 14d26b26390..c0315582702 100644 --- a/quest/m2/api-shape/transport.md +++ b/quest/m2/api-shape/transport.md @@ -18,8 +18,14 @@ takes the raw upgraded IO plus a role, `Error::WebSocket` is opaque, and `pub use tokio_tungstenite` goes (`rs/qmux/src/ws.rs`), so a tungstenite major is not a qmux break. -- moq-tokio's `server::Request::quic()` is removed; nothing outside the - crate calls it, and it exposes the QUIC backend through the session API. +- moq-tokio's `server::Request::quic()` is removed, since it exposes the QUIC + backend's connection through the session API. Its one outside caller, the + relay's `pacer()` (`rs/moq-relay/src/incoming.rs`), clones it to apply + changed bitrate caps after acceptance, which `with_quic_limits` cannot do. + It gets a narrow replacement: a cloneable live-limits handle (for example + `Request::quic_limits() -> Option` with `set(moq_quic::Limits)`), + `None` on qmux streams as today, so the relay keeps updating caps on a + running session without naming the connection. ## Plan diff --git a/quest/m2/audio-codec-seam.md b/quest/m2/audio-codec-seam.md index 4180bf7d282..516e03c47ac 100644 --- a/quest/m2/audio-codec-seam.md +++ b/quest/m2/audio-codec-seam.md @@ -18,6 +18,9 @@ MediaCodec, Media Foundation, and WebCodecs in m5's audio encode and decode quests) emits zero or more outputs per call and needs a flush, so each would otherwise break `encode`'s one-packet return in its own release. -Mirror moq-video's names and return types. moq-ffi, moq-c, and the wrappers +Mirror moq-video's names and return types. Prove delayed and multiple +outputs and flushing in the shared encoder and decoder tests with a test +codec that buffers, since no backend in this repository does yet; the m5 +platform backends rely on those tests rather than each owning them. moq-ffi, moq-c, and the wrappers follow if they expose the codec. Bench the libopus path before and after, since it allocates per call if the return becomes a `Vec`. diff --git a/quest/m2/cluster-routing/routes/acceptance.md b/quest/m2/cluster-routing/routes/acceptance.md index c792a7450c4..81a13656808 100644 --- a/quest/m2/cluster-routing/routes/acceptance.md +++ b/quest/m2/cluster-routing/routes/acceptance.md @@ -74,6 +74,13 @@ wildcards, a hidden exportable alternative under one selection, epochless Restar grant union crossing the scoped boundary each way (a `**` token added, then expiring). Fixtures are public and time-mocked, wired into CI alongside Rust/JS interop. +Mounts get the same continuity checks (`rs/moq-net/tests/integration/mount.rs`): +a claim whose predecessor covers a mount's target arrives beneath the mount +point exactly as it does unmounted, on lite-06 and lite-07. This replaces +the deleted mount-takeover quest, whose `Takeover` event +[moq-dev/moq#8063](https://github.com/moq-dev/moq/pull/8063) removes in +favor of the claim's instance; if #8063 closes unmerged, restore that quest. + Benchmark origins, broadcasts per origin, neighbors, active tracks/fronts, and announce cursors independently. A route update must not expand back into per-broadcast table rewrites or poll unrelated fronts. Measure messages, bytes, diff --git a/quest/m2/finish-self.md b/quest/m2/finish-self.md index 73bba9f276b..695aa7bf2bb 100644 --- a/quest/m2/finish-self.md +++ b/quest/m2/finish-self.md @@ -5,7 +5,10 @@ Every public importer and producer whose `finish` takes `&mut self` takes `self` instead, so a finished producer cannot be written to and no runtime "already finished" refusal is needed. moq-rtmp and moq-srt already consume -on finish. +on finish. A `Clone` producer that shares its state (moq-json's +`snapshot`, `stream`, and `window` producers, and moq-mux's +`catalog::Producer`) still consumes the handle it finishes with, but its +other clones can still write, so it keeps the shared runtime refusal. ## Plan diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 41c4790ec67..d759e555932 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -79,9 +79,13 @@ receive-window eviction can wait for the header, take the no-wire path, and remove this quest from [lite07-finalize](/quest/m2/lite07-finalize.md)'s Required. -Public API: additive for a separate read; breaking if folded into `recv_group` -(its `Result>` return changes for every caller), with -MIGRATE notes. `@moq/net` and the bindings mirror it only with a named consumer. +Public API: breaking for `track::Ordered` only. Its one read, +`poll_next_group` (and its async wrapper), returns an item enum instead of +`Result>`: a group or a `Gap { range, error }`. +Callers match the new item, and a caller that ignores drops takes the group +arm; the PR's MIGRATE notes say so. `recv_group` and the unordered cursor are +unchanged, so a reader that needs drop accounting reads through `Ordered`. +`@moq/net` and the bindings mirror it only with a named consumer. Wire: possibly lite-07 (SUBSCRIBE_DROP for a stopped group), decided here. ## Required diff --git a/quest/m2/no-sentinels.md b/quest/m2/no-sentinels.md index 29ca57b0078..2bb41c4074b 100644 --- a/quest/m2/no-sentinels.md +++ b/quest/m2/no-sentinels.md @@ -7,7 +7,9 @@ No public type uses a huge value or zero as a marker for "none" or - `moq_net::transport::ReceiveWindow.connection` is documented as `u64::MAX` "when streams share none"; it becomes `Option`, - matching `transport::Limits.receive_window`. + matching `transport::Limits.receive_window`. A zero connection window lets + no stream receive a byte, so a transport that would report one is + misconfigured and errors at setup. - `cache_duration` defaults to `Duration::MAX` on `origin::Config` and `broadcast::Info` in moq-net, and `moq_relay::cache::Cache.duration` does the same; each becomes `Option`, `None` meaning no ceiling. diff --git a/quest/m2/rendition-stats-type.md b/quest/m2/rendition-stats-type.md index 2157accdc23..99c04597350 100644 --- a/quest/m2/rendition-stats-type.md +++ b/quest/m2/rendition-stats-type.md @@ -23,5 +23,10 @@ schemas, which would lose the 53-bit integer check on read. Added 2026-11-07 (maintainer, /quest-plan from the API shape audit): `Video.Stats` and `Audio.Stats`, a third and fourth copy of the shape. +Every counter in the schema is optional, but the encoders initialize theirs +and do arithmetic on them, so these two derive from the schema input with +the counters they always set made required (for example +`Required, "frames" | "bytes" | ...>>` +plus the optional rest), rather than restating fields or loosening them. It changes a published TypeScript type, so it lands before the cut. diff --git a/quest/m2/time-addressing/model.md b/quest/m2/time-addressing/model.md index 19a777ebf0a..89165d03923 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -130,10 +130,14 @@ recorded only sequencing. tracks stay independent. - **No local clock in the model.** Added 2026-11-07 (maintainer, /quest-plan from the API shape audit): `Timestamp::now()`, the only model - API that reads the local clock, is removed, and its caller (moq-boy) - stamps from its own clock. `Timed

` moves from moq-net's root to - moq-json, whose producers and readers are its only users, and its `at` - becomes required under the rule above. + API that reads the local clock, is removed, and its callers stamp from + their own clock: moq-boy, moq-hls, moq-room, moq-stats, moq-bench, hang's + video example, moq-tokio's examples, and tests across moq-net, moq-json, + moq-mux, and moq-hls. `Timed

` moves from moq-net's root to moq-json, + since moq-net never uses it internally, and its `at` becomes required under + the rule above. Every crate that names `moq_net::Timed` follows the move: + moq-mux, moq-ffi, moq-c, moq-cli, moq-room, moq-boy, moq-hls, moq-stats, + and moq-net-tests. - **One anchor rule.** Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): ✅ collapse `Anchor` to `{Oldest, Relative(n), Time(ts)}` with every end inclusive (rejected: keep `Absolute` and make it inclusive; only add `Oldest`). Today an `Absolute` @@ -141,7 +145,12 @@ recorded only sequencing. (`rs/moq-net/src/model/subscription.rs`), and "oldest" is the sentinel `Relative(u64::MAX)`. Once keys are starts, `Absolute(key)` and `Time(ts)` name the same group, so `Absolute` goes; a legacy exclusive end `E` maps - to `Time(E - 1)`, since legacy keys pass through. `Oldest` is explicit and + to `Time(E - 1)`, since legacy keys pass through. An exclusive end of 0 + (today `sequence_bounds(..0)` and an empty range list's + `Subscription::end()`) selects nothing, so it is dropped as an empty range + before conversion, never saturated to `Time(0)`, which would include + group 0. Regressions cover `E = 0` and `E = 1` beside the legacy round + trips. `Oldest` is explicit and encoded the same on every wire (lite-07, lite-06 and earlier, IETF), where today the lite encoder treats any `back > MAX_QUIC` as oldest and the model does not. `Range::groups(RangeBounds)` and diff --git a/quest/m3/README.md b/quest/m3/README.md index d83e7f83e25..8b16f273dbc 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -79,7 +79,7 @@ federation) land. - [Android capture](/quest/m3/mobile-capture-android.md) - Rust captures through NDK/JNI on Android, reusing the existing codecs and setting the catalog rotation - [Latest readers use Range::live()](/quest/m3/readers-range-live.md) - after #6278, readers start at the live edge without waiting on `largest()` - [PulseAudio capture periods](/quest/m3/pulseaudio-capture-period.md) - capture on cpal's PulseAudio host arrives in short periods, not the server's 2 s default fragment, proven on the null sink's monitor -- [A JSON snapshot consumer resyncs after a bad frame](/quest/m3/json-snapshot-resync.md) - a decode failure drops the group with a typed error, so `@moq/room` and moq-boy resume at the next snapshot +- [A JSON snapshot consumer resyncs after a bad frame](/quest/m3/json-snapshot-resync.md) - a decode failure drops the group and the consumer resumes at the next snapshot by itself, so `@moq/room` and moq-boy keep reading - [Go module proxy](/quest/m3/go-module-proxy.md) - `moq.dev/moq-ffi` ships from a static GOPROXY we host, so its staticlibs stop growing git history by ~61 MiB per release - [Go per-platform lib modules](/quest/m3/go-ffi-platform-modules.md) - a Go build downloads only the host's staticlib, and `go mod vendor` works - [Dart on iOS](/quest/m3/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can diff --git a/quest/m3/cli-packaging.md b/quest/m3/cli-packaging.md index 3169af1175c..7dcbbcdd480 100644 --- a/quest/m3/cli-packaging.md +++ b/quest/m3/cli-packaging.md @@ -18,17 +18,17 @@ documents the `--features capture` build. Decided 2026-10-26 (maintainer): defaults stay lean, and releases build everything. A default skips any feature that is expensive to build or relies on a system library, so `cargo build` and `cargo install moq-cli` stay fast -and portable. moq-cli gains a `release` feature that turns on `capture`, +and portable. moq-cli gains a `full` feature that turns on `capture`, `play`, `openh264`, `vaapi`, `nvidia`, and `v4l2` where the platform has it, and every distribution (the release binaries, Nix, Docker, winget, Homebrew) builds with it. `doc/bin/cli.md` tells source builders to pass -`--features release`. This replaces the earlier plan to turn `capture` and +`--features full`. This replaces the earlier plan to turn `capture` and `play` on by default. The individual sub-features stay, so a self-compiler can still pick a subset. `vaapi` and `nvidia` load their driver libraries at runtime (dlopen), so they -belong in `release`. The microphone pulls ALSA through cpal, which is why -`release` waits on [ALSA without a load-time link](/quest/m3/capture-alsa-link.md); +belong in `full`. The microphone pulls ALSA through cpal, which is why +`full` waits on [ALSA without a load-time link](/quest/m3/capture-alsa-link.md); `play` pulls winit plus a GPU stack. macOS and Windows use OS frameworks and add nothing. @@ -52,7 +52,7 @@ without NVENC; Pi 4, CM4, Zero 2 W, and Orin NX and above encode. RK3588 encodes through rkmpp in a vendor kernel, not V4L2, so it stays on the `moq-gst` route. -`pipewire` stays out of `release` (decided 2026-10-06, reaffirmed +`pipewire` stays out of `full` (decided 2026-10-06, reaffirmed 2026-10-26): it needs libpipewire-0.3 to load, the same load-time requirement [ALSA](/quest/m3/capture-alsa-link.md) removes. It joins once it loads lazily. @@ -61,9 +61,9 @@ its remaining work was one release feature flag and a doc note. Decided in the 2026-10-06 audit: this does not wait on the library `capture` defaults. moq-cli's `capture` feature enables `moq-video/capture` -and `moq-audio/capture` explicitly, and `release` enables `capture`. +and `moq-audio/capture` explicitly, and `full` enables `capture`. -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the moq-cli feature that enables everything is named `full`, not `release`. +Renamed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the moq-cli feature that enables everything is named `full`, not `release`, so this quest and its followers say `full`. ## Required diff --git a/quest/m3/fetch-synced.md b/quest/m3/fetch-synced.md index f55b9b3863a..45f85c9d539 100644 --- a/quest/m3/fetch-synced.md +++ b/quest/m3/fetch-synced.md @@ -13,6 +13,4 @@ Decided 2026-10-30 (maintainer, follow-up of [moq-dev/moq#7366](https://github.c - The 30 s deadline stays fixed and keeps bounding the group fetch and the response body's frame reads. Making it configurable was not wanted (2026-10-30). - Tests: a fetch for an unannounced broadcast on a synced origin returns 404 without advancing the clock to the deadline. A fetch whose broadcast is announced after the request but before sync still serves the group. A fetch for an unannounced broadcast while an upstream session hasn't synced yet waits for that sync; an announced broadcast is served without waiting on it. -Public API: none. Wire: none. - -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): this adds a public method, so its Public API line says so instead of "none". +Public API: adds `Following::poll_synced` to moq-net. Wire: none. diff --git a/quest/m3/h265-min-width.md b/quest/m3/h265-min-width.md index 8a7774dd27c..4c888258f61 100644 --- a/quest/m3/h265-min-width.md +++ b/quest/m3/h265-min-width.md @@ -38,11 +38,10 @@ prerequisite inside this quest. it comes from the failed open or a per-driver table. Check what NVENC and VideoToolbox report for the same case. -Public API: maybe a minimum size on the encoder probe in moq-video. Wire: -none. - Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the probe stays private, and the typed error names the minimum width. It becomes public only when a consumer asks. +Public API: the encode error names the minimum size; the probe stays private. Wire: none. + ## Related - [VA-API encode is correct on radeonsi](/quest/m1/vaapi-radeonsi.md) - the same AMD hardware run diff --git a/quest/m3/import-metadata-policy.md b/quest/m3/import-metadata-policy.md index d72d097a3fb..a941b64383d 100644 --- a/quest/m3/import-metadata-policy.md +++ b/quest/m3/import-metadata-policy.md @@ -16,8 +16,6 @@ Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-a - The fMP4 side has landed (`MAX_HELD_BYTES`, `MAX_METADATA_BYTES`, `MAX_FRAGMENT_SAMPLES`, and `MAX_TRACKS` in `rs/moq-mux/src/container/fmp4/mod.rs`). Note the MKV avcC bound (about 34 MiB) sits far above fMP4's 2 MiB `MAX_METADATA_BYTES`. - Inventory what each importer still holds whole, and how much parsed state it builds from it (fMP4's parse expands up to tenfold, which is what sets `MAX_METADATA_BYTES`). - Keep audio and video payloads unbounded in both: streaming each sample into its frame was decided 2026-10-27, and this quest is about metadata only. An fMP4 text sample is the one payload held whole, because its rewrite needs every byte, so `MAX_HELD_BYTES` covers it; keep that exception. MKV has no counterpart, since it refuses subtitle tracks. -- Document the policy once, in moq-mux's import docs, and make both importers' bounds `pub const`s as #7232's are. +- Document the policy once, in moq-mux's import docs. Both importers' bounds stay private, with no `pub const` (as [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) did for `fmp4::MAX_*`). Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests). -Public API: possibly new `pub const` bounds and a shared refusal error in moq-mux. Wire: none. - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the policy's bounds are private, with no `pub const` (as [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) did for `fmp4::MAX_*`). +Public API: possibly a shared refusal error in moq-mux. Wire: none. diff --git a/quest/m3/json-snapshot-resync.md b/quest/m3/json-snapshot-resync.md index f01ed8c5fad..b8b09912d69 100644 --- a/quest/m3/json-snapshot-resync.md +++ b/quest/m3/json-snapshot-resync.md @@ -3,10 +3,9 @@ ## Goal When a frame fails to decode (a `SyntaxError` or `DuplicateKey`), `@moq/json`'s -`Snapshot.Consumer` drops the current group and throws a distinct decode -error, then resumes at the next group's snapshot. Callers such as -`@moq/room` and moq-boy can catch that error and keep reading instead of -ending. `rs/moq-json`'s snapshot consumer does the same. +`Snapshot.Consumer` drops the current group and resumes at the next group's +snapshot by itself, so callers such as `@moq/room` and moq-boy keep reading +instead of ending. `rs/moq-json`'s snapshot consumer does the same. ## Plan @@ -24,18 +23,14 @@ recover: after a parse error `#framesRead` and the delta base go stale `rs/moq-json/src/snapshot/consumer.rs`), so continuing would show wrong state. The maintainer approved planning the fix from #7693's iterate. -- On a decode failure, reset the frame count and delta base, skip the rest - of the group, and throw a new typed error (wrapping the cause) so callers - can tell it apart from a track end. -- Mirror it in Rust as a new `Error` variant, with the same skip. -- Move `@moq/room`'s metadata reader and moq-boy's status loop - (`js/room/src/metadata.ts`, `js/moq-boy/src/game.ts`) to skip the error - and resync, and test a malformed delta followed by a good group in both - languages. +- Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the consumer resyncs itself, with no new error variant. On a + decode failure it resets its frame count and delta base, skips the rest + of the group, and counts the skip (optionally a `skipped()` counter). A + terminal error stays terminal, so `@moq/room` and moq-boy need no change. +- Do the same in Rust's snapshot consumer, and test a malformed delta + followed by a good group in both languages. -Public API: a new decode error in `@moq/json` and `moq-json`. Wire: none. - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the consumer resyncs itself. It drops the bad group, resets its frame count and delta base, and counts the skip (optionally a `skipped()` counter), with no new error variant; a terminal error stays terminal, so room and moq-boy need no change. +Public API: at most a `skipped()` counter in `@moq/json` and `moq-json`. Wire: none. ## Related diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index 5383b6b9909..a15cb272116 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -48,8 +48,11 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: - An endpoint ID is a persistent Ed25519 device key, iroh-style. It is not the [routing identity](/quest/m2/cluster-routing/routes/README.md), which each process declares fresh. -- Addressing is announcement: each node publishes under `mesh//...`, and - reaching an ID is subscribing there. There is no separate directory. +- Addressing is announcement: each node publishes its address and status + tracks under `mesh//...`, and reaching an ID is subscribing there. + There is no separate directory. Services are not under `mesh//`: each + is one socket endpoint per service name, outside every member subtree + (see [Endpoint API](/quest/m3/mesh/endpoint.md)). - Certificates can stand in for the token (decided 2026-11-07, maintainer, Kixel's planning): a downstream mesh that must admit and evict devices with no internet issues long-lived certificates from its own signers, and diff --git a/quest/m3/mesh/cert-credentials.md b/quest/m3/mesh/cert-credentials.md index ded9d3ab9ce..2b43a2a51be 100644 --- a/quest/m3/mesh/cert-credentials.md +++ b/quest/m3/mesh/cert-credentials.md @@ -58,7 +58,7 @@ Added 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and rem - A self-describing, versioned encoding (for example a `moqc1.` prefix, or a distinct token type) in a slot named by role. If the query key stays `jwt` for compatibility, the prefix still makes it dispatchable without sniffing, and moq-transport uses its AUTHORIZATION TOKEN type field. - One proof structure whose signed payload has a `nonce | timestamp` field, so [the challenge](/quest/m4/cert-challenge.md) reuses it instead of adding a second format. -- Revocation is data in the trust-store handle (a revoked SPKI-hash or serial set the application replaces), not a per-connection predicate. +- Revocation is data in the trust-store handle (a revoked SPKI-hash set, or a set of serials qualified by their issuer, which the application replaces), not a per-connection predicate. A bare serial is never enough, since two trusted issuers can reuse one; a test revokes one issuer's serial and still admits the other issuer's certificate with the same serial. - Chains are 2 to 4 KB in base64, close to common 8 KB URL limits; cache verified chains by fingerprint, and say in the PR how a long chain is carried. - The shared token corpus planned in [moq-dev/moq#8151](https://github.com/moq-dev/moq/pull/8151) includes this credential form. diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index a0b66c24b3b..eeba45b8be7 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -14,14 +14,14 @@ with small changes, without iroh's wire or discovery. Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, `EndpointAddr`, and `Router` are out unless porting proves they are needed. -- A service is the iroh ALPN analog: a name under `mesh//`. +- A service is the iroh ALPN analog: a socket endpoint per service name + (below), while each node's address and status tracks stay under its + `mesh//`. - Decided 2026-11-01 (maintainer, socket planning interview), and updated 2026-11-03 when sockets became endpoints and 2026-11-04 when the segment became `.socket` with the protocol in the session name: an `Endpoint` wraps a [socket](/doc/concept/socket.md) endpoint, which since 2026-11-06 is a - server at `.server/`, a client at `.client/`, or both. Settle the - layout here: such as one socket endpoint per service under - `mesh//`, or one per node with the service named in the session. + server at `.server/`, a client at `.client/`, or both. `connect` dials with the caller's own endpoint ID, and `accept` reads the remote ID from the dial, which the socket's answer check proves and the grant pins (publish `.server/` and `.client/` only). Update `moq auth`'s mesh grant and @@ -39,6 +39,26 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one socket endpoint per service at prefix `mesh/`, with the grant adding publish `mesh/*/.server/` and `mesh/*/.client/`, so `moq_net::socket` ships unchanged and needs no service field. +Two constraints on that layout, found in review of +[moq-dev/moq#8214](https://github.com/moq-dev/moq/pull/8214): + +- A service name is one path segment, validated when the `Endpoint` is + built, so `*` in the grant covers it (`video/h264` would fall outside). +- Service sockets must not overlap member subtrees. Each member may publish + `mesh//**`, so a service named after member A puts `.server/B` under + A's own grant, and A could answer as B. The prefix in the Waiting item + below keeps the two apart. + +## Waiting + +- Maintainer: pick the service prefix that keeps service sockets out of + `mesh//**`. Options: **`mesh/.service/` (recommended)**, + since endpoint IDs never start with `.`, so no member subtree can contain + it, and the grant becomes publish `mesh/.service/*/.server/` and + `.client/`; or keep `mesh/` and refuse service names that + parse as an endpoint ID, which leaves the check in every relay's grant + logic. Done when the Plan names the prefix. + ## Required - [Rust byte streams](/quest/m3/stream/rust.md) - the stream this API returns diff --git a/quest/m3/nixpkgs-cli.md b/quest/m3/nixpkgs-cli.md index 8348f19638d..7b0cb59c3ed 100644 --- a/quest/m3/nixpkgs-cli.md +++ b/quest/m3/nixpkgs-cli.md @@ -17,7 +17,7 @@ Decided 2026-11-05 (maintainer, /quest-plan): - The maintainer added "moq-cli only when we're happy with the feature set" and left the bar to the planner. Decided: the bar is [Ship capture and playback](/quest/m3/cli-packaging.md) merged, since that - is when every distribution builds with `--features release`. + is when every distribution builds with `--features full`. Follow [moq-relay in nixpkgs](/quest/m3/nixpkgs-relay.md)'s process: prepare a branch on kixelated/nixpkgs with `Assisted-by:` trailers, then wait for the @@ -26,7 +26,7 @@ by then. The attribute is `moq-cli`, because nixpkgs' `moq` is an unrelated Go mocking tool ([matryer/moq](https://github.com/matryer/moq)) that also installs -`bin/moq`. Set `meta.mainProgram = "moq"`. Build with `--features release` +`bin/moq`. Set `meta.mainProgram = "moq"`. Build with `--features full` and the `jemalloc` feature our overlay uses. `vaapi` and `nvidia` dlopen their driver libraries, so make them findable at runtime (for example `addDriverRunpath` for libcuda, and libva on the runpath). Prove it with diff --git a/quest/m3/probe-rung-disable-js.md b/quest/m3/probe-rung-disable-js.md index 410d2aca130..10dff4968f6 100644 --- a/quest/m3/probe-rung-disable-js.md +++ b/quest/m3/probe-rung-disable-js.md @@ -32,10 +32,10 @@ it only past the hysteresis and after its viewers left; a jittering grant near the boundary does not flap the catalog. The epic's shaped-uplink browser test proves recovery end to end. -Public API: whatever knob `@moq/publish` exposes for the rule. Wire: none. - Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no new knob. Mirror `moq_mux::rate::Policy`'s rule and constants, and let `enabled` combine with them. +Public API: none. Wire: none. + ## Required - [Padding probes](/quest/m3/probe-padding.md) - the browser's sender, which raises the estimate so a disabled rung can resume diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index 1d545107d2c..726405dd4c4 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -19,24 +19,31 @@ upstream. This quest supersedes the design in moq-dev/web-transport#368, whose snapshot-counter shape loses the wakeups a latency sample needs. -Add one method to `SendStream`, in the trait's poll style: +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs +and remaining quests): no `Option<()>` outcome, and one offset type on both +layers. Add an offset type and two methods to `SendStream`, in the trait's +poll style: ```rust -fn poll_acked(&self, waiter: &kio::Waiter, offset: u64) -> Poll, Self::Error>>; +type Offset: Copy; +fn offset(&self) -> Self::Offset; +fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll>; + +#[non_exhaustive] +pub enum Acked { Delivered, Unsupported } ``` -It is ready with `Some` once every byte below `offset` has been acknowledged. +It is ready with `Delivered` once every byte below `offset` has been acknowledged. It carries no instant: the caller records one when woken, which includes the peer's delayed-ACK timer (up to `max_ack_delay`) as well as the return trip. Decided 2026-10-17 on #5817, which dropped `moq-quic`'s ACK-delay-corrected instant until a consumer shows it matters. It resolves with an error once the stream is reset by either side or the session closes, so a waiter never hangs on bytes the peer will never acknowledge. The default -implementation is ready with `Ok(None)` immediately: `None` means the backend -cannot see acknowledgments, the same convention the trait's `Stats` methods -use. A default body cannot construct a backend's own `Self::Error`, so -unsupported has to live in the return type rather than the error, and a -consumer must treat `None` as unknown, never as delivered. +implementation is ready with `Ok(Acked::Unsupported)` immediately. A default +body cannot construct a backend's own `Self::Error`, so unsupported has to +live in the return type rather than the error, and a consumer must treat +`Unsupported` as unknown, never as delivered. Each QUIC driver, moq-tokio's `quic::driver` and moq-uring's, gets the hook first, in the drivers' caller-owned waiter shape, @@ -44,8 +51,8 @@ with an async wrapper: ```rust impl send::Stream { - pub fn poll_acked(&self, waiter: &kio::Waiter, offset: u64) -> Poll>; - pub async fn acked(&self, offset: u64) -> Result<(), send::Error>; + pub fn poll_acked(&self, waiter: &kio::Waiter, offset: send::Offset) -> Poll>; + pub async fn acked(&self, offset: send::Offset) -> Result<(), send::Error>; } ``` @@ -67,11 +74,14 @@ lives: - `reset_at` below the acknowledged prefix, or STOP_SENDING after a reset (which truncates to 0), shrinks the acknowledged prefix. The waiters fail anyway; keep the prefix a `poll_acked` reports monotonic. -- The offset counts bytes on the QUIC stream. The trait method takes a byte - offset, like `moq-quic` (decided 2026-10-17 on #5817), and the lag - histogram's writer counts the bytes it writes, so neither driver needs a public - `offset()`. A layer that writes its own prefix adds its length: `quic::web` - already tracks its WebTransport header for `reset_at`. +- The offset counts bytes on the QUIC stream, but nobody computes one: the + trait's `Offset` is the driver's minted `send::Offset`, and the lag + histogram's writer records `offset()` after each frame end instead of + counting the bytes it writes. A layer that writes its own prefix mints + offsets that already include it, so `quic::web` forwards the driver's + `Offset` and its WebTransport header needs no adjustment. A backend that + cannot see acknowledgments mints a `u64` byte count and keeps the default + `poll_acked`. The moq-tokio and moq-uring adapters implement the trait method over the driver's. Leave the browser transport on the default; the browser's `WebTransportSendStream.getStats()` is @@ -93,9 +103,6 @@ offset in the middle of an in-flight frame, several waiters on one stream in offset order, reset by sender, STOP_SENDING by the receiver, and session close. - Decided in the 2026-09-30 audit: moved to m2 with its consumers, the [viewer lag histogram](/quest/m3/qos/lag-histogram.md) and the [delivery-delay histogram](/quest/m5/delivery-delay.md). - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no `Option<()>` outcome. Return a named `enum Acked { Delivered, Unsupported }` (or add `fn acks(&self) -> bool` and make the poll a plain `Result`), and use one offset type on both layers. diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 9104e5c0d67..1d7831358f9 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -41,7 +41,11 @@ moq-video's environment knobs). Its approved changes are m2 quests gateway-ingest, and the [api-shape epic](/quest/m2/api-shape/README.md)), two m1 quests, and plan edits. Check first, next run: surfaces `just api-diff` cannot see (GStreamer properties, CLI flags and env, MIGRATE drift) -and publish versions of packages exempt from the cut's version. +and publish versions of packages exempt from the cut's version. `just +api-diff` compares against this repository's `release` branch, which never +held `@moq/qmux`, so compare `js/qmux`'s candidate API against npm's newest +`@moq/qmux` (0.3.4, from moq-dev/web-transport) by hand, and the Rust `qmux` +crate against crates.io's 0.6.6 the same way. This review still runs after m2 lands, over what changed since. ## Required diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 09c2a6f0dcd..c5a98fc7d03 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -19,7 +19,12 @@ from moq-dev/web-transport, while `js/qmux` is at 0.3.3. Publishing 0.3.3 fails, and `workspace:^` would resolve `@moq/net`'s dependency to web-transport's 0.3.4, a different API. `js/qmux` must publish above 0.3.4; the maintainer picks the version (found 2026-11-07 by the API shape audit). -Rust +Before publishing, confirm moq-dev/web-transport's release config no longer +publishes `@moq/qmux` or `qmux` (the freeze step of +[qmux-js-retire](/quest/m3/release/qmux-js-retire.md) and +[qmux-rs-retire](/quest/m3/release/qmux-rs-retire.md)): otherwise it could +publish a 0.3.x above ours, which `@moq/net`'s `^` range would pick up with +the old API. Rust publication remains owned by release-plz. This supersedes keeping `moq-rs` at its unpublished 0.6.0 (decided 2026-11-01). Run candidate compatibility, draft, package, and all-language interop checks, and verify diff --git a/quest/m3/release/qmux-js-retire.md b/quest/m3/release/qmux-js-retire.md index ee40a67e7b5..1165977e5ac 100644 --- a/quest/m3/release/qmux-js-retire.md +++ b/quest/m3/release/qmux-js-retire.md @@ -19,3 +19,10 @@ publication and a maintainer with npm rights: - `npm deprecate @moq/web-socket-stream "Folded into @moq/qmux; see https://github.com/moq-dev/moq/blob/main/js/qmux/MIGRATE.md"`. - Remove or freeze `js/qmux` and `js/web-socket-stream` in moq-dev/web-transport, whose release script would otherwise publish a competing `@moq/qmux`. + +## Waiting + +- Maintainer: with npm rights, run the deprecation above and freeze + web-transport's `js/qmux` publisher before the cut; an agent has no npm or + web-transport rights. Done when `npm view @moq/qmux repository` names + moq-dev/moq and `npm view @moq/web-socket-stream deprecated` is set. diff --git a/quest/m3/release/qmux-rs-retire.md b/quest/m3/release/qmux-rs-retire.md index 023603d24ea..62945dff551 100644 --- a/quest/m3/release/qmux-rs-retire.md +++ b/quest/m3/release/qmux-rs-retire.md @@ -15,5 +15,12 @@ web-transport release-plz config. Found by the 2026-11-07 API shape audit (transport); mirrors [qmux-js-retire](/quest/m3/release/qmux-js-retire.md) for the Rust crate. web-transport still carries `qmux` 0.6.6 and live quests that change it; -move or close them there. Waiting on the crate's publication and a -maintainer with rights in moq-dev/web-transport. +move or close them there. + +## Waiting + +- Maintainer: with rights in moq-dev/web-transport, freeze or remove its + `rs/qmux` and drop the crate from its release-plz config before the cut + publishes `qmux` from this repository; an agent has no publish rights + there. Done when `cargo info qmux` names moq-dev/moq and web-transport's + release-plz config no longer lists `qmux`. diff --git a/quest/m3/rtc-pacing.md b/quest/m3/rtc-pacing.md index 8d6965ea7b8..5b8b589dcea 100644 --- a/quest/m3/rtc-pacing.md +++ b/quest/m3/rtc-pacing.md @@ -58,8 +58,11 @@ WHEP enforcement needs it and nobody owned it. Public API: a rate handle on moq-webrtc's WHEP server. Decided 2026-10-30 (maintainer): `whep::accept` takes the same shape as `whip::accept`, a -`whep::Request` struct with `Request::with_rate(bandwidth::Limit)`, -replacing its argument list rather than adding a fifth argument. The handle +`whep::Request` struct, rather than a fifth argument. That struct lands +first in [gateway-ingest](/quest/m2/gateway-ingest.md), `#[non_exhaustive]`, +so this quest adds a `rate: Option` field to it, never a +`with_rate` setter (2026-11-07, maintainer, /quest-plan from the API sweep +of open PRs and remaining quests). The handle is `moq_net::bandwidth::Limit`, which replaces moq-webrtc's `rate::{Cap, Limit}` in [gateway-ingest](/quest/m2/gateway-ingest.md) (2026-11-07, maintainer, /quest-plan from the API shape audit). Wire: none. diff --git a/quest/m4/binding-export-coverage.md b/quest/m4/binding-export-coverage.md index 2246a155127..19445a7a311 100644 --- a/quest/m4/binding-export-coverage.md +++ b/quest/m4/binding-export-coverage.md @@ -2,16 +2,17 @@ ## Goal -The Python, Go, and Swift wrappers each fail a test when a moq-ffi record, -enum, or handle has no wrapper path, as Kotlin's smoke test already does -(`SmokeTest.kt`). Today these three hand-wrap 3,000 to 5,000 lines each, -and parity depends on review. +The Python, Go, Swift, and Kotlin wrappers each fail a test when a moq-ffi +record, enum, or handle has no wrapper path. Today Python, Go, and Swift +hand-wrap 3,000 to 5,000 lines each, and Kotlin's `all public ffi records and +handles have aliases` test (`SmokeTest.kt`) constructs a fixed list, so a new +record without an alias still passes. Parity depends on review. ## Plan Found by the 2026-11-07 API shape audit (bindings). Generate the list of FFI items from UniFFI's metadata once, and have each wrapper's test check it against the wrapper's public types, with an explicit allowlist for items -a wrapper deliberately hides. Kotlin keeps its own check or moves to the -shared list. When [the exporter](/quest/m3/ffi-exporter.md) replaces UniFFI, +a wrapper deliberately hides. Kotlin's +fixed list moves to the shared one. When [the exporter](/quest/m3/ffi-exporter.md) replaces UniFFI, the list comes from it. diff --git a/quest/m4/p2p/README.md b/quest/m4/p2p/README.md index ab012abe793..80ec16e9c03 100644 --- a/quest/m4/p2p/README.md +++ b/quest/m4/p2p/README.md @@ -71,16 +71,16 @@ off by default, and used only when the application lists it. ### Policy is the application's -`Peers` takes the shared origin, plus: +`Peers` takes the shared origin, plus the knobs below (decided 2026-11-07, +maintainer, /quest-plan from the API sweep of open PRs and remaining quests: +no `max` roster gate, and the on/off `enabled` is the element's attribute, +not a `Peers` knob): -- `enabled`: an explicit on/off signal, off by default; - `prefix`: the reserved prefix, `.p2p/` under the session root by default; -- `iceServers`: the RTCPeerConnection server list; empty means LAN only; -- `max`: the roster size above which a new negotiation is built with an empty - server list. Host and mDNS candidates are always gathered, so LAN pairing - never stops; only server-reflexive candidates are withheld. Pairs already - established are left alone when the roster grows past `max`, which is what - keeps the boundary from flapping; +- `iceServers`: the default RTCPeerConnection server list, which each + selected or admitted peer may override with its own; empty means LAN only. + Host and mDNS candidates are always gathered, so LAN pairing never stops, + and changing a peer's list never closes an established pair; - `meta`: an opaque JSON value published in this peer's roster entry; - application-owned peer selection: discovery exposes candidates and only explicitly selected peers are dialed; incoming connections need application diff --git a/quest/m4/p2p/cli.md b/quest/m4/p2p/cli.md index bae71e94129..0ce127f00ec 100644 --- a/quest/m4/p2p/cli.md +++ b/quest/m4/p2p/cli.md @@ -12,8 +12,10 @@ them and the relay. Its policy knobs mirror `@moq/p2p`. `--p2p` (`MOQ_P2P`) needs a relay session (`--connect`) and a listener (`--listen`); shape the flag so the value carries those prerequisites rather than adding startup checks. `--p2p-ice-server`, -`--p2p-max`, `--p2p-prefix`, and `--p2p-meta` carry the same knobs the JS -`Peers` takes. Decided 2026-10-13: the operator explicitly selects peers; +`--p2p-prefix`, and `--p2p-meta` carry the same knobs the JS +`Peers` takes; there is no `--p2p-max` (decided 2026-11-07, maintainer, +/quest-plan from the API sweep of open PRs and remaining quests: no `max` +roster gate, see [signal](/quest/m4/p2p/signal.md)). Decided 2026-10-13: the operator explicitly selects peers; there is no built-in dial-all default. Provide an explicit selection/configuration surface and per-connection priority/cost mirroring the application API; settle its concrete CLI shape before coding and update all invocations against --help. @@ -39,8 +41,6 @@ Discovery alone does not initiate a connection. Docs: a "P2P" section in `doc/bin/cli.md` beside the LAN cluster one. -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): no `max` flag ([signal](/quest/m4/p2p/signal.md)). - ## Required - [Native pairs over ICE and QUIC](/quest/m4/p2p/native-quic.md) - the native-to-native path diff --git a/quest/m4/p2p/signal.md b/quest/m4/p2p/signal.md index 17e81d827bf..222cc191907 100644 --- a/quest/m4/p2p/signal.md +++ b/quest/m4/p2p/signal.md @@ -5,20 +5,21 @@ An opted-in browser discovers the other opted-in peers on its relay session, exposes candidates for the application to select, and ends up holding an established `@moq/net` connection to each selected peer ICE can reach, wired into the shared origin -in both directions. The application supplies the ICE servers and the roster -size above which new negotiations stop using them. No new relay behavior. +in both directions. The application supplies the ICE servers, per peer when +it wants. No new relay behavior. ## Plan `Peers` in `@moq/p2p` takes the shared origin, a reconnect-safe handle to the relay connection's auth, and the policy knobs from the -[questline README](/quest/m4/p2p/README.md): `enabled`, `prefix`, -`iceServers`, `max`, `meta`, plus application-owned selection and per-connection -priority/cost. Decided 2026-10-13: only explicitly selected peers are dialed; +[questline README](/quest/m4/p2p/README.md): `prefix`, `iceServers`, +`meta`, plus application-owned selection and per-connection +priority/cost. `Peers` exists only while P2P is on; the on/off `enabled` +lives on the element as an attribute. Decided 2026-10-13: only explicitly selected peers are dialed; there is no default dial-all. Prefer a selected set/handle to a callback, settling the public shape with its consumer. Publishing into the origin reaches the relay and its announce stream is the roster. Tests inject transport -factories and cover pairing, application selection, and the roster gate. +factories and cover pairing, application selection, and per-peer ICE servers. Identity, decided 2026-11-02 (maintainer, /quest-unblock): each peer generates a keypair, and its roster `` (also the perfect-negotiation tiebreak) is its public key, like an @@ -54,11 +55,14 @@ then each ICE candidate as it arrives; the target answers on `/`. Every peer subscribes to its own `/` prefix. -The gate: a peer connection is built with `iceServers` when the roster holds -`max` peers or fewer, and with an empty list otherwise. Host and mDNS -candidates are always gathered, so LAN pairs form at any roster size. -Established pairs are never closed by the gate. This is a STUN policy, not a -connection budget; test roster churn and pending negotiations separately. +ICE servers, decided 2026-11-07 (maintainer, /quest-plan from the API sweep +of open PRs and remaining quests): each selected or admitted peer takes its +own `iceServers`, defaulting to `Peers`' list, which replaces the earlier +roster-size gate and its `max` knob. An application that wants to stop using +STUN past some roster size passes an empty list for the peers it selects +then. Host and mDNS candidates are always gathered, so LAN pairs form with +an empty list. Changing a peer's list never closes an established pair; test +roster churn and pending negotiations separately. Native entries: when `info.webtransport` is present the dialer tries its URLs in advertised order, using `connect` with the listener's fingerprint @@ -85,5 +89,3 @@ never crosses a peer session: a `moq_auth` JWT is a bearer credential, so a peer that received one could replay it against the relay. Rejected: relay-issued, key-bound peer grants with a possession proof (the earlier plan), until a use case needs per-peer scopes. - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): each selected or admitted peer takes its own `iceServers` (default: `Peers`' list); `max` and its CLI flag go, and `enabled` stays only as the element attribute, not on `Peers`. diff --git a/quest/m4/p2p/watch.md b/quest/m4/p2p/watch.md index e40efaed2f6..dc563b88ad0 100644 --- a/quest/m4/p2p/watch.md +++ b/quest/m4/p2p/watch.md @@ -19,7 +19,7 @@ does for the cut's packages. `moq-watch` and `moq-publish` gain a `p2p` attribute that constructs `Peers` on the shared connection's origin and its relay auth handle (see [Signaling and policy](/quest/m4/p2p/signal.md)), with the demo's ICE servers -and a `max` from the page; `demo/web` exposes the toggle and an explicit application +(per peer when the page selects them); `demo/web` exposes the toggle and an explicit application peer-selection policy. Enabling discovery alone must not dial every peer. The route pick is the origin's, under the rule from [Peer route policy](/quest/m4/p2p/cost-scopes.md): application priority then total cost selects among eligible connections. diff --git a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index d29549d880e..c08d1c591fe 100644 --- a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -15,8 +15,9 @@ Use the shared event contract [emsg](/quest/m5/emsg.md) settles. Deliver cues im future; consumers need advance notification. Metadata group sequences are independent of media GOPs. -- A top-level `scte35` catalog section names cue tracks with optional program - or rendition association. Video is not required for audio-only programs. +- A SCTE-35 scheme entry in the shared catalog `events` section names cue + tracks with optional program or rendition association, not a top-level + `scte35` section (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs and remaining quests). Video is not required for audio-only programs. - Preserve complete raw splice_info_section bytes. Carry the event's presentation time on the broadcast clock; commands without splice_time use the media clock observed at arrival. Do not delay publication until the @@ -26,14 +27,14 @@ independent of media GOPs. timestamp and retention behavior for a future cue followed by a current event. - **Typed decode is a helper, not the wire.** A parser for `splice_insert`, `time_signal`, and segmentation descriptors (a maintained crate if one is - adequate) lives beside the section in Rust and JS, and `js/watch` raises a + adequate) lives beside the scheme in Rust and JS, and `js/watch` raises a cue event from it. Applications that want the rest parse the bytes. - **The TS lanes stay.** The importer keeps the verbatim `mpegts` track for contribution fidelity and additionally emits the sidecar; the exporter must not double-emit: an import-to-export test with the sidecar present asserts each source section is emitted exactly once, including audio-only programs. -Wire and catalog schema: a new optional section, additive, so it lands on +Wire and catalog schema: a new scheme in the optional `events` section, additive, so it lands on `main`, with `drafts/draft-lcurley-moq-hang.md` updated in the same PR as the schema: the draft is the normative spec, and a section Rust and JS emit must be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, @@ -45,4 +46,4 @@ be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, ## Related -- [ID3 catalog section](/quest/m5/id3.md) - the other typed timed-metadata section, same rule +- [ID3 in the events section](/quest/m5/id3.md) - the other typed timed-metadata scheme, same rule diff --git a/quest/m5/README.md b/quest/m5/README.md index 0ff4dde5147..a972d90f560 100644 --- a/quest/m5/README.md +++ b/quest/m5/README.md @@ -69,7 +69,7 @@ lite-07; bitrate enforcement is not part of the next release. in five minutes - [Ladder](/quest/m5/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling - [fMP4 emsg](/quest/m5/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them -- [ID3 catalog section](/quest/m5/id3.md) - timed ID3 as a first-class container-neutral catalog section +- [ID3 in the events section](/quest/m5/id3.md) - timed ID3 as a container-neutral scheme in the catalog's `events` section - [FLV script tags](/quest/m5/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import - [Half and quarter rate AC-3](/quest/m5/ac3-low-rate.md) - bsid 9 and 10 AC-3 parse through TS and FLV instead of being refused - [MSF feedback tracks](/quest/m5/msf-publish-tracks.md) - `--report` and `--echo` work under `--catalog-format msf` through `publishTracks`, once a consumer asks diff --git a/quest/m5/audio-encode-audiotoolbox.md b/quest/m5/audio-encode-audiotoolbox.md index c1780fcb094..24418d94649 100644 --- a/quest/m5/audio-encode-audiotoolbox.md +++ b/quest/m5/audio-encode-audiotoolbox.md @@ -18,10 +18,6 @@ the encode seam as the platform candidate on macOS and iOS. `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. - Bitrate through `kAudioConverterEncodeBitRate`, updated live where the converter allows. -- This quest owns changing `Encoder::encode` from one packet per frame to - a zero-or-more packet return with a flush operation. MediaCodec requires - this shared contract even if AudioToolbox itself emits immediately. Prove - delayed and multiple outputs and flushing in the shared encoder tests. - Gate the seam's "AAC refused without a platform encoder" test to hosts without one. - Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox @@ -33,7 +29,10 @@ the encode seam as the platform candidate on macOS and iOS. duplicates as holes and resets AAC between them. Shift the whole timeline by the deficit instead, including the terminal end (found in #4081 review). -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. +This backend implements the zero-or-more packet return and `flush` that +[audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut +(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs +and remaining quests), so it adds no break and waits on no other backend. ## Required diff --git a/quest/m5/audio-encode-mediacodec.md b/quest/m5/audio-encode-mediacodec.md index 638104c4a36..d7ca20bd077 100644 --- a/quest/m5/audio-encode-mediacodec.md +++ b/quest/m5/audio-encode-mediacodec.md @@ -17,15 +17,17 @@ behind the `mediacodec` feature and the encode seam. synthesized at construction per the encode seam, since `csd-0` only arrives with the first output buffer; assert the two match. - MediaCodec pipelines output. Reuse the flush and zero-or-more packet - return owned by AudioToolbox encode; do not design another encoder seam. + return from the m2 seam; do not design another encoder seam. - Multichannel is device-dependent; probe the encoder's capabilities at open and refuse a layout it does not list. - Round-trip regression through the MediaCodec decoder; runtime proof on a device or emulator through `just rs android-test`, as in the decode quest. -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. +This backend implements the zero-or-more packet return and `flush` that +[audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut +(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs +and remaining quests), so it adds no break and waits on no other backend. ## Required - [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - the round-trip regression decodes through it -- [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - owns the shared flush and zero-or-more packet encoder contract diff --git a/quest/m5/audio-encode-mediafoundation.md b/quest/m5/audio-encode-mediafoundation.md index 83ea5692653..4443124132f 100644 --- a/quest/m5/audio-encode-mediafoundation.md +++ b/quest/m5/audio-encode-mediafoundation.md @@ -18,10 +18,12 @@ behind the encode seam on Windows. - Round-trip regression through the Media Foundation decoder; verification on a Windows host, since the per-PR CI compiles only. -Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [audio-codec-seam](/quest/m2/audio-codec-seam.md) makes moq-audio's codecs return zero or more outputs with `flush` before the cut, so this backend adds no break. +This backend implements the zero-or-more packet return and `flush` that +[audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut +(decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs +and remaining quests), so it adds no break and waits on no other backend. ## Required -- [AudioToolbox encode](/quest/m5/audio-encode-audiotoolbox.md) - changes `Encoder::encode` to a zero-or-more packet return with a flush, which this backend implements - [Media Foundation decode](/quest/m5/audio-decode-mediafoundation.md) - the round-trip regression decodes through it diff --git a/quest/m5/emsg.md b/quest/m5/emsg.md index de5c10428c4..84d50d91f5e 100644 --- a/quest/m5/emsg.md +++ b/quest/m5/emsg.md @@ -59,6 +59,6 @@ Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and r ## Related -- [ID3 catalog section](/quest/m5/id3.md) - gives one payload type carried here a +- [ID3 in the events section](/quest/m5/id3.md) - gives one payload type carried here a typed contract - [FLV script tags](/quest/m5/flv-script.md) - likewise diff --git a/quest/m5/ffi-e2ee.md b/quest/m5/ffi-e2ee.md index 4653b521b5d..60873455750 100644 --- a/quest/m5/ffi-e2ee.md +++ b/quest/m5/ffi-e2ee.md @@ -20,9 +20,9 @@ the binding layer, and keep the encrypting publisher's refusal of a shared or explicit epoch. Add a binding test that decrypts a JS-published broadcast and the reverse to the interop suite. -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the bindings wrap moq-crypto's concrete `broadcast::{Producer, Consumer}` directly, without waiting on [net-wrap](/quest/m5/net-wrap/README.md). +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the bindings wrap moq-crypto's concrete `broadcast::{Producer, Consumer}` (`rs/moq-crypto/src/e2ee/broadcast.rs`, already public) directly, without waiting on [net-wrap](/quest/m5/net-wrap/README.md). So this quest requires neither e2ee quest below, both of which wait on net-wrap: it exposes encrypted tracks and frames, which is what the T3 app reads. Encrypted media publishing through moq-mux's catalog and codec publishers comes with [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md), and the bindings pick it up then without a break. -## Required +## Related -- [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md) - the producer these bindings wrap -- [Encrypted consumer shape](/quest/m5/e2ee/consumer.md) - the consumer these bindings wrap +- [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md) - moq-mux publishing into an encrypted broadcast, after net-wrap +- [Encrypted consumer shape](/quest/m5/e2ee/consumer.md) - Rust and JS media readers over an encrypted broadcast, after net-wrap diff --git a/quest/m5/id3.md b/quest/m5/id3.md index bc703934b30..562fb620819 100644 --- a/quest/m5/id3.md +++ b/quest/m5/id3.md @@ -1,9 +1,10 @@ -# [M] ID3 catalog section +# [M] ID3 in the catalog's events section ## Goal -A Hang catalog exposes ID3 metadata in a top-level `id3` section with named -tracks and media correlation, independent of the MPEG-TS PID that supplied it. +A Hang catalog exposes ID3 metadata as an ID3 scheme entry in the shared +`events` section [emsg](/quest/m5/emsg.md) defines, with named tracks and +media correlation, independent of the MPEG-TS PID that supplied it. Consumers can discover and read timed ID3 without understanding the `mpegts` extension, while MPEG-TS export still reconstructs a valid ID3 elementary stream. @@ -12,18 +13,19 @@ stream. Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer for timed metadata. -Define the catalog section and frame contract for complete ID3 tags on the -shared event contract [emsg](/quest/m5/emsg.md) settles. Publish tags when +Define the ID3 scheme's entry and frame contract for complete ID3 tags on the +shared event contract [emsg](/quest/m5/emsg.md) settles: one catalog `events` +section keyed by scheme URI, not a top-level `id3` section (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs and remaining quests). Publish tags when received on independently sequenced groups, with their presentation time on the broadcast clock and an optional association to the program's rendition. ID3-only programs need no artificial media owner. Carry original tag bytes, -and in the section the raw stream-level PMT descriptor loop plus any +and in the scheme's entry the raw stream-level PMT descriptor loop plus any application or program registration metadata the exporter needs to reproduce the input. Do not parse the tag into a fixed metadata vocabulary; applications can decode frames with their ID3 library and new tag types remain forward-compatible. -Teach MPEG-TS import to use this section only when the PMT descriptors or +Teach MPEG-TS import to use this entry only when the PMT descriptors or application metadata identify ID3 and complete payloads validate as ID3 tags. Stream type `0x15` alone is generic metadata PES and does not qualify. Ambiguous, non-ID3, or inconsistent streams stay byte-faithful in the generic diff --git a/quest/m5/teleop-robot.md b/quest/m5/teleop-robot.md index f915a9bb124..457c25b19b9 100644 --- a/quest/m5/teleop-robot.md +++ b/quest/m5/teleop-robot.md @@ -3,10 +3,11 @@ ## Goal The track shapes and discovery every teleoperated machine needs are -documented conventions in `doc/`, built on moq-net and moq-json, that -[the MAVLink gateway](/quest/m5/teleop-mavlink.md) implements, so an +documented conventions in `doc/`, built on moq-net and moq-json, so an integrator writes an adapter rather than a stack. There is no `moq-robot` -crate. It is the gate for the rest of the questline. +crate, and this quest ships documentation only; [the MAVLink +gateway](/quest/m5/teleop-mavlink.md) implements the conventions in its own +quest. It is the gate for the rest of the questline. ## Plan @@ -15,8 +16,7 @@ crate, too niche for a published library with no second consumer). The shapes below become documented conventions, and `moq-mavlink` ships as a moq-cli gateway like moq-srt. If a second consumer appears, generalize moq-boy's announce-prefix fan-in into moq-net instead of adding a robot -crate. Where the text below says "the crate", read the conventions and -their implementation in moq-mavlink. +crate. Where the text below says "the crate", read "the conventions". Decided 2026-10-08: parked in m5. No teleoperation consumer needs the crate yet; telemetry beside video needs [data sync](/quest/m3/watch-data-sync.md), @@ -89,7 +89,8 @@ The framing is where the guarantee lives, not the subscription flags: fields. Decide whether the robot's fields ride there or in a namespaced root section through `moq-mux`'s `CatalogExt` and `RenditionConfig`. No hang schema change. -- Announce-prefix fan-in, generalised from `rs/moq-boy/src/input.rs`. +- Announce-prefix fan-in, documented from `rs/moq-boy/src/input.rs`; the + code stays in moq-boy until a second consumer moves it into moq-net. - The two delivery classes with the group structure and `Info::max_age` each one needs: `moq-json`'s snapshot and stream modes for JSON; plain tracks for opaque bytes, one group per latest value or one bounded ordered group @@ -126,11 +127,13 @@ present, but never infer synchronization from its presence. No per-record anchors or clock-sync mechanism; see [#2278](https://github.com/moq-dev/moq/issues/2278). -### Port +### Check against moq-boy -Port `moq-boy` onto the crate in the same change, as the no-arbitration case. -It is the only existing consumer, and if the abstraction cannot express crowd -control then it is the wrong abstraction. +With no crate there is nothing to port. Instead, check the conventions +against `moq-boy`, the only existing consumer, as the no-arbitration case: it +merges viewers' JSON button states, where the gateway routes MAVLink frames, +so if the documented shapes cannot describe its crowd control they are the +wrong shapes. moq-boy changes only where it contradicts a convention. ## Related From 0a7085b3a8cf892652dd7eac3c0e7476ccc2f79d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:20:36 -0800 Subject: [PATCH 05/11] quest: #8088 has merged Co-Authored-By: Claude Opus 5.5 --- quest/m2/api-shape/README.md | 4 ++-- quest/m5/auth-http-request-kind.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index 4d5f362324e..df8e86741fb 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -22,8 +22,8 @@ became their own m1, m2, m3, and m4 quests; this epic holds the rest. This audit ran while [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088), the previous API audit's final pass, was open, and none of its children -repeats an item #8088 changes. A child that starts after #8088 merges -rechecks each item against `main` and drops what is already done. +repeats an item #8088 changes. #8088 has since merged, so a child rechecks +each item against `main` and drops what is already done. Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): fences for what later quests grow (`#[non_exhaustive]` on structs and enums m3 to m5 diff --git a/quest/m5/auth-http-request-kind.md b/quest/m5/auth-http-request-kind.md index 2d6e29756c7..b4505d81022 100644 --- a/quest/m5/auth-http-request-kind.md +++ b/quest/m5/auth-http-request-kind.md @@ -29,7 +29,7 @@ yet. Public API: additive (HTTP auth contract fields). Wire: none. -Re-planned 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) removes `auth::Request::{kind, path}`, so this quest starts by re-adding them, additively, only once an auth server asks for per-request decisions. Needs a fresh `/quest-plan` then. +Re-planned 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088) removed `auth::Request::{kind, path}`, so this quest starts by re-adding them, additively, only once an auth server asks for per-request decisions. Needs a fresh `/quest-plan` then. ## Related From cca5848f4708e1921c62ba8412cb6cec3f6b9aa4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:33:47 -0800 Subject: [PATCH 06/11] quest: apply the API sweep's /quest-complete decisions Scope mesh members to mesh/node/ and services to mesh/service/; ffi-e2ee waits for net-wrap's e2ee; hosted-assets keeps per-package dirs. Also fix the with_proxy call-site count and SCTE-35's events association. Co-Authored-By: Claude Opus 5.5 --- quest/m1/hosted-assets.md | 4 ++ quest/m2/api-shape/net.md | 9 ++-- quest/m3/mesh/README.md | 20 ++++---- quest/m3/mesh/addr.md | 4 +- quest/m3/mesh/endpoint.md | 47 ++++++++++--------- quest/m3/mesh/status.md | 5 +- ...te-35-ad-cue-signaling-carried-opaquely.md | 3 +- quest/m5/ffi-e2ee.md | 17 ++++++- 8 files changed, 68 insertions(+), 41 deletions(-) diff --git a/quest/m1/hosted-assets.md b/quest/m1/hosted-assets.md index 4c13093eb81..2fb4b51138e 100644 --- a/quest/m1/hosted-assets.md +++ b/quest/m1/hosted-assets.md @@ -25,3 +25,7 @@ package's `assets/` ships the libav wasm it needs. `@moq/libav` stays an implementation dependency. Future hosted files (the watch worker) join the same call. Test it on the CSP demo pages, including watch and publish configured with different directories. + +✅ Decided 2026-11-07 (maintainer, /quest-complete): each package keeps its +own directory and points libav at its files, as above (rejected: one shared +directory for every package). diff --git a/quest/m2/api-shape/net.md b/quest/m2/api-shape/net.md index e342b8957c8..571be4434ee 100644 --- a/quest/m2/api-shape/net.md +++ b/quest/m2/api-shape/net.md @@ -56,11 +56,10 @@ its JS and binding mirrors: - Remove `origin::Consumer::with_proxy` (from [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)) in favor of `origin::Producer::with_proxy`, which already reaches every consumer taken - from that producer. Only tests call the consumer override, but the moq-net - integration harness (`rs/moq-net/tests/integration/support/harness.rs`) - passes it about 195 scoped consumers, and `mount.rs` and moq-mux's - `container/test_util.rs` call it too; each sets proxy on the producer it - consumes from instead. + from that producer. Only tests call the consumer override: the moq-net + integration harness (`rs/moq-net/tests/integration/support/harness.rs`, two + sites), `mount.rs`, and moq-mux's `container/test_util.rs` (two sites); + each sets proxy on the producer it consumes from instead. - `auth::Grant` gets `#[non_exhaustive]`, since [rate-grant](/quest/m5/rate-grant.md) adds rates to it; callers outside moq-net build it from `Grant::default()`. diff --git a/quest/m3/mesh/README.md b/quest/m3/mesh/README.md index a15cb272116..581c4a612fa 100644 --- a/quest/m3/mesh/README.md +++ b/quest/m3/mesh/README.md @@ -49,10 +49,10 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: the [routing identity](/quest/m2/cluster-routing/routes/README.md), which each process declares fresh. - Addressing is announcement: each node publishes its address and status - tracks under `mesh//...`, and reaching an ID is subscribing there. - There is no separate directory. Services are not under `mesh//`: each - is one socket endpoint per service name, outside every member subtree - (see [Endpoint API](/quest/m3/mesh/endpoint.md)). + tracks under `mesh/node//...`, and reaching an ID is subscribing + there. There is no separate directory. Services are not under a member + subtree: each is one socket endpoint at `mesh/service/` (decided + 2026-11-07, see [Endpoint API](/quest/m3/mesh/endpoint.md)). - Certificates can stand in for the token (decided 2026-11-07, maintainer, Kixel's planning): a downstream mesh that must admit and evict devices with no internet issues long-lived certificates from its own signers, and @@ -60,12 +60,14 @@ Decided 2026-10-25 with the maintainer (planning interview), still in force: against a trust store it supplies. The coordinator's token stays the default for `moq auth`. - The token is the binding: enrollment proves the device key, then the - coordinator issues a grant to publish `mesh//**` and subscribe + coordinator issues a grant to publish `mesh/node//**` and subscribe `mesh/**`, plus publish on its own [socket](/doc/concept/socket.md) - endpoints, `.server/` and `.client/`, so it can accept and dial - under its own id (amended 2026-11-01, 2026-11-03 when sockets became - endpoints, and 2026-11-06 when endpoints split into server and client - roles). Relays need no new check. Membership is the coordinator's + endpoints, `mesh/service/*/.server/` and `mesh/service/*/.client/`, + so it can accept and dial under its own id (amended 2026-11-01, + 2026-11-03 when sockets became endpoints, 2026-11-06 when endpoints split + into server and client roles, and 2026-11-07 when member and service + paths were scoped apart; the [Endpoint API](/quest/m3/mesh/endpoint.md) + changes the shipped `mesh//**` grant). Relays need no new check. Membership is the coordinator's token only; a Tailnet-Lock analog was declined. - Protection is per broadcast, with levels that nest: identity (the token only), authentication (per-frame Ed25519 signatures, the default), and diff --git a/quest/m3/mesh/addr.md b/quest/m3/mesh/addr.md index 90a42323fbc..66cbbc4e98f 100644 --- a/quest/m3/mesh/addr.md +++ b/quest/m3/mesh/addr.md @@ -5,7 +5,7 @@ Mesh nodes that can reach each other directly but cannot discover each other over mDNS still connect directly: each node publishes its dialable addresses (interface addresses, its listen port, its certificate fingerprint), signed by -its endpoint key, on a track under `mesh//`, and every node dials peers' +its endpoint key, on a track under `mesh/node//`, and every node dials peers' hinted addresses alongside `[cluster.lan]`. Two nodes on a network namespace with multicast disabled (the stand-in for a Docker bridge or a cloud VPC) find the direct path and prefer it over the relay. @@ -22,7 +22,7 @@ Decided 2026-10-31 (maintainer): a mesh node is a relay, and the rule in `doc/bin/relay/cluster.md` ("never a URL learned from an announcement") does not apply when the operator opts in to the mesh and everything is signed. Dial a hinted address only when the mesh is enabled, the hint verifies against -the endpoint key named by its `mesh//` path, and the dial pins the hinted +the endpoint key named by its `mesh/node//` path, and the dial pins the hinted fingerprint; admit the peer only after it proves its own enrollment, as LAN peers do. Amend that sentence of the docs with the mesh exception. diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index eeba45b8be7..7f45ed02eed 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -16,7 +16,7 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, - A service is the iroh ALPN analog: a socket endpoint per service name (below), while each node's address and status tracks stay under its - `mesh//`. + `mesh/node//`. - Decided 2026-11-01 (maintainer, socket planning interview), and updated 2026-11-03 when sockets became endpoints and 2026-11-04 when the segment became `.socket` with the protocol in the session name: an `Endpoint` wraps @@ -24,8 +24,7 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, server at `.server/`, a client at `.client/`, or both. `connect` dials with the caller's own endpoint ID, and `accept` reads the remote ID from the dial, which the socket's answer check proves and the - grant pins (publish `.server/` and `.client/` only). Update `moq auth`'s mesh grant and - `doc/bin/relay/auth.md` to match. + grant pins (publish `.server/` and `.client/` only). - Streams are [byte streams](/quest/m3/stream/rust.md) at the protection level the service declares: identity reads `moq-net` directly, and authentication, the mesh default, reads through `moq_crypto::sign` against the @@ -37,27 +36,33 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, local [mesh relay node](/quest/m3/mesh/node.md). - Write a short porting note into the [guide](/quest/m3/mesh/guide.md). -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one socket endpoint per service at prefix `mesh/`, with the grant adding publish `mesh/*/.server/` and `mesh/*/.client/`, so `moq_net::socket` ships unchanged and needs no service field. +Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): one socket endpoint per service, with a grant to publish on it under the member's own id, so `moq_net::socket` ships unchanged and needs no service field. -Two constraints on that layout, found in review of -[moq-dev/moq#8214](https://github.com/moq-dev/moq/pull/8214): +✅ Decided 2026-11-07 (maintainer, /quest-complete): scope both +namespaces. Members own `mesh/node//**` (was `mesh//**`) and each +service lives at `mesh/service/` (was `mesh/`), so the +grant adds publish `mesh/service/*/.server/` and +`mesh/service/*/.client/` (rejected: `mesh/.service/`; +keeping `mesh/` and refusing service names shaped like an endpoint +ID). Review of [moq-dev/moq#8214](https://github.com/moq-dev/moq/pull/8214) +found that each member publishing `mesh//**` lets a service named after +member A put `.server/B` under A's own grant, so A could answer as B; the +`node` and `service` segments keep the two apart. A service name is still +one path segment, validated when the `Endpoint` is built, so `*` in the +grant covers it (`video/h264` would fall outside). -- A service name is one path segment, validated when the `Endpoint` is - built, so `*` in the grant covers it (`video/h264` would fall outside). -- Service sockets must not overlap member subtrees. Each member may publish - `mesh//**`, so a service named after member A puts `.server/B` under - A's own grant, and A could answer as B. The prefix in the Waiting item - below keeps the two apart. +Member grants change shape, which breaks every enrolled device's paths: -## Waiting - -- Maintainer: pick the service prefix that keeps service sockets out of - `mesh//**`. Options: **`mesh/.service/` (recommended)**, - since endpoint IDs never start with `.`, so no member subtree can contain - it, and the grant becomes publish `mesh/.service/*/.server/` and - `.client/`; or keep `mesh/` and refuse service names that - parse as an endpoint ID, which leaves the check in every relay's grant - logic. Done when the Plan names the prefix. +- `moq_auth::mesh`'s coordinator issues publish `mesh/node//**` and the + two service patterns (`rs/moq-auth/src/mesh/coordinator.rs`), with its + docs (`rs/moq-auth/src/mesh/mod.rs`), contract tests, and a `MIGRATE.md` + entry replacing the `Pattern::subtree(&format!("mesh/{endpoint}"))` note. +- `doc/bin/relay/auth.md`'s mesh enrollment section names the new grant. +- moq-crypto's and `@moq/crypto`'s sign examples and tests that use + `mesh//agent` paths move to `mesh/node//agent`, so the examples + match the grant. +- A hosted coordinator implementing the JSON contract issues the same + grant; the PR's Impact section says so. ## Required diff --git a/quest/m3/mesh/status.md b/quest/m3/mesh/status.md index 8587d20ac74..e0db44aff97 100644 --- a/quest/m3/mesh/status.md +++ b/quest/m3/mesh/status.md @@ -3,14 +3,15 @@ ## Goal Each mesh node, a relay node with the mesh enabled or an application -embedding `Endpoint`, publishes `mesh//.status`, signed: its peers, its +embedding `Endpoint`, publishes `mesh/node//.status`, signed: its peers, its links (each with its smoothed and minimum RTT, and for a relay uplink the relay's identity), its routes, and its services. A subscriber can draw the whole mesh from these tracks alone. ## Plan -Decided 2026-10-25 (maintainer): the data is a track on `mesh/`, not an +Decided 2026-10-25 (maintainer): the data is a track on the node's +member subtree (`mesh/node/` since 2026-11-07), not an HTTP API. Decided 2026-10-31 (maintainer, moq.pro mesh planning interview): per-link diff --git a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index c08d1c591fe..3abe5a055ec 100644 --- a/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m5/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -16,7 +16,8 @@ future; consumers need advance notification. Metadata group sequences are independent of media GOPs. - A SCTE-35 scheme entry in the shared catalog `events` section names cue - tracks with optional program or rendition association, not a top-level + tracks with an optional `rendition` association (the program's rendition, + as [ID3](/quest/m5/id3.md) does), not a top-level `scte35` section (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs and remaining quests). Video is not required for audio-only programs. - Preserve complete raw splice_info_section bytes. Carry the event's presentation time on the broadcast clock; commands without splice_time diff --git a/quest/m5/ffi-e2ee.md b/quest/m5/ffi-e2ee.md index 60873455750..84d4632e6dc 100644 --- a/quest/m5/ffi-e2ee.md +++ b/quest/m5/ffi-e2ee.md @@ -20,7 +20,22 @@ the binding layer, and keep the encrypting publisher's refusal of a shared or explicit epoch. Add a binding test that decrypts a JS-published broadcast and the reverse to the interop suite. -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the bindings wrap moq-crypto's concrete `broadcast::{Producer, Consumer}` (`rs/moq-crypto/src/e2ee/broadcast.rs`, already public) directly, without waiting on [net-wrap](/quest/m5/net-wrap/README.md). So this quest requires neither e2ee quest below, both of which wait on net-wrap: it exposes encrypted tracks and frames, which is what the T3 app reads. Encrypted media publishing through moq-mux's catalog and codec publishers comes with [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md), and the bindings pick it up then without a break. +✅ Decided 2026-11-07 (maintainer, /quest-complete): wait for +[net-wrap's e2ee](/quest/m5/net-wrap/e2ee.md) and wrap its types once, +reversing the API sweep's earlier "don't wait on net-wrap". net-wrap/e2ee +reshapes moq-crypto's `broadcast::{Producer, Consumer}` (`abort` with an +error, `create_group` taking `group::Info`, `track(semantic)` then +`.subscribe(..)`, errors converting into `moq_net::Error`), so a binding +over today's types would break when it lands. There is no interim binding +over the existing encrypted broadcast types (rejected: binding the existing +encrypted types now; dropping ffi-e2ee). Encrypted media publishing through +moq-mux's catalog and codec publishers comes with +[Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md), and the +bindings pick it up then without a break. + +## Required + +- [moq-crypto's e2ee implements the moq-net traits](/quest/m5/net-wrap/e2ee.md) - the encrypted broadcast, track, and group types these bindings wrap, in their final shape ## Related From 521a9f3b43033bc611b048e1e2d5ab0d8d6ef92b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 18:11:57 -0800 Subject: [PATCH 07/11] quest: fold finish-self into finished-handle Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 1 - quest/m2/finish-self.md | 25 ------------------------- quest/m2/finished-handle.md | 25 ++++++++++++++++++++++--- 3 files changed, 22 insertions(+), 29 deletions(-) delete mode 100644 quest/m2/finish-self.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 2a3ad970eb8..9d3dc0b7593 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -206,7 +206,6 @@ quests that require them. - [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings - [Public constructors spawn nothing, or say why](/quest/m2/spawn-constructors.md) - each public library entry point that spawns returns a driver its caller polls, or is listed as kept - [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - `encode` and `decode` return any number of outputs and gain `flush`, as moq-video's do -- [Finishing consumes the producer](/quest/m2/finish-self.md) - importers and producers take `finish(self)`, so a finished producer cannot be written - [Bus writes land at a bus position](/quest/m2/bus-positioned-write.md) - callers sync audio to video without copying the bus's private latency, before the cut first publishes `bus` - [A mix-minus removes several sources](/quest/m2/bus-minus-several.md) - a guest's return feed drops every copy of their own sound - [Drop moq-auth's iroh transport](/quest/m2/auth-drop-iroh.md) - this breaking moq-auth release drops `Transport::Iroh` and the JS `"iroh"` value diff --git a/quest/m2/finish-self.md b/quest/m2/finish-self.md deleted file mode 100644 index a854562bb32..00000000000 --- a/quest/m2/finish-self.md +++ /dev/null @@ -1,25 +0,0 @@ -# [S] Finishing consumes the producer - -## Goal - -Every public importer and producer whose `finish` takes `&mut self` takes -`self` instead, so a finished producer cannot be written to and no runtime -"already finished" refusal is needed. moq-rtmp and moq-srt already consume -on finish. A `Clone` producer that shares its state (moq-json's -`snapshot`, `stream`, and `window` producers, and moq-mux's -`catalog::Producer`) still consumes the handle it finishes with, but its -other clones can still write, so it keeps the shared runtime refusal. - -## Plan - -Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs -and remaining quests): ✅ settle it as m2 before the cut (rejected: leaving -it to the finish-final child's "if this child takes it", which ships -`finish(&mut self)` plus a refusal or breaks after the cut). finish-final -landed the internal state work in -[moq-dev/moq#8210](https://github.com/moq-dev/moq/pull/8210); this quest -changes the signatures. A `finish` that can fail returns the -producer in its error when the caller can retry, and the PR says which do. -List every changed signature with its migration in the Impact section, -including moq-ffi and moq-c, whose handles keep a runtime check because a -foreign caller can't be consumed. diff --git a/quest/m2/finished-handle.md b/quest/m2/finished-handle.md index effa6ae291e..83957f56fce 100644 --- a/quest/m2/finished-handle.md +++ b/quest/m2/finished-handle.md @@ -3,12 +3,22 @@ ## Goal `finish(self)` consumes a producer and returns a `Finished` handle, so -appending after finish is a compile error instead of a runtime one. The +appending through the handle that finished is a compile error instead of a +runtime one. The handle keeps what finishing still allows: aborting, which reports a later failure and releases the cache, and, where the type supports it today, inserting below the end, such as a late group under a finished track's end. It has no append. One shape covers moq-net's `track::Producer` and `group::Producer` and the media producers and importers, with JS mirrors. +moq-rtmp and moq-srt already consume on finish. + +The compile-time guarantee covers only the consumed handle, and only in +Rust. A `Clone` producer that shares its state (such as moq-json's +`snapshot`, `stream`, and `window` producers and moq-mux's +`catalog::Producer`) leaves other clones that can still append, so those +clones keep a shared runtime refusal after any clone finishes. The JS +mirrors, moq-ffi, and moq-c can't consume a handle, so they keep a runtime +guard that refuses an append after finish. ## Plan @@ -24,6 +34,10 @@ failed finish final with explicit state and recommended against only; media only. - ✅ **Name: `Finished`**, as `track::Finished`, `group::Finished`, and so on. +- ✅ **Settle it in m2 before the cut** (maintainer, /quest-plan from the + API sweep, 2026-11-07; rejected: shipping `finish(&mut self)` plus a + refusal, then breaking after the cut). This quest absorbed the sweep's + separate `finish(self)` plan. Today each producer borrows on finish and enforces the rest at runtime. `track::Producer::finish(&self)` (`rs/moq-net/src/model/track.rs`) sets the @@ -36,11 +50,16 @@ documents as a use, becomes holding its `Finished`. Decide per type what `Finished` exposes beyond abort, such as read access to the cache or insert below the end, without adding anything the producer can't do today. +A `finish` that can fail returns the producer in its error when the caller +can retry, and the PR says which do. + This breaks every caller that finishes and then keeps using the producer. -List them in the PR, with the migration for each package in its Impact section. +List them in the PR, with every changed signature and the migration for each +package in its Impact section, including the runtime guards kept in +moq-ffi, moq-c, and the JS mirrors. Public API: breaking in moq-net, moq-mux, moq-audio, moq-json, and their JS -packages. Wire: none. +packages; moq-ffi and moq-c keep their signatures and runtime checks. Wire: none. ## Related From 324ded905fd627d8227975109e95b3cae234d38f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 18:12:15 -0800 Subject: [PATCH 08/11] quest: apply CodeRabbit's #8232 findings to catalog-finish and video-declared-end Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/catalog-finish.md | 5 +++++ quest/m1/explicit-state/video-declared-end.md | 9 +++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/quest/m1/explicit-state/catalog-finish.md b/quest/m1/explicit-state/catalog-finish.md index b13e67125e6..9fc4e3ccd54 100644 --- a/quest/m1/explicit-state/catalog-finish.md +++ b/quest/m1/explicit-state/catalog-finish.md @@ -21,4 +21,9 @@ Record the terminal outcome after the fallible work, as #8210 did: keep the first error, abort or end the other track, and store the failure rather than `Closed`. Test a failing track finish. +A handle created after the failed finish reports that same first error, not +`NotPublished`: a `catalog::Producer::video(..., None)` (or `audio`/`text`) +container producer, and its `modify()`, `set`, and the other calls that +reach the catalog. Test one created after the failure. + Public API: none. Wire: none. diff --git a/quest/m1/explicit-state/video-declared-end.md b/quest/m1/explicit-state/video-declared-end.md index 88f31eaae8d..aadb94d107c 100644 --- a/quest/m1/explicit-state/video-declared-end.md +++ b/quest/m1/explicit-state/video-declared-end.md @@ -5,7 +5,9 @@ `` doesn't count a stall while video holds its last picture through a publisher's declared end, as audio already doesn't for a declared silence. The stall count, stalled time, and the echo `stalls`/`stalled` -feedback agree between audio and video. +feedback agree between audio and video. A declared end before the first +picture also ends startup buffering, so the spinner goes away instead of +waiting for a picture that won't come. ## Plan @@ -15,6 +17,9 @@ watch count a stall only while a rendition plays. It left this one case as on `main`: a picture held through a declared end for longer than the 500 ms buffering timer still counts as a stall. Give video's playback state a declared-end phase, as audio's handles a declared silence, so the buffering -timer doesn't run there. Test a declared end held past 500 ms. +timer doesn't run there. Entering that phase clears a stalled signal that +is already raised, and stops its stalled time, as audio's declared silence +does. Test a declared end held past 500 ms, a declared end after a stall +has begun, and a declared end before the first picture. Public API: none. Wire: none. From d588515ae92498f01eb4ee938e16249c7474b506 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 18:14:51 -0800 Subject: [PATCH 09/11] quest: address CodeRabbit's open plan findings on the API sweep Co-Authored-By: Claude Opus 5.5 --- quest/m2/api-shape/bindings.md | 6 ++++++ quest/m2/api-shape/net.md | 9 ++++++--- quest/m2/gateway-ingest.md | 1 + quest/m2/group-drops.md | 11 +++++++++-- quest/m2/time-addressing/model.md | 9 ++++++++- quest/m3/cli-packaging.md | 6 +++--- quest/m3/json-snapshot-resync.md | 4 +++- quest/m3/mesh/endpoint.md | 6 ++++++ quest/m3/quic-ack-hook.md | 11 ++++++++--- quest/m3/release/api-review.md | 8 ++++++-- quest/m3/release/qmux-js-retire.md | 11 +++++++---- quest/m3/release/qmux-rs-retire.md | 11 ++++++----- quest/m4/p2p/README.md | 10 +++++++--- quest/m4/p2p/signal.md | 5 +++-- quest/m5/audio-encode-audiotoolbox.md | 1 + quest/m5/audio-encode-mediacodec.md | 1 + quest/m5/audio-encode-mediafoundation.md | 1 + quest/m5/teleop-robot.md | 11 +++++++---- 18 files changed, 89 insertions(+), 33 deletions(-) diff --git a/quest/m2/api-shape/bindings.md b/quest/m2/api-shape/bindings.md index 00a5cdb3040..937297859d5 100644 --- a/quest/m2/api-shape/bindings.md +++ b/quest/m2/api-shape/bindings.md @@ -16,6 +16,12 @@ - moq-ffi's `MoqVideoSurface` gets `#[non_exhaustive]`: it has one variant, and Android HardwareBuffer, D3D11, and DMA-BUF surfaces are planned in m3. Check any other output-only UniFFI enum an m3 quest plans to grow. + `#[non_exhaustive]` fences Rust and C only: UniFFI's Kotlin, Swift, and + Dart enums stay exhaustive, so a new variant breaks a foreign `when` or + `switch`. Open, for whoever starts this, with the maintainer: fence it in + the bindings too (recommended: the wrappers add an unknown arm that a new + variant maps to until the wrapper learns it), or record a new variant as + breaking for those bindings. - Go's `*DecoderOutput` aliases go (from [the OBS adapter](/quest/m3/obs-moq-video/adapter.md)). - Dart's wrapper names the route instance accessor `instance()`, as the diff --git a/quest/m2/api-shape/net.md b/quest/m2/api-shape/net.md index 571be4434ee..093d8078e9e 100644 --- a/quest/m2/api-shape/net.md +++ b/quest/m2/api-shape/net.md @@ -40,8 +40,8 @@ its JS and binding mirrors: `RouteEvent::Takeover`, un-hide `origin::Consumer::routes`, `Routes`, and `RouteEvent`, documented as the relay-level stream that moq-relay and downstream relays already consume, and fix `request`'s doc to say what #8063 made it - do. `RouteEvent` becomes `struct RouteEvent { kind: RouteKind, announce: - Announce }` with `enum RouteKind { Start, Update, Restart, End }`, + do. `RouteEvent` becomes `pub struct RouteEvent { pub kind: RouteKind, pub + announce: Announce }` with `pub enum RouteKind { Start, Update, Restart, End }`, mirroring JS's `{ kind } & Routed`, so callers need no or-pattern and no accessors. - `stats::Registry::report` takes an explicit `now`, and @@ -52,7 +52,10 @@ its JS and binding mirrors: fields instead of breaking moq-net again. - `group::MAX_CACHE_BYTES` becomes `pub(crate)`: byte-holes turns it from a size cap into a tail budget, and moq-json's `max_group_bytes` keeps its own - 32 MiB default. + 32 MiB default. Each outside use takes a limit of its own: moq-json's + encoder defaults and clamp, moq-mux's jitter, container-consumer, and + fMP4 bounds, the moq-stats `producer_tick` benchmark, and the oversize + tests in moq-json, moq-mux, and moq-gst. - Remove `origin::Consumer::with_proxy` (from [moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)) in favor of `origin::Producer::with_proxy`, which already reaches every consumer taken diff --git a/quest/m2/gateway-ingest.md b/quest/m2/gateway-ingest.md index e69ef0a7ae6..1316f2fd5ee 100644 --- a/quest/m2/gateway-ingest.md +++ b/quest/m2/gateway-ingest.md @@ -33,4 +33,5 @@ Added 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and rem - `whep::accept` takes a `whep::Request` (`#[non_exhaustive]`), mirroring `whip::Request`, moved here from [rtc-pacing](/quest/m3/rtc-pacing.md), so its rate handle is additive. - moq-webrtc's `server::Config.udp_bind` becomes `socket: server::Socket` (`#[non_exhaustive]`, only `Bind(SocketAddr)` today), so a fed socket from [one port](/quest/m3/one-port/README.md) is additive. +- moq-srt's dial-out `Client::publish` (`rs/moq-srt/src/dial.rs`), an egress that takes neither `Ingest` nor a request today, takes a `#[non_exhaustive]` `dial::Publish` request (the path, with room for m3's rate `Limit`), so [srt-rate-handle](/quest/m3/srt-rate-handle.md) reaches egress additively. - Per-session knobs m3 adds (the rate `Limit`, report and echo, the SRT `Wire`) are fields on these request structs or on `Ingest`, never new setters on `Client` or `Publish`. diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 1a88ccf816c..adb977da2d0 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -79,9 +79,16 @@ receive-window eviction can wait for the header, take the no-wire path, and remove this quest from [lite07-finalize](/quest/m2/lite07-finalize.md)'s Required. +Open, for whoever starts this, with the maintainer: a `Gap`'s start-keyed +`range` doesn't say how many groups it covers once starts are sparse, yet +the Goal has readers count losses. Recommended: `Gap` also carries the +number of groups dropped, which the drop set's runs already know. + Public API: breaking for `track::Ordered` only. Its one read, -`poll_next_group` (and its async wrapper), returns an item enum instead of -`Result>`: a group or a `Gap { range, error }`. +`poll_next_group` (and its async wrapper), returns +`Result>` instead of `Result>`, where +`Item` is a group or a `Gap { range, error }`; `Ok(None)` still ends the +read and `Err` still carries a track abort. Callers match the new item, and a caller that ignores drops takes the group arm; the PR's MIGRATE notes say so. `recv_group` and the unordered cursor are unchanged, so a reader that needs drop accounting reads through `Ordered`. diff --git a/quest/m2/time-addressing/model.md b/quest/m2/time-addressing/model.md index 89165d03923..e7e01574d5d 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -145,7 +145,10 @@ recorded only sequencing. (`rs/moq-net/src/model/subscription.rs`), and "oldest" is the sentinel `Relative(u64::MAX)`. Once keys are starts, `Absolute(key)` and `Time(ts)` name the same group, so `Absolute` goes; a legacy exclusive end `E` maps - to `Time(E - 1)`, since legacy keys pass through. An exclusive end of 0 + to `Time(E - 1)`, since legacy keys pass through. A legacy inclusive + start `S` keeps its bound: it resolves to the first group keyed at or + above `S`, never to an earlier group that covers `S`, and a regression + covers sparse keys (4 and 7 with a start of 5 selects 7). An exclusive end of 0 (today `sequence_bounds(..0)` and an empty range list's `Subscription::end()`) selects nothing, so it is dropped as an empty range before conversion, never saturated to `Time(0)`, which would include @@ -159,6 +162,10 @@ recorded only sequencing. invariant audit, model-4). - **Fence what grows after the cut.** Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `Position` becomes `#[non_exhaustive]`, so byte-holes can add a byte offset without a break. +- **Wires without a start.** Check which moq-lite versions can encode a + historical start; lite-01/02 may not. On any that can't, an `Oldest` or + earlier start gets the live feed, and the PR documents that exception + rather than changing the old format. - **Open, for whoever starts this, with the maintainer:** how lite-05/06, which carry both a sequence and frame timestamps, map on the way out. diff --git a/quest/m3/cli-packaging.md b/quest/m3/cli-packaging.md index 7dcbbcdd480..c165b1f82d8 100644 --- a/quest/m3/cli-packaging.md +++ b/quest/m3/cli-packaging.md @@ -19,7 +19,7 @@ Decided 2026-10-26 (maintainer): defaults stay lean, and releases build everything. A default skips any feature that is expensive to build or relies on a system library, so `cargo build` and `cargo install moq-cli` stay fast and portable. moq-cli gains a `full` feature that turns on `capture`, -`play`, `openh264`, `vaapi`, `nvidia`, and `v4l2` where the platform has it, +`play`, `transcode`, `openh264`, `vaapi`, `nvidia`, and `v4l2` where the platform has it, and every distribution (the release binaries, Nix, Docker, winget, Homebrew) builds with it. `doc/bin/cli.md` tells source builders to pass `--features full`. This replaces the earlier plan to turn `capture` and @@ -34,8 +34,8 @@ add nothing. Check each distribution actually builds: the Nix overlay needs those system dependencies present, and a Docker image without them fails at build rather -than at run. Then verify the shipped artifact runs `moq devices` and -`moq play` on each platform, since a feature that compiles into the binary and +than at run. Then verify the shipped artifact runs `moq devices`, +`moq play`, and a `transcode` command on each platform, since a feature that compiles into the binary and then fails to open a device is the same gap one layer down. Also enable `v4l2` in the Linux ARM release build, so a released binary on a diff --git a/quest/m3/json-snapshot-resync.md b/quest/m3/json-snapshot-resync.md index b8b09912d69..f995c4a3278 100644 --- a/quest/m3/json-snapshot-resync.md +++ b/quest/m3/json-snapshot-resync.md @@ -25,7 +25,9 @@ state. The maintainer approved planning the fix from #7693's iterate. - Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the consumer resyncs itself, with no new error variant. On a decode failure it resets its frame count and delta base, skips the rest - of the group, and counts the skip (optionally a `skipped()` counter). A + of the group, and counts the skip (optionally a `skipped()` counter). It + also logs a warning per skip, so a stream whose every group is malformed + is visible to an operator rather than silently stale. A terminal error stays terminal, so `@moq/room` and moq-boy need no change. - Do the same in Rust's snapshot consumer, and test a malformed delta followed by a good group in both languages. diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index 7f45ed02eed..564083bd07c 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -63,6 +63,12 @@ Member grants change shape, which breaks every enrolled device's paths: match the grant. - A hosted coordinator implementing the JSON contract issues the same grant; the PR's Impact section says so. +- Rollout: an old client with a new grant, or a new client with an old + grant, can't publish. Open, for whoever starts this, with the maintainer: + recommended, the coordinator issues both the old and new patterns for one + release while clients upgrade and refresh their tokens, then drops the old + one, with the MIGRATE entry giving that order; the old pattern keeps the + service-name collision open until it is dropped. ## Required diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index 726405dd4c4..5fa7953582e 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -61,7 +61,9 @@ The same pair goes on `send::Finished`, the handle `finish(self)` returns `offset()` mints, instead of a `u64`. The `send::Error` says why the bytes will never be acknowledged: a reset, the peer's STOP_SENDING, or the connection's loss. Both drivers forward to `moq-quic`'s own `send::Stream::poll_acked` -wait, which replaced `StreamEvent::Acked`. Four traps, each settled in moq-quic where the wait +wait, which replaced `StreamEvent::Acked`. That wait is `#[cfg(test)]` and +`pub(crate)` today (`rs/moq-quic/src/connection/streams/send.rs`), so the +first step makes it public in a normal build. Four traps, each settled in moq-quic where the wait lives: - A finished stream whose every byte was acknowledged must not look like a @@ -95,8 +97,11 @@ rejected as a fallback. Acceptance includes the first two traps, through each driver: a finished stream whose bytes were all acknowledged resolves `poll_acked` as delivered, -while a reset one resolves it with the error; and an offset past the data -written returns an error, not a panic, before and after finish. +while a reset one resolves it with the error. An offset past the data +written can only come from another stream, since only `offset()` mints one, +so that case is the foreign-offset trap: build it from a longer stream and +check it panics before the connection lock, leaving other handles on the +connection usable, before and after finish. Tests also cover: offset already acknowledged before the first poll, an offset in the middle of an in-flight frame, several waiters on one stream in diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 1d7831358f9..df0abbac3ca 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -44,8 +44,12 @@ api-diff` cannot see (GStreamer properties, CLI flags and env, MIGRATE drift) and publish versions of packages exempt from the cut's version. `just api-diff` compares against this repository's `release` branch, which never held `@moq/qmux`, so compare `js/qmux`'s candidate API against npm's newest -`@moq/qmux` (0.3.4, from moq-dev/web-transport) by hand, and the Rust `qmux` -crate against crates.io's 0.6.6 the same way. +`@moq/qmux` (0.3.4 today, from moq-dev/web-transport) by hand, and the Rust `qmux` +crate against crates.io's newest `qmux` (0.6.6 today) the same way. The +web-transport publishers are frozen by then +([qmux-js-retire](/quest/m3/release/qmux-js-retire.md), +[qmux-rs-retire](/quest/m3/release/qmux-rs-retire.md)), so the newest is +the last. This review still runs after m2 lands, over what changed since. ## Required diff --git a/quest/m3/release/qmux-js-retire.md b/quest/m3/release/qmux-js-retire.md index 1165977e5ac..3a3f9e9242d 100644 --- a/quest/m3/release/qmux-js-retire.md +++ b/quest/m3/release/qmux-js-retire.md @@ -22,7 +22,10 @@ publication and a maintainer with npm rights: ## Waiting -- Maintainer: with npm rights, run the deprecation above and freeze - web-transport's `js/qmux` publisher before the cut; an agent has no npm or - web-transport rights. Done when `npm view @moq/qmux repository` names - moq-dev/moq and `npm view @moq/web-socket-stream deprecated` is set. +- Maintainer: freeze web-transport's `js/qmux` publisher before the cut, + then, with npm rights, run the deprecation above once the first moq + release of `@moq/qmux` is on npm, so the migration guide never points at + web-transport's 0.3.4; an agent has no npm or web-transport rights. Done + when web-transport's release config no longer publishes `@moq/qmux`, + `npm view @moq/qmux repository` names moq-dev/moq, and + `npm view @moq/web-socket-stream deprecated` is set. diff --git a/quest/m3/release/qmux-rs-retire.md b/quest/m3/release/qmux-rs-retire.md index 62945dff551..c6a19e3d905 100644 --- a/quest/m3/release/qmux-rs-retire.md +++ b/quest/m3/release/qmux-rs-retire.md @@ -4,7 +4,8 @@ After the first `qmux` crate built from `rs/qmux` in this repository is on crates.io, moq-dev/web-transport no longer publishes `qmux`: its `rs/qmux` -is frozen or removed, its release-plz config drops the crate, and its README +is removed from its workspace or marked `release = false` in its +release-plz config (dropping the entry alone leaves it publishable), and its README points at moq-dev/moq, so one repository owns the crate name. Check with `cargo info qmux` (its repository names moq-dev/moq) and the @@ -20,7 +21,7 @@ move or close them there. ## Waiting - Maintainer: with rights in moq-dev/web-transport, freeze or remove its - `rs/qmux` and drop the crate from its release-plz config before the cut - publishes `qmux` from this repository; an agent has no publish rights - there. Done when `cargo info qmux` names moq-dev/moq and web-transport's - release-plz config no longer lists `qmux`. + `rs/qmux` (remove it from the workspace, or set `release = false` for it + in release-plz) before the cut publishes `qmux` from this repository; an + agent has no publish rights there. Done when `cargo info qmux` names + moq-dev/moq and web-transport can no longer publish `qmux`. diff --git a/quest/m4/p2p/README.md b/quest/m4/p2p/README.md index 80ec16e9c03..71fbb021d2d 100644 --- a/quest/m4/p2p/README.md +++ b/quest/m4/p2p/README.md @@ -15,7 +15,9 @@ fails: a symmetric NAT, a denied local-network prompt, or a filtered multicast segment leaves the client exactly where it started. The application is in charge of policy. It supplies the ICE servers (an empty -list is LAN only: host candidates and nothing else), publishes opaque hints +list disables ICE servers: only host and mDNS candidates, which pair on a +LAN when the network allows it, and can still pair across the Internet +when a host address, often IPv6, is publicly reachable), publishes opaque hints about itself, decides which roster peers to dial, and sets the roster size above which new negotiations stop using STUN. P2P is off unless the application turns it on. @@ -78,8 +80,10 @@ not a `Peers` knob): - `prefix`: the reserved prefix, `.p2p/` under the session root by default; - `iceServers`: the default RTCPeerConnection server list, which each - selected or admitted peer may override with its own; empty means LAN only. - Host and mDNS candidates are always gathered, so LAN pairing never stops, + selected or admitted peer may override with its own; empty disables ICE + servers (no STUN or TURN), which is not a LAN-only guarantee. + Host and mDNS candidates are always gathered, so LAN pairing stays + possible where local-network access and mDNS work, and changing a peer's list never closes an established pair; - `meta`: an opaque JSON value published in this peer's roster entry; - application-owned peer selection: discovery exposes candidates and only diff --git a/quest/m4/p2p/signal.md b/quest/m4/p2p/signal.md index 222cc191907..e2b0a58a565 100644 --- a/quest/m4/p2p/signal.md +++ b/quest/m4/p2p/signal.md @@ -60,8 +60,9 @@ of open PRs and remaining quests): each selected or admitted peer takes its own `iceServers`, defaulting to `Peers`' list, which replaces the earlier roster-size gate and its `max` knob. An application that wants to stop using STUN past some roster size passes an empty list for the peers it selects -then. Host and mDNS candidates are always gathered, so LAN pairs form with -an empty list. Changing a peer's list never closes an established pair; test +then. Host and mDNS candidates are always gathered, so an empty list can +still pair on a LAN when local-network access and mDNS resolution work; +otherwise the peers stay on the relay. Changing a peer's list never closes an established pair; test roster churn and pending negotiations separately. Native entries: when `info.webtransport` is present the dialer tries its diff --git a/quest/m5/audio-encode-audiotoolbox.md b/quest/m5/audio-encode-audiotoolbox.md index 24418d94649..0af2d77d65a 100644 --- a/quest/m5/audio-encode-audiotoolbox.md +++ b/quest/m5/audio-encode-audiotoolbox.md @@ -36,6 +36,7 @@ and remaining quests), so it adds no break and waits on no other backend. ## Required +- [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - the encoder API this backend implements - [AudioToolbox decode](/quest/m3/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it ## Related diff --git a/quest/m5/audio-encode-mediacodec.md b/quest/m5/audio-encode-mediacodec.md index d7ca20bd077..153a7204761 100644 --- a/quest/m5/audio-encode-mediacodec.md +++ b/quest/m5/audio-encode-mediacodec.md @@ -30,4 +30,5 @@ and remaining quests), so it adds no break and waits on no other backend. ## Required +- [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - the encoder API this backend implements - [MediaCodec decode](/quest/m5/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m5/audio-encode-mediafoundation.md b/quest/m5/audio-encode-mediafoundation.md index 4443124132f..dcfe5a345c8 100644 --- a/quest/m5/audio-encode-mediafoundation.md +++ b/quest/m5/audio-encode-mediafoundation.md @@ -25,5 +25,6 @@ and remaining quests), so it adds no break and waits on no other backend. ## Required +- [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - the encoder API this backend implements - [Media Foundation decode](/quest/m5/audio-decode-mediafoundation.md) - the round-trip regression decodes through it diff --git a/quest/m5/teleop-robot.md b/quest/m5/teleop-robot.md index 457c25b19b9..ca8d6563595 100644 --- a/quest/m5/teleop-robot.md +++ b/quest/m5/teleop-robot.md @@ -15,7 +15,7 @@ Decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and r crate, too niche for a published library with no second consumer). The shapes below become documented conventions, and `moq-mavlink` ships as a moq-cli gateway like moq-srt. If a second consumer appears, generalize -moq-boy's announce-prefix fan-in into moq-net instead of adding a robot +an announce-prefix fan-in helper into moq-net instead of adding a robot crate. Where the text below says "the crate", read "the conventions". Decided 2026-10-08: parked in m5. No teleoperation consumer needs the crate @@ -89,8 +89,11 @@ The framing is where the guarantee lives, not the subscription flags: fields. Decide whether the robot's fields ride there or in a namespaced root section through `moq-mux`'s `CatalogExt` and `RenditionConfig`. No hang schema change. -- Announce-prefix fan-in, documented from `rs/moq-boy/src/input.rs`; the - code stays in moq-boy until a second consumer moves it into moq-net. +- Announce-prefix fan-in, documented against moq-net's origin announce + stream (`origin::Consumer`'s announcements under a prefix). moq-boy no + longer reads viewer broadcasts (its viewers dial a socket endpoint), so + there is no fan-in code to move; a helper lands in moq-net only when a + second consumer needs one. - The two delivery classes with the group structure and `Info::max_age` each one needs: `moq-json`'s snapshot and stream modes for JSON; plain tracks for opaque bytes, one group per latest value or one bounded ordered group @@ -112,7 +115,7 @@ its own quest. A command, the telemetry sample it produced, and the video frame showing the result share one timebase, so a recording is usable as training data and an operator sees what the machine actually saw. -The bridge is each broadcast's fixed catalog-root `clock: { wall, timescale }`, +The bridge is each broadcast's fixed catalog `media.clock: { wall, timescale }`, documented in `doc/concept/hang.md` (#4461). Media and command tracks keep their own timescales; convert PTS explicitly into the broadcast clock before joining samples. The robot's video and telemetry share a clock; the operator's From 7eecc2d8022c96c81e84696fc041bb3ee7a3905f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 21:54:02 -0800 Subject: [PATCH 10/11] quest: address review threads on the API sweep Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/catalog-finish.md | 5 ----- quest/m1/explicit-state/video-declared-end.md | 9 ++------- quest/m2/api-shape/bindings.md | 4 ++-- quest/m3/mesh/endpoint.md | 7 ++++--- quest/m3/release/api-review.md | 6 +++--- quest/m3/release/qmux-rs-retire.md | 5 +++-- quest/m4/p2p/README.md | 11 ++++++----- quest/m4/p2p/harness.md | 2 +- quest/m4/p2p/signal.md | 15 ++++++++++----- quest/m5/audio-encode-audiotoolbox.md | 2 +- quest/m5/audio-encode-mediacodec.md | 2 +- quest/m5/audio-encode-mediafoundation.md | 2 +- 12 files changed, 34 insertions(+), 36 deletions(-) diff --git a/quest/m1/explicit-state/catalog-finish.md b/quest/m1/explicit-state/catalog-finish.md index 9fc4e3ccd54..b13e67125e6 100644 --- a/quest/m1/explicit-state/catalog-finish.md +++ b/quest/m1/explicit-state/catalog-finish.md @@ -21,9 +21,4 @@ Record the terminal outcome after the fallible work, as #8210 did: keep the first error, abort or end the other track, and store the failure rather than `Closed`. Test a failing track finish. -A handle created after the failed finish reports that same first error, not -`NotPublished`: a `catalog::Producer::video(..., None)` (or `audio`/`text`) -container producer, and its `modify()`, `set`, and the other calls that -reach the catalog. Test one created after the failure. - Public API: none. Wire: none. diff --git a/quest/m1/explicit-state/video-declared-end.md b/quest/m1/explicit-state/video-declared-end.md index aadb94d107c..88f31eaae8d 100644 --- a/quest/m1/explicit-state/video-declared-end.md +++ b/quest/m1/explicit-state/video-declared-end.md @@ -5,9 +5,7 @@ `` doesn't count a stall while video holds its last picture through a publisher's declared end, as audio already doesn't for a declared silence. The stall count, stalled time, and the echo `stalls`/`stalled` -feedback agree between audio and video. A declared end before the first -picture also ends startup buffering, so the spinner goes away instead of -waiting for a picture that won't come. +feedback agree between audio and video. ## Plan @@ -17,9 +15,6 @@ watch count a stall only while a rendition plays. It left this one case as on `main`: a picture held through a declared end for longer than the 500 ms buffering timer still counts as a stall. Give video's playback state a declared-end phase, as audio's handles a declared silence, so the buffering -timer doesn't run there. Entering that phase clears a stalled signal that -is already raised, and stops its stalled time, as audio's declared silence -does. Test a declared end held past 500 ms, a declared end after a stall -has begun, and a declared end before the first picture. +timer doesn't run there. Test a declared end held past 500 ms. Public API: none. Wire: none. diff --git a/quest/m2/api-shape/bindings.md b/quest/m2/api-shape/bindings.md index 937297859d5..47e97abbf68 100644 --- a/quest/m2/api-shape/bindings.md +++ b/quest/m2/api-shape/bindings.md @@ -16,8 +16,8 @@ - moq-ffi's `MoqVideoSurface` gets `#[non_exhaustive]`: it has one variant, and Android HardwareBuffer, D3D11, and DMA-BUF surfaces are planned in m3. Check any other output-only UniFFI enum an m3 quest plans to grow. - `#[non_exhaustive]` fences Rust and C only: UniFFI's Kotlin, Swift, and - Dart enums stay exhaustive, so a new variant breaks a foreign `when` or + `#[non_exhaustive]` fences Rust and C only: UniFFI's Kotlin, Swift, Python, + Dart, and C++ enums stay exhaustive, so a new variant breaks a foreign `when` or `switch`. Open, for whoever starts this, with the maintainer: fence it in the bindings too (recommended: the wrappers add an unknown arm that a new variant maps to until the wrapper learns it), or record a new variant as diff --git a/quest/m3/mesh/endpoint.md b/quest/m3/mesh/endpoint.md index 564083bd07c..7d359254e9b 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -55,8 +55,9 @@ Member grants change shape, which breaks every enrolled device's paths: - `moq_auth::mesh`'s coordinator issues publish `mesh/node//**` and the two service patterns (`rs/moq-auth/src/mesh/coordinator.rs`), with its - docs (`rs/moq-auth/src/mesh/mod.rs`), contract tests, and a `MIGRATE.md` - entry replacing the `Pattern::subtree(&format!("mesh/{endpoint}"))` note. + docs (`rs/moq-auth/src/mesh/mod.rs`), and contract tests; the PR's Impact section + replaces the `Pattern::subtree(&format!("mesh/{endpoint}"))` migration note + (`MIGRATE.md` is written at the release cut). - `doc/bin/relay/auth.md`'s mesh enrollment section names the new grant. - moq-crypto's and `@moq/crypto`'s sign examples and tests that use `mesh//agent` paths move to `mesh/node//agent`, so the examples @@ -67,7 +68,7 @@ Member grants change shape, which breaks every enrolled device's paths: grant, can't publish. Open, for whoever starts this, with the maintainer: recommended, the coordinator issues both the old and new patterns for one release while clients upgrade and refresh their tokens, then drops the old - one, with the MIGRATE entry giving that order; the old pattern keeps the + one, with the PR's Impact section giving that order; the old pattern keeps the service-name collision open until it is dropped. ## Required diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index df0abbac3ca..67bdabc584e 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -45,11 +45,11 @@ and publish versions of packages exempt from the cut's version. `just api-diff` compares against this repository's `release` branch, which never held `@moq/qmux`, so compare `js/qmux`'s candidate API against npm's newest `@moq/qmux` (0.3.4 today, from moq-dev/web-transport) by hand, and the Rust `qmux` -crate against crates.io's newest `qmux` (0.6.6 today) the same way. The -web-transport publishers are frozen by then +crate against crates.io's newest `qmux` (0.6.6 today) the same way. Run +this comparison only after both web-transport publishers are frozen ([qmux-js-retire](/quest/m3/release/qmux-js-retire.md), [qmux-rs-retire](/quest/m3/release/qmux-rs-retire.md)), so the newest is -the last. +the last; if a freeze lands later, repeat it. This review still runs after m2 lands, over what changed since. ## Required diff --git a/quest/m3/release/qmux-rs-retire.md b/quest/m3/release/qmux-rs-retire.md index c6a19e3d905..73feccddcfe 100644 --- a/quest/m3/release/qmux-rs-retire.md +++ b/quest/m3/release/qmux-rs-retire.md @@ -8,7 +8,8 @@ is removed from its workspace or marked `release = false` in its release-plz config (dropping the entry alone leaves it publishable), and its README points at moq-dev/moq, so one repository owns the crate name. -Check with `cargo info qmux` (its repository names moq-dev/moq) and the +Check crates.io's published `qmux` (`cargo info qmux` run outside this +workspace, which otherwise reports the local package; its repository names moq-dev/moq) and the web-transport release-plz config. ## Plan @@ -23,5 +24,5 @@ move or close them there. - Maintainer: with rights in moq-dev/web-transport, freeze or remove its `rs/qmux` (remove it from the workspace, or set `release = false` for it in release-plz) before the cut publishes `qmux` from this repository; an - agent has no publish rights there. Done when `cargo info qmux` names + agent has no publish rights there. Done when crates.io's published `qmux` names moq-dev/moq and web-transport can no longer publish `qmux`. diff --git a/quest/m4/p2p/README.md b/quest/m4/p2p/README.md index 71fbb021d2d..2ee0ad1e4af 100644 --- a/quest/m4/p2p/README.md +++ b/quest/m4/p2p/README.md @@ -18,8 +18,8 @@ The application is in charge of policy. It supplies the ICE servers (an empty list disables ICE servers: only host and mDNS candidates, which pair on a LAN when the network allows it, and can still pair across the Internet when a host address, often IPv6, is publicly reachable), publishes opaque hints -about itself, decides which roster peers to dial, and sets the roster size -above which new negotiations stop using STUN. P2P is off unless the +about itself, decides which roster peers to dial, and may pass a peer an empty +`iceServers` list, for example past a roster size it picks. P2P is off unless the application turns it on. Three endpoint pairs work: browser to browser and browser to native over a @@ -82,8 +82,9 @@ not a `Peers` knob): - `iceServers`: the default RTCPeerConnection server list, which each selected or admitted peer may override with its own; empty disables ICE servers (no STUN or TURN), which is not a LAN-only guarantee. - Host and mDNS candidates are always gathered, so LAN pairing stays - possible where local-network access and mDNS work, + Host and mDNS candidates are gathered where the browser's privacy policy + allows, so LAN pairing stays possible where local-network access and mDNS + work, with the relay as fallback otherwise, and changing a peer's list never closes an established pair; - `meta`: an opaque JSON value published in this peer's roster entry; - application-owned peer selection: discovery exposes candidates and only @@ -165,7 +166,7 @@ Extractor declaration checks, which analyze only published packages since ## Required -- [Signaling and policy](/quest/m4/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used +- [Signaling and policy](/quest/m4/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and per-peer `iceServers` decide whether STUN is used - [Native pairs over ICE and QUIC](/quest/m4/p2p/native-quic.md) - two native peers connect through ICE, then `moq-quic` over the nominated path with fingerprints pinned from the offer - [moq-cli joins](/quest/m4/p2p/cli.md) - `--p2p` publishes a roster entry, dials native peers over ICE and QUIC, and serves browsers as a transit hop - [Peer route policy](/quest/m4/p2p/cost-scopes.md) - application priorities and total cost choose eligible routes, with epoch-aware handover diff --git a/quest/m4/p2p/harness.md b/quest/m4/p2p/harness.md index d24556b7935..9bcd341faff 100644 --- a/quest/m4/p2p/harness.md +++ b/quest/m4/p2p/harness.md @@ -31,7 +31,7 @@ Matrix: Add publisher/consumer and roster/selected-pair sweeps, including explicit full-mesh selection, roster churn, pending negotiations and cancellation. Report connection counts, signaling bytes, wakes, CPU and retained state; -the STUN roster gate alone does not bound pairing. Verify the CDN control +per-peer `iceServers` alone do not bound pairing. Verify the CDN control session survives peer handover while unused CDN payload demand stops. Real CDN/P2P route-health cases extend this harness from the m5 [Route health](/quest/m5/route-health/README.md) line, not here. diff --git a/quest/m4/p2p/signal.md b/quest/m4/p2p/signal.md index e2b0a58a565..f1da28f152c 100644 --- a/quest/m4/p2p/signal.md +++ b/quest/m4/p2p/signal.md @@ -59,11 +59,16 @@ ICE servers, decided 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): each selected or admitted peer takes its own `iceServers`, defaulting to `Peers`' list, which replaces the earlier roster-size gate and its `max` knob. An application that wants to stop using -STUN past some roster size passes an empty list for the peers it selects -then. Host and mDNS candidates are always gathered, so an empty list can -still pair on a LAN when local-network access and mDNS resolution work; -otherwise the peers stay on the relay. Changing a peer's list never closes an established pair; test -roster churn and pending negotiations separately. +STUN past some roster size passes an empty list for the peers it selects or +admits then. Host and mDNS candidates are gathered where the browser's privacy +policy allows, so an empty list can still pair on a LAN when local-network +access and mDNS resolution work, or across the Internet through a publicly +reachable host candidate, and a selected native peer may still connect over +its advertised WebTransport URL; otherwise the peers stay on the relay. +Changing a peer's list never closes an established pair; it applies to the +peer's next negotiation, and a pair whose ICE failed renegotiates with the new +list, without touching other pairs. Test roster churn and pending +negotiations separately. Native entries: when `info.webtransport` is present the dialer tries its URLs in advertised order, using `connect` with the listener's fingerprint diff --git a/quest/m5/audio-encode-audiotoolbox.md b/quest/m5/audio-encode-audiotoolbox.md index 0af2d77d65a..dd27a266390 100644 --- a/quest/m5/audio-encode-audiotoolbox.md +++ b/quest/m5/audio-encode-audiotoolbox.md @@ -32,7 +32,7 @@ the encode seam as the platform candidate on macOS and iOS. This backend implements the zero-or-more packet return and `flush` that [audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other backend. +and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. ## Required diff --git a/quest/m5/audio-encode-mediacodec.md b/quest/m5/audio-encode-mediacodec.md index 153a7204761..1ebf6a5cfd9 100644 --- a/quest/m5/audio-encode-mediacodec.md +++ b/quest/m5/audio-encode-mediacodec.md @@ -26,7 +26,7 @@ behind the `mediacodec` feature and the encode seam. This backend implements the zero-or-more packet return and `flush` that [audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other backend. +and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. ## Required diff --git a/quest/m5/audio-encode-mediafoundation.md b/quest/m5/audio-encode-mediafoundation.md index dcfe5a345c8..45412ce22b3 100644 --- a/quest/m5/audio-encode-mediafoundation.md +++ b/quest/m5/audio-encode-mediafoundation.md @@ -21,7 +21,7 @@ behind the encode seam on Windows. This backend implements the zero-or-more packet return and `flush` that [audio-codec-seam](/quest/m2/audio-codec-seam.md) lands in m2 before the cut (decided 2026-11-07, maintainer, /quest-plan from the API sweep of open PRs -and remaining quests), so it adds no break and waits on no other backend. +and remaining quests), so it adds no break and waits on no other encoder backend; its round-trip test still needs its platform decoder. ## Required From ca4bb3dedf9bf1df233e29a24246af3e3a4b8a5a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 22:28:51 -0800 Subject: [PATCH 11/11] quest: a peer's iceServers change does not retry a failed pair Co-Authored-By: Claude Opus 5.5 --- quest/m4/p2p/signal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m4/p2p/signal.md b/quest/m4/p2p/signal.md index f1da28f152c..620215c1cc7 100644 --- a/quest/m4/p2p/signal.md +++ b/quest/m4/p2p/signal.md @@ -66,8 +66,8 @@ access and mDNS resolution work, or across the Internet through a publicly reachable host candidate, and a selected native peer may still connect over its advertised WebTransport URL; otherwise the peers stay on the relay. Changing a peer's list never closes an established pair; it applies to the -peer's next negotiation, and a pair whose ICE failed renegotiates with the new -list, without touching other pairs. Test roster churn and pending +peer's next negotiation (a failed pair stays failed until a re-announce, as +Lifecycle says). Test roster churn and pending negotiations separately. Native entries: when `info.webtransport` is present the dialer tries its