diff --git a/quest/m1/precut-fixes/README.md b/quest/m1/precut-fixes/README.md new file mode 100644 index 00000000000..6f64066414c --- /dev/null +++ b/quest/m1/precut-fixes/README.md @@ -0,0 +1,34 @@ +# Pre-cut correctness fixes + +## Goal + +Every defect the 2026-11-17 pre-cut correctness audit found is fixed on `main` before the `0.22.0` cut, +so the cut publishes none of them. + +## Plan + +The audit read everything that changed from `release` +([ca3b801a6c](https://github.com/moq-dev/moq/commit/ca3b801a6c)) to `main` +([ec5a19540f](https://github.com/moq-dev/moq/commit/ec5a19540f)) for bugs, +hostile input, performance, fragile lifecycles, and unproven claims, with +eighteen read-only reviewers by area. API shape and whether a feature should +exist were out of scope: the 2026-11-16 audit and the +[API shape review](/quest/m3/release/api-review.md) own them. So was code an +open m2 quest replaces (the old lite-07 route rule, YIELDED continuations, +lite-07 sequence addressing, socket endpoints, moq-e2ee). + +Decided 2026-11-17 (maintainer, [moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): ✅ every finding gates the cut, including those `release` already ships, +so they all live in this epic, which the cut requires (rejected: gating only +what `release` lacks, the agent's /quest-afk recommendation; gating none). +The one exception: ✅ [ts-step-damage](/quest/m1/ts-step-damage.md) is a +standalone low-priority m1 quest outside the gate, since it was read from +source with no field report (rejected: keeping it in the gate; deleting it). +✅ Every quest the audit added stays in m1 (rejected: only this epic in m1). + +Each child reproduces its finding before fixing it: most were read from +source, not run. The reviewers' reports were scratch and are not kept; each +quest carries what its implementer needs. + +## Related + +- [Feature review](/quest/m3/release/feature-review.md) - the delta pass after m2 judges what m2 lands, which this audit skipped diff --git a/quest/m1/precut-fixes/archive-isolate.md b/quest/m1/precut-fixes/archive-isolate.md new file mode 100644 index 00000000000..c3c99a88921 --- /dev/null +++ b/quest/m1/precut-fixes/archive-isolate.md @@ -0,0 +1,29 @@ +# [S] One broadcast's failure never ends export archive for the others + +## Goal + +`moq export archive` records every broadcast independently: a broadcast +whose recording fails (a re-added track with another priority or timescale, +reused group sequences, a listing that ends in an error) is logged and +dropped, and every other broadcast keeps recording. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. +`rs/moq-cli/src/archive.rs` returns the first recording's error, which drops +the task set and aborts every other recording. `doc/bin/cli.md` documents it +("Any recording that fails ends the export"), but AGENTS.md's Required rule +says a publisher that breaks its identity hurts only its own broadcast. + +Decided 2026-11-17 (maintainer, [moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): ✅ log and drop the failed broadcast and keep exporting the rest; +the command still fails if the origin itself fails (rejected: keeping the +documented behavior, which lets one publisher end everyone's recording). +Update `doc/bin/cli.md`. Also check whether an ordinary publisher disconnect +surfaces as a listing error, which would make this hit on every dropped +session. + +Public API: none (CLI behavior). Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#4034](https://github.com/moq-dev/moq/pull/4034) - added `export archive` with one failure ending every recording diff --git a/quest/m1/precut-fixes/audio-capture-drift.md b/quest/m1/precut-fixes/audio-capture-drift.md new file mode 100644 index 00000000000..dc168a105bf --- /dev/null +++ b/quest/m1/precut-fixes/audio-capture-drift.md @@ -0,0 +1,25 @@ +# [M] Captured audio stays in sync with video over long sessions + +## Goal + +Native audio capture corrects its device clock's skew against the host clock, +so a published broadcast's audio does not drift against its video over hours: +the offset after a long session stays within one audio frame of the offset at +its start. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; measure +first. `rs/moq-audio/src/encode/producer.rs` and `encode/capture.rs` set the +audio PTS once from the first capture time and then advance it by sample +count at the nominal rate, while video is stamped from each frame's capture +time (`rs/moq-video/src/encode/producer.rs`). A mic clock tens to hundreds of +ppm off the host accumulates as A/V offset: an estimated 0.18 to 0.36 s per +hour at 50 to 100 ppm. On `release` too. + +Recommended: compare each buffer's capture time with its sample-count PTS and +correct the skew by resampling, the way the playback ring tracks its clock. +Measure with a simulated device clock offset by a fixed ppm, and on real +hardware over an hour. + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/bindings-negative-duration.md b/quest/m1/precut-fixes/bindings-negative-duration.md new file mode 100644 index 00000000000..82258f08fcd --- /dev/null +++ b/quest/m1/precut-fixes/bindings-negative-duration.md @@ -0,0 +1,26 @@ +# [S] Swift and Go refuse a negative duration with an error, not a crash + +## Goal + +Every duration a Swift or Go caller passes to the bindings is checked by the +wrapper, so a negative, infinite, or NaN value returns the wrapper's config +error instead of aborting the app, as Kotlin and Python already throw a +catchable exception. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source. The +generated converters call `fatalError` (Swift, from the pinned UniFFI fork) +or `panic` (Go) on a negative duration. Go guards every duration except +`EncoderOutput.Join` (`go/wrapper/video/video.go`). Swift guards none: +`Client(timeout:race:resolutionDelay:)` is documented to throw a config error +and aborts instead, and the JSON and media `delay`, `TrackInfo.maxAge`, +`Backoff`, and `VideoEncoderOutput.join` do the same. Neither API is on +`release`. + +Recommended: check in each wrapper before building the record, with a test +per wrapper. Fixing the generator fork instead would also fix any future +duration; prefer it if the fork takes the change cheaply +([UniFFI forks](/quest/m3/vendor-sync/uniffi.md)). + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/capture-audio-reopen.md b/quest/m1/precut-fixes/capture-audio-reopen.md new file mode 100644 index 00000000000..b1ed2d90fd6 --- /dev/null +++ b/quest/m1/precut-fixes/capture-audio-reopen.md @@ -0,0 +1,30 @@ +# [S] moq import capture keeps publishing when its microphone fails + +## Goal + +`moq import capture` survives a microphone that fails mid-session (a USB mic +re-enumerating, another app taking the default input, a sample-rate change): +the audio track reopens the device with backoff, as `release` did, and the +video track never stops because audio failed. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. In +`rs/moq-cli/src/publish.rs` the audio future returns the capture error and +`tokio::try_join!` fails the whole command, video included. +[moq-dev/moq#7706](https://github.com/moq-dev/moq/pull/7706) removed the +library's automatic reopen on purpose (`rs/moq-audio/MIGRATE.md`: "no +automatic device reopen"), but nothing moved the reopen into the CLI. +`release` recovered within 0.5 to 4 s. + +Decided 2026-11-17 (maintainer, [moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): ✅ the CLI reopens the capture and its publication in a loop +with `release`'s backoff, keeping #7706's decision that the library does not +(rejected: putting the reopen back in moq-audio, which reverses that +decision; ending only the audio track with no reopen). A failure that persists past the backoff ends only the audio +track, with its error, and the video keeps running. + +Public API: none (CLI behavior). Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#7706](https://github.com/moq-dev/moq/pull/7706) - removed moq-audio's device reopen without moving it to the CLI diff --git a/quest/m1/precut-fixes/error-outcomes.md b/quest/m1/precut-fixes/error-outcomes.md new file mode 100644 index 00000000000..3048e8e05fd --- /dev/null +++ b/quest/m1/precut-fixes/error-outcomes.md @@ -0,0 +1,37 @@ +# [M] Five call sites stop matching on errors + +## Goal + +None of these decide behavior by matching an error variant (AGENTS.md: +"Never match on errors"); each callee reports the case as a typed outcome +instead: + +- `rs/moq-stats/src/produce.rs`: whether an oversized frame aborts a track. +- `rs/moq-hls/src/import.rs`: refusing a rewind (`TimestampRewind`, + `NonMonotonicDecodeTime`) instead of retrying; give the fMP4 importer a + typed rewind outcome, as [moq-dev/moq#8939](https://github.com/moq-dev/moq/pull/8939) + did for TS import. +- `rs/qmux/src/driver.rs` `deliver`: a WebSocket message over the record + limit fails in tungstenite with `Capacity` and lands in the catch-all, so + the session resets with no CONNECTION_CLOSE. The WebSocket transport + reports "over the record limit" as an outcome and the driver sends + FRAME_ENCODING_ERROR. Also make `js/qmux` close violations with QUIC + transport codes, as rs/qmux does, keeping 1002/1003 for the WebSocket + close only. +- `rs/moq-uring/src/quic/driver/connection.rs` and + `rs/moq-tokio/src/quic/driver/connection.rs`: both skip publishing a close + reason when it is `Error::LocallyClosed`, then guess whether the close is + staged; moq-quic says directly whether a close is still owed. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source. None breaks +today; each turns a future error change into a silent behavior change (a +retry loop, a lost CONNECTION_CLOSE). Each is internal; check the HLS and +qmux ones with a test that drives the case end to end. + +Public API: none. Wire: none. + +## Related + +- [Session codes](https://github.com/moq-dev/moq/commit/b4c1db719358a25e351771e8ad33f01d45169bb0) - errors classify themselves in moq-net diff --git a/quest/m1/precut-fixes/failover-models-sync.md b/quest/m1/precut-fixes/failover-models-sync.md new file mode 100644 index 00000000000..cd2dd929996 --- /dev/null +++ b/quest/m1/precut-fixes/failover-models-sync.md @@ -0,0 +1,30 @@ +# [M] The failover and resume models mirror the code, and an ended track a reader holds keeps rerouting + +## Goal + +`FailoverChain.tla` and `ResumeReader.tla` describe the code that ships, their +skills' sync commits name a commit at or after the last covered change, and +an ended track that a reader still holds keeps moving a slow read to another +route after its 30 s linger. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source. + +- `.claude/skills/verify-failover/SKILL.md` still names 88572c583e and + `verify-resume/SKILL.md` names 103052ed07, though + [moq-dev/moq#8896](https://github.com/moq-dev/moq/pull/8896) edited both + models and #8859, #8958, #8867, and #8638 changed covered code since. + `ResumeReader.tla` cites `Route::finished`, which no longer exists. Run both + skills on `main`, mirror what changed, and move the sync commits. +- The linger and `Action::Conclude` are not modelled, and `Mesh.cfg`, the only + config that reaches the reroute, is sampled rather than exhaustive. Model the + linger. +- `rs/moq-net/src/model/front.rs` and the `Forget` arm in `origin.rs`: + `abort_unwanted` returns true for a closed track a reader still holds, so + after the linger the track's I/O drops and a slow read of the last group + fails when its upstream route dies. The `Reroute` path checks `is_held()`; + `Forget` does not. Recommended: don't forget an ended track while it is + held. Reproduce with the model before fixing. From #8896. + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/fmp4-init-backpressure.md b/quest/m1/precut-fixes/fmp4-init-backpressure.md new file mode 100644 index 00000000000..ff3b4230676 --- /dev/null +++ b/quest/m1/precut-fixes/fmp4-init-backpressure.md @@ -0,0 +1,36 @@ +# [M] The fMP4 export holds back reading, not memory, until its init segment + +## Goal + +Before it writes its init segment, the fMP4 export +(`rs/moq-mux/src/container/fmp4/export.rs`) holds a bounded share of each +track instead of queueing every other track's fragments for up to 30 s of +their own timestamps. A broadcast whose video never becomes describable, or +whose timestamps never advance, costs a subscriber bounded memory and ends +with `TrackUndescribed`. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. +`INIT_QUEUE` compares a track's frame timestamps with its first one, so a +publisher with frozen or bouncing timestamps never trips it, and every +fragment goes into `Init::Waiting` while an undescribable rendition holds the +init. That memory sits in `moq-cli subscribe`, moq-video's decoder, and +moq-transcode on a server. `release` held at most one pending frame per +track, as the MKV, FLV, and TS exports on `main` still do. + +Recommended: stop polling a track once it has queued its share before the +init, the way the other exports gate on the jitter buffer's `full`, so the +backlog stays in the transport cache that the subscription's max delay +already bounds; and time the init wait by arrival on the local clock, not by +the publisher's timestamps. + +Test: a simulated-clock export with one undescribable video track and an +audio track whose timestamps never advance; assert the queue stays bounded +and the export fails with `TrackUndescribed` after the wait. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#4883](https://github.com/moq-dev/moq/pull/4883) - queued fragments behind the init with only a media-time limit diff --git a/quest/m1/precut-fixes/js-net-leaks.md b/quest/m1/precut-fixes/js-net-leaks.md new file mode 100644 index 00000000000..64d3ced46cb --- /dev/null +++ b/quest/m1/precut-fixes/js-net-leaks.md @@ -0,0 +1,30 @@ +# [S] js/net leaks nothing on a long listing or an early subscription end + +## Goal + +`@moq/net` holds no listener, resolver, or group past its use: a front's +track listing does not grow per TRACKS event, a lite publisher closes a held +first group when its subscription ends first, and the ietf publisher sends +END_OF_TRACK only when the subscription's range reaches the track's end, as +Rust does. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first. + +- `js/net/src/resume.ts` `Front.#list`: `race([listing.next, wait()...])` + leaves the inner race's three registrations pending each time + `listing.next` wins. The same pattern is in `lite/subscriber.ts` + (`reoffers.changed()`). Race the change waits directly. From #6158 and + #8476. +- `js/net/src/lite/publisher.ts`: `first = { group, largest }` is held while + the source start is pending, and the early exits and the `finally` never + close it, so a relayed filled group keeps reading upstream for nobody. Close + it in the `finally`. From #6206. +- `js/net/src/ietf/publisher.ts`: `#runEndOfTrack` is sent unclipped to a + bounded subscription's range; port Rust's `reached` check from + `TrackServe::end` ([moq-dev/moq#5283](https://github.com/moq-dev/moq/pull/5283)). + On `release` too. + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/lite07-range-union.md b/quest/m1/precut-fixes/lite07-range-union.md new file mode 100644 index 00000000000..d82e74f4e0e --- /dev/null +++ b/quest/m1/precut-fixes/lite07-range-union.md @@ -0,0 +1,41 @@ +# [M] A lite-07 relay's upstream ranges always fit, and an update costs only its edit + +## Goal + +A lite-07 relay never gives back the upstream copy every viewer reads through +because its viewers' ranges, merged, do not fit one message: when the exact +union is too large it asks for a covering superset. A SUBSCRIBE_UPDATE costs +work proportional to the ranges it edits, not to every range the +subscription holds. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first. Rechecked after [moq-dev/moq#8908](https://github.com/moq-dev/moq/pull/8908) +rewrote lite-07 to address groups by start: it changed the ranges' units, not +how they merge. lite-07 publishes for the first time at this cut, so this +gates it. + +- The union in `rs/moq-net/src/model/track/demand/ranges.rs` (`fold`) merges + only touching runs. One session sending two SUBSCRIBEs of about 10k + interleaved single-group ranges, each fitting a message, makes a union that + does not; the upstream SUBSCRIBE_UPDATE fails and the shared copy is given + back (`lite/subscriber.rs`), and each new route hits the same union, so + other sessions' viewers end with an error. Gap fills across many viewers + can fragment the union the same way with no hostile peer. `edit_keyed` in + `lite/subscribe.rs` also changes its stored ranges before the size check, + so a refused edit leaves them out of step with what was sent. Recommended: + when the exact union cannot fit, coarsen it by merging the smallest gaps + until it fits, and size-check before mutating. Test: a relay with those two + SUBSCRIBEs over a lite-07 upstream, asserting a third plain viewer keeps + receiving. +- `LiveRanges::apply` returns every live range (`numbered`), and + `TrackRun::update` in `lite/publisher.rs` rebuilds its lookups and hands the + whole list to the track under the lock every subscriber of it shares, so a + stream of empty updates against a 32k-range subscription copies megabytes + each. Recommended: apply only the edit, keyed by Range ID, and skip the + track call when nothing changed. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#7872](https://github.com/moq-dev/moq/pull/7872) - exact range unions and whole-set updates diff --git a/quest/m1/precut-fixes/moq-c-rate-thread.md b/quest/m1/precut-fixes/moq-c-rate-thread.md new file mode 100644 index 00000000000..3b06f103fc4 --- /dev/null +++ b/quest/m1/precut-fixes/moq-c-rate-thread.md @@ -0,0 +1,29 @@ +# [S] moq-c's video rate follower runs off the session runtime + +## Goal + +A moq-c video encoder that follows a bandwidth allocator never blocks the +`moq-c` runtime thread, which drives every session's I/O, timers, and C +callbacks: a bitrate change, a rung flush, or a hardware encoder reopen +stalls only the encoder. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. +`follow_reservation` in `rs/moq-c/src/video.rs` runs through +`ffi::Background` on the single current-thread `RUNTIME` +(`rs/moq-c/src/ffi.rs`) and waits there on the encoder lock (held by a C +thread for a whole encode) and on codec round trips. moq-ffi already runs +the same loop on its own thread (`spawn_follow` in `rs/moq-ffi/src/video.rs`) +for exactly this reason. `release` blocked on bitrate changes only; the +flush and reopen came with #6781. + +Recommended: copy moq-ffi's dedicated-thread follower. Measure before and +after: step the bandwidth across a rung threshold and record another +subscription's frame delivery gaps. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#6781](https://github.com/moq-dev/moq/pull/6781) - added rung flush and encoder reopen to the follower on the shared runtime diff --git a/quest/m1/precut-fixes/nix-auth-restart.md b/quest/m1/precut-fixes/nix-auth-restart.md new file mode 100644 index 00000000000..56fd4d74c5f --- /dev/null +++ b/quest/m1/precut-fixes/nix-auth-restart.md @@ -0,0 +1,28 @@ +# [XS] Upgrading the NixOS moq-auth unit restarts the relay through its handoff + +## Goal + +With `services.moq-relay.handoff` on, a `nixos-rebuild switch` that changes +both units restarts the relay through `SIGUSR2` and keeps its sessions, +instead of stopping it cold because its required `moq-auth` unit stopped. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source and +systemd's semantics. In `nix/modules/moq-relay.nix`, `moq-auth` is +`requiredBy` the relay and keeps the default `stopIfChanged = true`. Its +`ExecStart` names the `moq-cli` store path, so nearly every upgrade changes +it: switching stops `moq-auth`, `Requires=` propagates the stop to the relay, +and the relay drains every session and starts with no handoff. + +Decided 2026-11-17 (maintainer, [moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): ✅ `moq-auth` sets `stopIfChanged = false`, so it restarts in place +and nothing propagates (rejected: `wants` instead of `requiredBy`, which lets +the relay run with no auth server and refuse every session). Check it with +the module's NixOS VM test if one covers handoff, else by a switch on a +test host. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#8596](https://github.com/moq-dev/moq/pull/8596) - made moq-auth a required unit of the relay diff --git a/quest/m1/precut-fixes/relay-config-loud.md b/quest/m1/precut-fixes/relay-config-loud.md new file mode 100644 index 00000000000..b5f3e24621d --- /dev/null +++ b/quest/m1/precut-fixes/relay-config-loud.md @@ -0,0 +1,40 @@ +# [S] Relay cluster config fails loud, keeps secrets out of logs, and its upgrade notes are right + +## Goal + +The relay refuses cluster settings it would ignore, never echoes a secret in +an error, re-checks a refreshed grant like every other credential, resets +its redial backoff after a stable session, and its upgrade notes name real +flags. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; each item confirmed from +source by its reviewer, reproduce first. + +- `rs/moq-relay/src/cluster.rs`: `release` accepted the 64-hex LAN secret + inline; `main` reads it as a file path and fails with "failed to read + secret file ", printing the mesh key into logs on upgrade. Refuse + an inline-looking value without echoing it. +- `rs/moq-relay/src/auth/refresh.rs`: the grant re-read at protocol setup + skips the root, mounts, link, and role checks the other credential paths + run (`valid()`); run them. +- `rs/moq-relay/src/cluster.rs`: `run_remote_once` only returns an error, so + the "reset after a stable session" backoff branch is unreachable and long + outages leave every later redial at 30 s. Reset on whether the attempt + connected. On `release` too. +- `rs/moq-relay/src/config.rs`: `cluster.api.root` without `cluster.api.url`, + and `cluster.token` on a relay with no peers to dial, are accepted and + never read; refuse both at startup. On `release` too. A config key that + starts failing is a break: note it in the PR's Impact for the migration + audit. +- `rs/moq-auth/src/wire.rs` and `key.rs`: Rust accepts `null` on grant and key + fields `@moq/auth` refuses (`"scope": null` loads as an unrestricted key). + Use the existing reject-`null` deserializer and add corpus cases. +- Docs: `rs/moq-relay/MIGRATE.md` names `--mtls-peer`, which does not exist + (`--mtls-link peer`), and never mentions that certificate-only peers now get + client limits and are cut off past 1000 broadcasts; `doc/bin/relay/auth.md` + says an older auth server reads new transport names as `unknown`, but a + `release` `moq auth serve` answers 422. + +Public API: none. Wire: none. Config: two ignored keys start failing. diff --git a/quest/m1/precut-fixes/relay-high-key.md b/quest/m1/precut-fixes/relay-high-key.md new file mode 100644 index 00000000000..f17db6f3d2c --- /dev/null +++ b/quest/m1/precut-fixes/relay-high-key.md @@ -0,0 +1,37 @@ +# [M] A publisher's far-ahead group key costs a relay nothing extra + +## Goal + +A publisher that sends one group with a huge key and then keeps publishing +below it makes a relay hold memory bounded by what it caches, and each +subscriber wake costs work bounded by what that subscriber can still be +handed, not by every group the track ever received. A subscriber asking a +broadcast for endless track names grows nothing once each name is forgotten. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first. Both are on `release` too. + +- `rs/moq-net/src/model/track.rs`: `insert_group` makes the highest key the + live edge, `protects` keeps it from eviction, and the arrival trim only pops + from the front, so behind a protected `1<<40` group nothing is ever trimmed + (16 B per group forever). `poll_recv_group` skips entries below a reader's + `min_key` without advancing its index, so every insert wakes every live + subscriber into a walk over all N stale entries under the track mutex: + quadratic CPU on the relay's shared runtime. Recommended: compact + `arrival` the way `evict` is rebuilt, and let a reader's cursor skip + entries it will never be handed. +- `rs/moq-net/src/model/front.rs`: the front's track-info map keeps entries + past `Forgotten`; drop them there. + +Decided 2026-11-17 (maintainer, [moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): ✅ +backport the track fix to `release` as a separate PR after it +lands on `main`, per RELEASE.md, since one publisher can burn a shared +relay's CPU (rejected: shipping it only with the cut). + +Test: a publisher writes key `1<<40`, then keys 0..N; assert the arrival +queue stays bounded and a live subscriber's per-wake scan does not grow with +N. Add a bench sweep over N and subscribers, per AGENTS.md's fan-out rule. + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/signals-flip-back.md b/quest/m1/precut-fixes/signals-flip-back.md new file mode 100644 index 00000000000..a6d1a823e88 --- /dev/null +++ b/quest/m1/precut-fixes/signals-flip-back.md @@ -0,0 +1,29 @@ +# [S] A signal set and set back before it notifies reaches every reader + +## Goal + +In `@moq/signals`, a reader that registered and read a signal's value while a +notification was pending is notified whenever the value it saw differs from +the final one, so a signal flipped and flipped back within one batch never +leaves an effect or `changed()` waiter stuck on the middle value. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; reproduced on `main` with +a bun test: an effect reading `t` and `s`, then `t.set(1)`, then +`queueMicrotask(() => s.set(0)); s.set(1)`. The effect sees `[0, 1]` and +never reruns, while `s.peek()` is 0. `set` (`js/signals/src/index.ts`) saves +the value it replaces, and the queued notification is skipped when the final +value equals it, though a listener added in between saw the middle value. +On `release` too, from the original batching design. + +Recommended: record the value each listener added during a pending +notification saw, and deliver to it when the final value differs. No API +change, so it does not touch [signal semantics](https://github.com/moq-dev/moq/commit/bc66d3eaecc1e2e02e07aeccb1d2f167dce496e5)'s +frozen shape. Add the repro as a test. + +Public API: none. Wire: none. + +## Related + +- [Signal semantics](https://github.com/moq-dev/moq/commit/bc66d3eaecc1e2e02e07aeccb1d2f167dce496e5) - changes `update`, `mutate`, and `set(v, false)` diff --git a/quest/m1/precut-fixes/stats-minted-reconnect.md b/quest/m1/precut-fixes/stats-minted-reconnect.md new file mode 100644 index 00000000000..debf8b7db12 --- /dev/null +++ b/quest/m1/precut-fixes/stats-minted-reconnect.md @@ -0,0 +1,43 @@ +# [S] The stats aggregator counts a reconnected node once + +## Goal + +`moq-stats`'s aggregator keeps one entry per node across a reconnect on a +route whose instance a session minted (every version before lite-07, and +moq-transport), so a cluster link redial, a route failover, or a relay +restart within the aggregator's grace (`Config::grace`, 10 minutes) never adds a node's cumulative counters on top of its own retained +contribution. A real node restart is still detected by its counters going +down, as `doc/concept/stats.md` says for minted routes. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. +`Merged::apply_announce` (`rs/moq-stats/src/aggregate.rs`) keys nodes by +`(path, instance)`. Below lite-07 the receiving session mints a fresh +instance per session for each advertised path (`Minted::acquire` in +`rs/moq-net/src/lite/subscriber.rs`), and lite-06 is the default version. +After a redial the same node arrives under a new key, its cumulative totals +count from the start again, and once the old entry's 10-minute grace ends +its last frame folds into `retired`: the node is counted twice for good. +`release` keyed nodes by path only, so it does not have this. + +Recommended: when the new instance `is_minted()` and the path's previous +entry is also minted, carry the previous entry over to the new key, and let +the existing `regressed` check treat a counter going down as a restart. +A lite-07 instance a publisher named keeps today's per-instance entry. +A return after the grace starts over from zero, as `Merged`'s docs already +say for every route: the old entry has folded into `retired` and its path +lookup is gone, and bounding a per-node ledger of retired nodes would cost +memory for every departed node. This quest keeps that documented limit. + +Test: a simulated-clock aggregator test that unannounces and re-announces a +node path under a fresh minted instance, with counters continuing, and +asserts the merged total after the grace equals the node's last frame; and +the boundary, a re-announce just after the grace, which starts over as +documented. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#7489](https://github.com/moq-dev/moq/pull/7489) - keyed aggregator nodes by announced instance diff --git a/quest/m1/precut-fixes/tail-ledger-bound.md b/quest/m1/precut-fixes/tail-ledger-bound.md new file mode 100644 index 00000000000..0ef24621ea7 --- /dev/null +++ b/quest/m1/precut-fixes/tail-ledger-bound.md @@ -0,0 +1,40 @@ +# [S] A subscription's drop ledger is billed and folds under memory pressure + +## Goal + +The runs a publisher's SUBSCRIBE_DROP and SUBSCRIBE_SKIP messages add to a +relay subscription's tail ledger are charged to that copy's account and fold +away under cache-pool pressure, so a publisher sending alternating +single-group drops cannot grow relay memory for the life of a subscription +that has no max age and no max delay. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; confirmed from source. +`Tail::account` (`rs/moq-net/src/tail.rs`) records any range the peer names, +and `rebill` charges only `finished`, never the ledger's runs. With no track +max age, no `cache.duration`, and no viewer max delay, the grace is +`Duration::MAX`, so `ledger.rs` never folds a run: each 4 to 6 wire bytes of +drop leaves about 160 B on the relay. On `release` the ledger was unbilled +too, but an unset max age gave a 1 s grace. + +Recommended: bill the ledger's runs to the copy's account and fold the +oldest gap with `Ledger::fold_oldest` under pressure, as the track's own +arrivals ledger already does (rejected: a cap on runs, which the review +rules refuse). This holds whatever +[the tail drop count](/quest/m3/lite-tail-drop-count.md) later decides about +the grace. + +Test: apply N disjoint drops on a track with no max age and no max delay, +advance the simulated clock, apply pool pressure, and assert the ledger +folds. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#7597](https://github.com/moq-dev/moq/pull/7597) - made an unset max age an unbounded grace + +## Related + +- [Tail drop count](/quest/m3/lite-tail-drop-count.md) - removes the grace from deciding the tail diff --git a/quest/m1/precut-fixes/video-decode-lifecycle.md b/quest/m1/precut-fixes/video-decode-lifecycle.md new file mode 100644 index 00000000000..50d133ccee9 --- /dev/null +++ b/quest/m1/precut-fixes/video-decode-lifecycle.md @@ -0,0 +1,34 @@ +# [S] moq-video keeps a boundary through a failed drain and bounds its colour queue + +## Goal + +The video decoder and capture keep their lifecycles whole: a Gap or End is +delivered and leading-picture recovery is armed even when the drain before +it fails; the colour-switch queue stays bounded by the decoder's reorder +depth whatever a publisher's keyframes signal; and capture flushes its +encoder before dropping it, so the frames it holds are published. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first (inject a flush error through the `probe` backend). + +- `rs/moq-video/src/decode/consumer.rs`: at a Gap or End, `self.drain().await?` + returns before queueing `Read::Gap`/`Read::End` and setting `recover`, and + the marker is already consumed. Keep the drained pictures ahead of their + boundary: take the drain's result without `?`, queue whatever it drained, + then the boundary, arm recovery, and only then return the drain's error. + Read the end-of-track branch, which already survives a failed drain. From + [moq-dev/moq#6475](https://github.com/moq-dev/moq/pull/6475). +- `rs/moq-video/src/decode/decoder.rs`: an entry pushes per keyframe whose SPS + changes colour space and pops only when a delivered picture reaches it; a + publisher alternating colour spaces with a dropped first picture grows it + until the next Gap. Drop entries at or after a new keyframe's timestamp and + cap at the reorder depth, as `arrivals` is. From + [moq-dev/moq#5808](https://github.com/moq-dev/moq/pull/5808). +- `rs/moq-video/src/encode/producer.rs` `capture_loop`: `drop(encoder)` with + no `flush()`, against the crate's own rule from #8372; Media Foundation and + MediaCodec lose their last frames on a source end or resize. On `release` + too. + +Public API: none. Wire: none. diff --git a/quest/m1/precut-fixes/video-node-imports.md b/quest/m1/precut-fixes/video-node-imports.md new file mode 100644 index 00000000000..4b70f7d7ef5 --- /dev/null +++ b/quest/m1/precut-fixes/video-node-imports.md @@ -0,0 +1,31 @@ +# [XS] @moq/video loads under Node, and every published tsc package is load-checked + +## Goal + +The published `@moq/video` loads under Node and webpack 5, so `@moq/watch` +and `@moq/publish`, which import it at runtime, load in Next.js and in a +server-side import. The Node load check covers every published JS package +built with plain `tsc`, so the next new package cannot ship the same defect. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit; reproduced: +`cd js/video && bun run build && node -e 'import("./dist/index.js")'` fails +with `ERR_MODULE_NOT_FOUND` for `dist/presentation`. Six relative imports +lack an extension (`js/video/src/index.ts`, `renderer.ts`, `canvas2d.ts`, +`webgpu.ts`), and `tsc` only rewrites imports that end in `.ts`. +[moq-dev/moq#8914](https://github.com/moq-dev/moq/pull/8914) fixed the same +defect in hang and msf, but its Node check (`js/justfile`, +`sh/js/workspace.py`) lists only those two packages, and the watch/publish +load check runs under Bun, which accepts the imports and resolves +`@moq/video` to its source. + +Recommended: add `.ts` to the six imports, and derive the Node load check's +list from the workspace (every published package whose build is plain +`tsc`) instead of naming packages. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#5138](https://github.com/moq-dev/moq/pull/5138) - added `@moq/video` with extensionless imports (found by the audit; the check from #8914 missed it) diff --git a/quest/m1/precut-fixes/whep-egress-end.md b/quest/m1/precut-fixes/whep-egress-end.md new file mode 100644 index 00000000000..7fd4c665c6b --- /dev/null +++ b/quest/m1/precut-fixes/whep-egress-end.md @@ -0,0 +1,37 @@ +# [M] A WHEP viewer ends with its broadcast and costs one line per kind + +## Goal + +A WHEP session ends, closing its peer connection, once its broadcast's +catalog ends cleanly and the pumps have written what they hold, so a viewer +learns to reconnect instead of freezing forever. An offer is answered with at +most one audio and one video media line, so one viewer cannot multiply the +server's per-viewer work. A client re-offering from the same address reaches +its new session. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first. All are on `release` too. + +- `rs/moq-webrtc/src/session.rs` `run_loop`: a clean catalog end clears + `catalog_end` and keeps looping on `writes_rx`, whose sender + `EgressSource` holds for the session's life, so the session never ends. + [moq-dev/moq#6649](https://github.com/moq-dev/moq/pull/6649) said + `Response::run` fails once the publisher leaves; that holds only for an + unclean leave. Recommended: each pump owns its sender, and the session ends + `Ok` and closes once the writes channel drains after the catalog ends. + Repro: RTMP `deleteStream` while a WHEP viewer plays. +- `session.rs`, `egress.rs`, `sdp.rs`: an offer with K video lines gets K + pumps, each with its own subscription, packetization, encryption, and + 3000-packet buffer. Recommended: reject extra lines as data channels + already are. [RTC pacing](/quest/m3/rtc-pacing.md) caps bandwidth only. +- `server/mux.rs`: a cached source address outranks the STUN username, so a + re-offer from the same address goes to the old session. Route binding + requests by username. + +Public API: none. Wire: none. + +## Related + +- [RTC pacing](/quest/m3/rtc-pacing.md) - paces WHEP viewers to a cap diff --git a/quest/m1/ts-step-damage.md b/quest/m1/ts-step-damage.md new file mode 100644 index 00000000000..447e3fae6fa --- /dev/null +++ b/quest/m1/ts-step-damage.md @@ -0,0 +1,51 @@ +# [M] A TS import survives one stream's timestamp step + +## Goal + +A single elementary stream whose PTS jumps alone (a bit error or splicer +glitch on one audio PID) damages only that stream: the import drops and +counts the stray packets and keeps running. A data-only program whose PCR +jumps by more than half a wrap counts the reading as unplaced instead of +failing the import. + +## Plan + +Found by the 2026-11-17 pre-cut correctness audit, from source; reproduce +first. In `rs/moq-mux/src/container/ts/import.rs`, `forward` (called for +AAC, Opus, and legacy audio) returns `TimestampRewind`, which becomes +`Fault::Fatal`. `step.rs` rules that a stream stepping alone "is not a new +source and is left to the import", yet the import then fails the ingest: one +AAC packet 50 minutes ahead raises the floor, and the next normal packet ends +everything. `release`'s `Reanchor` shifted a stepped track instead. The +data-only case: `place_pcr` with no media clock lets `PtsUnwrap` go +negative, and `u64::try_from` fails the import with `TimeOverflow`, where a +program with media drops the same packet as unplaced. + +Decided 2026-11-17 (maintainer, +[moq-dev/moq#9010](https://github.com/moq-dev/moq/pull/9010#issuecomment-6959731587)): +✅ a standalone, low-priority m1 quest that does not gate the cut, since no +field report backs it and a lone PID's PTS step needs a corrupt PES header +or a muxer resetting one stream (rejected: gating the cut; deleting it). +✅ This design stands for whenever it is done, reproduced first, and it +challenges [moq-dev/moq#7898](https://github.com/moq-dev/moq/pull/7898)'s +rule that a TS audio rewind is a restart: +once the step judge rules "not a new source", a packet below the stream's +floor is dropped and counted as that stream's damage, and a forward outlier +raises the floor only when a second packet confirms it (rejected: keeping +the fatal rewind, which lets one bad packet end a live ingest; re-anchoring +as `release` did, which shifts good audio against video). + +Tests: PCR, H.264, and AAC on one timeline with one AAC packet 30 s ahead, +then normal packets: `decode` keeps succeeding and counts one damaged +packet; and a data-only program with a PCR jump past half a wrap. + +Public API: none. Wire: none. + +Caused by, for the fix PR's `## Caused by`: + +- [moq-dev/moq#7898](https://github.com/moq-dev/moq/pull/7898) - made a lone stream's rewind fatal to the import +- [moq-dev/moq#5967](https://github.com/moq-dev/moq/pull/5967) - PCR unwrap that can go negative on a data-only program + +## Related + +- [moq-dev/moq#9035](https://github.com/moq-dev/moq/pull/9035) - plans `quest/m2/ts-passthrough-splice.md`, which handles a whole-source PCR step on the passthrough lane; this quest is the lone-stream step on the import diff --git a/quest/m3/audit-perf.md b/quest/m3/audit-perf.md index bf1f5281fb2..1932cd21b16 100644 --- a/quest/m3/audit-perf.md +++ b/quest/m3/audit-perf.md @@ -79,6 +79,19 @@ such as `relay_auth_refresh`, is not attributable this way. copies; moq-quic loss recovery and real congestion controllers; HTTP announcement snapshots; MPEG-TS, MKV, FLV, H.265, and AV1 import with real media; JS watch audio ring and publish `Fanout`. +- From the 2026-11-17 pre-cut correctness audit, from source, each needing a + measurement before a fix: `Lines::make_room` (`rs/moq-net/src/transport/open.rs`) + rebuilds the session's preemption map on every poll of a waiting open, + which a credit-starved viewer of K tracks re-polls per frame (O(K²), from + #8103); `follow_demand` in `model/origin.rs` locks every reader to rebuild + demand on each wake (`resume.rs`); `frame.rs` compares a second copy of a + group byte for byte only to catch a reused identity, which AGENTS.md says + not to spend cycles on; TS passthrough (`ts/passthrough.rs`) re-sums its + whole object queue per packet, quadratic when a sender flags every packet + random-access and sends rare PCRs (#5003); and payload copies: the JS CMAF + decoder copies each sample twice (`js/hang/src/cmaf/decode.ts`), the FLV + import each tag body twice, fMP4 and MKV export several times per payload, + and WebRTC egress twice per frame per viewer (`rs/moq-webrtc/src/egress.rs`). - Single-axis fan-out benches to widen: `session_delivery_paced`, `track_fanout_*`, `memory`, and `bench/workloads/fanout*.toml`. diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index e0a64c0df03..754002ddd34 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -243,3 +243,4 @@ Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - [Nightly passes on main](/quest/m0/nightly/README.md) - the release gate runs `features.yml`, red in the 2026-11-12 Nightly - [Claim new npm names](/quest/m3/release/npm-first-publish.md) - trusted publishing can publish every new `@moq/*` package - [The Playwright bump](/quest/m1/playwright-pin.md) - the cut PR's interop lane runs with `CI_STRICT`, which fails the route key lane on a Chromium below 158 +- [Pre-cut correctness fixes](/quest/m1/precut-fixes/README.md) - the cut publishes none of the defects the 2026-11-17 correctness audit found