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..2fb4b51138e 100644 --- a/quest/m1/hosted-assets.md +++ b/quest/m1/hosted-assets.md @@ -12,10 +12,20 @@ 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. + +✅ 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/README.md b/quest/m2/README.md index 062bef3c7a3..fa75bcb69f3 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. @@ -197,6 +204,12 @@ 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 +- [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) - [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 - [Finishing a producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes moq-net's and the media crates' producers, so appending after finish doesn't compile diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index 41890acc694..1b78418aacc 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -22,13 +22,23 @@ 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 +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. @@ -44,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 - [Crates re-export no whole crate](/quest/m2/api-shape/reexports.md) - no moq crate re-exports a whole crate, moq's own included, so a dependency bump is no moq break, and moq-mux's container `Guard` gets a name - [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 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..47e97abbf68 100644 --- a/quest/m2/api-shape/bindings.md +++ b/quest/m2/api-shape/bindings.md @@ -13,9 +13,25 @@ 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. + `#[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 + 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 + 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..fbd3ae4f7c3 100644 --- a/quest/m2/api-shape/media.md +++ b/quest/m2/api-shape/media.md @@ -6,8 +6,25 @@ 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. 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. +- `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 +37,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..093d8078e9e 100644 --- a/quest/m2/api-shape/net.md +++ b/quest/m2/api-shape/net.md @@ -40,12 +40,46 @@ 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 `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 + `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. 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 + 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()`. ## 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 +`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. #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 d7372270b15..c0315582702 100644 --- a/quest/m2/api-shape/transport.md +++ b/quest/m2/api-shape/transport.md @@ -6,13 +6,38 @@ 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. + 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, 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 +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..516e03c47ac --- /dev/null +++ b/quest/m2/audio-codec-seam.md @@ -0,0 +1,26 @@ +# [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. 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/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 05743abd669..246d319dd14 100644 --- a/quest/m2/cluster-routing/routes/README.md +++ b/quest/m2/cluster-routing/routes/README.md @@ -542,7 +542,6 @@ benchmarks. - [Route layer acceptance](/quest/m2/cluster-routing/routes/acceptance.md) - forwarding fixtures ported and the model deleted, incident fixtures, end-to-end checks, and 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 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/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/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 479b6d8cd87..df7e5168df7 100644 --- a/quest/m2/cluster-routing/routes/session.md +++ b/quest/m2/cluster-routing/routes/session.md @@ -27,21 +27,24 @@ 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: remove `Hops`, `RouteInfo::hops`, and the saturating `Cost` - from the public API now, keeping a private chain type for lite-06 and the - moq-transport cluster extension, which still carry hop chains. Decided - 2026-11-07 (maintainer, /quest-unblock): ✅ now (rejected: when lite-06 - retires). It is a breaking change; the PR marks its title with `!`. - -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, and /quest-unblock confirmed + ✅ now the same day. It is a breaking change; the PR marks its title with `!`. + - `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/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 diff --git a/quest/m2/gateway-ingest.md b/quest/m2/gateway-ingest.md index 7e8c30772fe..1316f2fd5ee 100644 --- a/quest/m2/gateway-ingest.md +++ b/quest/m2/gateway-ingest.md @@ -28,3 +28,10 @@ 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. +- 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 5b159451806..adb977da2d0 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -67,14 +67,38 @@ 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. -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. +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. + +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 +`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`. +`@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 - [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..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. @@ -16,6 +18,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 +31,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/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/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..e7e01574d5d 100644 --- a/quest/m2/time-addressing/model.md +++ b/quest/m2/time-addressing/model.md @@ -130,10 +130,42 @@ 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` + 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. 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 + 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 + `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. +- **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. @@ -181,7 +213,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..8b16f273dbc 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 @@ -80,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 @@ -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..c165b1f82d8 100644 --- a/quest/m3/cli-packaging.md +++ b/quest/m3/cli-packaging.md @@ -18,24 +18,24 @@ 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`, -`play`, `openh264`, `vaapi`, `nvidia`, and `v4l2` where the platform has it, +and portable. moq-cli gains a `full` feature that turns on `capture`, +`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 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. 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 @@ -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,7 +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`. + +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/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..45f85c9d539 100644 --- a/quest/m3/fetch-synced.md +++ b/quest/m3/fetch-synced.md @@ -13,4 +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. +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 72dc11ad530..97ad64bcf8a 100644 --- a/quest/m3/h265-min-width.md +++ b/quest/m3/h265-min-width.md @@ -37,8 +37,9 @@ 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 diff --git a/quest/m3/import-metadata-policy.md b/quest/m3/import-metadata-policy.md index cf69b1a3584..a941b64383d 100644 --- a/quest/m3/import-metadata-policy.md +++ b/quest/m3/import-metadata-policy.md @@ -16,6 +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. +Public API: possibly a shared refusal error in moq-mux. Wire: none. 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..f995c4a3278 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,16 +23,16 @@ 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). 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. -Public API: a new decode error in `@moq/json` and `moq-json`. Wire: none. +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 a5ef1c0f716..581c4a612fa 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/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 @@ -57,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 @@ -115,4 +120,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/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/cert-credentials.md b/quest/m3/mesh/cert-credentials.md index 1108e7237d5..2b43a2a51be 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 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. + ## 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..7d359254e9b 100644 --- a/quest/m3/mesh/endpoint.md +++ b/quest/m3/mesh/endpoint.md @@ -14,18 +14,17 @@ 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/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 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 - `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,6 +36,41 @@ 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, with a grant to publish on it under the member's own id, so `moq_net::socket` ships unchanged and needs no service field. + +✅ 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). + +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`), 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 + 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 PR's Impact section giving that order; the old pattern keeps the + service-name collision open until it is dropped. + ## Required - [Rust byte streams](/quest/m3/stream/rust.md) - the stream this API returns 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/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/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/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..10dff4968f6 100644 --- a/quest/m3/probe-rung-disable-js.md +++ b/quest/m3/probe-rung-disable-js.md @@ -32,7 +32,9 @@ 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 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..5fa7953582e 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>; } ``` @@ -54,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 @@ -67,11 +76,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 @@ -85,15 +97,17 @@ 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 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). 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/release/api-review.md b/quest/m3/release/api-review.md index 9104e5c0d67..67bdabc584e 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -41,7 +41,15 @@ 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 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. 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; 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/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..3a3f9e9242d 100644 --- a/quest/m3/release/qmux-js-retire.md +++ b/quest/m3/release/qmux-js-retire.md @@ -19,3 +19,13 @@ 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: 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 023603d24ea..73feccddcfe 100644 --- a/quest/m3/release/qmux-rs-retire.md +++ b/quest/m3/release/qmux-rs-retire.md @@ -4,10 +4,12 @@ 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 +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 @@ -15,5 +17,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` (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 crates.io's published `qmux` names + moq-dev/moq and web-transport can no longer publish `qmux`. diff --git a/quest/m3/rtc-pacing.md b/quest/m3/rtc-pacing.md index 33c1707fd88..5b8b589dcea 100644 --- a/quest/m3/rtc-pacing.md +++ b/quest/m3/rtc-pacing.md @@ -58,12 +58,17 @@ 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. +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 1c6226e9c91..218322aea5d 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -53,7 +53,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/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/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/README.md b/quest/m4/p2p/README.md index ab012abe793..2ee0ad1e4af 100644 --- a/quest/m4/p2p/README.md +++ b/quest/m4/p2p/README.md @@ -15,9 +15,11 @@ 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 -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 +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 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 @@ -71,16 +73,19 @@ 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 disables ICE + servers (no STUN or TURN), which is not a LAN-only guarantee. + 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 explicitly selected peers are dialed; incoming connections need application @@ -161,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/cli.md b/quest/m4/p2p/cli.md index a965979e7ce..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. 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 e2db53633ce..620215c1cc7 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,20 @@ 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 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 (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 URLs in advertised order, using `connect` with the listener's fingerprint 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/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/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..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 @@ -15,8 +15,10 @@ 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 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 use the media clock observed at arrival. Do not delay publication until the @@ -26,14 +28,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 +47,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 f9af65133f8..a972d90f560 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 @@ -68,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 @@ -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..dd27a266390 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,8 +29,14 @@ 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). +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 encoder backend; its round-trip test still needs its platform decoder. + ## 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 5ef9c74bb0f..1ebf6a5cfd9 100644 --- a/quest/m5/audio-encode-mediacodec.md +++ b/quest/m5/audio-encode-mediacodec.md @@ -17,13 +17,18 @@ 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. +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 encoder backend; its round-trip test still needs its platform decoder. + ## 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 -- [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 d0bb8cf4578..45412ce22b3 100644 --- a/quest/m5/audio-encode-mediafoundation.md +++ b/quest/m5/audio-encode-mediafoundation.md @@ -18,8 +18,13 @@ 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. +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 encoder backend; its round-trip test still needs its platform decoder. + ## 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 +- [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/auth-http-request-kind.md b/quest/m5/auth-http-request-kind.md index 13d76e6e910..b4505d81022 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) 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 - [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..84d50d91f5e 100644 --- a/quest/m5/emsg.md +++ b/quest/m5/emsg.md @@ -55,8 +55,10 @@ 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 +- [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 4181c2c45c2..84d4632e6dc 100644 --- a/quest/m5/ffi-e2ee.md +++ b/quest/m5/ffi-e2ee.md @@ -20,7 +20,24 @@ 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-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 -- [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 +- [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 + +- [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/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..ca8d6563595 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, so an +integrator writes an adapter rather than a stack. There is no `moq-robot` +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 +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 +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 yet; telemetry beside video needs [data sync](/quest/m3/watch-data-sync.md), not this primitive. @@ -79,7 +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, generalised from `rs/moq-boy/src/input.rs`. +- 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 @@ -101,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 @@ -116,11 +130,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