Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions quest/m1/precut-fixes/README.md
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions quest/m1/precut-fixes/archive-isolate.md
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions quest/m1/precut-fixes/audio-capture-drift.md
Original file line number Diff line number Diff line change
@@ -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.
26 changes: 26 additions & 0 deletions quest/m1/precut-fixes/bindings-negative-duration.md
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 30 additions & 0 deletions quest/m1/precut-fixes/capture-audio-reopen.md
Original file line number Diff line number Diff line change
@@ -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
37 changes: 37 additions & 0 deletions quest/m1/precut-fixes/error-outcomes.md
Original file line number Diff line number Diff line change
@@ -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
30 changes: 30 additions & 0 deletions quest/m1/precut-fixes/failover-models-sync.md
Original file line number Diff line number Diff line change
@@ -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.
36 changes: 36 additions & 0 deletions quest/m1/precut-fixes/fmp4-init-backpressure.md
Original file line number Diff line number Diff line change
@@ -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
30 changes: 30 additions & 0 deletions quest/m1/precut-fixes/js-net-leaks.md
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions quest/m1/precut-fixes/lite07-range-union.md
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions quest/m1/precut-fixes/moq-c-rate-thread.md
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions quest/m1/precut-fixes/nix-auth-restart.md
Original file line number Diff line number Diff line change
@@ -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
Loading