quest: plan the API shape fixes from the release-vs-main audit

quest/m1/README.md

@@ -48,6 +48,8 @@ moves what remains of them once their claims merge.
 - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out
 - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; time-stretched browser playback without steady-state underruns and a native trace replay remain
 - [Buffered playback subscribes in ascending order](/quest/m1/buffered-ascending.md) - a buffered `<moq-watch>` asks for the oldest group first, so a voice reply's opening arrives first, and audio's head hold shrinks to the floor
+- [One assets() for every hosted file](/quest/m1/hosted-assets.md) - `@moq/hang` owns `assets()`, which also points the libav polyfill at the hosted wasm
+- [Watch sources default to the decoder's probe](/quest/m1/watch-supported-default.md) - a source built without `in.supported` plays instead of selecting nothing
 - [Push-to-talk's press-to-audible latency fits a budget on the defaults](/quest/m1/push-to-talk-latency.md) - press to audible on the browser defaults, excluding device output, stays under a kixtop-measured budget that `just test push-to-talk` enforces
 - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide
 - [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

quest/m1/explicit-state/ffi-state.md

@@ -51,6 +51,14 @@ Also sweep:
 - `MoqServer` (`server.rs`): its lifecycle is spread over four places.
 - `MoqTrackProducer.keep: None`, which means both "finished" and "has no
   family".
+- `MoqConnectionState` (`session.rs`) is a flat snapshot (`revision`,
+  `phase`, `connects`, `failure`, `version`), so `failure` and `version` are
+  readable in phases where they mean nothing. It carries each phase's data
+  with that phase, mirroring whatever shape Rust's connection state takes,
+  and moq-c's `moq_connection_state` follows (renaming its `protocol` to
+  `version`). It breaks every binding, so under the epic's milestone rule
+  this item splits into its own m2 quest when this quest starts (added
+  2026-11-07, maintainer, /quest-plan from the API shape audit).
 - moq-c's global id counter, whose wrap lets a stale route id name a newer
   broadcast. Use generation-tagged ids or clear ids on close.
 

quest/m1/explicit-state/publish-capture.md

@@ -45,6 +45,10 @@ Also sweep:
 - The preview `Transcode.#active`.
 - The `<moq-watch>` and `<moq-publish>` enable latches (`#enabled`,
   `#connected`, `#invalid`, `#resume`). Derive enabled as connected with no
-  invalid attributes.
+  invalid attributes. `<moq-publish>`'s `announce` getter returns
+  `AnnounceMode`, and an invalid `announce` attribute suspends announcing
+  through `#invalid` like every other attribute, instead of the getter
+  returning `undefined` (added 2026-11-07, maintainer, /quest-plan from the
+  API shape audit).
 - `js/moq-boy/src/game.ts`: a command sent while disconnected replays on
   reconnect.

quest/m1/hosted-assets.md

@@ -0,0 +1,21 @@
+# [S] One assets() for every hosted file
+
+## Goal
+
+A page that serves the player's files itself (for a strict
+`Content-Security-Policy` with no `blob:` workers) calls one `assets(url)`,
+and that call also points the libav AAC polyfill at the hosted wasm. Today
+`@moq/watch` and `@moq/publish` each carry an identical copy of `assets()`
+(`js/watch/src/assets.ts`, `js/publish/src/assets.ts`), and an app that
+needs the polyfill must also import `@moq/libav` and set its mutable
+`LibAV.base`, a transitive dependency our API never mentions.
+
+## Plan
+
+Found by the 2026-11-07 API shape audit (browser media). Move `assets` and
+its resolver into `@moq/hang`, the shared dependency whose
+`Util.Libav.polyfill()` (`js/hang/src/util/libav.ts`) loads libav, and have
+the polyfill take its base from it. `@moq/watch` and `@moq/publish`
+re-export it, so their existing `assets()` callers keep working and nothing
+breaks. `@moq/libav` stays an implementation dependency. Future hosted files
+(the watch worker) join the same call. Test it on the CSP demo pages.

quest/m1/stream-credit/README.md

@@ -36,10 +36,17 @@ which JS cannot raise; Chrome stalled at 103, Firefox at 100):
   browser test stays this README's own work. Not chosen: holding the whole
   quest until #7670 merges.
 
+- Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit):
+  ✅ delete Rust's `StreamCredit` hook too, with no replacement hook
+  ([no-credit-hook](/quest/m1/stream-credit/no-credit-hook.md)). #7894's
+  reversal removed the JS half; the Rust trait kept it because the open line
+  reads it. Not chosen: keeping the hook and recording why.
+
 This epic owns the end-to-end test: a browser reader and a Rust relay over
 WebTransport, 300 live tracks of mixed priority, the highest-priority ones
 receiving every group, and nothing hanging.
 
 ## Required
 
 - [Takeover](/quest/m1/stream-credit/takeover.md) - on lite-07 a higher-priority group takes over an acknowledged stream, and a group that lost its stream resumes
+- [Transports report no stream credit](/quest/m1/stream-credit/no-credit-hook.md) - `StreamCredit` and the `poll::Session::stream_credit` hook are gone, and the open line infers a credit wait from its own state

quest/m1/stream-credit/no-credit-hook.md

@@ -0,0 +1,29 @@
+# [S] Transports report no stream credit
+
+## Goal
+
+`moq_net::transport::StreamCredit`, `Dir`, and the `poll::Session::stream_credit`
+hook are gone, so no transport implements a credit API. The open line
+(`rs/moq-net/src/transport/open.rs`) decides when a waiting open preempts a
+lower-ranked stream from its own state, as `js/net` already does, and an
+open waiting on something other than credit still never triggers a reset.
+
+## Plan
+
+Decided 2026-11-07 (maintainer, /quest-plan from the API shape audit):
+✅ "Delete, no hooks" (rejected: keeping the hook and recording why). This
+follows the [moq-dev/moq#7894](https://github.com/moq-dev/moq/pull/7894)
+reversal recorded in this epic ("the signal is the open line's waiting
+state, with no transport credit or blocked API") and overrides
+[moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088)'s refutation,
+which kept the hook because the open line reads it.
+
+The hook exists today so an open waiting on a WebTransport stream header is
+not mistaken for a credit wait (`make_room`, open.rs). Remove that case at
+its source, for example by having a transport's open complete only once
+credit is granted and write the header after, so a pending head always means
+credit. Implementers of `poll::Session` (moq-tokio, moq-uring, qmux, the
+memory transport) drop their implementations.
+
+Breaking for transport implementers; the Impact section says what replaces
+the hook.

quest/m1/watch-supported-default.md

@@ -0,0 +1,16 @@
+# [XS] Watch sources default to the decoder's probe
+
+## Goal
+
+A composer that builds `@moq/watch`'s `Audio.Source` or `Video.Source`
+without `in.supported` gets playback. Today the input defaults to
+`undefined`, and "nothing is selected until one is provided"
+(`js/watch/src/audio/source.ts`), so forgetting it is silent non-playback.
+When `in.supported` is absent, the source uses its decoder's `supported`
+probe.
+
+## Plan
+
+Found by the 2026-11-07 API shape audit (browser media). Additive: callers
+that pass `supported`, such as the `<moq-watch>` element, are unchanged. Add a test that a source built without it selects a
+rendition.

quest/m2/README.md

@@ -163,6 +163,13 @@ Added 2026-11-04 (maintainer): the relay reports the native sessions its
 drain deadline force-closes while still open, apart from those only finishing
 their end report, so an embedder's drain alert pages on real cuts.
 
+Added 2026-11-07 (maintainer, /quest-plan from an API shape audit of
+`release` against `main` and the open quests): the breaks it found that the
+cut would otherwise publish. A route's role becomes its type; JS durations
+and instants become objects; native playout sync decouples its tracks like
+the browser's; sentinels, moq-video's environment reads, and per-gateway
+ingest setters go; and an epic batches the small fixes per area.
+
 Decided 2026-11-05 (maintainer, /quest-audit): blockers rank above the
 quests that require them.
 
@@ -178,12 +185,19 @@ quests that require them.
 - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate (held in m1 by an open claim)
 - [Cluster routing](/quest/m2/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters
 - [A job's exact route continues its claim's readers](/quest/m2/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design
+- [A route's role is its type](/quest/m2/route-roles.md) - no route method panics, throws, or errors because the other constructor made the route; prototypes of a single prefix route and an exact/prefix split decide the shape
 - [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - the wire names every abandoned group and the drop signal is public, so readers count losses instead of stalling
 - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out (held in m1 by an open claim)
 - [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it
 - [Unbounded groups](/quest/m2/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh
 - [moq-quic drops inherited surfaces with no consumer](/quest/m2/moq-quic-unused-surface.md) - unused accept, connection, and stream-id surfaces leave moq-quic's public API before the cut
 - [Publish reports rendition stats as hang's type](/quest/m2/rendition-stats-type.md) - `Rendition.stats` and `Report.Writer` take the rendition stats schema's input type, so encoders write plain numbers
+- [No sentinel values in public API](/quest/m2/no-sentinels.md) - receive windows, cache durations, reconnect timeouts, and the FFI test clock use `Option` instead of a huge value or zero
+- [moq-video takes devices, not environment variables](/quest/m2/video-devices.md) - VA-API and V4L2 device paths are config fields, and `moq_video::ENV` never ships
+- [Gateways share one ingest config and one rate cap](/quest/m2/gateway-ingest.md) - `moq_mux::Ingest` replaces 18 per-gateway setters, and the live rate cap moves to `moq_net::bandwidth`
+- [Native playout sync keeps tracks decoupled](/quest/m2/mux-sync.md) - `moq_mux::timeline` becomes `moq_mux::sync`, and one slow track no longer stalls or moves another
+- [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile
+- [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings
 - [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto (held in m1 by an open claim)
 - [A recreated or restarted track cannot reuse group sequences](/quest/m2/sequence-reuse.md) - recreating a track or restarting an instance cannot give new content an old group identity unless the app seeds past it, and datagrams are documented as exempt
 - [Subscriptions name the oldest group without a u64::MAX sentinel](/quest/m2/anchor-oldest.md) - `Anchor` gets an explicit oldest variant, decoded the same way on every wire

quest/m2/api-shape/README.md

@@ -0,0 +1,53 @@
+# [L] Small API fixes before the cut
+
+## Goal
+
+The surfaces `main` adds since `release` follow the repository's API rules
+before the cut publishes them: one path and one spelling per item, names by
+role, no dead or unreachable public items, no setter that a caller can apply
+to the wrong role, and Rust, JS, and the bindings mirrored. Each child is a
+batch of small, mostly breaking fixes to one area, sized so one PR reviews in
+one sitting.
+
+## Plan
+
+Planned 2026-11-07 (maintainer, /quest-plan) from an audit of `release`
+(a005c7ad9a) against `main` (a9d7925123) plus the open quests. Nine
+read-only reviewers (net model, net session, transport, media formats,
+native media, apps, JS core, browser media, bindings) scored 127 clusters
+for performance, usability, testability, and future fit, using
+`just api-diff` and consumer searches in this repository and its
+downstream applications. The maintainer approved the plan as shown. The larger findings
+became their own m1, m2, m3, and m4 quests; this epic holds the rest.
+
+This audit ran while [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088),
+the previous API audit's final pass, was open, and none of its children
+repeats an item #8088 changes. A child that starts after #8088 merges
+rechecks each item against `main` and drops what is already done.
+
+Rules every child follows:
+
+- Removal beats addition. A public item with no caller in this repository,
+  a known downstream application goes private, unless an m1 or m2 quest plans a
+  caller.
+- No serde aliases, refusals, or shims for a spelling `release` never
+  shipped.
+- Each child lists its public API and wire impact in its PR, and its Impact
+  section says how to migrate.
+
+Rejected in planning:
+
+- One audit PR for every area: each child touches a different owner's code,
+  and #8088 showed that a 100-file audit PR spends weeks rebasing.
+- Folding these items into the larger quests: those wait on decisions or
+  prototypes, and these do not.
+
+## Required
+
+- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, and priority surface, and no public wire codes
+- [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals
+- [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name
+- [Native media's small surface fixes](/quest/m2/api-shape/native.md) - audio encode internals go private, `on_demand` has one meaning, and video and render setters fold into their constructors
+- [Apps' small surface fixes](/quest/m2/api-shape/apps.md) - the relay, gateways, moq-hls, moq-cli, and moq-boy drop dead or unreachable surface and gain role names
+- [JS packages' small surface fixes](/quest/m2/api-shape/js.md) - track info, connection, qmux, watch, publish, ui, video, boy, and auth exports each have one path and one name
+- [Bindings' small surface fixes](/quest/m2/api-shape/bindings.md) - Go's read cancel, JSON producer construction, and the Python wheel's test module

quest/m2/api-shape/apps.md

@@ -0,0 +1,35 @@
+# [M] Apps' small surface fixes
+
+## Goal
+
+- moq-relay:
+  - `Internal::with_uring` becomes crate-private; it takes a type nobody
+    outside can build since `uring` went private.
+  - The hidden refusals for config keys and flags `release` never shipped
+    (`[session]`, `[peer]`, `--peer-*`, `--limits-*-requests`,
+    `auth.verifications`) are deleted.
+  - `cluster::Options.session` becomes `client`, matching its type and the
+    `[limits.client]` key.
+  - `Relay::{rtmp, webrtc}` become take-once `&mut self -> Option<_>`, like
+    `admissions()`.
+  - `session::View` and `shutdown::{Tally, Drained}` get
+    `#[non_exhaustive]`.
+- moq-webrtc drops the dead `Error::{SessionNotFound, SessionClosed}` and
+  hides `p2p` (`#[doc(hidden)]`, as on release) until the
+  [m4 p2p work](/quest/m4/p2p/README.md) has a caller.
+- moq-srt's `dial` module becomes private; `Client` keeps one path.
+- moq-hls gains `Error::is_denied()`, so embedders stop matching nested
+  errors.
+- `moq export hls`'s listener flags become `--hls-listen` and
+  `--hls-tls-{cert,key,generate,root}`, matching the `MOQ_HLS_*`
+  environment, with named refusals for the old flags, which shipped.
+- moq-boy's Rust crate stops exporting its internals (the JS half is in
+  [the JS child](/quest/m2/api-shape/js.md)).
+
+## Plan
+
+Found by the 2026-11-07 API shape audit (apps); see the
+[epic](/quest/m2/api-shape/README.md). Decided 2026-11-07 (maintainer):
+✅ hide `p2p` until m4 (rejected: keep it public; delete it). Gateway ingest
+is [gateway-ingest](/quest/m2/gateway-ingest.md). Downstream code that
+matches the deleted webrtc variants loses only dead arms.

quest/m2/api-shape/bindings.md

@@ -0,0 +1,23 @@
+# [S] Bindings' small surface fixes
+
+## Goal
+
+- Go: a cancelled context on `Next`, `ReadFrame`, or `RecvGroup` cancels
+  only that read, as in Python, Swift, Kotlin, Dart, and C++. Today
+  `go/wrapper/subscribe.go` passes the consumer's `Cancel`, so a caller
+  cannot bound one read and continue. Range-loop iterators still cancel the
+  consumer when the loop exits. Check first that the Go generator fork
+  supports a per-call cancel.
+- JSON tracks have one constructor shape in moq-ffi and every wrapper: a
+  producer the catalog advertises comes from the catalog producer, not from
+  a free constructor that the caller must then register.
+- Python: `moq.testing` leaves the published wheel; tests import it from the
+  source tree.
+
+## Plan
+
+Found by the 2026-11-07 API shape audit (bindings); see the
+[epic](/quest/m2/api-shape/README.md). The generated check that each
+hand-written wrapper exports every FFI item is
+[binding-export-coverage](/quest/m4/binding-export-coverage.md). moq-c's
+renames are in [moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060).

quest/m2/api-shape/js.md

@@ -0,0 +1,35 @@
+# [M] JS packages' small surface fixes
+
+## Goal
+
+- `@moq/net`:
+  - A resolved `Track.Info` uses `null` for "none" (`maxAge`, `timescale`);
+    `Track.infoDefaults` and the `Track.rescale` alias go.
+  - `Connection.Established` becomes `Session`, and the orphan
+    `Connection.Extensions` type goes.
+  - `readBool` goes; it has no caller and no Rust mirror.
+  - `RouteOptions.instance` takes `{ id, epoch }`, like Rust's
+    `with_instance(instance, epoch)`.
+- `@moq/qmux` exports `Session` by name instead of an anonymous default.
+- `@moq/watch`: the decoder and source plumbing outputs are `@internal`, the
+  renderer's output is a named `Video.RendererOutput`, and `<moq-watch>`'s
+  `player` property goes private, so each component has one path.
+- `@moq/publish`: `Rendition.onDemand` becomes an enum, `Broadcast.join`
+  becomes a `Getter`, and the five internal source helpers are unexported.
+- `@moq/ui` and `@moq/video` mark their helpers `@internal`; only `Support`,
+  `Report`, `Show`, `Level`, and `Status` stay public in `@moq/ui`, and
+  `rotateVideoDimensions`, `Dimensions`, `Presentation`, and
+  `Preview.Transcode` leave `@moq/video`'s public API.
+- `@moq/boy` stops exporting `Game`, `GameConfig`, `KEY_MAP`, and its
+  `Moq` and `Watch` namespace re-exports, keeping the element and status
+  schemas.
+- `@moq/auth`'s `Key.sign` takes one spelling for caps.
+
+## Plan
+
+Found by the 2026-11-07 API shape audit (JS core and browser media); see
+the [epic](/quest/m2/api-shape/README.md). Durations are
+[js-time-types](/quest/m2/js-time-types.md); hosted assets and the
+`supported` default are m1 quests. Each change updates its package's
+`api/*.api.md`, and moq.dev's npm consumer is checked for each removed
+export.