From 9f052142fe8b24d267132190c70aa4a77935c606 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 17 Nov 2026 05:04:00 -0800 Subject: [PATCH 1/4] quest: plan the 2026-11-17 pre-cut correctness audit's fixes Co-Authored-By: Claude Opus 5.5 --- quest/m1/audio-capture-drift.md | 25 +++++++++++ quest/m1/bindings-negative-duration.md | 26 ++++++++++++ quest/m1/error-outcomes.md | 37 +++++++++++++++++ quest/m1/failover-models-sync.md | 30 ++++++++++++++ quest/m1/js-net-leaks.md | 30 ++++++++++++++ quest/m1/precut-fixes/README.md | 35 ++++++++++++++++ quest/m1/precut-fixes/archive-isolate.md | 29 +++++++++++++ quest/m1/precut-fixes/capture-audio-reopen.md | 30 ++++++++++++++ .../m1/precut-fixes/fmp4-init-backpressure.md | 36 ++++++++++++++++ quest/m1/precut-fixes/moq-c-rate-thread.md | 29 +++++++++++++ quest/m1/precut-fixes/nix-auth-restart.md | 28 +++++++++++++ quest/m1/precut-fixes/relay-config-loud.md | 40 ++++++++++++++++++ .../m1/precut-fixes/stats-minted-reconnect.md | 37 +++++++++++++++++ quest/m1/precut-fixes/tail-ledger-bound.md | 40 ++++++++++++++++++ quest/m1/precut-fixes/ts-step-damage.md | 41 +++++++++++++++++++ quest/m1/precut-fixes/video-node-imports.md | 31 ++++++++++++++ quest/m1/relay-high-key.md | 37 +++++++++++++++++ quest/m1/signals-flip-back.md | 29 +++++++++++++ quest/m1/video-decode-lifecycle.md | 32 +++++++++++++++ quest/m1/whep-egress-end.md | 37 +++++++++++++++++ quest/m2/time-addressing/lite07.md | 20 +++++++++ quest/m3/audit-perf.md | 13 ++++++ quest/m3/release/cut.md | 1 + 23 files changed, 693 insertions(+) create mode 100644 quest/m1/audio-capture-drift.md create mode 100644 quest/m1/bindings-negative-duration.md create mode 100644 quest/m1/error-outcomes.md create mode 100644 quest/m1/failover-models-sync.md create mode 100644 quest/m1/js-net-leaks.md create mode 100644 quest/m1/precut-fixes/README.md create mode 100644 quest/m1/precut-fixes/archive-isolate.md create mode 100644 quest/m1/precut-fixes/capture-audio-reopen.md create mode 100644 quest/m1/precut-fixes/fmp4-init-backpressure.md create mode 100644 quest/m1/precut-fixes/moq-c-rate-thread.md create mode 100644 quest/m1/precut-fixes/nix-auth-restart.md create mode 100644 quest/m1/precut-fixes/relay-config-loud.md create mode 100644 quest/m1/precut-fixes/stats-minted-reconnect.md create mode 100644 quest/m1/precut-fixes/tail-ledger-bound.md create mode 100644 quest/m1/precut-fixes/ts-step-damage.md create mode 100644 quest/m1/precut-fixes/video-node-imports.md create mode 100644 quest/m1/relay-high-key.md create mode 100644 quest/m1/signals-flip-back.md create mode 100644 quest/m1/video-decode-lifecycle.md create mode 100644 quest/m1/whep-egress-end.md diff --git a/quest/m1/audio-capture-drift.md b/quest/m1/audio-capture-drift.md new file mode 100644 index 00000000000..dc168a105bf --- /dev/null +++ b/quest/m1/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/bindings-negative-duration.md b/quest/m1/bindings-negative-duration.md new file mode 100644 index 00000000000..82258f08fcd --- /dev/null +++ b/quest/m1/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/error-outcomes.md b/quest/m1/error-outcomes.md new file mode 100644 index 00000000000..b0d61416ac9 --- /dev/null +++ b/quest/m1/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](/quest/m2/session-codes.md) - errors classify themselves in moq-net diff --git a/quest/m1/failover-models-sync.md b/quest/m1/failover-models-sync.md new file mode 100644 index 00000000000..cd2dd929996 --- /dev/null +++ b/quest/m1/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/js-net-leaks.md b/quest/m1/js-net-leaks.md new file mode 100644 index 00000000000..64d3ced46cb --- /dev/null +++ b/quest/m1/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/README.md b/quest/m1/precut-fixes/README.md new file mode 100644 index 00000000000..4dc740cb0e0 --- /dev/null +++ b/quest/m1/precut-fixes/README.md @@ -0,0 +1,35 @@ +# Pre-cut correctness fixes + +## Goal + +Every regression and defect in newly shipped code that 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). + +Recommended 2026-11-17 (agent, under /quest-afk, for the maintainer's +review): ✅ a finding gates the cut when `release` does not have it, being a +regression or a defect in code the cut publishes for the first time +(rejected: gating every finding, which holds the cut on bugs `release` +already ships; gating none, which publishes regressions). The audit's +findings that `release` already has are standalone m1 quests that ship +whenever they land. + +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..9bda1cf6342 --- /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. + +Recommended: ✅ 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/capture-audio-reopen.md b/quest/m1/precut-fixes/capture-audio-reopen.md new file mode 100644 index 00000000000..8a236177d47 --- /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. + +Recommended: ✅ 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). 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/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/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..60a241c5dbd --- /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. + +Recommended: `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/stats-minted-reconnect.md b/quest/m1/precut-fixes/stats-minted-reconnect.md new file mode 100644 index 00000000000..c1c5458eda2 --- /dev/null +++ b/quest/m1/precut-fixes/stats-minted-reconnect.md @@ -0,0 +1,37 @@ +# [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 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. + +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. + +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/ts-step-damage.md b/quest/m1/precut-fixes/ts-step-damage.md new file mode 100644 index 00000000000..4ab202211ef --- /dev/null +++ b/quest/m1/precut-fixes/ts-step-damage.md @@ -0,0 +1,41 @@ +# [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. + +Recommended (challenges [moq-dev/moq#7898](https://github.com/moq-dev/moq/pull/7898)'s +rule that a TS audio rewind is a restart, for the maintainer's review): ✅ +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 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/relay-high-key.md b/quest/m1/relay-high-key.md new file mode 100644 index 00000000000..03019999680 --- /dev/null +++ b/quest/m1/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. + +Recommended 2026-11-17 (agent, under /quest-afk, for the maintainer's +review): ✅ 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/signals-flip-back.md b/quest/m1/signals-flip-back.md new file mode 100644 index 00000000000..1c8e57d5e6b --- /dev/null +++ b/quest/m1/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](/quest/m2/signals-semantics.md)'s +frozen shape. Add the repro as a test. + +Public API: none. Wire: none. + +## Related + +- [Signal semantics](/quest/m2/signals-semantics.md) - changes `update`, `mutate`, and `set(v, false)` diff --git a/quest/m1/video-decode-lifecycle.md b/quest/m1/video-decode-lifecycle.md new file mode 100644 index 00000000000..67b23b5f277 --- /dev/null +++ b/quest/m1/video-decode-lifecycle.md @@ -0,0 +1,32 @@ +# [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. Queue the boundary and arm recovery before + the fallible drain, as the end-of-track branch does. 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/whep-egress-end.md b/quest/m1/whep-egress-end.md new file mode 100644 index 00000000000..7fd4c665c6b --- /dev/null +++ b/quest/m1/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/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md index a568d7ad9de..356cd26ec2d 100644 --- a/quest/m2/time-addressing/lite07.md +++ b/quest/m2/time-addressing/lite07.md @@ -179,6 +179,26 @@ reserved-prefix rule). Not reopened by the audit: AUTH_ERROR's retry codes (the 2026-11-14 pick stands), and AUTH_OK's rate fields, which wait for lite-08 with [the rate grant](/quest/m5/rate-grant.md). +Found by the 2026-11-17 pre-cut correctness audit, from source, in the +range machinery this rewrite keeps (it changes the ranges' units, not how +they merge); fix both here, since lite-07 freezes with this quest: + +- A relay asks upstream for the exact union of its viewers' ranges + (`model/track/demand/ranges.rs` merges only touching ranges), so one session + sending two SUBSCRIBEs of about 10k interleaved single-group ranges, each + fitting a message, makes a union that does not, and the shared upstream + copy every viewer reads through is given back (`lite/subscriber.rs`); gap + fills across many viewers can fragment it the same way. `edit_keyed` in + `lite/subscribe.rs` also changes its stored ranges before the size check. + Recommended: when the exact union cannot fit, ask for a covering superset + by merging the smallest gaps, and size-check before mutating. From + [moq-dev/moq#7872](https://github.com/moq-dev/moq/pull/7872). +- Each SUBSCRIBE_UPDATE costs work proportional to every range the + subscription holds: `LiveRanges::apply` clones them all and + `TrackRun::update` rebuilds its lookups under the track lock. Apply only + the edit, keyed by Range ID, and skip the track call when nothing changed. + From #7872. + Public API: none beyond [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). `@moq/net` and the bindings' track listing gain a kind. Wire: lite-07-wip GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, 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 9c8268a70b1..dac750a01f4 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -240,3 +240,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 regressions the 2026-11-17 correctness audit found From ab791aadc68ad3890e2fbd7b51fa4d430300671c Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 17 Nov 2026 05:08:27 -0800 Subject: [PATCH 2/4] quest: keep drained pictures ahead of their boundary Co-Authored-By: Claude Opus 5.5 --- quest/m1/video-decode-lifecycle.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/quest/m1/video-decode-lifecycle.md b/quest/m1/video-decode-lifecycle.md index 67b23b5f277..50d133ccee9 100644 --- a/quest/m1/video-decode-lifecycle.md +++ b/quest/m1/video-decode-lifecycle.md @@ -15,8 +15,10 @@ 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. Queue the boundary and arm recovery before - the fallible drain, as the end-of-track branch does. From + 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 From e47fb27b56b99ef4450659a302159eb7b9ae5bc9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 12:21:09 -0800 Subject: [PATCH 3/4] quest: apply the maintainer's precut audit decisions Every finding gates the cut, so the nine standalone m1 quests move into the precut-fixes epic; ts-step-damage leaves it as a standalone low-priority quest. The stats quest keeps the documented grace limit. Co-Authored-By: Claude Opus 5.5 --- quest/m1/precut-fixes/README.md | 17 ++++++++--------- quest/m1/precut-fixes/archive-isolate.md | 2 +- .../{ => precut-fixes}/audio-capture-drift.md | 0 .../bindings-negative-duration.md | 0 quest/m1/precut-fixes/capture-audio-reopen.md | 4 ++-- quest/m1/{ => precut-fixes}/error-outcomes.md | 0 .../{ => precut-fixes}/failover-models-sync.md | 0 quest/m1/{ => precut-fixes}/js-net-leaks.md | 0 quest/m1/precut-fixes/nix-auth-restart.md | 2 +- quest/m1/{ => precut-fixes}/relay-high-key.md | 4 ++-- .../m1/{ => precut-fixes}/signals-flip-back.md | 0 quest/m1/precut-fixes/stats-minted-reconnect.md | 10 ++++++++-- .../video-decode-lifecycle.md | 0 quest/m1/{ => precut-fixes}/whep-egress-end.md | 0 quest/m1/{precut-fixes => }/ts-step-damage.md | 14 ++++++++++++-- quest/m3/release/cut.md | 2 +- 16 files changed, 35 insertions(+), 20 deletions(-) rename quest/m1/{ => precut-fixes}/audio-capture-drift.md (100%) rename quest/m1/{ => precut-fixes}/bindings-negative-duration.md (100%) rename quest/m1/{ => precut-fixes}/error-outcomes.md (100%) rename quest/m1/{ => precut-fixes}/failover-models-sync.md (100%) rename quest/m1/{ => precut-fixes}/js-net-leaks.md (100%) rename quest/m1/{ => precut-fixes}/relay-high-key.md (90%) rename quest/m1/{ => precut-fixes}/signals-flip-back.md (100%) rename quest/m1/{ => precut-fixes}/video-decode-lifecycle.md (100%) rename quest/m1/{ => precut-fixes}/whep-egress-end.md (100%) rename quest/m1/{precut-fixes => }/ts-step-damage.md (72%) diff --git a/quest/m1/precut-fixes/README.md b/quest/m1/precut-fixes/README.md index 4dc740cb0e0..6f64066414c 100644 --- a/quest/m1/precut-fixes/README.md +++ b/quest/m1/precut-fixes/README.md @@ -2,8 +2,7 @@ ## Goal -Every regression and defect in newly shipped code that the 2026-11-17 -pre-cut correctness audit found is fixed on `main` before the `0.22.0` cut, +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 @@ -18,13 +17,13 @@ exist were out of scope: the 2026-11-16 audit and the open m2 quest replaces (the old lite-07 route rule, YIELDED continuations, lite-07 sequence addressing, socket endpoints, moq-e2ee). -Recommended 2026-11-17 (agent, under /quest-afk, for the maintainer's -review): ✅ a finding gates the cut when `release` does not have it, being a -regression or a defect in code the cut publishes for the first time -(rejected: gating every finding, which holds the cut on bugs `release` -already ships; gating none, which publishes regressions). The audit's -findings that `release` already has are standalone m1 quests that ship -whenever they land. +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 diff --git a/quest/m1/precut-fixes/archive-isolate.md b/quest/m1/precut-fixes/archive-isolate.md index 9bda1cf6342..c3c99a88921 100644 --- a/quest/m1/precut-fixes/archive-isolate.md +++ b/quest/m1/precut-fixes/archive-isolate.md @@ -15,7 +15,7 @@ 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. -Recommended: ✅ log and drop the failed broadcast and keep exporting the rest; +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 diff --git a/quest/m1/audio-capture-drift.md b/quest/m1/precut-fixes/audio-capture-drift.md similarity index 100% rename from quest/m1/audio-capture-drift.md rename to quest/m1/precut-fixes/audio-capture-drift.md diff --git a/quest/m1/bindings-negative-duration.md b/quest/m1/precut-fixes/bindings-negative-duration.md similarity index 100% rename from quest/m1/bindings-negative-duration.md rename to quest/m1/precut-fixes/bindings-negative-duration.md diff --git a/quest/m1/precut-fixes/capture-audio-reopen.md b/quest/m1/precut-fixes/capture-audio-reopen.md index 8a236177d47..b1ed2d90fd6 100644 --- a/quest/m1/precut-fixes/capture-audio-reopen.md +++ b/quest/m1/precut-fixes/capture-audio-reopen.md @@ -17,10 +17,10 @@ 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. -Recommended: ✅ the CLI reopens the capture and its publication in a loop +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). A failure that persists past the backoff ends only the audio +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. diff --git a/quest/m1/error-outcomes.md b/quest/m1/precut-fixes/error-outcomes.md similarity index 100% rename from quest/m1/error-outcomes.md rename to quest/m1/precut-fixes/error-outcomes.md diff --git a/quest/m1/failover-models-sync.md b/quest/m1/precut-fixes/failover-models-sync.md similarity index 100% rename from quest/m1/failover-models-sync.md rename to quest/m1/precut-fixes/failover-models-sync.md diff --git a/quest/m1/js-net-leaks.md b/quest/m1/precut-fixes/js-net-leaks.md similarity index 100% rename from quest/m1/js-net-leaks.md rename to quest/m1/precut-fixes/js-net-leaks.md diff --git a/quest/m1/precut-fixes/nix-auth-restart.md b/quest/m1/precut-fixes/nix-auth-restart.md index 60a241c5dbd..56fd4d74c5f 100644 --- a/quest/m1/precut-fixes/nix-auth-restart.md +++ b/quest/m1/precut-fixes/nix-auth-restart.md @@ -15,7 +15,7 @@ systemd's semantics. In `nix/modules/moq-relay.nix`, `moq-auth` is it: switching stops `moq-auth`, `Requires=` propagates the stop to the relay, and the relay drains every session and starts with no handoff. -Recommended: `moq-auth` sets `stopIfChanged = false`, so it restarts in place +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 diff --git a/quest/m1/relay-high-key.md b/quest/m1/precut-fixes/relay-high-key.md similarity index 90% rename from quest/m1/relay-high-key.md rename to quest/m1/precut-fixes/relay-high-key.md index 03019999680..f17db6f3d2c 100644 --- a/quest/m1/relay-high-key.md +++ b/quest/m1/precut-fixes/relay-high-key.md @@ -25,8 +25,8 @@ first. Both are on `release` too. - `rs/moq-net/src/model/front.rs`: the front's track-info map keeps entries past `Forgotten`; drop them there. -Recommended 2026-11-17 (agent, under /quest-afk, for the maintainer's -review): ✅ backport the track fix to `release` as a separate PR after it +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). diff --git a/quest/m1/signals-flip-back.md b/quest/m1/precut-fixes/signals-flip-back.md similarity index 100% rename from quest/m1/signals-flip-back.md rename to quest/m1/precut-fixes/signals-flip-back.md diff --git a/quest/m1/precut-fixes/stats-minted-reconnect.md b/quest/m1/precut-fixes/stats-minted-reconnect.md index c1c5458eda2..debf8b7db12 100644 --- a/quest/m1/precut-fixes/stats-minted-reconnect.md +++ b/quest/m1/precut-fixes/stats-minted-reconnect.md @@ -5,7 +5,7 @@ `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 never adds a node's cumulative counters on top of its own retained +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. @@ -25,10 +25,16 @@ 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. +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. diff --git a/quest/m1/video-decode-lifecycle.md b/quest/m1/precut-fixes/video-decode-lifecycle.md similarity index 100% rename from quest/m1/video-decode-lifecycle.md rename to quest/m1/precut-fixes/video-decode-lifecycle.md diff --git a/quest/m1/whep-egress-end.md b/quest/m1/precut-fixes/whep-egress-end.md similarity index 100% rename from quest/m1/whep-egress-end.md rename to quest/m1/precut-fixes/whep-egress-end.md diff --git a/quest/m1/precut-fixes/ts-step-damage.md b/quest/m1/ts-step-damage.md similarity index 72% rename from quest/m1/precut-fixes/ts-step-damage.md rename to quest/m1/ts-step-damage.md index 4ab202211ef..447e3fae6fa 100644 --- a/quest/m1/precut-fixes/ts-step-damage.md +++ b/quest/m1/ts-step-damage.md @@ -21,8 +21,14 @@ 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. -Recommended (challenges [moq-dev/moq#7898](https://github.com/moq-dev/moq/pull/7898)'s -rule that a TS audio rewind is a restart, for the maintainer's review): ✅ +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 @@ -39,3 +45,7 @@ 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/release/cut.md b/quest/m3/release/cut.md index dac750a01f4..ef8274a3042 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -240,4 +240,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 regressions the 2026-11-17 correctness audit found +- [Pre-cut correctness fixes](/quest/m1/precut-fixes/README.md) - the cut publishes none of the defects the 2026-11-17 correctness audit found From 7a890a01c84bac1bac3d045a95800067e0941a9c Mon Sep 17 00:00:00 2001 From: quest fixer Date: Tue, 17 Nov 2026 13:41:09 -0800 Subject: [PATCH 4/4] docs: point completed quest references to landing commits --- quest/m1/precut-fixes/error-outcomes.md | 2 +- quest/m1/precut-fixes/signals-flip-back.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/quest/m1/precut-fixes/error-outcomes.md b/quest/m1/precut-fixes/error-outcomes.md index b0d61416ac9..3048e8e05fd 100644 --- a/quest/m1/precut-fixes/error-outcomes.md +++ b/quest/m1/precut-fixes/error-outcomes.md @@ -34,4 +34,4 @@ Public API: none. Wire: none. ## Related -- [Session codes](/quest/m2/session-codes.md) - errors classify themselves in moq-net +- [Session codes](https://github.com/moq-dev/moq/commit/b4c1db719358a25e351771e8ad33f01d45169bb0) - errors classify themselves in moq-net diff --git a/quest/m1/precut-fixes/signals-flip-back.md b/quest/m1/precut-fixes/signals-flip-back.md index 1c8e57d5e6b..a6d1a823e88 100644 --- a/quest/m1/precut-fixes/signals-flip-back.md +++ b/quest/m1/precut-fixes/signals-flip-back.md @@ -19,11 +19,11 @@ 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](/quest/m2/signals-semantics.md)'s +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](/quest/m2/signals-semantics.md) - changes `update`, `mutate`, and `set(v, false)` +- [Signal semantics](https://github.com/moq-dev/moq/commit/bc66d3eaecc1e2e02e07aeccb1d2f167dce496e5) - changes `update`, `mutate`, and `set(v, false)`